# 需求文档：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 接口的向后兼容性