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/requirements.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

12 KiB
Raw Blame History

需求文档：admin-web 后台重构优化

简介

将现有 admin-web 系统管理后台从 18 个页面 / 11 个一级菜单重组为 7 个一级菜单模块，新增运行状态仪表盘、触发器统一管理、数据库健康监控等功能，废弃 LogViewer 页面，采用新老页面交替开发策略，逐步完成迁移。

术语表

  • Admin_Web：系统管理后台前端应用，位于 apps/admin-web/，面向开发者和运维人员
  • Dashboard：运行状态仪表盘，重组后的默认首页，聚合系统运行状况
  • ETL_Task_Module：ETL 任务管理模块，合并原 TaskConfig、TaskManager、ETLStatus 三个页面为 Tab 视图
  • MiniApp_Task_Module：小程序任务管理模块，原"任务引擎"改名，包含定时任务、转移日志、待审核任务、参数管理
  • Trigger_Module：触发器管理模块，统一展示和管理三套触发器数据源
  • Trigger_Unified_View：触发器统一视图，在"全部"Tab 中聚合 biz.trigger_jobs、biz.ai_trigger_jobs、scheduled_tasks 三张表的数据
  • DB_Health_Monitor：数据库健康监控组件，检测 4 个数据库（etl_feiqiu / test_etl_feiqiu / zqyy_app / test_zqyy_app）的连接池、大小、慢查询
  • Archived_Page：已归档页面，测试通过后移入 _archived/ 目录且菜单不再显示的旧页面
  • Trigger_Config_PATCH_API：新增的后端 PATCH 接口，用于编辑 trigger_config 中的 cron_expression 和 interval_seconds
  • E2E_Test：端到端测试，使用 Playwright 编写，每个新页面必须配套

需求

需求 1：侧边栏菜单重组

用户故事： 作为开发者/运维人员，我希望侧边栏菜单从 11 个一级项重组为 7 个一级项，以便更高效地导航和管理后台功能。

验收标准

  1. THE Admin_Web SHALL 将侧边栏菜单重组为以下 7 个一级菜单项：运行状态、ETL 任务管理、小程序任务管理、触发器管理、租户管理员、系统设置、日志调试
  2. THE Admin_Web SHALL 将"运行状态"菜单项设置为侧边栏第一项，并作为登录后的默认路由
  3. THE Admin_Web SHALL 在"ETL 任务管理"菜单下提供 3 个 Tab：任务配置、任务管理、ETL 状态
  4. THE Admin_Web SHALL 将原"任务引擎"菜单改名为"小程序任务管理"，保留 4 个子项：定时任务、转移日志、待审核任务、参数管理
  5. THE Admin_Web SHALL 在"触发器管理"菜单下提供 4 个 Tab：全部、业务、AI、ETL
  6. THE Admin_Web SHALL 在"系统设置"菜单下包含环境配置页面和触发器配置跳转入口
  7. THE Admin_Web SHALL 在"日志调试"菜单下包含 3 个子项：DevTrace（全链路日志）、AI 调用明细、数据库查看器
  8. THE Admin_Web SHALL 保持"租户管理员"作为独立一级菜单，功能不变
  9. WHEN 用户登录成功后，THE Admin_Web SHALL 自动导航到运行状态（仪表盘）页面

需求 2：运行状态仪表盘

用户故事： 作为开发者/运维人员，我希望登录后看到一个聚合仪表盘，以便一目了然地掌握系统整体运行状况。

验收标准

  1. THE Dashboard SHALL 聚合展示以下内容区块：OpsPanel 运维面板内容、数据库健康监控、AI Dashboard 内容、AI 调度状态摘要
  2. THE Dashboard SHALL 提供跳转链接，点击后分别导航到 ETL 任务管理的"ETL 状态"Tab 和触发器管理的"触发器状态"Tab
  3. THE DB_Health_Monitor SHALL 检测以下 4 个数据库的健康状态：etl_feiqiu、test_etl_feiqiu、zqyy_app、test_zqyy_app
  4. THE DB_Health_Monitor SHALL 展示每个数据库的连接池状态、数据库大小、慢查询信息
  5. IF 某个数据库不存在或无法连接，THEN THE DB_Health_Monitor SHALL 将该数据库标记为"未连接"状态，而非抛出错误
  6. THE Dashboard SHALL 复用原 OpsPanel 组件的服务状态、Git 状态、系统资源等内容
  7. THE Dashboard SHALL 复用原 AIDashboard 组件的统计卡片、趋势图、预算进度等内容
  8. THE Dashboard SHALL 展示 AI 调度状态的摘要信息（今日触发数、成功率、最近错误）

