# Flask 模板迁移到 Vue 前端 — 工作任务清单

> 版本：1.0 ｜ 日期：2026-07-27 ｜ 作者：Claude

---

## 1. 背景与目标

### 现状

- 前端全部是 Flask 模板渲染的 HTML（`templates/*.html`）
- CSS/JS 内联在模板中，无组件化开发体验
- ECharts 从 CDN 加载（离线环境不可用）
- 前后端耦合，更新前端需重建镜像或 volume 挂载模板

### 目标

- 新建 Vue 3 前端项目，实现前后端分离
- Flask 只提供 REST API，不再渲染页面
- 前端编译后的静态文件（`dist/`）由 nginx 服务
- 前端更新只需替换静态文件，无需重启容器
- 保持现有功能和 UI 一致，不新增功能
- 覆盖所有三个模块：问题排查助手、服务监测、服务管理

---

## 2. 技术选型

| 组件 | 选型 | 理由 |
|------|------|------|
| 框架 | Vue 3 + Composition API | 最新稳定版，组合式 API 更灵活 |
| 构建工具 | Vite | 比 Vue CLI 更快，官方推荐 |
| UI 组件库 | Element Plus | 适合后台管理系统，组件丰富，文档完善 |
| 图表 | ECharts（npm 安装） | 当前用 ECharts，保持一致；打包进 bundle 避免 CDN 依赖 |
| HTTP 客户端 | Axios | 主流选择，拦截器支持好 |
| 路由 | Vue Router | 官方路由 |
| 状态管理 | Pinia | Vue 3 官方推荐，比 Vuex 更简洁 |
| 样式 | SCSS + Element Plus 主题 | 支持变量、嵌套，便于定制主题 |
| 语言 | TypeScript | 类型安全，IDE 支持好 |

---

## 3. 现有页面清单（三大模块共 18 个页面）

### 模块一：问题排查助手（3 个页面）

| 模板 | 路由 | 功能 | 复杂度 |
|------|------|------|--------|
| `login.html` | `/login` | 登录页（用户名/密码 + 记住我） | 低 |
| `platform.html` | `/` | 平台首页（三个模块卡片入口） | 低 |
| `index.html` | `/troubleshoot` | 问题排查主页（搜索框 + 知识库匹配 + AI 分析流式输出） | **高** |

**关键功能**：
- SSE 流式输出 AI 分析结果
- 知识库匹配结果高亮
- 历史记录侧边栏

---

### 模块二：服务监测（10 个页面）

| 模板 | 路由 | 功能 | 复杂度 |
|------|------|------|--------|
| `base.html` | - | 基础布局（侧边栏 + 顶部栏 + 内容区） | 中 |
| `index.html` | `/service-monitor` | 监测主页（目标卡片 + 最近报告列表） | 中 |
| `targets.html` | `/service-monitor/targets` | 目标管理（CRUD 弹窗 + 连通性测试） | 中 |
| `run.html` | `/service-monitor/run` | 巡检执行（SSE 进度条 + 模块清单实时更新） | **高** |
| `report.html` | `/service-monitor/report/:id` | 报告详情（汇总卡片 + 异常置顶 + 分模块折叠） | 高 |
| `reports.html` | `/service-monitor/reports` | 报告列表（目标筛选 + 批量删除） | 中 |
| `statistics.html` | `/service-monitor/statistics` | 监测统计（ECharts 多图表 + 筛选） | **高** |
| `schedule.html` | `/service-monitor/schedule` | 定时任务管理（CRUD + 启用/禁用 + 立即执行） | 中 |
| `compare.html` | `/service-monitor/compare` | 报告对比（两份报告并列对比差异） | 中 |
| `notification.html` | `/service-monitor/notification` | 通知配置（钉钉/企业微信/邮件 + 测试发送） | 中 |

**关键功能**：
- SSE 实时进度（巡检执行页）
- ECharts 多图表联动（统计页）
- 报告免登访问（token 参数）
- 定时任务执行状态轮询

---

### 模块三：服务管理（4 个页面）

| 模板 | 路由 | 功能 | 复杂度 |
|------|------|------|--------|
| `base.html` | - | 服务管理基础布局（Tab 切换） | 低 |
| `authorization.html` | `/service-manage/authorization` | 授权管理（授权码输入 + 状态展示） | 低 |
| `upgrade.html` | `/service-manage/upgrade` | 升级管理（版本信息 + 升级操作） | 低 |
| `info.html` | `/service-manage/info` | 服务信息（系统版本、运行状态） | 低 |

