Neo-ZQYY/docs/audit/changes/2026-04-20__ai-module-complete.md

审计记录：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)