需求 3：ETL 任务管理模块

用户故事： 作为开发者/运维人员，我希望将 ETL 相关的三个页面合并为一个 Tab 视图，以便在同一页面内切换任务配置、任务管理和 ETL 状态。

验收标准

  1. THE ETL_Task_Module SHALL 将原 TaskConfig、TaskManager、ETLStatus 三个页面合并为同一路由下的 3 个 Tab
  2. THE ETL_Task_Module SHALL 将"任务配置"Tab 的功能与原 TaskConfig 页面保持一致，包括 Flow 选择、任务勾选、参数设置、CLI 预览、执行/入队
  3. THE ETL_Task_Module SHALL 将"任务管理"Tab 的功能与原 TaskManager 页面保持一致，包括队列管理、执行历史、实时日志流
  4. THE ETL_Task_Module SHALL 将"ETL 状态"Tab 的功能与原 ETLStatus 页面保持一致，包括数据游标监控和最近执行记录
  5. WHEN 用户切换 Tab 时，THE ETL_Task_Module SHALL 保持各 Tab 的状态不丢失（如筛选条件、滚动位置）

需求 4：触发器统一管理模块

用户故事： 作为开发者/运维人员，我希望在一个统一视图中查看所有触发器的运行状态，以便快速定位调度问题。

验收标准

  1. THE Trigger_Unified_View SHALL 在"全部"Tab 中聚合展示来自三个数据源的触发器：biz.trigger_jobs（业务触发器）、biz.ai_trigger_jobs（AI 事件链）、scheduled_tasks（ETL 调度）
  2. THE Trigger_Unified_View SHALL 为每个触发器展示以下统一字段：名称、类型标签（业务/AI/ETL）、触发条件、状态（运行中/空闲/错误/禁用）、上次执行时间、下次执行时间、最近错误
  3. THE Trigger_Unified_View SHALL 在"全部"Tab 中仅提供只读查看，不提供编辑功能
  4. THE Trigger_Module SHALL 在"业务"Tab 中展示 biz.trigger_jobs 的 4 个业务触发器，并支持编辑 trigger_config 中的 cron_expression 和 interval_seconds
  5. THE Trigger_Module SHALL 在"AI"Tab 中展示 biz.ai_trigger_jobs 的 AI 事件链触发器，并提供 AI 手动操作功能（重跑、缓存失效、批量执行、告警管理）
  6. THE Trigger_Module SHALL 在"ETL"Tab 中展示 scheduled_tasks 的 ETL 调度任务
  7. WHEN 用户在"业务"Tab 中编辑触发器配置时，THE Trigger_Module SHALL 仅允许修改 cron_expression 和 interval_seconds 两个字段
  8. THE Trigger_Module SHALL 不提供编辑历史记录功能

需求 5：触发器配置编辑后端 API

用户故事： 作为开发者/运维人员，我希望通过管理后台直接编辑触发器的 cron 表达式和间隔秒数，以便无需直接操作数据库即可调整调度策略。

验收标准

  1. THE Trigger_Config_PATCH_API SHALL 提供 PATCH /api/trigger-jobs/{id}/config 端点，接受 cron_expression 和 interval_seconds 的部分更新
  2. WHEN 请求体包含 cron_expression 字段时，THE Trigger_Config_PATCH_API SHALL 更新 trigger_config JSON 中的 cron_expression 值，并重新计算 next_run_at
  3. WHEN 请求体包含 interval_seconds 字段时，THE Trigger_Config_PATCH_API SHALL 更新 trigger_config JSON 中的 interval_seconds 值，并重新计算 next_run_at
  4. IF cron_expression 格式不符合 5 字段 cron 语法，THEN THE Trigger_Config_PATCH_API SHALL 返回 HTTP 422 错误及描述性错误信息
  5. IF interval_seconds 小于 1，THEN THE Trigger_Config_PATCH_API SHALL 返回 HTTP 422 错误及描述性错误信息
  6. THE Trigger_Config_PATCH_API SHALL 要求 JWT 认证，与现有 trigger-jobs 端点保持一致的鉴权策略
  7. WHEN 更新成功时，THE Trigger_Config_PATCH_API SHALL 返回更新后的完整 trigger_job 信息

需求 6：数据库健康监控后端 API

用户故事： 作为开发者/运维人员，我希望仪表盘能实时展示数据库健康状态，以便及时发现连接池耗尽或慢查询等问题。

