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 遗留确认）