Neo-ZQYY/docs/specs/ai-monitoring-testing/requirements.md

# 需求文档 — P15：AI 监控后台 + 测试重建 + 回填

## 简介

P14 完成 DashScope SDK 迁移和调度器修复后，本 Spec 覆盖三个方面：
1. admin-web AI 监控后台（4 个页面：运行总览 Dashboard、调度状态、调用明细、手动操作）
2. 测试体系重建（旧脚本归档、新全链路测试 15 个场景、属性测试更新 7 个）
3. 历史数据回填（半年内活跃会员 <100 人，分批执行 + 断点续跑）

**实施过程中如遇细节不明确，应优先查阅 PRD 原文 `docs/prd/specs/P15-ai-monitoring-testing.md`**

### 问题覆盖

本 Spec 覆盖 `docs/reports/2026-03-21__ai_module_issues.md` 中的：
- P2-1：App5 话术缺分类（回填时验证 App5 输出包含分类字段）
- P2-2：MCP 无健康检查（admin-web Dashboard 展示各 App 最近调用状态）
- P2-4：全链路测试不完整（§3.2 新全链路测试）
- P3-3：Prompt 版本管理（仅监控展示部分，只读）

### 依赖

- P14（DashScope 迁移 + 调度器完善）— `P14-ai-dashscope-migration` spec 必须全部完成并验证通过

### 来源文档（权威参考）

- `docs/prd/specs/P15-ai-monitoring-testing.md` — PRD 主文档
- `docs/reports/2026-03-21__ai_module_issues.md` — 问题清单
- `docs/database/BD_Manual_ai_tables.md` — AI 表 BD 手册

### 不在本 spec 范围

- 多门店支持（BACKLOG）
- 消息队列（单独 PRD）
- Prompt 版本管理的编辑功能（BACKLOG，本轮仅展示）
- 前端刷新机制（P1-5）
- FDW 数据一致性（P1-6）
- 企业微信/邮件告警推送（后续迭代）

## 术语表

- **admin-web**：系统管理后台（`apps/admin-web/`），面向系统管理员，React + Vite + Ant Design
- **Backend**：FastAPI 后端应用，位于 `apps/backend/`
- **Admin_AI_Service**：新增的 admin AI 聚合服务（`apps/backend/app/services/ai/admin_service.py`），负责聚合查询、批量操作、告警管理
- **Admin_AI_Router**：新增的 admin AI 路由文件（`apps/backend/app/routers/admin_ai.py`），注册 13 个 API 端点
- **Dashboard**：AI 运行总览页面，展示统计卡片、趋势图、App 分布、Token 预算、告警列表
- **ai_run_logs**：AI 运行记录表（P14 已创建），记录每次 DashScope API 调用的详细日志
- **ai_trigger_jobs**：调度运行记录表（P14 已创建），记录事件触发的调用链执行状态
- **ai_cache**：AI 应用缓存表，各应用的结构化输出结果
- **App1~App8**：8 个百炼智能体应用（App1 通用对话、App2 财务洞察、App3 维客线索、App4 关系分析、App5 话术参考、App6 备注分析、App7 客户分析、App8 维客线索整理）
- **Backfill_Script**：历史数据回填脚本（`scripts/ops/ai_backfill.py`）
- **Circuit_Breaker**：熔断器，按 app_id 独立计数（P14 已实现）
- **Dispatcher**：AI 事件调度与调用链编排器（P14 已实现）
- **member_retention_clue**：会员留存线索业务表，App8 写入目标

## 需求

### 模块 A：admin-web AI 监控后台 — 后端 API

#### 需求 A1：Dashboard 总览统计 API

**用户故事：** 作为系统管理员，我希望通过 Dashboard API 获取 AI 运行总览数据，以便在一个页面内掌握今日调用次数、成功率、Token 消耗、平均延迟和近 7 天趋势。

##### 验收标准

