# 审计记录：AI 模块完整实现

**日期**：2026-04-20  
**会话**：AI 模块全量建设（Phase 0~4）  
**影响范围**：backend / miniprogram / db / docs  

---

## 变更摘要

本次会话完成了 NeoZQYY AI 模块从架构重组到端到端贯通的全量实现，涵盖：

1. **Phase 0**：删除 8 个死代码 App 文件，新建 `prompts/` 模块 + dispatcher 完整重构
2. **Phase 1**：多轮会话 session_id 透传、references 注入、EventBus 广播
3. **Phase 2**：小程序 chat 页完善、ai-float-button 上下文透传、AI 缓存渲染
4. **Phase 2.2**：chat SSE 断线指数退避自动重连（最多 2 次）
5. **Phase 3**：WebSocket AI 告警端点、熔断/限流/预算告警推送
6. **Phase 3.2**：admin-web AIDashboard 接入 WS 实时告警（/ws/ai-alerts/{site_id}）
7. **Phase 4.1**：admin-web AIOperations 新增"按需重新生成"Card（POST /admin/ai/run/{app_type}）
8. **Phase 4.2**：缓存失效 Card 已在前序会话实现（adminAI.ts + AIOperations Card 2）
9. **修复**：`main.py` 未调用 `internal_ai.set_dispatcher()` 导致 Dispatcher 503

---

## 变更文件清单

### 删除（8 个死代码文件）

| 文件 | 原因 |
|------|------|
| `apps/backend/app/ai/apps/__init__.py` | 调用未定义的 `bailian.chat_json()`，死代码 |
| `apps/backend/app/ai/apps/app1_chat.py` ～ `app8_consolidation.py` | 同上，`run()` 从未被调用 |

### 新建

| 文件 | 说明 |
|------|------|
| `apps/backend/app/ai/prompts/__init__.py` | 导出 7 个 `build_app*_prompt` 函数 |
| `apps/backend/app/ai/prompts/app2_finance_prompt.py` | App2 财务数据拼 prompt |
| `apps/backend/app/ai/prompts/app3_clue_prompt.py` | App3 消费线索 prompt |
| `apps/backend/app/ai/prompts/app4_analysis_prompt.py` | App4 助教-会员分析 prompt |
| `apps/backend/app/ai/prompts/app5_tactics_prompt.py` | App5 话术 prompt（含 App4 结果） |
| `apps/backend/app/ai/prompts/app6_note_prompt.py` | App6 备注分析 prompt |
| `apps/backend/app/ai/prompts/app7_customer_prompt.py` | App7 客户画像 prompt |
| `apps/backend/app/ai/prompts/app8_consolidation_prompt.py` | App8 线索整合 prompt |
| `apps/backend/app/ai/references.py` | `_references` 注入 + `reference_card` 构建 |
| `apps/backend/app/ai/event_bus.py` | in-process pub/sub，site_id 隔离 |
| `apps/backend/app/ws/ai_events.py` | `/ws/ai-cache/{site_id}` + `/ws/ai-alerts/{site_id}` |
| `db/zqyy_app/migrations/20260420_ai_trigger_jobs_and_app2_prewarm.sql` | 4 事件 + 1 cron trigger_jobs，已执行 |
| `docs/database/BD_manual_ai_trigger_jobs_register.md` | 手动注册说明 |

### 修改

