root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
70324d8542aa9bfcb96f67dc949ad31a20abbe09
Neo-ZQYY/docs/specs/admin-web-restructure/tasks.md
Neo 70324d8542 chore: 文档与 IDE 配置整理 
- .kiro/specs/ → docs/specs/（41 个历史需求 spec 迁移，移除 .config.kiro）
- CLAUDE.md 三层拆分：根文件精简 + apps/backend/CLAUDE.md + .claude/commands/
- 新增 /spec-close、/pre-change 两个工作流命令
- DDL 基线刷新（从测试库重新导出 11 个文件，dws 35→38 表，biz 18→21 表）
- BD_Manual → BD_manual 命名统一（48 个文件）
- 修复 3 处文档与数据库不一致（auth.users.status 默认值、scheduled_tasks 字段、RLS 视图数）
- 新增 BD_manual_public_rbac_tables.md（public schema 8 张 RBAC/工作流表）
- 合并 biz.trigger_jobs 文档（10→12 字段，归档独立文档）
- docs/database/README.md 索引更新

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-06 00:02:37 +08:00

17 KiB
Raw Blame History

实施计划：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:\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）
Reference in New Issue View Git Blame Copy Permalink