1. THE Backend SHALL 实现 `GET /api/admin/ai/dashboard` 端点，返回以下聚合数据：今日调用次数、今日成功率、今日 Token 消耗总量、今日平均延迟（ms）
2. THE Backend SHALL 在 Dashboard 响应中包含近 7 天的调用量和成功率按日聚合数据，用于趋势图展示
3. THE Backend SHALL 在 Dashboard 响应中包含各 App 调用占比分布数据（按 `ai_run_logs.app_type` 分组）
4. THE Backend SHALL 在 Dashboard 响应中包含日/月 Token 预算使用进度（已用量 / 预算上限）
5. THE Backend SHALL 在 Dashboard 响应中包含最近失败/超时/熔断告警事件列表（取自 `ai_run_logs` WHERE status IN ('failed', 'timeout', 'circuit_open')）
6. THE Backend SHALL 支持 `site_id` 查询参数进行门店筛选
7. THE Backend SHALL 在 Dashboard 响应中包含各 App 最近一次调用状态，用于展示 App 健康状态（覆盖 P2-2 MCP 健康检查需求）

#### 需求 A2：调度任务列表与详情 API

**用户故事：** 作为系统管理员，我希望查看调度任务的列表和详情，以便了解事件触发的执行状态、调用链和去重统计。

##### 验收标准

1. THE Backend SHALL 实现 `GET /api/admin/ai/trigger-jobs` 端点，返回分页的调度任务列表，包含事件类型、会员、状态、执行链（app_chain）、耗时
2. THE Backend SHALL 支持以下筛选参数：`event_type`、`status`、`site_id`、`date_from`、`date_to`
3. THE Backend SHALL 在列表响应中包含今日跳过的重复事件数（`ai_trigger_jobs` WHERE status='skipped_duplicate' AND created_at >= 今日零点）
4. THE Backend SHALL 实现 `GET /api/admin/ai/trigger-jobs/:id` 端点，返回单条调度任务的完整详情（含 payload、error_message）

#### 需求 A3：手动重跑 API

**用户故事：** 作为系统管理员，我希望对失败的调度任务进行手动重跑，以便修复因临时故障导致的执行失败。

##### 验收标准

1. THE Backend SHALL 实现 `POST /api/admin/ai/trigger-jobs/:id/retry` 端点，对指定调度任务发起手动重跑
2. WHEN 手动重跑时，THE Backend SHALL 创建新的 `ai_trigger_jobs` 记录，标记 `is_forced=true`，跳过去重检查
3. THE Backend SHALL 在重跑请求后立即返回新的 `trigger_job_id` 和 `status: "pending"`，调用链在后台异步执行

#### 需求 A4：调用记录列表与详情 API

**用户故事：** 作为系统管理员，我希望查看 AI 调用记录的列表和详情，以便追踪每次调用的 prompt、response、token 消耗和错误信息。

##### 验收标准

1. THE Backend SHALL 实现 `GET /api/admin/ai/run-logs` 端点，返回分页的调用记录列表，包含 app_type、trigger_type、member_id、tokens_used、latency_ms、status
2. THE Backend SHALL 支持以下筛选参数：`app_type`、`status`、`trigger_type`、`site_id`、`date_from`、`date_to`
3. THE Backend SHALL 实现 `GET /api/admin/ai/run-logs/:id` 端点，返回单条调用记录的完整详情，包含完整 request_prompt、完整 response_text、error_message
4. THE Backend SHALL 对调用记录详情不做脱敏处理，系统管理员可查看原文

#### 需求 A5：缓存失效 API

**用户故事：** 作为系统管理员，我希望按 App / 会员 / 门店批量将缓存标记为失效，以便在数据异常时强制重新生成 AI 分析结果。

##### 验收标准

1. THE Backend SHALL 实现 `POST /api/admin/ai/cache/invalidate` 端点，接受请求体包含：`app_type`（可选）、`member_id`（可选）、`site_id`（必填）
2. WHEN 缓存失效请求到达时，THE Backend SHALL 将匹配条件的 `ai_cache` 记录的 `status` 字段更新为 `invalidated`
3. THE Backend SHALL 返回受影响的缓存记录数量

