Neo-ZQYY/docs/prd/specs/P15-ai-monitoring-testing.md

# P15：AI 监控后台 + 测试重建 + 回填

> 状态：Draft | 创建日期：2026-03-21 | 依赖：P14（DashScope 迁移 + 调度器完善）
> 前置条件：P14 全部完成并验证通过后，方可开始 P15 实施

---

## 一、执行摘要

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

### 问题覆盖

本 PRD 覆盖 `docs/reports/2026-03-21__ai_module_issues.md` 中的：
- P2-1：App5 话术缺分类
- P2-2：MCP 无健康检查
- P2-4：全链路测试不完整
- P3-3：Prompt 版本管理（仅监控展示部分）

---

## 二、admin-web AI 监控后台

### 2.1 技术基础

- 框架：React + Vite + Ant Design（已有 8 个页面，加页面即可）
- 认证：JWT Bearer Token，复用现有 admin 权限体系
- API 前缀：`/api/admin/ai/*`
- 权限：系统管理员全量可见，不脱敏，点开详情看原文
- 门店筛选：支持按 `site_id` 筛选查看

### 2.2 页面规划

#### 页面 1：AI 运行总览（Dashboard）

| 区域 | 内容 | 数据来源 |
|------|------|---------|
| 顶部统计卡片 | 今日调用次数、成功率、Token 消耗、平均延迟 | `ai_run_logs` 聚合 |
| 趋势图 | 近 7 天调用量 + 成功率折线图 | `ai_run_logs` 按日聚合 |
| App 分布 | 各 App 调用占比饼图 | `ai_run_logs.app_type` 分组 |
| Token 预算 | 日/月预算使用进度条 | `ai_run_logs.tokens_used` 聚合 |
| 告警列表 | 最近失败/超时/熔断事件 | `ai_run_logs` WHERE status IN ('failed','timeout') |

#### 页面 2：调度状态

| 区域 | 内容 | 数据来源 |
|------|------|---------|
| 触发任务列表 | 分页表格：事件类型、会员、状态、执行链、耗时 | `ai_trigger_jobs` |
| 筛选器 | event_type / status / site_id / 日期范围 | — |
| 操作列 | 查看详情、手动重跑 | — |
| 去重统计 | 今日跳过的重复事件数 | `ai_trigger_jobs` WHERE status='skipped_duplicate' |

#### 页面 3：调用明细

| 区域 | 内容 | 数据来源 |
|------|------|---------|
| 调用记录表格 | app_type、trigger_type、member_id、tokens、延迟、状态 | `ai_run_logs` |
| 筛选器 | app_type / status / trigger_type / site_id / 日期范围 | — |
| 详情抽屉 | 点击行展开：完整 prompt、完整 response、error_message | `ai_run_logs` 单条 |

#### 页面 4：手动操作

| 功能 | 说明 |
|------|------|
| 手动重跑 | 选择 App + 会员 + 门店，触发单次执行（标记 `is_forced=true`） |
| 缓存失效 | 按 App / 会员 / 门店批量将 `ai_cache.status` 设为 `invalidated` |
| 成本二次确认 | 批量操作前展示预估调用次数和 Token 消耗，点"确认执行"后才真正执行 |
| 告警确认/忽略 | 对失败告警标记"已确认"或"忽略" |

### 2.3 后端 API 清单

```
GET  /api/admin/ai/dashboard          — 总览统计数据
GET  /api/admin/ai/trigger-jobs       — 调度任务列表（分页 + 筛选）
GET  /api/admin/ai/trigger-jobs/:id   — 调度任务详情
POST /api/admin/ai/trigger-jobs/:id/retry  — 手动重跑
GET  /api/admin/ai/run-logs           — 调用记录列表（分页 + 筛选）
GET  /api/admin/ai/run-logs/:id       — 调用记录详情（含完整 prompt/response）
POST /api/admin/ai/cache/invalidate   — 批量缓存失效
GET  /api/admin/ai/budget             — Token 预算使用情况
POST /api/admin/ai/batch-run          — 批量执行（需二次确认）
POST /api/admin/ai/batch-run/confirm  — 确认批量执行
GET  /api/admin/ai/alerts             — 告警列表
POST /api/admin/ai/alerts/:id/ack     — 确认告警
POST /api/admin/ai/alerts/:id/ignore  — 忽略告警
```

### 2.4 成本二次确认流程