---

## 4. 后端 API 清单

前端迁移需确保以下 API 稳定可用：

### 问题排查助手 API

| 接口 | 方法 | 功能 |
|------|------|------|
| `/api/troubleshoot` | POST | AI 分析（SSE 流式） |
| `/api/search` | GET | 知识库搜索 |
| `/api/projects` | GET | 项目列表 |
| `/api/categories` | GET | 分类列表 |
| `/api/health` | GET | 健康检查 |
| `/api/user/info` | GET | 当前用户信息 |
| `/api/cache/stats` | GET | 缓存统计 |
| `/api/cache/clear` | POST | 清空缓存 |
| `/api/export` | POST | 导出报告 |
| `/api/submit` | POST | 提交问题记录 |

### 服务监测 API

| 接口 | 方法 | 功能 |
|------|------|------|
| `/api/service-monitor/targets` | GET/POST/PUT/DELETE | 目标 CRUD |
| `/api/service-monitor/targets/:id/test` | POST | 连通性测试 |
| `/api/service-monitor/reports` | GET | 报告列表 |
| `/api/service-monitor/reports/:id` | GET/DELETE | 报告详情/删除 |
| `/api/service-monitor/reports/:id/export` | GET | 报告导出（md/json/xlsx/pdf） |
| `/api/service-monitor/run` | POST | 执行巡检（SSE） |
| `/api/service-monitor/schedules` | GET/POST/PUT/DELETE | 定时任务 CRUD |
| `/api/service-monitor/schedules/:id/run` | POST | 立即执行 |
| `/api/service-monitor/statistics/*` | GET | 统计数据（5 个接口） |
| `/api/service-monitor/notification` | GET/POST | 通知配置 |
| `/api/service-monitor/notification/test` | POST | 测试发送 |

### 服务管理 API

| 接口 | 方法 | 功能 |
|------|------|------|
| `/api/service-manage/authorization` | GET/POST | 授权管理 |
| `/api/service-manage/upgrade` | GET/POST | 升级管理 |
| `/api/service-manage/info` | GET | 服务信息 |

### 认证 API

| 接口 | 方法 | 功能 |
|------|------|------|
| `/login` | GET/POST | 登录页面/提交登录 |
| `/logout` | POST | 登出 |
| `/api/users` | GET/POST | 用户管理（管理员） |

---

## 5. 工作阶段划分

### 阶段一：前端项目骨架搭建（预估 2-3 天）

| # | 任务 | 输出 |
|---|------|------|
| 1.1 | 创建 Vue 3 + Vite + TypeScript 项目 | `frontend/` 目录 |
| 1.2 | 配置 Element Plus + SCSS + Vue Router + Pinia | `main.ts`, `router/`, `stores/` |
| 1.3 | 安装并配置 ECharts（npm 方式） | `package.json` |
| 1.4 | 实现基础布局组件（侧边栏 + 顶部栏 + 内容区） | `components/Layout/` |
| 1.5 | 实现登录页 + 路由守卫 + 登录状态管理 | `views/Login.vue`, `stores/user.ts` |
| 1.6 | 配置 Axios + 请求/响应拦截器 | `utils/http.ts` |
| 1.7 | 配置环境变量（开发/生产 API 地址） | `.env.*` |
| 1.8 | 实现全局组件（Loading、Message 确认框等） | `components/common/` |

### 阶段二：API 层封装 + TypeScript 类型定义（预估 2 天）

| # | 任务 | 输出 |
|---|------|------|
| 2.1 | 定义 TypeScript 类型（API 请求/响应结构） | `types/*.ts` |
| 2.2 | 封装认证 API | `api/auth.ts` |
| 2.3 | 封装问题排查 API（含 SSE 流式处理） | `api/troubleshoot.ts` |
| 2.4 | 封装服务监测 API（10+ 接口） | `api/service-monitor/*.ts` |
| 2.5 | 封装服务管理 API | `api/service-manage.ts` |

### 阶段三：页面迁移 — 问题排查助手模块（预估 2 天）

| # | 页面 | 预估工时 |
|---|------|----------|
| 3.1 | 登录页 | 0.5 天 |
| 3.2 | 平台首页 | 0.5 天 |
| 3.3 | 问题排查主页（SSE 流式输出） | 1 天 |