#### 需求 A6：Token 预算查询 API

**用户故事：** 作为系统管理员，我希望查看 Token 预算的使用情况，以便监控 AI 调用成本。

##### 验收标准

1. THE Backend SHALL 实现 `GET /api/admin/ai/budget` 端点，返回日预算和月预算的使用情况：已用量、预算上限、使用百分比
2. THE Backend SHALL 从 `ai_run_logs.tokens_used` 按日/月聚合计算已消耗 token 数

#### 需求 A7：批量执行与成本二次确认 API

**用户故事：** 作为系统管理员，我希望批量执行 AI 调用前能看到预估成本，确认后才真正执行，以便防止误操作导致大量 API 调用和费用。

##### 验收标准

1. THE Backend SHALL 实现 `POST /api/admin/ai/batch-run` 端点，接受请求体包含：`app_types`（App 列表）、`member_ids`（会员 ID 列表）、`site_id`（门店 ID）
2. WHEN 批量执行请求到达时，THE Backend SHALL 计算预估调用次数（会员数 × App 数）和预估 Token 消耗，返回 `{ batch_id, estimated_calls, estimated_tokens }`，不立即执行
3. THE Backend SHALL 实现 `POST /api/admin/ai/batch-run/confirm` 端点，接受 `{ batch_id }`，确认后在后台异步执行批量调用
4. IF batch_id 无效或已过期，THEN THE Backend SHALL 返回 HTTP 400 错误

#### 需求 A8：告警管理 API

**用户故事：** 作为系统管理员，我希望查看、确认和忽略 AI 运行告警，以便对失败事件进行分类处理。

##### 验收标准

1. THE Backend SHALL 实现 `GET /api/admin/ai/alerts` 端点，返回告警列表（来源：`ai_run_logs` WHERE status IN ('failed', 'timeout', 'circuit_open')），支持分页和状态筛选
2. THE Backend SHALL 实现 `POST /api/admin/ai/alerts/:id/ack` 端点，将指定告警标记为"已确认"
3. THE Backend SHALL 实现 `POST /api/admin/ai/alerts/:id/ignore` 端点，将指定告警标记为"已忽略"
4. THE Backend SHALL 支持告警的三种状态：`pending`（待处理）、`acknowledged`（已确认）、`ignored`（已忽略）

#### 需求 A9：API 认证与权限

**用户故事：** 作为系统管理员，我希望 AI 监控后台的所有 API 端点都受 JWT 认证保护，以便只有授权管理员才能访问。

##### 验收标准

1. THE Backend SHALL 对所有 `/api/admin/ai/*` 端点使用 JWT Bearer Token 认证，复用现有 admin 权限体系
2. IF JWT Token 缺失或无效，THEN THE Backend SHALL 返回 HTTP 401
3. THE Backend SHALL 确保系统管理员对所有 AI 监控数据全量可见，不做数据脱敏

---

### 模块 B：admin-web AI 监控后台 — 前端页面

#### 需求 B1：AI 运行总览页面（Dashboard）

**用户故事：** 作为系统管理员，我希望在 admin-web 中看到 AI 运行总览 Dashboard，以便一目了然地掌握 AI 模块的运行状况。

##### 验收标准

1. THE admin-web SHALL 新增 AI 运行总览页面，包含以下区域：顶部统计卡片（今日调用次数、成功率、Token 消耗、平均延迟）、近 7 天趋势折线图（调用量 + 成功率）、各 App 调用占比饼图、Token 预算使用进度条（日/月）、告警列表
2. THE admin-web SHALL 在 Dashboard 页面展示各 App 最近一次调用状态，用于健康状态监控
3. THE admin-web SHALL 支持门店筛选（`site_id` 下拉选择）
4. THE admin-web SHALL 展示当前 App 配置信息（只读），覆盖 P3-3 Prompt 版本管理的监控展示需求

#### 需求 B2：调度状态页面