验收标准

  1. THE Admin_Web SHALL 提供 GET /api/admin/db-health 端点，返回 4 个数据库的健康状态
  2. THE Admin_Web SHALL 为每个数据库返回以下指标：连接池活跃连接数、连接池空闲连接数、数据库大小（MB）、慢查询数量（最近 1 小时内执行时间超过 1 秒的查询）
  3. IF 某个数据库无法连接，THEN THE Admin_Web SHALL 返回该数据库的状态为 "disconnected"，其余指标为 null，而非返回 HTTP 错误
  4. THE Admin_Web SHALL 要求 JWT 认证访问数据库健康端点

需求 7：AI 内容拆分重组

用户故事： 作为开发者/运维人员，我希望 AI 相关功能按使用场景分散到对应模块中，以便在合适的上下文中使用 AI 功能。

验收标准

  1. THE Dashboard SHALL 包含原 AIDashboard 页面的运行总览内容（统计卡片、趋势图、饼图、预算进度、告警列表）
  2. THE Dashboard SHALL 包含原 AITriggerJobs 页面的调度状态摘要信息
  3. THE Trigger_Module SHALL 在"AI"Tab 中包含原 AIOperations 页面的手动操作功能（重跑、缓存失效、批量执行、告警管理）
  4. THE Admin_Web SHALL 将原 AIRunLogs 页面（AI 调用明细）移入"日志调试"模块下
  5. WHEN 用户从仪表盘的 AI 调度状态摘要点击"查看详情"时，THE Admin_Web SHALL 导航到触发器管理的"AI"Tab

需求 8：LogViewer 废弃

用户故事： 作为开发者/运维人员，我不再需要独立的 LogViewer 页面，因为 ETL 任务管理模块已提供实时日志功能。

验收标准

  1. THE Admin_Web SHALL 从侧边栏菜单中移除 LogViewer（/log-viewer）入口
  2. THE Admin_Web SHALL 从路由配置中移除 /log-viewer 路由
  3. WHEN 用户直接访问 /log-viewer 路径时，THE Admin_Web SHALL 重定向到 ETL 任务管理页面
  4. THE Admin_Web SHALL 将 LogViewer.tsx 源文件移入 _archived/ 目录

需求 9：新老页面交替开发策略

用户故事： 作为开发者，我希望采用渐进式迁移策略，以便在不影响现有功能的前提下逐步完成重构。

验收标准

  1. THE Admin_Web SHALL 使用目标路由开发新页面，不修改老页面的路由和功能
  2. WHEN 新页面的 E2E 测试全部通过后，THE Admin_Web SHALL 将对应的老页面源文件移入 _archived/ 目录
  3. THE Admin_Web SHALL 在老页面移入 _archived/ 后，从侧边栏菜单中移除对应的老菜单项
  4. THE Admin_Web SHALL 为每个新页面编写 Playwright E2E 测试，测试内容包含页面渲染验证和数据库查询校验数据正确性
  5. THE Admin_Web SHALL 将 E2E 测试按合理批次切割，每个测试文件的执行时间控制在 Playwright 默认超时范围内

需求 10：默认路由与导航

用户故事： 作为开发者/运维人员，我希望登录后直接看到系统运行状态，以便第一时间了解系统健康状况。

验收标准

  1. WHEN 用户登录成功后，THE Admin_Web SHALL 将默认路由从 "/" (TaskConfig) 变更为 "/dashboard"（运行状态仪表盘）
  2. WHEN 用户访问根路径 "/" 时，THE Admin_Web SHALL 重定向到 "/dashboard"
  3. THE Admin_Web SHALL 在侧边栏中高亮当前所在模块对应的菜单项
  4. WHEN 用户在 Tab 视图内切换 Tab 时，THE Admin_Web SHALL 更新 URL 查询参数以反映当前 Tab，支持浏览器前进/后退导航

需求 11：明确排除范围

用户故事： 作为开发者，我需要明确本次重构的边界，以便聚焦于前端重组工作。

验收标准

  1. THE Admin_Web SHALL 不修改后端业务逻辑（除新增 PATCH API 和数据库健康 API 外）
  2. THE Admin_Web SHALL 不修改 tenant-admin 租户管理后台的任何功能
  3. THE Admin_Web SHALL 不修改小程序端的任何功能
  4. THE Admin_Web SHALL 不变更现有权限模型（JWT 认证方式和角色体系保持不变）
  5. THE Admin_Web SHALL 保持所有现有 API 接口的向后兼容性
Reference in New Issue View Git Blame Copy Permalink