293 lines
14 KiB
Markdown
293 lines
14 KiB
Markdown
# 实现计划：Web 管理后台（admin-web-console）
|
||
|
||
## 概述
|
||
|
||
将现有 PySide6 桌面 GUI 替换为 BS 架构的 Web 管理后台。后端在 `apps/backend/` 上扩展 FastAPI API，前端在 `apps/admin-web/` 下使用 React + Vite + Ant Design 构建。实现按"后端基础设施 → 核心 API → 前端骨架 → 功能模块逐个对接"的顺序推进。
|
||
|
||
## 任务
|
||
|
||
- [x] 1. 后端基础设施搭建
|
||
- [x] 1.1 创建数据库迁移脚本，在 `zqyy_app` 库中创建 4 张新表（admin_users、task_queue、task_execution_log、scheduled_tasks），所有表包含 site_id 字段
|
||
- 迁移脚本放在 `db/zqyy_app/migrations/`，日期前缀命名
|
||
- 包含索引创建（site_id 相关的复合索引）
|
||
- 包含种子数据：插入一个默认管理员账号
|
||
- _Requirements: 1.1, 4.1, 5.1_
|
||
|
||
- [x] 1.2 实现 JWT 认证模块（`apps/backend/app/auth/`）
|
||
- `jwt.py`：JWT 令牌生成（access_token + refresh_token）、验证、解码，payload 包含 user_id 和 site_id
|
||
- `dependencies.py`：FastAPI 依赖注入函数 `get_current_user`，从 JWT 提取用户信息和 site_id
|
||
- 新增依赖：`python-jose[cryptography]`、`passlib[bcrypt]` 到 `apps/backend/pyproject.toml`
|
||
- _Requirements: 1.1, 1.2, 1.3, 1.4_
|
||
|
||
- [x] 1.3 实现认证路由（`apps/backend/app/routers/auth.py`）
|
||
- `POST /api/auth/login`：验证用户名密码，返回 JWT 令牌对
|
||
- `POST /api/auth/refresh`：用刷新令牌换取新的访问令牌
|
||
- Pydantic schemas：`LoginRequest`、`TokenResponse`
|
||
- _Requirements: 1.1, 1.2, 1.4_
|
||
|
||
- [x] 1.4 编写认证模块属性测试
|
||
- **Property 2: 无效凭据始终被拒绝**
|
||
- **Property 3: 有效 JWT 令牌授权访问**
|
||
- **Validates: Requirements 1.2, 1.3**
|
||
|
||
- [x] 1.5 扩展 `apps/backend/app/database.py`，新增 ETL 数据库只读连接函数
|
||
- `get_etl_readonly_connection(site_id)`：连接 ETL 数据库，设置 `SET LOCAL app.current_site_id`
|
||
- 配置项从 .env 读取 ETL 数据库连接参数
|
||
- _Requirements: 7.4, 7.5_
|
||
|
||
- [x] 1.6 在 `apps/backend/app/main.py` 中注册所有路由和中间件，配置 CORS 允许前端开发服务器访问
|
||
- _Requirements: 10.2_
|
||
|
||
- [x] 2. 检查点 — 确保认证模块测试通过
|
||
- 确保所有测试通过，如有问题请向用户确认。
|
||
|
||
- [x] 3. 任务配置与执行 API
|
||
- [x] 3.1 迁移 CLIBuilder 到后端（`apps/backend/app/services/cli_builder.py`）
|
||
- 从 `gui/utils/cli_builder.py` 迁移核心逻辑
|
||
- 适配新的 TaskConfigSchema，自动注入 `--store-id` 参数
|
||
- 支持 7 种 Flow 和 4 种处理模式
|
||
- _Requirements: 2.6_
|
||
|
||
- [x] 3.2 实现任务注册表 API（`apps/backend/app/routers/tasks.py`）
|
||
- `GET /api/tasks/registry`：返回按业务域分组的任务列表
|
||
- `GET /api/tasks/dwd-tables`：返回按业务域分组的 DWD 表定义
|
||
- `GET /api/tasks/flows`：返回 7 种 Flow 定义和 4 种处理模式定义
|
||
- `POST /api/tasks/validate`：验证 TaskConfig 并返回生成的 CLI 命令预览
|
||
- Pydantic schemas 在 `apps/backend/app/schemas/tasks.py`
|
||
- _Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 11.1, 11.2_
|
||
|
||
- [x] 3.3 编写 TaskConfig 属性测试
|
||
- **Property 1: TaskConfig 序列化往返一致性**
|
||
- **Property 6: 时间窗口验证**
|
||
- **Property 7: TaskConfig 到 CLI 命令转换完整性**
|
||
- **Validates: Requirements 2.3, 2.5, 2.6, 11.1, 11.2, 11.3**
|
||
|
||
- [x] 3.4 实现 TaskExecutor 服务（`apps/backend/app/services/task_executor.py`）
|
||
- 使用 `asyncio.create_subprocess_exec` 启动 ETL_CLI 子进程
|
||
- 逐行读取 stdout/stderr，存储到内存缓冲区并广播到 WebSocket
|
||
- 记录退出码、执行时长到 task_execution_log 表
|
||
- 支持取消（发送 SIGTERM）
|
||
- _Requirements: 3.1, 3.2, 3.3, 3.4, 3.5_
|
||
|
||
- [x] 3.5 实现 TaskQueue 服务（`apps/backend/app/services/task_queue.py`）
|
||
- `enqueue(config, site_id)`：入队，自动分配 position
|
||
- `dequeue(site_id)`：取出 position 最小的 pending 任务
|
||
- `reorder(task_id, new_position, site_id)`：调整顺序
|
||
- `delete(task_id, site_id)`：删除 pending 任务
|
||
- `process_loop()`：后台协程，自动取出并执行
|
||
- _Requirements: 4.1, 4.2, 4.3, 4.4_
|
||
|
||
- [x] 3.6 实现执行与队列路由（`apps/backend/app/routers/execution.py`）
|
||
- `POST /api/execution/run`：直接执行任务
|
||
- `GET /api/execution/queue`：获取当前队列（按 site_id 过滤）
|
||
- `POST /api/execution/queue`：添加到队列
|
||
- `PUT /api/execution/queue/reorder`：重排
|
||
- `DELETE /api/execution/queue/{id}`：删除
|
||
- `POST /api/execution/{id}/cancel`：取消
|
||
- `GET /api/execution/history`：执行历史（按 site_id 过滤，limit 参数）
|
||
- `GET /api/execution/{id}/logs`：获取历史日志
|
||
- _Requirements: 3.1, 3.5, 4.1, 4.2, 4.3, 4.4, 4.5_
|
||
|
||
- [x] 3.7 编写队列属性测试
|
||
- **Property 8: 队列 CRUD 不变量**
|
||
- **Property 9: 队列出队顺序**
|
||
- **Property 10: 队列重排一致性**
|
||
- **Property 11: 执行历史排序与限制**
|
||
- **Validates: Requirements 4.1, 4.2, 4.3, 4.4, 4.5, 8.2**
|
||
|
||
- [x] 4. 检查点 — 确保任务配置与执行 API 测试通过
|
||
- 确保所有测试通过，如有问题请向用户确认。
|
||
|
||
- [x] 5. 调度与辅助 API
|
||
- [x] 5.1 实现 Scheduler 服务（`apps/backend/app/services/scheduler.py`）
|
||
- `check_and_enqueue()`：查询 enabled=true 且 next_run_at <= now 的调度任务，将其 TaskConfig 入队
|
||
- `start()`：启动后台 asyncio 循环，每 30 秒检查一次
|
||
- 在 FastAPI lifespan 中启动/停止
|
||
- _Requirements: 5.2_
|
||
|
||
- [x] 5.2 实现调度路由（`apps/backend/app/routers/schedules.py`）
|
||
- `GET /api/schedules`：列表（按 site_id 过滤）
|
||
- `POST /api/schedules`：创建
|
||
- `PUT /api/schedules/{id}`：更新
|
||
- `DELETE /api/schedules/{id}`：删除
|
||
- `PATCH /api/schedules/{id}/toggle`：启用/禁用
|
||
- Pydantic schemas 在 `apps/backend/app/schemas/schedules.py`
|
||
- _Requirements: 5.1, 5.3, 5.4, 5.5, 5.6_
|
||
|
||
- [x] 5.3 编写调度属性测试
|
||
- **Property 12: 调度任务 CRUD 往返**
|
||
- **Property 13: 到期调度任务自动入队**
|
||
- **Property 14: 调度任务启用/禁用状态**
|
||
- **Validates: Requirements 5.1, 5.2, 5.3, 5.4**
|
||
|
||
- [x] 5.4 实现环境配置路由（`apps/backend/app/routers/env_config.py`）
|
||
- `GET /api/env-config`：读取 .env，敏感值掩码
|
||
- `PUT /api/env-config`：验证并写入 .env
|
||
- `GET /api/env-config/export`：导出去敏感值的配置文件
|
||
- 敏感键列表：PASSWORD、TOKEN、SECRET、DSN
|
||
- _Requirements: 6.1, 6.2, 6.3, 6.4_
|
||
|
||
- [x] 5.5 编写环境配置属性测试
|
||
- **Property 15: .env 解析与敏感值掩码**
|
||
- **Property 16: .env 写入往返一致性**
|
||
- **Validates: Requirements 6.1, 6.2, 6.3**
|
||
|
||
- [x] 5.6 实现数据库查看器路由（`apps/backend/app/routers/db_viewer.py`）
|
||
- `GET /api/db/schemas`：返回 Schema 列表
|
||
- `GET /api/db/schemas/{name}/tables`：返回表列表和行数
|
||
- `GET /api/db/tables/{schema}/{table}/columns`：返回列定义
|
||
- `POST /api/db/query`：只读 SQL 执行（写操作拦截、1000 行限制、30 秒超时）
|
||
- 使用 `get_etl_readonly_connection(site_id)` 确保 RLS 隔离
|
||
- _Requirements: 7.1, 7.2, 7.3, 7.4, 7.5, 7.6_
|
||
|
||
- [x] 5.7 编写数据库查看器属性测试
|
||
- **Property 17: SQL 写操作拦截**
|
||
- **Property 18: SQL 查询结果行数限制**
|
||
- **Validates: Requirements 7.4, 7.5**
|
||
|
||
- [x] 5.8 实现 ETL 状态路由（`apps/backend/app/routers/etl_status.py`）
|
||
- `GET /api/etl-status/cursors`：查询 etl_admin.etl_cursor 表，返回各任务游标
|
||
- `GET /api/etl-status/recent-runs`：查询 task_execution_log 表，返回最近 50 条记录
|
||
- _Requirements: 8.1, 8.2, 8.3_
|
||
|
||
- [x] 5.9 实现 WebSocket 日志推送（`apps/backend/app/ws/logs.py`）
|
||
- `WS /ws/logs/{execution_id}`：实时推送任务执行日志
|
||
- TaskExecutor 执行时广播日志行到已连接的 WebSocket 客户端
|
||
- _Requirements: 9.1, 9.4_
|
||
|
||
- [x] 6. 检查点 — 确保所有后端 API 测试通过
|
||
- 确保所有测试通过，如有问题请向用户确认。
|
||
|
||
- [x] 7. 前端项目初始化
|
||
- [x] 7.1 在 `apps/admin-web/` 下初始化 React + Vite + TypeScript 项目
|
||
- `pnpm create vite . --template react-ts`
|
||
- 安装核心依赖：`antd`、`@ant-design/icons`、`react-router-dom`、`axios`、`zustand`
|
||
- 配置 `vite.config.ts`：API 代理到后端 `http://localhost:8000`
|
||
- 配置中文 locale（antd ConfigProvider）
|
||
- _Requirements: 10.1, 10.2_
|
||
|
||
- [x] 7.2 实现 API 客户端（`src/api/client.ts`）
|
||
- 创建 axios 实例，baseURL 指向 `/api`
|
||
- 请求拦截器：自动附加 JWT Authorization header
|
||
- 响应拦截器：401 时尝试刷新令牌，刷新失败跳转登录页
|
||
- _Requirements: 1.3, 1.4, 1.5_
|
||
|
||
- [x] 7.3 实现认证状态管理（`src/store/authStore.ts`）和登录页（`src/pages/Login.tsx`）
|
||
- Zustand store：存储 token、user info、site_id
|
||
- 登录页：Ant Design Form，用户名 + 密码
|
||
- 登录成功后存储令牌到 localStorage 并跳转首页
|
||
- _Requirements: 1.1, 1.2_
|
||
|
||
- [x] 7.4 实现主布局（`src/App.tsx`）和路由配置
|
||
- Ant Design Layout：Sider（侧边栏导航）+ Content + Footer（状态栏）
|
||
- react-router-dom：6 个功能页面路由 + 登录页路由
|
||
- 路由守卫：未登录重定向到登录页
|
||
- 侧边栏导航项：任务配置、任务管理、环境配置、数据库、ETL 状态、日志
|
||
- _Requirements: 10.1, 10.2, 10.3_
|
||
|
||
- [x] 8. 前端功能页面 — 任务配置
|
||
- [x] 8.1 实现任务配置页面（`src/pages/TaskConfig.tsx`）
|
||
- Flow 选择器：Radio Group，7 种 Flow，选择后动态显示/隐藏任务区域
|
||
- 处理模式选择器：3 种模式 + 校验附加选项
|
||
- 时间窗口配置：回溯模式（lookback_hours + overlap_seconds）/ 自定义模式（DatePicker）
|
||
- 窗口切分选项：不切分 / 按天（1/10/30）
|
||
- 高级选项折叠面板：dry-run、force-full 等 Checkbox
|
||
- _Requirements: 2.2, 2.3, 2.5_
|
||
|
||
- [x] 8.2 实现 TaskSelector 组件（`src/components/TaskSelector.tsx`）
|
||
- 从 `/api/tasks/registry` 获取任务列表
|
||
- 按业务域分组展示（Collapse + Checkbox Group）
|
||
- 根据当前 Flow 包含的层过滤可见任务
|
||
- 全选/反选功能
|
||
- _Requirements: 2.1, 2.2_
|
||
|
||
- [x] 8.3 实现 DwdTableSelector 组件（`src/components/DwdTableSelector.tsx`）
|
||
- 从 `/api/tasks/dwd-tables` 获取 DWD 表定义
|
||
- 按业务域分组展示（Collapse + Checkbox Group）
|
||
- 仅在 Flow 包含 DWD 层时显示
|
||
- _Requirements: 2.4_
|
||
|
||
- [x] 8.4 实现任务提交和 CLI 命令预览
|
||
- 提交前调用 `/api/tasks/validate` 预览生成的 CLI 命令
|
||
- 提交到队列（`/api/execution/queue`）或直接执行（`/api/execution/run`）
|
||
- 提交成功后跳转到任务管理页面
|
||
- _Requirements: 2.6, 3.1, 4.1_
|
||
|
||
- [x] 8.5 编写 Flow 层级过滤前端单元测试
|
||
- **Property 21: Flow 层级与任务兼容性**
|
||
- 使用 Vitest 测试过滤逻辑函数
|
||
- **Validates: Requirements 2.2**
|
||
|
||
- [x] 9. 前端功能页面 — 任务管理
|
||
- [x] 9.1 实现任务管理页面（`src/pages/TaskManager.tsx`）
|
||
- Ant Design Tabs：队列 + 调度 + 历史
|
||
- 队列 Tab：Table 展示当前队列，支持拖拽排序、删除、取消
|
||
- 历史 Tab：Table 展示执行历史，点击行查看详情和日志
|
||
- _Requirements: 4.1, 4.2, 4.3, 4.4, 4.5_
|
||
|
||
- [x] 9.2 实现调度管理 Tab
|
||
- 调度任务列表 Table：名称、调度描述、启用状态 Switch、下次执行时间、执行次数
|
||
- 创建/编辑调度任务 Modal：任务选择 + 调度配置（类型、间隔、时间等）
|
||
- 删除确认
|
||
- _Requirements: 5.1, 5.3, 5.4, 5.5, 5.6_
|
||
|
||
- [x] 9.3 实现状态栏任务执行指示
|
||
- 在 Layout Footer 或 Sider 底部显示当前执行状态
|
||
- 轮询 `/api/execution/queue` 检查是否有 running 状态的任务
|
||
- 有任务执行时显示 Spin 动画和任务名称
|
||
- _Requirements: 10.3, 10.4_
|
||
|
||
- [x] 10. 前端功能页面 — 辅助模块
|
||
- [x] 10.1 实现环境配置页面（`src/pages/EnvConfig.tsx`）
|
||
- 键值对编辑表格（Ant Design Table，editable cells）
|
||
- 敏感值显示为 `****`，编辑时可输入新值
|
||
- 保存按钮调用 `PUT /api/env-config`
|
||
- 导出按钮调用 `GET /api/env-config/export` 下载文件
|
||
- _Requirements: 6.1, 6.2, 6.3, 6.4_
|
||
|
||
- [x] 10.2 实现数据库查看器页面（`src/pages/DBViewer.tsx`）
|
||
- 左侧 Tree：Schema → Table 层级浏览
|
||
- 右侧上方：SQL 编辑器（Ant Design Input.TextArea 或集成 CodeMirror）
|
||
- 右侧下方：查询结果 Table
|
||
- 选择表时自动展示列定义
|
||
- 执行查询按钮，结果分页展示
|
||
- _Requirements: 7.1, 7.2, 7.3, 7.4_
|
||
|
||
- [x] 10.3 实现 ETL 状态页面（`src/pages/ETLStatus.tsx`）
|
||
- 游标状态 Table：任务编码、最后抓取时间、记录数
|
||
- 最近执行记录 Table：任务名称、状态 Tag、开始时间、执行时长
|
||
- 刷新按钮
|
||
- _Requirements: 8.1, 8.2, 8.3_
|
||
|
||
- [x] 10.4 实现日志查看器页面（`src/pages/LogViewer.tsx`）和 LogStream 组件
|
||
- WebSocket 连接 `/ws/logs/{execution_id}`，实时追加日志行
|
||
- 日志过滤输入框：按关键词过滤显示
|
||
- 自动滚动到底部，可手动暂停滚动
|
||
- 历史日志：从 `/api/execution/{id}/logs` 加载
|
||
- _Requirements: 9.1, 9.2, 9.3, 9.4_
|
||
|
||
- [x] 10.5 编写日志过滤前端单元测试
|
||
- **Property 19: 日志过滤正确性**
|
||
- 使用 Vitest 测试过滤函数
|
||
- **Validates: Requirements 9.2**
|
||
|
||
- [x] 11. 门店隔离集成验证
|
||
- [x] 11.1 编写门店隔离属性测试
|
||
- **Property 20: 门店隔离 — 队列和调度数据不跨站泄露**
|
||
- 使用 pytest + hypothesis 生成随机 site_id 对，验证数据隔离
|
||
- **Validates: Requirements 1.3**
|
||
|
||
- [x] 11.2 编写任务注册表分组属性测试
|
||
- **Property 4: 任务注册表按业务域正确分组**
|
||
- **Validates: Requirements 2.1**
|
||
|
||
- [x] 12. 最终检查点 — 确保所有测试通过 ✅
|
||
- 后端 302 passed / 0 failed，前端 33 passed / 0 failed，全部通过。
|
||
|
||
## 说明
|
||
|
||
- 标记 `*` 的子任务为可选测试任务，可跳过以加速 MVP
|
||
- 每个任务引用了具体的需求编号，确保可追溯
|
||
- 检查点用于阶段性验证，确保增量正确
|
||
- 属性测试验证通用正确性属性，单元测试覆盖具体示例和边界条件
|