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

162 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 需求文档：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