```
管理员选择批量操作（如：回填 50 个会员）
  → POST /api/admin/ai/batch-run
    → 后端计算：50 会员 × 5 App = 250 次调用，预估 ~500K tokens
    → 返回 { batch_id, estimated_calls: 250, estimated_tokens: 500000 }
  → 前端展示确认弹窗："本次将执行 250 次 AI 调用，预估消耗 50 万 tokens，确认执行？"
  → 管理员点"确认执行"
    → POST /api/admin/ai/batch-run/confirm { batch_id }
    → 后端异步执行
```

---

## 三、测试体系重建

### 3.1 旧测试脚本归档

以下 4 个脚本移至 `_archived/` 目录：

| 脚本 | 原位置 | 归档位置 |
|------|---------|---------|
| `ai_full_chain_test.py` | `scripts/ops/` | `scripts/ops/_archived/` |
| `test_chat_e2e.py` | `scripts/ops/` | `scripts/ops/_archived/` |
| `test_chat_ai_quality.py` | `scripts/ops/` | `scripts/ops/_archived/` |
| `test_bailian_apps.py` | `scripts/ops/` | `scripts/ops/_archived/` |
| `test_bailian_single.py` | `scripts/ops/` | `scripts/ops/_archived/` |
| `test_bailian_full.py` | `scripts/ops/` | `scripts/ops/_archived/` |
| `_run_ai_tests_remaining.py` | `scripts/ops/` | `scripts/ops/_archived/` |
| `test_ai_bailian.py` | `apps/backend/tests/` | `apps/backend/tests/_archived/` |
| `2026-03-21__ai_full_chain_test.md` | `docs/reports/` | `docs/reports/_archived/` |

归档时保留文件内容不变，仅移动位置。审计记录（`docs/audit/`）不删除，只停止引用。

### 3.2 新全链路测试

#### 测试覆盖矩阵

| 测试场景 | 覆盖 App | 验证点 |
|---------|---------|--------|
| App1 对话（10 种入口） | App1 | SSE 流式、session_id 双轨、对话复用规则 |
| App2 定时预生成 | App2 | 8 个时间维度、缓存写入、JSON 合法性 |
| 消费事件触发链 | App3→App8→App7 | 事件传播、缓存写入、业务表写入 |
| 助教消费触发链 | App3→App8→App7→App4→App5 | 完整链路、助教关联 |
| 备注事件触发链 | App6→App8 | 备注分析、线索整合 |
| 任务分配触发链 | App4→App5 | 关系分析、话术生成 |
| 缓存命中 | App2~8 | 缓存有效期内直接返回、过期后重新生成 |
| 缓存失效 | App2~8 | admin-web 手动失效后重新生成 |
| 熔断触发 | 任意 App | 连续 5 次失败→熔断→半开→恢复 |
| Token 预算超限 | 任意 App | 超限后正确降级 |
| 失败记录 | 任意 App | `ai_run_logs` 记录完整、error_message 有值 |
| 后台可见性 | 全部 | admin-web 能看到所有运行记录和详情 |
| JSON 兜底 | App2~8 | 非法 JSON 重试 3 次 |
| 幂等验证 | App8 | 同一 member 同一天重复触发只执行一次 |
| 内容质量 | App2~8 | 返回内容包含必要字段、格式正确 |

#### App1 的 10 种入口

1. general（通用对话，始终新建）
2. customer_detail（客户详情页）
3. coach_detail（助教详情页）
4. task_detail（任务详情页）
5. finance_overview（财务总览页）
6. member_list（会员列表页）
7. settlement_detail（结算详情页）
8. note_detail（备注详情页）
9. dashboard（首页仪表盘）
10. report（报表页）

### 3.3 属性测试更新

更新 `tests/` 下的 Hypothesis 属性测试：

| 属性测试 | 验证不变量 |
|---------|-----------|
| 熔断器状态机 | 状态转换合法性：closed→open→half_open→closed/open |
| Token 预算计算 | 日/月聚合值 = 各条记录 tokens_used 之和 |
| 去重逻辑 | 相同 (event_type, member_id, site_id, date) 只产生一条非 skipped 记录 |
| 缓存过期 | expires_at 过期的缓存 status 必须为 expired |
| App8 幂等 | 同一 member 同一天的 member_retention_clue 只有一组记录 |
| session_id 重建 | 重建后的 messages 数组与本地 ai_messages 一致 |
| 限流计数 | 窗口内请求数不超过上限 |

---

## 四、历史数据回填

### 4.1 回填范围

半年内（2025-09-21 ~ 2026-03-21）三者并集：
- 有消费记录的 member
- 有备注记录的 member
- 有任务变更的 member

预估规模：<100 会员。

