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
parent 8228b3fa37
commit 70324d8542
185 changed files with 13595 additions and 1219 deletions
--- a/docs/specs/ai-monitoring-testing/design.md
+++ b/docs/specs/ai-monitoring-testing/design.md
--- a/docs/specs/ai-monitoring-testing/requirements.md
+++ b/docs/specs/ai-monitoring-testing/requirements.md
@@ -0,0 +1,334 @@
+# 需求文档 — 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 遗留确认）
--- a/docs/specs/ai-monitoring-testing/tasks.md
+++ b/docs/specs/ai-monitoring-testing/tasks.md
@@ -0,0 +1,386 @@
+# 实施计划：P15 — AI 监控后台 + 测试重建 + 回填
+
+> 权威参考：实施过程中如遇细节不明确，应优先查阅 PRD 原文：
+> - `docs/prd/specs/P15-ai-monitoring-testing.md` — P15 完整设计（Dashboard、调度状态、调用明细、手动操作、测试重建、回填、数据保留）
+
+## 概述
+
+按依赖关系分阶段实施六个模块：DDL 迁移 → 旧脚本归档 → 后端 API（模块 A）→ 数据保留（模块 E）→ 回填脚本（模块 D）→ 测试重建（模块 C）→ 前端页面（模块 B）→ 文档收尾（模块 F）→ 收尾。
+
+后端使用 Python（FastAPI + Pydantic），前端使用 TypeScript（React + Vite + Ant Design），属性测试使用 Hypothesis。
+
+## 任务
+
+### 阶段一：DDL 迁移
+
+- [x] 1. DDL 迁移 — ai_run_logs 新增 alert_status + BRIN 索引
+  - [x] 1.1 创建迁移脚本 `db/zqyy_app/migrations/2026-03-23__p15_ai_monitoring.sql`
+    - ALTER TABLE `biz.ai_run_logs` ADD COLUMN `alert_status` VARCHAR(20) DEFAULT NULL
+    - ADD CONSTRAINT `chk_ai_run_logs_alert_status` CHECK (alert_status IN ('pending', 'acknowledged', 'ignored'))
+    - CREATE INDEX `idx_ai_run_logs_alert` ON biz.ai_run_logs(alert_status, created_at DESC) WHERE status IN ('failed', 'timeout', 'circuit_open')（部分索引）
+    - CREATE INDEX `idx_ai_run_logs_created_brin` ON biz.ai_run_logs USING BRIN (created_at) WITH (pages_per_range = 32)
+    - UPDATE 回填：已有 status IN ('failed','timeout','circuit_open') 的记录设置 alert_status='pending'
+    - 编写回滚脚本（逆序 DROP INDEX + DROP CONSTRAINT + DROP COLUMN）
+    - _需求: A8.4, F1.1_
+
+### 阶段二：旧测试脚本归档（模块 C1）
+
+- [x] 2. 归档旧测试脚本
+  - [x] 2.1 移动 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`
+    - _需求: C1.1_
+
+  - [x] 2.2 移动后端测试和报告到归档目录
+    - `apps/backend/tests/test_ai_bailian.py` → `apps/backend/tests/_archived/test_ai_bailian.py`
+    - `docs/reports/2026-03-21__ai_full_chain_test.md` → `docs/reports/_archived/2026-03-21__ai_full_chain_test.md`
+    - 保留文件内容不变，仅移动位置
+    - _需求: C1.2, C1.3, C1.4, C1.5_
+
+### 阶段三：后端 API（模块 A）
+
+- [x] 3. 后端 Schema — Admin AI
+  - [x] 3.1 创建 `apps/backend/app/schemas/admin_ai.py`
+    - 定义 Dashboard 相关：`DashboardResponse`、`DailyTrend`、`AppDistItem`、`BudgetInfo`、`AlertItem`、`AppHealthItem`
+    - 定义调度任务相关：`TriggerJobListResponse`、`TriggerJobItem`、`TriggerJobDetailResponse`、`RetryResponse`
+    - 定义调用记录相关：`RunLogListResponse`、`RunLogItem`、`RunLogDetailResponse`
+    - 定义缓存失效：`CacheInvalidateRequest`（site_id 必填）、`CacheInvalidateResponse`
+    - 定义 Token 预算：`BudgetResponse`
+    - 定义批量执行：`BatchRunRequest`、`BatchRunEstimate`、`BatchRunConfirm`、`BatchRunConfirmResponse`
+    - 定义告警：`AlertListResponse`、`AlertActionResponse`
+    - _需求: A1.1, A2.1, A4.1, A5.1, A6.1, A7.1, A8.1_
+
+- [x] 4. 后端服务层 — AdminAIService
+  - [x] 4.1 创建 `apps/backend/app/services/ai/admin_service.py`
+    - 实现 `AdminAIService` 类，注入 `AIDispatcher` 和 `BudgetTracker`
+    - 实现 Dashboard 聚合方法：`get_dashboard()`、`_get_today_stats()`、`_get_7d_trend()`、`_get_app_distribution()`、`_get_app_health()`
+    - 实现调度任务方法：`list_trigger_jobs()`、`get_trigger_job()`、`retry_trigger_job()`（创建 is_forced=true 的新 trigger_job）
+    - 实现调用记录方法：`list_run_logs()`、`get_run_log()`（含完整 prompt/response，不脱敏）
+    - 实现缓存失效方法：`invalidate_cache()`（将匹配记录 status 设为 invalidated）
+    - 实现 Token 预算方法：`get_budget()`（复用 BudgetTracker）
+    - 实现批量执行方法：`estimate_batch()`（生成 batch_id 存入内存 dict，TTL 10min）、`confirm_batch()`（取出参数异步执行）、`_cleanup_expired_batches()`
+    - 实现告警管理方法：`list_alerts()`、`ack_alert()`、`ignore_alert()`
+    - _需求: A1.1, A1.2, A1.3, A1.4, A1.5, A1.6, A1.7, A2.1, A2.2, A2.3, A2.4, A3.1, A3.2, A3.3, A4.1, A4.2, A4.3, A4.4, A5.1, A5.2, A5.3, A6.1, A6.2, A7.1, A7.2, A7.3, A7.4, A8.1, A8.2, A8.3, A8.4_
+
+- [x] 5. 后端路由 — Admin AI API
+  - [x] 5.1 创建 `apps/backend/app/routers/admin_ai.py`
+    - 实现 13 个端点，全部使用 `Depends(require_admin)` JWT 认证：
+    - `GET /api/admin/ai/dashboard` — 总览统计（支持 site_id 筛选）
+    - `GET /api/admin/ai/trigger-jobs` — 调度任务分页列表（筛选：event_type, status, site_id, date_from, date_to）
+    - `GET /api/admin/ai/trigger-jobs/{job_id}` — 调度任务详情
+    - `POST /api/admin/ai/trigger-jobs/{job_id}/retry` — 手动重跑
+    - `GET /api/admin/ai/run-logs` — 调用记录分页列表（筛选：app_type, status, trigger_type, site_id, date_from, date_to）
+    - `GET /api/admin/ai/run-logs/{log_id}` — 调用记录详情
+    - `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/{log_id}/ack` — 确认告警
+    - `POST /api/admin/ai/alerts/{log_id}/ignore` — 忽略告警
+    - _需求: A1.1, A2.1, A2.4, A3.1, A4.1, A4.3, A5.1, A6.1, A7.1, A7.3, A8.1, A8.2, A8.3, A9.1, A9.2, A9.3_
+
+  - [x] 5.2 在 `apps/backend/app/main.py` 中注册 admin_ai router
+    - _需求: A9.1_
+
+  - [x] 5.3 创建 `apps/backend/tests/unit/test_admin_ai_router.py`
+    - 测试 13 个端点的请求/响应格式
+    - 测试 JWT 认证拒绝（无 Token → 401）
+    - 测试参数校验（无效日期格式 → 422、缺少 site_id → 422）
+    - _需求: A9.1, A9.2_
+
+  - [x] 5.4 创建 `apps/backend/tests/unit/test_admin_ai_service.py`
+    - 测试 AdminAIService 各方法的边界条件（空数据集、单条记录）
+    - 测试 batch_id 过期清理逻辑
+    - 测试告警状态转换（pending → acknowledged / ignored）
+    - _需求: A7.4, A8.4_
+
+- [x] 6. 检查点 — 模块 A 后端 API 验证
+  - 确保 Admin AI API 所有端点正常工作，单元测试通过，ask the user if questions arise.
+
+### 阶段四：数据保留与清理（模块 E）
+
+- [x] 7. 数据清理服务
+  - [x] 7.1 创建 `apps/backend/app/services/ai/cleanup_service.py`
+    - 实现 `AICleanupService` 类
+    - `_cleanup_run_logs()` — DELETE FROM ai_run_logs WHERE created_at < now() - 90 days
+    - `_cleanup_trigger_jobs()` — DELETE FROM ai_trigger_jobs WHERE created_at < now() - 90 days
+    - `_cleanup_cache()` — 遍历 App2~App8（7 个类型），每个保留最新 20,000 条，删除超出部分
+    - `run_cleanup()` — 依次执行三步清理，返回各步骤删除记录数
+    - 永久保留 App1 对话记录（ai_conversations + ai_messages），不清理
+    - _需求: E1.1, E1.2, E1.3, E1.4_
+
+  - [x] 7.2 注册清理定时任务
+    - 在 `scheduled_tasks` 表中注册清理任务，每日凌晨 03:00 执行
+    - 清理任务调用 `AICleanupService.run_cleanup()`
+    - 记录每次清理结果到日志
+    - _需求: E2.1, E2.2, E2.3_
+
+  - [x] 7.3 创建 `apps/backend/tests/unit/test_ai_cleanup_service.py`
+    - 测试清理服务边界条件（无数据、刚好 20000 条、跨日边界）
+    - _需求: E1.2, E1.3_
+
+### 阶段五：回填脚本（模块 D）
+
+- [x] 8. 历史数据回填脚本
+  - [x] 8.1 创建 `scripts/ops/ai_backfill.py`
+    - 实现 `AIBackfillRunner` 类
+    - `query_active_members()` — 查询半年内（2025-09-21 ~ 2026-03-21）活跃会员（消费 ∪ 备注 ∪ 任务变更三者并集）
+    - `load_checkpoint()` / `save_checkpoint()` — 断点续跑（checkpoint 文件：`scripts/ops/_ai_backfill_checkpoint.json`）
+    - `run_member()` — 对单个会员执行调用链：App3→App8→App7；如有助教关联→App4→App5；如有备注→App6→App8
+    - `run()` — 主入口：加载断点 → 查询会员 → 分批执行（每批 10 人，间隔 5 秒）→ 保存断点
+    - `print_estimate()` — 执行前输出预估信息（会员数、预估调用次数、预估 Token 消耗）
+    - App8 写入 `member_retention_clue` 使用 DELETE + INSERT 事务包裹
+    - 验证 App5 输出包含分类字段（覆盖 P2-1 修复）
+    - 支持 `--dry-run`、`--batch-size`、`--interval` CLI 参数
+    - 写死 `site_id = 2790685415443269`
+    - _需求: D1.1, D1.2, D1.3, D1.4, D1.5, D1.6, D1.7, D2.1, D2.3_
+
+  - [x] 8.2 创建 `apps/backend/tests/unit/test_backfill_script.py`
+    - 测试 checkpoint 文件读写（空文件、已有数据）
+    - 测试空会员列表处理
+    - 测试批次划分逻辑
+    - _需求: D1.4_
+
+- [x] 9. 检查点 — 模块 A + E + D 后端验证
+  - 确保后端 API、清理服务、回填脚本所有测试通过，ask the user if questions arise.
+
+### 阶段六：测试重建（模块 C2 + C3）
+
+- [x] 10. 属性测试更新 — PRD §3.3 指定的 7 个属性（Property 1-7）
+  - [x] 10.1 更新 `tests/test_circuit_breaker_props.py`
+    - **Property 1: 熔断器状态机 — 状态转换合法性**（P14 Property 6 更新）
+    - 增强测试覆盖，确保 P14 迁移后熔断器在新 DashScope 调用链中行为一致
+    - **验证: 需求 C3.1**
+
+  - [x] 10.2 更新 `tests/test_budget_tracker_props.py`
+    - **Property 2: Token 预算计算 — 日/月聚合不变量**（P14 Property 8 更新）
+    - 验证 AdminAIService 的聚合查询与 BudgetTracker 的聚合结果一致
+    - **验证: 需求 C3.2, A6.2**
+
+  - [x] 10.3 更新 `tests/test_dispatcher_props.py`
+    - **Property 3: 去重逻辑 — 唯一性不变量**（P14 Property 12 更新）
+    - 验证 admin-web 手动重跑（is_forced=true）正确绕过去重检查
+    - **验证: 需求 C3.3, A3.2**
+
+  - [x] 10.4 新增/更新 `tests/test_cache_service_props.py`
+    - **Property 4: 缓存过期 — expires_at 过期状态一致性**（P15 新增）
+    - 验证 expires_at < now() 时 status 为 expired，过期记录不返回为有效缓存
+    - **验证: 需求 C3.4**
+
+  - [x] 10.5 更新 `tests/test_app8_idempotent.py`
+    - **Property 5: App8 幂等 — member_retention_clue 唯一性**（P14 Property 13 更新）
+    - 验证回填脚本中的 App8 写入同样满足幂等性
+    - **验证: 需求 C3.5**
+
+  - [x] 10.6 新增/更新 `tests/test_session_props.py`
+    - **Property 6: session_id 重建 — round-trip 属性**（P15 新增）
+    - 验证重建后的 messages 数组与本地 ai_messages 一致（内容和顺序均匹配）
+    - **验证: 需求 C3.6**
+
+  - [x] 10.7 更新 `tests/test_rate_limiter_props.py`
+    - **Property 7: 限流计数 — 窗口内请求数上限**（P14 Property 7 更新）
+    - 确保限流器在高并发回填场景下行为正确
+    - **验证: 需求 C3.7**
+
+- [x] 11. 属性测试新增 — P15 监控后台属性（Property 8-14）
+  - [x] 11.1 创建 `tests/test_admin_ai_dashboard_props.py`
+    - **Property 8: Dashboard 聚合正确性**
+    - 验证 today_calls、today_success_rate、today_tokens、today_avg_latency_ms、trend_7d、app_distribution 与直接 SQL 聚合结果一致
+    - **验证: 需求 A1.1, A1.2, A1.3, A1.6**
+
+  - [x] 11.2 创建 `tests/test_admin_ai_alert_props.py`
+    - **Property 9: 告警筛选与状态转换**
+    - 验证告警列表仅包含 status IN ('failed','timeout','circuit_open') 的记录
+    - 验证 ack → acknowledged、ignore → ignored 状态转换
+    - **验证: 需求 A8.1, A8.2, A8.3, A8.4**
+
+  - [x] 11.3 创建 `tests/test_admin_ai_cache_props.py`
+    - **Property 10: 缓存失效精确性**
+    - 验证匹配条件的记录 status 变为 invalidated，不匹配的保持不变
+    - **验证: 需求 A5.1, A5.2, A5.3**
+
+  - [x] 11.4 创建 `tests/test_admin_ai_batch_props.py`
+    - **Property 11: 批量执行预估公式**
+    - 验证 estimated_calls = len(app_types) × len(member_ids)，estimated_tokens = estimated_calls × avg_tokens_per_call
+    - **验证: 需求 A7.1, A7.2**
+
+  - [x] 11.5 创建 `tests/test_admin_ai_pagination_props.py`
+    - **Property 12: 分页与筛选正确性**
+    - 验证 items 均匹配筛选条件、len(items) <= page_size、total 正确
+    - **验证: 需求 A2.1, A2.2, A4.1, A4.2, A1.6**
+
+  - [x] 11.6 创建 `tests/test_backfill_props.py`
+    - **Property 13: 回填断点续跑 round-trip**
+    - 验证 checkpoint 文件序列化/反序列化 round-trip 一致性
+    - **验证: 需求 D1.4**
+
+  - [x] 11.7 创建 `tests/test_ai_cleanup_props.py`
+    - **Property 14: 数据保留不变量**
+    - 验证清理后 ai_run_logs/ai_trigger_jobs 无 90 天前记录、每个 App 的 ai_cache ≤ 20000、ai_conversations/ai_messages 不减少
+    - **验证: 需求 E1.1, E1.2, E1.3, E1.4**
+
+- [x] 12. 全链路测试 — 15 个场景（模块 C2）
+  - [x] 12.1 创建 `apps/backend/tests/integration/test_ai_full_chain.py`
+    - 实现 Mock/Real 双轨模式（`AI_TEST_MODE` 环境变量控制）
+    - Mock 模式：mock `Application.call()` 返回预设 JSON
+    - Real 模式：调用真实百炼 API（需要 `DASHSCOPE_API_KEY`）
+    - 实现 15 个测试场景：
+      1. `test_app1_10_entries` — App1 对话 10 种入口（SSE 流式 + session_id 双轨持久化）
+      2. `test_app2_pregenerate` — App2 定时预生成 8 维度
+      3. `test_consumption_chain` — 消费事件链 App3→App8→App7
+      4. `test_coach_consumption_chain` — 助教消费链 App3→App8→App7→App4→App5
+      5. `test_note_chain` — 备注事件链 App6→App8
+      6. `test_task_chain` — 任务分配链 App4→App5
+      7. `test_cache_hit` — 缓存命中（有效期内直接返回）
+      8. `test_cache_invalidation` — 缓存失效后重新生成
+      9. `test_circuit_breaker_flow` — 熔断触发→半开→恢复
+      10. `test_budget_exceeded` — Token 预算超限降级
+      11. `test_failure_logging` — 失败记录完整性
+      12. `test_admin_visibility` — admin-web API 可见性
+      13. `test_json_fallback` — JSON 兜底重试 3 次
+      14. `test_app8_idempotent` — App8 幂等验证
+      15. `test_content_quality` — 内容质量（必要字段+格式）
+    - _需求: C2.1, C2.2, C2.3, C2.4, C2.5, C2.6, C2.7, C2.8, C2.9, C2.10, C2.11, C2.12, C2.13, C2.14, C2.15, C2.16_
+
+- [x] 13. 检查点 — 测试体系验证
+  - 运行 Monorepo 属性测试：`cd C:\NeoZQYY && pytest tests/ -v`
+  - 运行全链路测试（Mock 模式）：`cd apps/backend && pytest tests/integration/test_ai_full_chain.py -v`
+  - 确保 Property 1-14 全部通过，15 个全链路场景 Mock 模式通过，ask the user if questions arise.
+
+### 阶段七：前端页面（模块 B）
+
+- [x] 14. 前端 API 层
+  - [x] 14.1 创建 `apps/admin-web/src/api/adminAI.ts`
+    - 封装 Dashboard API：`getDashboard(siteId?)`
+    - 封装调度任务 API：`getTriggerJobs(params)`、`getTriggerJobDetail(id)`、`retryTriggerJob(id)`
+    - 封装调用记录 API：`getRunLogs(params)`、`getRunLogDetail(id)`
+    - 封装缓存管理 API：`invalidateCache(data)`
+    - 封装 Token 预算 API：`getBudget()`
+    - 封装批量执行 API：`createBatchRun(data)`、`confirmBatchRun(batchId)`
+    - 封装告警 API：`getAlerts(params)`、`ackAlert(id)`、`ignoreAlert(id)`
+    - _需求: B1.1, B2.1, B3.1, B4.1_
+
+- [x] 15. 前端页面 — AI Dashboard
+  - [x] 15.1 创建 `apps/admin-web/src/pages/AIDashboard.tsx`
+    - 顶部：门店筛选 Select + 刷新按钮
+    - 第一行：4 个 Statistic 卡片（今日调用次数、成功率、Token 消耗、平均延迟）
+    - 第二行左：7 天趋势折线图（调用量 + 成功率）
+    - 第二行右：App 调用占比饼图
+    - 第三行左：Token 预算进度条（日/月各一个 Progress）
+    - 第三行右：App 健康状态列表（Badge 标记状态）
+    - 第四行：告警列表 Table + App 配置信息（只读 Descriptions）
+    - _需求: B1.1, B1.2, B1.3, B1.4_
+
+- [x] 16. 前端页面 — 调度状态
+  - [x] 16.1 创建 `apps/admin-web/src/pages/AITriggerJobs.tsx`
+    - 顶部筛选器行：event_type Select + status Select + site_id Select + DatePicker.RangePicker
+    - 统计行：今日去重跳过数 Statistic
+    - 主体：Table 分页表格（事件类型、会员、状态 Tag、执行链、耗时、操作列）
+    - 操作列：查看详情 → Modal、手动重跑 → Popconfirm
+    - _需求: B2.1, B2.2, B2.3, B2.4, B2.5_
+
+- [x] 17. 前端页面 — 调用明细
+  - [x] 17.1 创建 `apps/admin-web/src/pages/AIRunLogs.tsx`
+    - 顶部筛选器行：app_type + status + trigger_type + site_id + DatePicker.RangePicker
+    - 主体：Table 分页表格（app_type、trigger_type、member_id、tokens、延迟、状态 Tag）
+    - 点击行：Drawer 抽屉展示完整 prompt（代码块）、完整 response（代码块）、error_message
+    - _需求: B3.1, B3.2, B3.3_
+
+- [x] 18. 前端页面 — 手动操作
+  - [x] 18.1 创建 `apps/admin-web/src/pages/AIOperations.tsx`
+    - Card 1 — 手动重跑：App Select + member_id Input + site_id Select + 执行 Button
+    - Card 2 — 缓存失效：app_type Select + member_id Input + site_id Select + 失效 Button + 结果 message
+    - Card 3 — 批量执行：app_types Checkbox.Group + member_ids TextArea + site_id Select → 预估 → 确认弹窗 Modal（成本二次确认流程）
+    - Card 4 — 告警管理：Table（告警列表）+ 每行"确认"/"忽略" Button
+    - _需求: B4.1, B4.2, B4.3, B4.4, B4.5_
+
+- [x] 19. 前端路由与侧边栏
+  - [x] 19.1 修改 `apps/admin-web/src/App.tsx`
+    - 新增 4 个路由：`/ai/dashboard`、`/ai/trigger-jobs`、`/ai/run-logs`、`/ai/operations`
+    - 侧边栏新增"AI 监控"菜单组，包含 4 个子菜单项
+    - _需求: B1.1, B2.1, B3.1, B4.1_
+
+- [x] 20. 检查点 — 前端页面验证
+  - 确保所有前端组件渲染正常，API 调用层工作正确，ask the user if questions arise.
+
+### 阶段八：收尾
+
+- [x] 21. 前后端联调与集成验证
+  - [x] 21.1 启动后端服务，使用测试库验证各端点完整请求-响应链路
+    - 验证 13 个 admin AI API 端点 JSON 响应结构与 Schema 定义一致
+    - 验证 JWT 认证在真实请求中生效（无 Token → 401）
+    - 验证 site_id 筛选在 Dashboard 和列表端点中正常工作
+  - [x] 21.2 前端联调验证
+    - 确认 Dashboard 页面能正确调用 API 并渲染统计卡片、趋势图、饼图、预算进度
+    - 确认调度状态页面筛选、分页、手动重跑正常工作
+    - 确认调用明细页面 Drawer 展示完整 prompt/response
+    - 确认手动操作页面批量执行二次确认流程、告警确认/忽略正常
+    - 验证空数据/降级场景下前端不崩溃
+
+- [x] 22. 数据库变更审计与 DDL 合并
+  - [x] 22.1 审计本次实现中对数据库的所有改动
+    - 检查新增字段（ai_run_logs.alert_status）、新增索引（部分索引 + BRIN 索引）、新增定时任务记录
+  - [x] 22.2 执行迁移脚本到测试库（`test_zqyy_app`）
+    - 验证 alert_status 字段和索引已正确创建（使用 BD 手册中的验证 SQL）
+  - [x] 22.3 合并到主 DDL 基线文件
+    - ai_run_logs 变更 → `docs/database/ddl/zqyy_app__biz.sql`
+  - [x] 22.4 验证回滚脚本可执行（任务 1 中已编写）
+
+- [x] 23. BD 手册更新
+  - [x] 23.1 更新 `docs/database/BD_Manual_ai_tables.md`
+    - 补充 `alert_status` 字段说明（值域、默认值、CHECK 约束）
+    - 补充部分索引 `idx_ai_run_logs_alert` 说明
+    - 补充 BRIN 索引 `idx_ai_run_logs_created_brin` 说明
+    - 补充 admin API 相关的查询模式说明（Dashboard 聚合、告警筛选、分页查询）
+    - 包含：字段明细、约束与索引、验证 SQL（≥3 条）、回滚策略
+    - _规范: db-docs.md_
+    - _需求: F2.4_
+
+- [x] 24. 文档同步更新
+  - [x] 24.1 更新后端文档
+    - 在 `apps/backend/docs/API-REFERENCE.md` 新增 admin_ai 路由模块文档（13 个端点）
+    - 更新 `apps/backend/README.md` 新增 admin AI API 说明
+    - _需求: F2.2_
+  - [x] 24.2 更新 admin-web 文档
+    - 在 `apps/admin-web/README.md` 新增 AI 监控页面说明（4 个页面）
+    - _需求: F2.1_
+  - [x] 24.3 更新文档地图
+    - 在 `docs/DOCUMENTATION-MAP.md` 新增 P15 相关条目（BD 手册、Spec、API 文档）
+    - _规范: doc-map.md_
+    - _需求: F2.3_
+  - [x] 24.4 确认 `docs/prd/ai-app-prompts.md` 环境变量已全部更新（P14 遗留确认）
+    - _需求: F2.5_
+
+- [x] 25. 最终检查点 — 全量验证
+  - 运行 Monorepo 属性测试：`cd C:\NeoZQYY && pytest tests/ -v`
+  - 运行后端单元测试：`cd apps/backend && pytest tests/ -v`
+  - 运行全链路测试（Mock 模式）：`cd apps/backend && pytest tests/integration/test_ai_full_chain.py -v`
+  - 确保所有属性测试（Property 1-14）和单元测试全部通过
+  - 确保 DDL 迁移已合并到主基线
+  - 确保 BD 手册已同步更新
+  - 确保 API 文档、后端 README、admin-web README、文档地图均已更新
+  - 确保前端页面连接真实后端运行正常（Dashboard + 调度状态 + 调用明细 + 手动操作）
+  - 确保旧测试脚本已归档到 `_archived/` 目录
+  - ask the user if questions arise.
+
+- [x] 26. 服务清理
+  - [x] 26.1 关闭浏览器、停止后端和前端服务、清理资源
+    - 停止 uvicorn 后端进程（controlPwshProcess stop）
+    - 停止前端开发服务器（controlPwshProcess stop）
+
+## 备注
+
+- 标记 `*` 的子任务为可选（属性测试 / 单元测试），可跳过以加速 MVP
+- 每个任务引用了具体的需求编号以确保可追溯性（A1-A9 后端 API、B1-B4 前端页面、C1-C3 测试重建、D1-D2 回填、E1-E2 数据保留、F1-F2 查询优化与文档）
+- 属性测试验证 14 个正确性属性（Property 1-14）：Property 1-7 为 PRD §3.3 指定（5 个 P14 更新 + 2 个 P15 新增），Property 8-14 为 P15 监控后台新增
+- 单元测试验证具体边界条件和错误处理
+- 全链路测试覆盖 15 个场景，支持 Mock/Real 双轨模式
+- 检查点任务确保增量验证，避免问题累积（任务 6、9、13、20、25）
+- 后端使用 Python（FastAPI + Pydantic + Hypothesis），前端使用 TypeScript（React + Vite + Ant Design）
+- 收尾阶段遵循 `spec-closing-checklist.md`（全栈类 Spec，步骤 1-6 全覆盖）：
+  - 步骤 1（最终测试）→ 任务 25
+  - 步骤 2（前后端联调）→ 任务 21
+  - 步骤 3（DDL 合并）→ 任务 22
+  - 步骤 4（BD 手册）→ 任务 23
+  - 步骤 5（文档同步）→ 任务 24
+  - 步骤 6（服务清理）→ 任务 26