Neo-ZQYY/docs/specs/admin-web-restructure/tasks.md

实施计划：admin-web 后台重构优化

概述

按"后端 API → 前端页面 → 联调收尾"的顺序实施。后端新增 3 个 API 端点，前端重组菜单和路由、新建 4 个页面组件，最后归档老页面并补充 E2E 测试。每个阶段结束后插入检查点。

任务

• 1. 后端：新增 Pydantic 模型与工具函数

  • 1.1 创建 UpdateTriggerConfigRequest、DbHealthItem、UnifiedTriggerItem 三个 Pydantic 模型

    • 在 apps/backend/app/schemas/ 下新建或扩展 schema 文件
    • UpdateTriggerConfigRequest 包含 model_validator 确保至少提供一个字段
    • DbHealthItem.status 使用 Literal['connected', 'disconnected']
    • UnifiedTriggerItem.source 使用 Literal['biz', 'ai', 'etl']
    • Requirements: 5.1, 5.2, 5.3, 6.1, 6.2, 4.1, 4.2

  • 1.2 实现 cron 表达式校验工具函数 validate_cron_expression

    • 在 apps/backend/app/utils/ 下新建 cron_validator.py
    • 校验 5 字段 cron 语法，支持 * 和数值范围
    • Requirements: 5.4

  • 1.3 编写属性测试：cron 表达式校验拒绝无效输入

    • Property 6: 触发器配置校验拒绝无效输入
    • 使用 hypothesis 生成任意非 5 字段字符串、超范围数值字段
    • 验证 validate_cron_expression 对无效输入返回 False
    • 验证: 需求 5.4, 5.5

  • 1.4 编写单元测试：cron 校验与 Pydantic 模型

    • 测试有效 cron 表达式通过校验
    • 测试无效格式（字段数不对、超范围值）被拒绝
    • 测试 UpdateTriggerConfigRequest 空请求体触发 ValidationError
    • 测试 DbHealthItem disconnected 状态下指标字段可为 null
    • Requirements: 5.4, 5.5, 6.3

• 2. 后端：实现 PATCH /api/trigger-jobs/{id}/config 端点

  • 2.1 在 apps/backend/app/routers/trigger_jobs.py 新增 PATCH 端点

    • 查询 trigger_job 是否存在（不存在返回 404）
    • 校验 cron_expression 格式（无效返回 422）
    • 校验 interval_seconds >= 1（无效返回 422）
    • 更新 trigger_config JSON 中对应字段
    • 重新计算 next_run_at
    • 返回更新后的完整 trigger_job
    • JWT 认证与现有端点一致
    • Requirements: 5.1, 5.2, 5.3, 5.4, 5.5, 5.6, 5.7

  • 2.2 编写属性测试：触发器配置编辑不变量

    • Property 4: 触发器配置编辑不变量
    • 使用 hypothesis 生成有效的 cron_expression 和 interval_seconds
    • 验证更新后 trigger_job 中除 trigger_config 和 next_run_at 外的字段不变
    • 验证: 需求 4.7

  • 2.3 编写属性测试：触发器配置更新正确性

    • Property 5: 触发器配置更新正确性
    • 使用 hypothesis 生成有效的 cron_expression（5 字段格式）和 interval_seconds（>= 1）
    • 验证返回的 trigger_config 对应字段值等于请求值，且 next_run_at 非 null
    • 验证: 需求 5.2, 5.3, 5.7

  • 2.4 编写单元测试：PATCH 端点边界条件

    • 测试不存在的 job_id 返回 404
    • 测试空请求体返回 422
    • 测试无 JWT 返回 401
    • Requirements: 5.1, 5.4, 5.5, 5.6