**用户故事：** 作为系统管理员，我希望在 admin-web 中查看调度任务的执行状态，以便监控事件触发链的运行情况。

##### 验收标准

1. THE admin-web SHALL 新增调度状态页面，包含分页表格展示：事件类型、会员、状态、执行链（app_chain）、耗时
2. THE admin-web SHALL 提供筛选器：event_type / status / site_id / 日期范围
3. THE admin-web SHALL 在页面顶部展示今日跳过的重复事件数
4. THE admin-web SHALL 在操作列提供"查看详情"和"手动重跑"按钮
5. WHEN 点击"手动重跑"时，THE admin-web SHALL 弹出确认对话框，确认后调用 `POST /api/admin/ai/trigger-jobs/:id/retry`

#### 需求 B3：调用明细页面

**用户故事：** 作为系统管理员，我希望在 admin-web 中查看 AI 调用的详细记录，以便排查问题和分析调用模式。

##### 验收标准

1. THE admin-web SHALL 新增调用明细页面，包含分页表格展示：app_type、trigger_type、member_id、tokens_used、latency_ms、status
2. THE admin-web SHALL 提供筛选器：app_type / status / trigger_type / site_id / 日期范围
3. WHEN 点击表格行时，THE admin-web SHALL 展开详情抽屉（Drawer），展示完整 prompt、完整 response、error_message

#### 需求 B4：手动操作页面

**用户故事：** 作为系统管理员，我希望在 admin-web 中执行手动重跑、缓存失效、批量执行和告警管理操作，以便在需要时进行人工干预。

##### 验收标准

1. THE admin-web SHALL 新增手动操作页面，包含以下功能区域：手动重跑、缓存失效、批量执行（含成本二次确认）、告警确认/忽略
2. THE admin-web SHALL 在手动重跑区域提供 App 选择、会员输入、门店选择，触发单次执行
3. THE admin-web SHALL 在缓存失效区域提供按 App / 会员 / 门店的批量失效操作
4. THE admin-web SHALL 在批量执行区域实现成本二次确认流程：选择操作参数 → 调用 `POST /api/admin/ai/batch-run` 获取预估 → 展示确认弹窗（"本次将执行 N 次 AI 调用，预估消耗 M tokens，确认执行？"）→ 确认后调用 `POST /api/admin/ai/batch-run/confirm`
5. THE admin-web SHALL 在告警区域展示告警列表，每条告警提供"确认"和"忽略"操作按钮

---

### 模块 C：测试体系重建

#### 需求 C1：旧测试脚本归档

**用户故事：** 作为开发者，我希望将基于旧 openai SDK 的测试脚本归档到 `_archived/` 目录，以便清理过时代码，避免误用。

##### 验收标准

1. THE Backend SHALL 将以下 7 个脚本从 `scripts/ops/` 移至 `scripts/ops/_archived/`：`ai_full_chain_test.py`、`test_chat_e2e.py`、`test_chat_ai_quality.py`、`test_bailian_apps.py`、`test_bailian_single.py`、`test_bailian_full.py`、`_run_ai_tests_remaining.py`
2. THE Backend SHALL 将 `apps/backend/tests/test_ai_bailian.py` 移至 `apps/backend/tests/_archived/test_ai_bailian.py`
3. THE Backend SHALL 将 `docs/reports/2026-03-21__ai_full_chain_test.md` 移至 `docs/reports/_archived/2026-03-21__ai_full_chain_test.md`
4. THE Backend SHALL 保留归档文件内容不变，仅移动位置
5. THE Backend SHALL 不删除 `docs/audit/` 中的审计记录，仅停止引用

#### 需求 C2：新全链路测试 — 15 个场景

**用户故事：** 作为开发者，我希望建立覆盖 15 个场景的全链路测试，以便验证 DashScope 迁移后所有 AI 应用的端到端功能正确性。

##### 验收标准

