root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
ffe309e8018c27970ed4c5d72d631d8ae306e32f
Neo-ZQYY/docs/audit/changes/2026-04-20__ai-module-complete.md
Neo caf179a5da 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 逐一处理
2026-05-04 02:30:19 +08:00

111 lines
6.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 审计记录：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 View Git Blame Copy Permalink