• 3. 后端：实现 GET /api/admin/db-health 端点

  • 3.1 新建 apps/backend/app/routers/admin_db_health.py 路由模块

    • 遍历 4 个数据库 DSN 配置（etl_feiqiu / test_etl_feiqiu / zqyy_app / test_zqyy_app）
    • 对每个库执行诊断 SQL：pg_stat_activity（连接池）、pg_database_size()（大小）、慢查询统计
    • 连接失败时返回 status: "disconnected"，其余字段为 null
    • JWT 认证
    • 在 apps/backend/app/main.py 中注册路由
    • Requirements: 6.1, 6.2, 6.3, 6.4

  • 3.2 编写属性测试：DB 健康 API 已连接数据库返回完整指标

    • Property 1: DB 健康 API 已连接数据库返回完整指标
    • 使用 hypothesis 生成 connected 状态的 DbHealthItem
    • 验证 active_connections、idle_connections、db_size_mb、slow_query_count 均非 null 且类型正确
    • 验证: 需求 2.4, 6.2

  • 3.3 编写单元测试：DB 健康端点

    • 测试正常连接返回 connected 状态和完整指标
    • 测试连接失败返回 disconnected 状态和 null 指标
    • 测试所有库连接失败仍返回 HTTP 200
    • 测试无 JWT 返回 401
    • Requirements: 6.1, 6.2, 6.3, 6.4

• 4. 后端：实现 GET /api/admin/triggers/unified 端点

  • 4.1 新建 apps/backend/app/routers/admin_triggers.py 路由模块

    • 查询 biz.trigger_jobs，映射 source="biz"
    • 查询 biz.ai_trigger_jobs（最近 100 条），映射 source="ai"
    • 查询 scheduled_tasks，映射 source="etl"
    • 统一字段格式后合并返回
    • 某数据源查询失败时记录日志，返回其他数据源数据
    • JWT 认证
    • 在 apps/backend/app/main.py 中注册路由
    • Requirements: 4.1, 4.2, 4.3

  • 4.2 编写属性测试：触发器统一视图数据完整性

    • Property 3: 触发器统一视图数据完整性与字段完整性
    • 使用 hypothesis 生成三个数据源的触发器列表
    • 验证合并后记录总数等于三个数据源之和，且每条记录包含所有必需字段
    • 验证: 需求 4.1, 4.2

  • 4.3 编写单元测试：统一触发器端点

    • 测试正常返回包含三种 source 的数据
    • 测试某数据源失败时仍返回其他数据源数据
    • 测试无 JWT 返回 401
    • Requirements: 4.1, 4.2, 4.3

• 5. 检查点 — 后端 API 验证

  • 运行后端测试：cd apps/backend && pytest tests/ -v
  • 确保 3 个新端点的所有属性测试（Property 1, 3, 4, 5, 6）和单元测试全部通过
  • 确保现有端点测试无回归
  • ask the user if questions arise.

• 6. 前端：新增 API 模块与 TypeScript 类型

  • 6.1 创建前端 API 模块和类型定义
    • 新建 src/api/dbHealth.ts：DbHealthItem 接口 + fetchDbHealth() 函数
    • 新建 src/api/triggers.ts：UnifiedTriggerItem 接口 + fetchUnifiedTriggers() 函数
    • 扩展 src/api/triggerJobs.ts：UpdateTriggerConfigReq 接口 + updateTriggerConfig() 函数
    • Requirements: 4.1, 5.1, 6.1

• 7. 前端：侧边栏菜单重组与路由重构

  • 7.1 重构 App.tsx 路由与菜单配置

    • NAV_ITEMS 从 11 个一级项重组为 7 个：运行状态、ETL 任务管理、小程序任务管理、触发器管理、租户管理员、系统设置、日志调试
    • 更新 Routes 为新路由结构
    • 添加 / → /dashboard 重定向
    • 添加 /log-viewer → /etl-tasks?tab=manager 重定向
    • 登录成功后导航到 /dashboard
    • 侧边栏高亮当前所在模块对应的菜单项
    • Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 8.1, 8.2, 8.3, 10.1, 10.2, 10.3

  • 7.2 编写属性测试：侧边栏高亮与当前路由一致

    • Property 7: 侧边栏高亮与当前路由一致
    • 使用 fast-check 生成所有有效路由路径
    • 验证 selectedKeys 对应该路由所属的一级模块
    • 验证: 需求 10.3

  • 7.3 编写单元测试：菜单结构与路由重定向

    • 测试菜单包含 7 个一级项且子项正确
    • 测试 / 重定向到 /dashboard
    • 测试 /log-viewer 重定向到 /etl-tasks?tab=manager
    • Requirements: 1.1, 8.3, 10.1, 10.2