1. THE Backend SHALL 实现 App1 对话测试，覆盖 10 种入口（general、customer_detail、coach_detail、task_detail、finance_overview、member_list、settlement_detail、note_detail、dashboard、report），验证 SSE 流式输出、session_id 双轨持久化、对话复用规则
2. THE Backend SHALL 实现 App2 定时预生成测试，验证 8 个时间维度（今日、昨日、本周、上周、本月、上月、本季、上季）的缓存写入和 JSON 合法性
3. THE Backend SHALL 实现消费事件触发链测试（App3→App8→App7），验证事件传播、缓存写入、业务表写入
4. THE Backend SHALL 实现助教消费触发链测试（App3→App8→App7→App4→App5），验证完整链路和助教关联
5. THE Backend SHALL 实现备注事件触发链测试（App6→App8），验证备注分析和线索整合
6. THE Backend SHALL 实现任务分配触发链测试（App4→App5），验证关系分析和话术生成
7. THE Backend SHALL 实现缓存命中测试（App2~8），验证缓存有效期内直接返回、过期后重新生成
8. THE Backend SHALL 实现缓存失效测试（App2~8），验证 admin-web 手动失效后重新生成
9. THE Backend SHALL 实现熔断触发测试，验证连续 5 次失败→熔断→半开→恢复的完整流程
10. THE Backend SHALL 实现 Token 预算超限测试，验证超限后正确降级
11. THE Backend SHALL 实现失败记录测试，验证 `ai_run_logs` 记录完整且 error_message 有值
12. THE Backend SHALL 实现后台可见性测试，验证 admin-web API 能返回所有运行记录和详情
13. THE Backend SHALL 实现 JSON 兜底测试（App2~8），验证非法 JSON 重试 3 次
14. THE Backend SHALL 实现幂等验证测试（App8），验证同一 member 同一天重复触发只执行一次
15. THE Backend SHALL 实现内容质量测试（App2~8），验证返回内容包含必要字段、格式正确
16. THE Backend SHALL 支持 Mock 模式和真实 API 模式双轨运行，Mock 模式用于 CI 环境，真实 API 模式用于集成验证

#### 需求 C3：属性测试更新 — 7 个属性测试

**用户故事：** 作为开发者，我希望更新 Hypothesis 属性测试，以便通过随机输入验证 AI 模块的关键不变量。

##### 验收标准

1. THE Backend SHALL 实现熔断器状态机属性测试，验证状态转换合法性：closed→open→half_open→closed/open，任意操作序列不产生非法状态
2. THE Backend SHALL 实现 Token 预算计算属性测试，验证日/月聚合值等于各条记录 tokens_used 之和（聚合不变量）
3. THE Backend SHALL 实现去重逻辑属性测试，验证相同 (event_type, member_id, site_id, date) 只产生一条非 skipped 记录
4. THE Backend SHALL 实现缓存过期属性测试，验证 expires_at 过期的缓存 status 必须为 expired
5. THE Backend SHALL 实现 App8 幂等属性测试，验证同一 member 同一天的 member_retention_clue 只有一组记录
6. THE Backend SHALL 实现 session_id 重建属性测试，验证重建后的 messages 数组与本地 ai_messages 一致（round-trip 属性）
7. THE Backend SHALL 实现限流计数属性测试，验证窗口内请求数不超过上限

---

### 模块 D：历史数据回填

#### 需求 D1：回填脚本

**用户故事：** 作为系统管理员，我希望通过回填脚本为半年内活跃会员生成 AI 分析数据，以便新上线的 AI 功能对历史会员也有完整的分析结果。

##### 验收标准