### 阶段四：页面迁移 — 服务监测模块（预估 6-8 天）

| # | 页面 | 预估工时 |
|---|------|----------|
| 4.1 | 监测主页（目标卡片 + 报告列表） | 1 天 |
| 4.2 | 目标管理 | 1 天 |
| 4.3 | 定时任务管理 | 1 天 |
| 4.4 | 通知配置 | 1 天 |
| 4.5 | 报告列表 | 1 天 |
| 4.6 | 报告详情 | 1 天 |
| 4.7 | 巡检执行（SSE 进度） | 1 天 |
| 4.8 | 监测统计（ECharts 多图表） | 1.5 天 |
| 4.9 | 报告对比 | 1 天 |

### 阶段五：页面迁移 — 服务管理模块（预估 1 天）

| # | 页面 | 预估工时 |
|---|------|----------|
| 5.1 | 服务管理布局（Tab 切换） | 0.3 天 |
| 5.2 | 授权管理 | 0.2 天 |
| 5.3 | 升级管理 | 0.2 天 |
| 5.4 | 服务信息 | 0.3 天 |

### 阶段六：后端调整（预估 1 天）

| # | 任务 | 输出 |
|---|------|------|
| 6.1 | 移除模板渲染路由，只保留 API 路由 | 修改 `routes/*.py` |
| 6.2 | 新增 SPA 回退路由（所有非 API 请求返回 index.html） | `server.py` |
| 6.3 | CORS 配置（开发环境允许前端跨域） | `flask-cors` |
| 6.4 | 移除 templates/ 目录（可选，保留备份） | - |

### 阶段七：部署配置（预估 1 天）

| # | 任务 | 输出 |
|---|------|------|
| 7.1 | Dockerfile 多阶段构建（Node 构建 Vue → Python Flask） | `Dockerfile` |
| 7.2 | nginx 配置（静态文件服务 + API 反向代理） | `nginx.conf` |
| 7.3 | docker-compose.yml 更新 | `docker-compose.yml` |
| 7.4 | 部署脚本更新 | `deploy/docker_deploy.sh` |
| 7.5 | 前端构建脚本 | `frontend/build.sh` |

### 阶段八：测试与验收（预估 2-3 天）

| # | 任务 | 输出 |
|---|------|------|
| 8.1 | 功能回归测试（18 个页面） | 测试报告 |
| 8.2 | API 兼容性测试 | - |
| 8.3 | SSE 流式输出测试 | - |
| 8.4 | ECharts 图表渲染测试 | - |
| 8.5 | 部署验证（本地 Docker + 5.60） | - |
| 8.6 | 性能对比（页面加载时间） | - |
| 8.7 | 浏览器兼容性测试（Chrome/Edge/Firefox） | - |

---

## 6. 目录结构设计