• 8. 前端：实现 Dashboard 运行状态仪表盘

  • 8.1 拆分 OpsPanel 为可独立使用的子组件

    • 从 OpsPanel.tsx 提取 ServiceStatusSection、GitStatusSection、SystemResourceSection
    • 保持原 OpsPanel 页面功能不变（内部改为组合子组件）
    • Requirements: 2.6

  • 8.2 创建 DbHealthCard 组件

    • 新建 src/components/DbHealthCard.tsx
    • 接收 DbHealthItem[] 数据，为每个数据库渲染卡片
    • 展示连接池状态（活跃/空闲，进度条）、数据库大小、慢查询数量
    • 连接失败时显示"未连接"状态标签
    • 加载超时时展示"加载超时"状态 + 重试按钮
    • Requirements: 2.3, 2.4, 2.5

  • 8.3 创建 Dashboard 页面

    • 新建 src/pages/Dashboard.tsx
    • 聚合 4 个区块：OpsPanel 子组件、DbHealthCard、AIDashboard 子模块、AI 调度摘要
    • AI 调度摘要展示今日触发数、成功率、最近错误
    • 跳转链接："ETL 状态详情" → /etl-tasks?tab=status、"触发器详情" → /triggers?tab=all、"AI 调度详情" → /triggers?tab=ai
    • Requirements: 2.1, 2.2, 2.6, 2.7, 2.8, 7.1, 7.2

  • 8.4 编写单元测试：Dashboard 页面

    • 测试 4 个区块正确渲染
    • 测试跳转链接指向正确路由
    • 测试 DbHealthCard connected/disconnected 状态渲染
    • Requirements: 2.1, 2.2, 2.3, 2.4, 2.5

• 9. 前端：实现 ETLTasks 页面（Tab 合并）

  • 9.1 创建 ETLTasks 页面

    • 新建 src/pages/ETLTasks.tsx
    • 使用 Ant Design Tabs 组件，3 个 Tab：config（任务配置）、manager（任务管理）、status（ETL 状态）
    • 各 Tab 渲染对应的现有组件：<TaskConfig />、<TaskManager />、<ETLStatus />
    • Tab 切换通过 useSearchParams 同步 URL 查询参数 ?tab=config|manager|status
    • destroyInactiveTabPane={false} 保持 Tab 状态不丢失
    • Requirements: 3.1, 3.2, 3.3, 3.4, 3.5, 10.4

  • 9.2 编写属性测试：Tab 切换与 URL 查询参数同步

    • Property 8: Tab 切换与 URL 查询参数同步 round-trip
    • 使用 fast-check 生成有效 tab 值（config / manager / status / all / biz / ai / etl）
    • 验证设置 ?tab=X 后激活的 Tab 为 X；点击 Tab Y 后 URL 参数更新为 ?tab=Y
    • 验证: 需求 10.4

  • 9.3 编写属性测试：Tab 切换状态保持

    • Property 2: Tab 切换状态保持 round-trip
    • 使用 fast-check 模拟在某 Tab 设置筛选条件 → 切换到另一 Tab → 切回
    • 验证原 Tab 筛选条件保持不变
    • 验证: 需求 3.5

  • 9.4 编写单元测试：ETLTasks 页面

    • 测试默认 Tab 为 config
    • 测试 3 个 Tab 内容正确渲染
    • 测试 URL 参数驱动 Tab 选择
    • Requirements: 3.1, 3.2, 3.3, 3.4, 10.4