门店范围：`site_id = 2790685415443269`（写死）。

### 4.2 回填策略

- 执行方式：专门脚本（`scripts/ops/ai_backfill.py`）
- 分批执行：每批 10 个会员，批间间隔 5 秒
- 断点续跑：脚本记录已完成的 member_id 列表到本地文件，失败后从断点继续
- 不备份现有数据
- App8 写业务表（`member_retention_clue`）：DELETE + INSERT，事务包裹

### 4.3 回填调用链

每个会员执行：
```
App3（维客线索）→ App8（线索整理）→ App7（客户分析）
  如有助教关联：→ App4（关系分析）→ App5（话术参考）
如有备注：→ App6（备注分析）→ App8（再次整合）
```

### 4.4 成本预估

- 100 会员 × 平均 5 个 App = 500 次调用
- 每次约 2000 tokens → 总计约 100 万 tokens
- 执行前通过 admin-web 二次确认

---

## 五、数据保留策略

| 数据类型 | 保留策略 | 清理方式 |
|---------|---------|---------|
| App1 对话记录（ai_conversations + ai_messages） | 永久保留，不自动删除 | — |
| App2~8 缓存（ai_cache） | 每个 App 保留最新 20,000 条 | 定时任务：按 created_at 排序，超出部分 DELETE |
| AI 运行记录（ai_run_logs） | 保留 90 天 | 定时任务：DELETE WHERE created_at < now() - 90 days |
| 调度记录（ai_trigger_jobs） | 保留 90 天 | 同上 |

清理定时任务建议每日凌晨 03:00 执行。

---

## 六、后端 API 变更汇总

### 新增路由文件

`apps/backend/app/routers/admin_ai.py`

### 新增 Service

`apps/backend/app/services/ai/admin_service.py` — 聚合查询、批量操作、告警管理

### 数据库查询优化

- `ai_run_logs` 的 Dashboard 聚合查询需要按日分区或添加 BRIN 索引
- `ai_trigger_jobs` 的去重查询已有复合索引（§P14 六.2）

---

## 七、问题修复映射

| 问题编号 | 优先级 | 描述 | 本 PRD 对应章节 |
|---------|--------|------|----------------|
| P2-1 | P2 | App5 话术缺分类 | 回填时验证 App5 输出包含分类字段 |
| P2-2 | P2 | MCP 无健康检查 | admin-web Dashboard 展示各 App 最近调用状态 |
| P2-4 | P2 | 全链路测试不完整 | §3.2（新全链路测试） |
| P3-3 | P3 | Prompt 版本管理 | admin-web 展示当前 App 配置（只读） |

---

## 八、收尾标准流程

### 8.1 DDL 迁移

本 PRD 无新增表（P14 已创建）。如有字段调整：
1. 编写增量迁移脚本
2. 测试库验证
3. 合并基线

### 8.2 BD 手册更新

- 更新 `docs/database/BD_Manual_ai_tables.md`：补充 admin API 相关的查询模式说明

### 8.3 文档同步

| 文档 | 更新内容 |
|------|---------|
| `apps/admin-web/README.md` | 新增 AI 监控页面说明 |
| `apps/backend/README.md` | 新增 admin AI API 说明 |
| `docs/DOCUMENTATION-MAP.md` | 新增条目 |
| `docs/prd/ai-app-prompts.md` | 确认环境变量已全部更新 |

### 8.4 属性测试

- 新增 §3.3 中列出的 7 个属性测试
- 确保所有属性测试通过

### 8.5 最终检查点

- [ ] admin-web AI 监控 4 个页面功能正常
- [ ] 手动重跑功能正常，标记 forced
- [ ] 缓存失效功能正常
- [ ] 成本二次确认流程完整
- [ ] 旧测试脚本已归档到 `_archived/`
- [ ] 新全链路测试覆盖 15 个场景
- [ ] 属性测试全部通过
- [ ] 回填脚本执行完成，<100 会员数据完整
- [ ] 数据保留定时任务配置完成
- [ ] 所有文档已同步更新

---

## 九、风险与缓解

| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| 回填触发大量 API 调用 | 成本突增 | 分批执行 + admin-web 二次确认 |
| 回填中途失败 | 部分会员数据不完整 | 断点续跑机制 |
| admin-web 查询大量 ai_run_logs 性能差 | 页面卡顿 | 分页 + 索引 + 90 天保留策略 |
| 全链路测试依赖真实百炼 API | 测试不稳定 | Mock 模式 + 真实 API 模式双轨 |

---

## 十、不在本 PRD 范围

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