```
/data/third_party/monitor-platform/
├── frontend/                         # Vue 前端项目
│   ├── src/
│   │   ├── api/                      # API 封装
│   │   │   ├── auth.ts
│   │   │   ├── troubleshoot.ts
│   │   │   └── service-monitor/
│   │   │       ├── target.ts
│   │   │       ├── report.ts
│   │   │       ├── schedule.ts
│   │   │       ├── statistics.ts
│   │   │       └── notification.ts
│   │   ├── components/               # 公共组件
│   │   │   ├── Layout/
│   │   │   │   ├── AppLayout.vue     # 主布局
│   │   │   │   ├── Sidebar.vue       # 侧边栏
│   │   │   │   └── Header.vue        # 顶部栏
│   │   │   └── common/
│   │   │       ├── Loading.vue
│   │   │       └── ConfirmDialog.vue
│   │   ├── views/                    # 页面组件
│   │   │   ├── login/
│   │   │   │   └── Index.vue
│   │   │   ├── platform/
│   │   │   │   └── Index.vue
│   │   │   ├── troubleshoot/
│   │   │   │   └── Index.vue         # 问题排查主页
│   │   │   ├── service-monitor/
│   │   │   │   ├── Index.vue         # 监测主页
│   │   │   │   ├── Targets.vue
│   │   │   │   ├── Run.vue
│   │   │   │   ├── Report.vue
│   │   │   │   ├── Reports.vue
│   │   │   │   ├── Statistics.vue
│   │   │   │   ├── Schedule.vue
│   │   │   │   ├── Compare.vue
│   │   │   │   └── Notification.vue
│   │   │   └── service-manage/
│   │   │       ├── Index.vue
│   │   │       ├── Authorization.vue
│   │   │       ├── Upgrade.vue
│   │   │       └── Info.vue
│   │   ├── stores/                   # Pinia 状态管理
│   │   │   ├── user.ts               # 用户登录状态
│   │   │   ├── troubleshoot.ts       # 问题排查状态
│   │   │   └── service-monitor/      # 服务监测状态
│   │   ├── router/                   # 路由配置
│   │   │   └── index.ts
│   │   ├── styles/                   # 全局样式
│   │   │   ├── variables.scss
│   │   │   └── global.scss
│   │   ├── types/                    # TypeScript 类型定义
│   │   │   ├── api.ts
│   │   │   ├── troubleshoot.ts
│   │   │   └── service-monitor.ts
│   │   ├── utils/                    # 工具函数
│   │   │   ├── http.ts               # Axios 封装
│   │   │   ├── sse.ts                # SSE 工具
│   │   │   └── storage.ts            # 本地存储
│   │   ├── App.vue
│   │   └── main.ts
│   ├── public/
│   │   └── favicon.ico
│   ├── .env.development              # 开发环境变量
│   ├── .env.production              # 生产环境变量
│   ├── index.html
│   ├── package.json
│   ├── vite.config.ts
│   └── tsconfig.json
│
├── backend/                          # Flask 后端（当前 skill/code/web/）
│   ├── server.py
│   ├── routes/
│   │   ├── auth.py
│   │   ├── troubleshoot.py
│   │   ├── service_monitor.py
│   │   └── service_manage.py
│   ├── services/
│   ├── utils/
│   └── service_monitor/
│
├── dist/                             # 前端编译产物（部署时）
│   ├── index.html
│   └── assets/
│
├── data/                             # 运行时数据（volume 挂载）
│   ├── troubleshoot.db               # SQLite 数据库
│   ├── 搜索索引.json
│   ├── 搜索向量.json
│   └── logs/
│
├── nginx.conf                        # nginx 配置
├── docker-compose.yml                # 编排配置
└── Dockerfile
```

---

## 7. Docker 部署架构

```
┌─────────────────────────────────────────────────────────────────┐
│                      Docker Container                            │
│                                                                  │
│  nginx:80                                                        │
│  ├── /                    → /data/dist/index.html (前端 SPA)     │
│  ├── /assets/*            → /data/dist/assets/*                 │
│  └── /api/*               → 反向代理到 Flask:8088                │
│                                                                  │
│  Flask:8088 (后端 API)                                           │
│  └── /api/*               → 业务逻辑 + SQLite                    │
│                                                                  │
│  SQLite: /data/data/troubleshoot.db                              │
└─────────────────────────────────────────────────────────────────┘
        │
   port 80:80 (对外)
        │
   宿主机 5.60
```

**更新流程**：
- 更新前端：替换 `/data/dist/` 目录，**无需重启容器**
- 更新后端：重建镜像并重启容器

---

## 8. 关键技术点

### 8.1 SSE 流式输出（问题排查 AI 分析）

```typescript
// Vue 前端接收 SSE
async function fetchAIAnalysis(query: string) {
  const response = await fetch(`/api/troubleshoot?query=${encodeURIComponent(query)}`)
  const reader = response.body?.getReader()
  const decoder = new TextDecoder()
  
  while (true) {
    const { done, value } = await reader!.read()
    if (done) break
    const chunk = decoder.decode(value)
    // 解析 SSE 格式: data: {...}\n\n
    const lines = chunk.split('\n')
    for (const line of lines) {
      if (line.startsWith('data: ')) {
        const data = JSON.parse(line.slice(6))
        // 更新响应内容
      }
    }
  }
}
```

### 8.2 巡检执行 SSE 进度

```typescript
// EventSource 方式（巡检执行页）
const eventSource = new EventSource('/api/service-monitor/run?target_id=xxx')

eventSource.addEventListener('progress', (event) => {
  const data = JSON.parse(event.data)
  // 更新进度条
})

eventSource.addEventListener('complete', (event) => {
  // 跳转报告页
  router.push(`/service-monitor/report/${data.report_id}`)
})
```

### 8.3 ECharts 使用