• 10. 前端：实现 TriggerManager 触发器统一管理页面

  • 10.1 创建 TriggerManager 页面

    • 新建 src/pages/TriggerManager.tsx
    • 4 个 Tab：all（全部，只读统一视图）、biz（业务）、ai（AI）、etl（ETL）
    • "全部"Tab 调用 fetchUnifiedTriggers()，展示统一字段表格（名称、类型标签、触发条件、状态、上次/下次执行、最近错误）
    • "业务"Tab 复用现有 TriggerJobs 组件 + 新增编辑功能（调用 updateTriggerConfig）
    • "AI"Tab 复用现有 AIOperations + AITriggerJobs 组件
    • "ETL"Tab 展示 scheduled_tasks 数据
    • 编辑功能仅允许修改 cron_expression 和 interval_seconds
    • Tab 切换通过 useSearchParams 同步 URL 参数
    • destroyInactiveTabPane={false} 保持状态
    • Requirements: 4.1, 4.2, 4.3, 4.4, 4.5, 4.6, 4.7, 4.8, 7.3, 7.5, 10.4

  • 10.2 编写单元测试：TriggerManager 页面

    • 测试 4 个 Tab 正确渲染
    • 测试"全部"Tab 为只读（无编辑按钮）
    • 测试"业务"Tab 编辑表单仅包含 cron_expression 和 interval_seconds
    • 测试 422 错误在表单中展示具体错误信息
    • Requirements: 4.1, 4.3, 4.4, 4.7

• 11. 前端：菜单子项路由调整与页面移动

  • 11.1 调整"小程序任务管理"菜单

    • 将原"任务引擎"菜单改名为"小程序任务管理"
    • 保留 4 个子项路由不变：定时任务、转移日志、待审核任务、参数管理
    • Requirements: 1.4

  • 11.2 调整"系统设置"菜单

    • 将环境配置页面路由移至 /settings/env-config
    • 添加触发器配置跳转入口（跳转到 /triggers?tab=biz）
    • Requirements: 1.6

  • 11.3 调整"日志调试"菜单

    • DevTrace（全链路日志）路由移至 /logs/dev-trace
    • AI 调用明细（原 AIRunLogs）路由移至 /logs/ai-run-logs
    • 数据库查看器路由移至 /logs/db-viewer
    • Requirements: 1.7, 7.4

  • 11.4 废弃 LogViewer 页面

    • 从侧边栏菜单移除 LogViewer 入口
    • 从路由配置移除 /log-viewer 路由（已在 7.1 中添加重定向）
    • 将 LogViewer.tsx 移入 _archived/ 目录
    • Requirements: 8.1, 8.2, 8.3, 8.4

• 12. 检查点 — 前端页面验证

  • 运行前端测试：cd apps/admin-web && npx vitest --run
  • 确保所有属性测试（Property 2, 7, 8）和单元测试全部通过
  • 确保 TypeScript 编译无错误
  • ask the user if questions arise.

• 13. E2E 测试

  • 13.1 编写 Dashboard E2E 测试

    • 新建 e2e/dashboard.spec.ts
    • 测试页面渲染、4 个区块存在、跳转链接正确
    • Requirements: 2.1, 2.2, 9.4

  • 13.2 编写 ETL 任务管理 E2E 测试

    • 新建 e2e/etl-tasks.spec.ts
    • 测试 Tab 切换、各 Tab 内容渲染
    • Requirements: 3.1, 3.2, 3.3, 3.4, 9.4

  • 13.3 编写触发器管理 E2E 测试

    • 新建 e2e/trigger-manager.spec.ts
    • 测试 4 个 Tab、统一视图数据、业务 Tab 编辑功能
    • Requirements: 4.1, 4.3, 4.4, 4.7, 9.4

  • 13.4 编写导航与路由 E2E 测试

    • 新建 e2e/navigation.spec.ts
    • 测试默认路由 / → /dashboard、/log-viewer 重定向、菜单高亮、Tab-URL 同步
    • Requirements: 8.3, 9.4, 10.1, 10.2, 10.3, 10.4

