feat: 2026-04-15~05-02 累积变更基线 — AI 重构 + Runtime Context + DWS 修复
涵盖（每条对应已存的审计记录）： - AI 模块拆分：apps/backend/app/ai/apps -> prompts/（8 个 APP + app2a 派生） audit: 2026-04-20__ai-module-complete.md - admin-web AI 管理套件：AIDashboard / AIOperations / AIRunLogs / AITriggers / TriggerManager audit: 2026-04-21__admin-web-ai-management-suite.md - App2 财务洞察 prompt v3 -> v5.1 + 小程序 AI 接入（chat / board-finance） audit: 2026-04-22__app2_prompt_v5_1_and_miniprogram_ai_insight.md - App2 prewarm 全过滤器 + AI 触发器 cron reschedule audit: 2026-04-21__app2-finance-prewarm-all-filters.md migration: 20260420_ai_trigger_jobs_and_app2_prewarm.sql / 20260421_app2_prewarm_cron_reschedule.sql - AppType 联合类型对齐 + adminAiAppTypes.test.ts audit: 2026-04-30__admin_web_ai_app_type_alignment.md - DashScope tokens_used 提取修复 audit: 2026-04-30__backend_dashscope_tokens_used_extraction.md - App3 线索完整详情 prompt audit: 2026-05-01__backend_app3_full_detail_prompt.md - Runtime Context 沙箱（5-1~5-2 主线）： - 后端 schema/service + admin_runtime_context / xcx_runtime_clock 两个 router - admin-web RuntimeContext.tsx + miniprogram runtime-clock.ts - migration: 20260501__runtime_context_sandbox.sql - tools/db/verify_admin_web_sandbox.py + verify_sandbox_end_to_end.py - database/changes: 7 份 sandbox_* 验证报告 - 飞球 DWS 修复：finance_area_daily 区域汇总 + task_engine 调整 + RLS 视图业务日上界（migration 20260502 + scripts/ops/gen_rls_business_date_migration.py） 合规： - .gitignore 启用 tmp/ 排除 - 不入仓：apps/etl/connectors/feiqiu/.env（API_TOKEN secret，本地修改保留） 待验证清单： - docs/audit/changes/2026-05-04__cumulative_baseline_pending_verification.md 每个主题的功能完整性 / 上线验证几乎都未收口，按优先级 P0~P3 逐一处理
This commit is contained in:
110
docs/audit/changes/2026-04-20__ai-module-complete.md
Normal file
110
docs/audit/changes/2026-04-20__ai-module-complete.md
Normal file
@@ -0,0 +1,110 @@
|
||||
# 审计记录：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)`
|
||||
Reference in New Issue
Block a user