| 文件 | 关键变更 |
|------|----------|
| `apps/backend/app/ai/dispatcher.py` | 完整重构：调用 `prompts.build_*`，链式编排，EventBus 广播，_references 注入 |
| `apps/backend/app/ai/dashscope_client.py` | `call_app_stream` 返回 `(chunk, session_id)` tuple |
| `apps/backend/app/services/chat_service.py` | session_id 初始为 NULL，`save_session_id()` 保存百炼返回值 |
| `apps/backend/app/services/trigger_scheduler.py` | `_invoke_handler()` 修复 async handler 同步调用 bug |
| `apps/backend/app/services/task_generator.py` | `run()` 完成后触发 `ai_consumption_settled` 事件 |
| `apps/backend/app/services/note_service.py` | 备注创建后触发 `ai_note_created` |
| `apps/backend/app/routers/admin_task_engine.py` | 任务分配后触发 `ai_task_assigned` |
| `apps/backend/app/routers/internal_events.py` | ETL 完成后触发 `ai_dws_completed` |
| `apps/backend/app/routers/xcx_chat.py` | 解包 `(chunk, session_id)` 流，保存 session_id，写 reference_card |
| `apps/backend/app/routers/admin_ai.py` | 新增 `POST /api/admin/ai/run/{app_type}` 端点 |
| `apps/backend/app/schemas/admin_ai.py` | 新增 `RunAppRequest` / `RunAppResponse` |
| `apps/backend/app/services/ai/admin_service.py` | 缓存失效后广播 `cache_invalidated` 事件 |
| `apps/backend/app/main.py` | lifespan 补调 `internal_ai.set_dispatcher(_dispatcher)` |
| `apps/backend/pytest.ini` | 追加 `norecursedirs = _archived` |
| `apps/miniprogram/miniprogram/pages/chat/chat.ts` | referenceCard 点击跳转，pageFilters URL 解析；Phase 2.2 SSE 断线指数退避自动重连（最多 2 次） |
| `apps/miniprogram/miniprogram/pages/chat/chat.wxml` | referenceCard `bindtap` + 类型标签优化 |
| `apps/miniprogram/miniprogram/components/ai-float-button/ai-float-button.ts` | 新增 `sourcePage` + `pageFilters` 属性透传 |
| `apps/miniprogram/miniprogram/pages/board-finance/board-finance.ts` | `_loadAIInsights()` 从 `app2_finance` 缓存加载洞察 |
| `apps/miniprogram/miniprogram/pages/customer-detail/customer-detail.ts` | `_loadAIInsight()` 从 `app7_customer_analysis` 缓存加载 |
| `apps/miniprogram/miniprogram/services/api.ts` | 新增 `fetchAICache()` 函数 |

---

## E2E 验证结果

**消费事件链**（site_id=2790685415443269，member_id=2799212491392773）：

| App | 状态 | 延迟 |
|-----|------|------|
| app3_clue | timeout | 121s（prompt 过大，需优化） |
| app8_consolidate | **success** | ~15s，缓存已写入 |
| app7_customer | **success** | ~60s，缓存含真实 AI 分析 |

**缓存验证**：
- `app7_customer_analysis` result_json 含 `summary` + `strategies[{title,content}]`
- `app8_clue_consolidated` result_json 含 `_references`（link 正确拼装）
- board-finance AI 洞察已通过微信 MCP 验证在页面渲染（5 条真实 insight）

---

## 遗留风险点

1. **app3 超时（已缓解）**：`_MAX_PROMPT_LEN` 已从 8000 降至 4000，最多保留 3 条消费记录 + 二次截断 reference。待下次 E2E 验证是否仍超时。
2. **tokens_used = 0**：DashScope SDK 响应未提取 token 计数，影响预算追踪精度。需检查 `call_app` 的 usage 提取。
3. **dispatcher 内存去重**：`_dedup_set` 重启后丢失，生产环境需改为查 DB。
4. **task-detail aiAnalysis**：Phase 2.5 暂未实现，结构较复杂，待单独 session。
5. **admin-web Phase 3.2/4.1/4.2**：后端端点已就位，前端实现延后。

---

## 回滚策略

- 删除的 8 个 apps/ 文件在 git 历史可恢复：`git checkout <sha> apps/backend/app/ai/apps/`
- DB 迁移回滚：`DELETE FROM biz.trigger_jobs WHERE id >= 57;`
- `main.py` 新增一行可直接删除：`_internal_ai_router.set_dispatcher(_dispatcher)`