```typescript
import * as echarts from 'echarts'

const chartDom = ref<HTMLElement>()
const chart = echarts.init(chartDom.value!)

chart.setOption({
  title: { text: '模块健康概览' },
  tooltip: {},
  xAxis: { type: 'category' },
  yAxis: { type: 'value' },
  series: [{ type: 'bar', data: [...] }]
})
```

### 8.4 路由配置

```typescript
// router/index.ts
const routes = [
  { path: '/login', component: () => import('@/views/login/Index.vue') },
  { path: '/', component: () => import('@/views/platform/Index.vue') },
  { 
    path: '/troubleshoot', 
    component: () => import('@/views/troubleshoot/Index.vue'),
    meta: { requiresAuth: true }
  },
  {
    path: '/service-monitor',
    component: () => import('@/views/service-monitor/Index.vue'),
    meta: { requiresAuth: true },
    children: [
      { path: 'targets', component: () => import('@/views/service-monitor/Targets.vue') },
      { path: 'run', component: () => import('@/views/service-monitor/Run.vue') },
      // ... 其他子路由
    ]
  },
  // ...
]
```

### 8.5 Axios 拦截器

```typescript
// utils/http.ts
const http = axios.create({
  baseURL: import.meta.env.VITE_API_BASE,
  timeout: 30000,
  withCredentials: true,  // 自动带 cookie
})

// 响应拦截器：处理错误
http.interceptors.response.use(
  response => response.data,
  error => {
    if (error.response?.status === 401) {
      // 未登录，跳转登录页
      router.push('/login')
    }
    return Promise.reject(error)
  }
)
```

---

## 9. 风险与缓解

| 风险 | 影响 | 缓解措施 |
|------|------|----------|
| 前端重构引入 UI 差异 | 用户不适应 | 严格按现有模板还原，不改变交互逻辑 |
| SSE 流式输出兼容性问题 | AI 分析/巡检进度失效 | 优先实现并单独测试 SSE |
| ECharts 图表渲染差异 | 统计页面异常 | 保持相同配置项 |
| 后端 API 变更 | 前端调用失败 | 先冻结 API，前端完全适配后再考虑优化 |
| 开发周期超出预期 | 项目延期 | 按阶段交付，优先核心页面 |
| TypeScript 类型定义不全 | 开发效率下降 | 先定义核心类型，逐步补充 |
| 移动端适配问题 | 体验下降 | 复用当前已有的响应式样式 |

---

## 10. 估算工时

| 阶段 | 预估工时 | 说明 |
|------|----------|------|
| 阶段一：前端骨架 | 2-3 天 | 含布局、登录、Axios 配置 |
| 阶段二：API 封装 + TS 类型 | 2 天 | TypeScript 类型定义 |
| 阶段三：问题排查模块 | 2 天 | 3 个页面 |
| 阶段四：服务监测模块 | 6-8 天 | 10 个页面，核心模块 |
| 阶段五：服务管理模块 | 1 天 | 4 个页面，逻辑简单 |
| 阶段六：后端调整 | 1 天 | 移除模板路由、CORS |
| 阶段七：部署配置 | 1 天 | Dockerfile、nginx |
| 阶段八：测试验收 | 2-3 天 | 功能回归、部署验证 |
| **总计** | **17-21 天** | 约 3-4 周 |

---

## 11. 建议执行顺序

### 方案 A：先容器化，再 Vue 重构（推荐）

1. **先完成容器化部署**（用当前 Flask 模板 + volume 挂载模板目录）
   - 部署架构先定下来
   - SQLite 迁移也先完成
   - 验证容器化流程

2. **并行推进 Vue 前端重构**
   - 独立任务，不影响后端开发
   - 可分配给前端开发者

3. **Vue 完成后切换**
   - 修改 nginx 配置指向新的前端 dist/
   - 删除 volume 挂载的旧模板

### 方案 B：直接一步到位

1. 新建 Vue 项目
2. 完成所有页面迁移
3. 后端调整 + Dockerfile + nginx
4. 一次性部署

**方案 A 的优势**：不阻塞容器化和 SQLite 迁移，Vue 重构可以稳步推进，风险更低。

---

## 12. 后续扩展方向

Vue 前端建成后，后续可方便地：

- **移动端适配**：响应式布局已具备基础
- **国际化**：Vue I18n 插件
- **暗黑模式**：Element Plus 内置支持
- **PWA 支持**：离线访问能力
- **组件库升级**：Element Plus 持续更新
- **前端单元测试**：Vitest + Vue Test Utils