1. THE Backend SHALL 实现回填脚本 `scripts/ops/ai_backfill.py`，查询半年内（2025-09-21 ~ 2026-03-21）三者并集的活跃会员：有消费记录、有备注记录、有任务变更
2. THE Backfill_Script SHALL 写死门店范围 `site_id = 2790685415443269`
3. THE Backfill_Script SHALL 分批执行：每批 10 个会员，批间间隔 5 秒
4. THE Backfill_Script SHALL 实现断点续跑：将已完成的 member_id 列表记录到本地文件，失败后从断点继续
5. THE Backfill_Script SHALL 对每个会员执行以下调用链：App3（维客线索）→ App8（线索整理）→ App7（客户分析）；如有助教关联：→ App4（关系分析）→ App5（话术参考）；如有备注：→ App6（备注分析）→ App8（再次整合）
6. THE Backfill_Script SHALL 对 App8 写入 `member_retention_clue` 业务表时使用 DELETE + INSERT 事务包裹
7. THE Backfill_Script SHALL 不备份现有数据

#### 需求 D2：回填成本确认

**用户故事：** 作为系统管理员，我希望在执行回填前通过 admin-web 二次确认预估成本，以便防止意外的大量 API 调用。

##### 验收标准

1. THE Backfill_Script SHALL 在执行前输出预估信息：会员数量、预估调用次数（会员数 × 平均 5 个 App）、预估 Token 消耗（每次约 2000 tokens）
2. THE Backfill_Script SHALL 支持通过 admin-web 的批量执行 + 成本二次确认流程触发（复用需求 A7 的 API）
3. THE Backfill_Script SHALL 在回填过程中验证 App5 输出包含分类字段（覆盖 P2-1 问题修复）

---

### 模块 E：数据保留与清理

#### 需求 E1：数据保留策略

**用户故事：** 作为系统管理员，我希望 AI 相关数据按策略自动清理，以便控制数据库存储增长。

##### 验收标准

1. THE Backend SHALL 永久保留 App1 对话记录（`ai_conversations` + `ai_messages`），不自动删除
2. THE Backend SHALL 对 App2~8 缓存（`ai_cache`）每个 App 保留最新 20,000 条，超出部分按 `created_at` 排序删除最旧记录
3. THE Backend SHALL 对 `ai_run_logs` 保留 90 天，删除 90 天前的记录
4. THE Backend SHALL 对 `ai_trigger_jobs` 保留 90 天，删除 90 天前的记录

#### 需求 E2：清理定时任务

**用户故事：** 作为系统管理员，我希望数据清理任务每日自动执行，以便无需人工干预即可维持数据保留策略。

##### 验收标准

1. THE Backend SHALL 实现数据清理定时任务，每日凌晨 03:00 执行
2. THE Backend SHALL 在清理任务中依次执行：删除 90 天前的 `ai_run_logs`、删除 90 天前的 `ai_trigger_jobs`、对每个 App 类型清理超出 20,000 条上限的 `ai_cache` 记录
3. THE Backend SHALL 记录每次清理任务的执行结果（删除记录数）到日志

---

### 模块 F：数据库查询优化与收尾

#### 需求 F1：Dashboard 聚合查询优化

**用户故事：** 作为后端开发者，我希望 Dashboard 的聚合查询性能良好，以便页面加载不卡顿。

##### 验收标准

1. THE Backend SHALL 为 `ai_run_logs` 的 Dashboard 聚合查询评估并添加 BRIN 索引（基于 `created_at` 列），提升按时间范围聚合的查询性能
2. THE Backend SHALL 确保 Dashboard API 的响应时间在合理范围内（分页 + 索引 + 90 天保留策略共同保障）

#### 需求 F2：文档同步

**用户故事：** 作为开发者，我希望所有相关文档在 P15 完成后保持同步更新，以便文档与代码一致。

##### 验收标准

1. THE Backend SHALL 更新 `apps/admin-web/README.md`，新增 AI 监控页面说明
2. THE Backend SHALL 更新 `apps/backend/README.md`，新增 admin AI API 说明
3. THE Backend SHALL 更新 `docs/DOCUMENTATION-MAP.md`，新增 P15 相关条目
4. THE Backend SHALL 更新 `docs/database/BD_Manual_ai_tables.md`，补充 admin API 相关的查询模式说明
5. THE Backend SHALL 确认 `docs/prd/ai-app-prompts.md` 中环境变量已全部更新（P14 遗留确认）