• 14. 归档老页面

  • 14.1 E2E 测试通过后归档老页面
    • 将被替代的老页面源文件（OpsPanel、TaskConfig、TaskManager、ETLStatus、AIDashboard、AITriggerJobs、AIOperations、LogViewer 等独立页面入口）移入 _archived/ 目录
    • 从侧边栏菜单移除对应的老菜单项
    • 保留被复用的子组件（如 OpsPanel 拆分后的子组件、AIDashboard 子模块）
    • 注：LogViewer 已在 11.4 归档；其余老页面（OpsPanel、TaskConfig、TaskManager、ETLStatus、AIDashboard、AITriggerJobs、AIOperations）仍被新页面作为子组件复用，暂不移动
    • Requirements: 9.1, 9.2, 9.3

• 15. 检查点 — E2E 与归档验证

  • 运行 E2E 测试：cd apps/admin-web && npx playwright test
  • 确保所有 E2E 测试通过
  • 确保归档后的页面不再出现在菜单中
  • 确保 /log-viewer 正确重定向
  • 注：E2E 测试需手动运行（需启动 dev server + 浏览器），LogViewer 已归档且重定向已配置
  • ask the user if questions arise.

• 16. 前后端联调与集成验证

  • 16.1 启动后端服务，验证 3 个新端点完整请求-响应链路
    • 使用测试库验证 SQL 查询正确性
    • 验证 JSON 响应结构与 Schema 定义一致
    • 验证 JWT 认证在真实请求中生效
    • 注：后端 API 已通过 pytest 单元测试和属性测试验证，真实联调需手动启动服务
    • Requirements: 5.1, 5.6, 6.1, 6.4, 11.4
  • 16.2 前端联调验证
    • 确认 Dashboard 页面能正确调用 db-health API 并渲染数据
    • 确认触发器管理页面能正确调用 unified triggers API 并渲染数据
    • 确认业务 Tab 编辑功能能正确调用 PATCH API
    • 验证空数据/降级场景下前端不崩溃
    • 注：E2E 测试已覆盖 mock API 场景，真实联调需手动启动前后端服务
    • Requirements: 2.1, 2.3, 4.1, 4.4, 11.1

• 17. 最终检查点 — 全量验证

  • 运行 Monorepo 属性测试：cd C:\Project\NeoZQYY && pytest tests/ -v
  • 运行后端测试：cd apps/backend && pytest tests/ -v
  • 运行前端测试：cd apps/admin-web && npx vitest --run
  • 运行 E2E 测试：cd apps/admin-web && npx playwright test
  • 确保所有属性测试（Property 1-8）和单元测试全部通过
  • 确保前端页面连接真实后端运行正常
  • ask the user if questions arise.

• 18. 文档同步更新

  • 18.1 更新后端 API 参考文档
    • 在 apps/backend/docs/API-REFERENCE.md 新增 3 个端点文档
    • 更新 apps/backend/README.md 路由模块摘要
    • Requirements: 11.1, 11.5
  • 18.2 更新文档地图
    • 在 docs/DOCUMENTATION-MAP.md 新增本次模块条目
    • Requirements: 11.1

备注

• 标记 * 的子任务为可选（属性测试/单元测试），可跳过以加速 MVP
• 每个任务引用了具体的需求编号以确保可追溯性
• 属性测试验证通用正确性属性（Property 1-8），单元测试验证具体边界条件
• 检查点任务确保增量验证，避免问题累积
• 本项目不涉及数据库 DDL 变更，无需 DB 变更审计和 BD 手册步骤
• E2E 测试按页面切割为 4 个文件，每个文件控制在 Playwright 默认超时（30s）范围内
• 后端使用 Python（FastAPI + pytest + hypothesis），前端使用 TypeScript（React + Vitest + fast-check）