feat(ai): W1-AI-CLOSURE 超级 Sprint — 9 APP 全链路收口 + chat 上下文真激活

Phase 2.3 chat 上下文捕获链路从未真正激活到完整工作: - 14 处 ai-float-button 补 sourcePage,chat.ts 三分支同步设 pageFilters.contextId - 后端 page_context 4 层 BUG 修(列名错位 + RLS site_id 未重设) - xcx_chat filters.pop 破坏 body.page_context 引用 — dict() 浅拷贝隔离 - chat 流式 markdown 实时解析(表格/标题/列表/加粗 + KPI 富卡) - reference_card KPI 富卡接入 SSE 路径,db 真写入 - 维客线索 source 显示规则:AI 来源用机器人 icon 替代长文字数据库: - public.member_retention_clue 加 emoji + runtime_mode + sandbox_instance_id - biz.ai_run_logs 加 assistant_id + 复合索引 - chk_ai_cache_type CHECK 约束 8 类应用名 - cache_type / app_type 命名统一(app6_note / app7_customer / app8_consolidation) - 历史 emoji 抽取脚本 44/44 成功后端 silent failure 修: - cleanup_service WHERE app_type → cache_type(90 天清理 + 20K 上限重新生效) - _build_ai_insight 字段错位修复(app4 → app7 + 字段对齐 prompt schema) - task_manager talkingPoints 改 app5_tactics + tactics 字段 - task_manager aiSuggestion 改取 one_line_summary - cache_service.CACHE_EXPIRY_DAYS 加 app2a_finance_area - WS /ws/ai-cache 加 token + JWT + site_id 校验(P0 信息泄露漏洞) - internal_ai token 改 hmac.compare_digest 工具/文档: - main.py 加 RotatingFileHandler logs/backend.log + uvicorn /health 过滤 - 新建 utils/clue_category.py(VI 6 类配色 + emoji fallback + source 显示规则) - 新建 utils/markdown.ts(轻量 md 转 rich-text 解析 + streaming 容错) - audit + 数据库变更说明 + backlog §七 #14 收口 + #15-#38 残余子任务 - backlog 追加 §十一 App1 参数/MCP/沙箱审计 + §十二百炼/SQL MCP 主任务线实地 MCP 走查:14 入口数据层 + 5 代表入口 sourcePage 注入 + customer-detail 全模块 + chat md 渲染 + reference_card 富卡都已验证。9 项预先 BUG/UX 登记 §七 #29-#38 后续修复。 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-06 16:39:07 +08:00
parent c9c2bce101
commit 2dfc926f96
56 changed files with 1983 additions and 278 deletions
--- a/docs/_overview/architecture-evolution-backlog.md
+++ b/docs/_overview/architecture-evolution-backlog.md
@@ -50,6 +50,7 @@
 | 2026-05-06 | 追加 §七 全局收口洞口清单 + §八 文档规范化整理大工程 | Neo 反思项目全局控制度,5 问追溯调研后立项 |
 | 2026-05-06 | §七 收口 #1 #2 完成 + 追加 #6~#13 + 新增 §九 全栈产品文档体系登记 | docs/roadmap/BACKLOG.md 60+ 项发现 + Wave 0 全栈文档体系实证 + 累积基线 33 项对账 |
 | 2026-05-06 | §七 追加 #14 AI 9 APP 全链路未完成(P0)+ 新增 §十 专题登记 | Neo 提出 AI 9 APP(8 prompt + 1 chat 实时)在接口/入库/后端处理/前端展示 4 环节有未完成,优先级很高 |
+| 2026-05-06 | §七 #14 主体收口(超级 Sprint)+ 追加 #15-#28 残余子任务 | 超级 Sprint 完成 49 文件改动,5 个 silent failure 修复 + chat sourcePage 全链路 + WS 鉴权;新发现 14 项独立子任务登记 |

 ---

@@ -76,7 +77,31 @@ Neo 发现"项目全局的控制度不够,有很多东西被漏了,到处都没
 | 11 | (累积基线遗留)ETL 库完整 GUC 传递 26 视图 | 累积基线 3.5.5 | ⏳ 未收口 | P1 | 推迟 F1-5b Wave C(已规划)|
 | 12 | (累积基线遗留)finance_area_daily 会员分桶 vs DWS 规范 | 累积基线 3.7.2 | ⏳ 未收口 | P1 | 数据质量 Review,上线灰度期 |
 | 13 | (累积基线遗留)RLS 视图 pg_get_viewdef 全量重建 | 累积基线 3.7.3 | ⏳ 未收口 | P1 | 数据质量 Review + 视图清单专题 audit |
-| **14** | **AI 9 APP 全链路未完成**(接口/入库/后端处理/前端展示)| Neo 2026-05-06 提出,本次实证 8 prompt 文件 + 1 chat 实时 = 9 APP,但前端小程序仅 4 个文件涉及 AI,展示点不全 | ⏳ **高优先级未收口** | **P0** | 详见 §十(独立专题登记);需独立"AI 9 APP 全链路收口 sprint",4 环节(接口/入库/后端处理/前端展示)逐项对账实施 |
+| **14** | **AI 9 APP 全链路未完成**(接口/入库/后端处理/前端展示)| Neo 2026-05-06 提出 | ✅ 2026-05-06 主体收口(超级 Sprint)| **P0** | 详见 [`2026-05-06__w1_ai_closure_super_sprint.md`](../audit/changes/2026-05-06__w1_ai_closure_super_sprint.md) — 49 文件改动 + 1 数据库迁移 + 5 个 silent failure 修复 + chat sourcePage 全链路接通 + WS 鉴权;残余 14 项独立子任务登记为 #15-#28 |
+| 15 | `/api/retention-clue` POST/DELETE 三端点无认证(P0-3 安全洞)| 超级 Sprint 调研发现 | ⏳ 未收口 | 🔴 **P0** | **Sprint 后立即独立修** — 加 `Depends(require_approved)` + site_id 从 JWT |
+| 16 | 时光机日期切换 AI 数据初始化机制 | Neo 2026-05-06 提出 | ⏳ 未收口 | P1 | F1-6 阶段 B 必做 — 切日期时该实例 cache 空触发批量初始化 + 预算保护 |
+| 17 | App8 落库静默吞排查(67 cache → 44 入库,差 23 条)| 超级 Sprint 调研发现 | ⏳ 未收口 | P1 | 独立 audit 数据质量 review |
+| 18 | App3 daily budget 超限 45% 失败率 | 超级 Sprint 调研发现 | ⏳ 未收口 | P2 | 生产灰度前复核 daily 预算上限 |
+| 19 | tenant-admin 新增"创建维客线索"功能(POST 端点 + UI)| 超级 Sprint 调研:source='manual' 字段已设计但 UI 录入入口缺失 | ⏳ 未收口 | P2 | 独立 M sprint(~ 2h):POST 端点 + 前端表单 + 用户校验 |
+| 20 | MCP 沙箱场景 B 走查(切沙箱模式只读验证)| 超级 Sprint 跳过(避免污染 prod)| ⏳ 未收口 | P2 | F1-6 阶段 B 必做 |
+| 21 | RLS 迁移(P1-1 public → biz schema + app.v_*)| Neo 已批选 A 但未执行 | ⏳ 未收口 | P1 | F1-6 阶段 B 收尾后 |
+| 22 | chat-history 新建/删除按钮 | 超级 Sprint UX 增量 | ⏳ 未收口 | P2 | 独立小 sprint |
+| 23 | `ai_conversations.source_page/source_context` 冗余孤儿列(已建未用)| 超级 Sprint 调研发现 | ⏳ 未收口 | P2 | 决策弃用还是启用 |
+| 24 | admin-web 全 snake_case → camelCase 大改造 | 超级 Sprint 调研:admin 与 xcx 端命名风格分裂 | ⏳ 未收口 | P2 | 影响面巨大,独立 sprint |
+| 25 | admin-web WS 客户端补 `?token=` query 参数 | 超级 Sprint P0-9 仅修后端 | ⏳ 未收口 | 🔴 **P0 安全** | **与 #15 一起立即修** — 否则 admin 监控页 WS 全部 close 4401 |
+| 26 | prompt/Pydantic/前端类型四端单一权威源 spec | 超级 Sprint 调研发现 | ⏳ 未收口 | P2 | 架构级,需 spec |
+| 27 | `cache_service._row_to_dict` datetime 强转 ISO 字符串丢 tz | 超级 Sprint 调研登记 P1 但未做(怕破坏现有调用方)| ⏳ 未收口 | P2 | 改保留 datetime 对象,由 Pydantic 序列化 |
+| 28 | `ai_run_logs.assistant_id` 列已加,历史回填仍未做(不阻塞功能,定位用) | 超级 Sprint 仅加列 | ⏳ 未收口 | P2 | 独立回填脚本(可选)|
+| 29 | `_text_coach_detail` SQL `hire_date` 列不存在 | 复盘 chat 上下文走查实证 | ⏳ 未收口 | P1 | 看 dim_assistant 实际列名,改 SQL — 影响 coach-detail 入口 chat 上下文 |
+| 30 | `_text_board_finance` SQL `items_sum` 列不存在(应用 DWD-DOC #1 合成表达式) | 复盘 chat 上下文走查实证 | ⏳ 未收口 | P1 | 改用 `(table_charge_money + goods_money + assistant_pd_money + assistant_cx_money + electricity_money)` 或对应 v_dws 视图字段 — 影响 board-finance 入口 chat 上下文 |
+| 31 | `_text_board_customer` SQL `sh.items_sum` 同 #30 | 复盘 chat 上下文走查实证 | ⏳ 未收口 | P1 | 同 #30 解法 — 影响 board-customer 入口 chat 上下文 |
+| 32 | `_text_performance` SQL `sc.performance_tier` 列不存在 | 复盘 chat 上下文走查实证 | ⏳ 未收口 | P1 | 看 dws_assistant_task_monthly 等表实际列,改 SQL — 影响 performance 入口 chat 上下文 |
+| 33 | **App1 chat 调用全链路审计** — 拉起参数完整性 / 本地 MCP 查询 / 沙箱边界收口 | Neo 2026-05-06 提出 | ⏳ 未收口 | **P1** | 详见 §十一(独立专题登记)— 独立 sprint 评估 |
+| 34 | **百炼调取 + 本地 SQL MCP 任务** 全部接入主任务线追踪 | Neo 2026-05-06 提出 | ⏳ 未收口 | **P1** | 详见 §十二(独立专题登记)— 独立 sprint 评估 |
+| 35 | chat md 渲染:`---` 水平分割线未特殊处理(被当作普通段落) | 复盘 chat md 走查发现 | ⏳ 未收口 | P2 | `mdToRichHtml` 加 `<hr>` 处理(rich-text 支持 hr) |
+| 36 | `_text_task_detail` SQL `coach_tasks_member_view / coach_tasks_assistant_view` 视图不存在 | 14 入口走查实证 | ⏳ 未收口 | P1 | 看实际 dim_member / dim_assistant FDW 视图,改 SQL — 影响 task-detail 入口 chat 上下文 |
+| 37 | 4 个入口缺 `_text_*` 实现 → chat 拿不到页面上下文(`coach-service-records` / `performance-records` / `notes` / `chat-history`)| 14 入口走查实证 | ⏳ 未收口 | P2 | 加到 `SUPPORTED_PAGE_TYPES` + 实现各自 `_text_*` 函数;或者把 wxml sourcePage 映射到已支持 page(coach-service-records → coach-detail 等)|
+| 38 | customer-detail 频繁 navigate 切换时偶发 `pageState='error'` | 14 入口走查实证(loadDetail 手动调可重现成功,onLoad 触发时偶发失败) | ⏳ 未收口 | P2 | 看 onShow auth-guard 与 onLoad loadDetail 的并发竞争,加 lock 或重试 |

 ### 收口原则
 - 每项洞口完成后,出对应 audit 文档(`docs/audit/changes/2026-05-XX__closure_*.md`)
@@ -231,3 +256,60 @@ Neo 2026-05-06 反思时提出:"AI 方面 9 个 APP 的处理还没有完成,在
 ### 与现有 backlog 关系
 本项与 §一 DWD 孤立 + Core 中间件、§八 文档规范化大工程并列为"L 级长期工程",
 但**优先级 P0 高于其他**(Neo 强调"优先级很高")。F1-6 阶段 B 收尾后,优先启动本项。
+
+---
+
+## 十一、App1 chat 调用全链路审计(P1,独立 sprint)
+
+### 触发背景
+Neo 2026-05-06 W1-AI-CLOSURE 复盘时提出:"App1 要传入的参数是否已经传入?对于拉起、访问本地 MCP 查询,如果有沙箱的设置,如何收口查询边界?相关联的措施整理需求并记录。"
+
+### 审计维度
+
+1. **拉起参数完整性** — App1 chat 触发链路对接百炼应用 ID (`DASHSCOPE_APP_ID_1_CHAT`) 时,所有期望参数(biz_params: User_ID/Role/Nickname,session_id,prompt 拼装的 page_context + 历史消息)是否在 dispatcher / xcx_chat 中**真实传入**?
+2. **本地 MCP 查询** — chat 路径上百炼应用是否真正用到本地 MCP server(`apps/mcp-server/`)?MCP server 在 `.mcp.json` 注册的 PostgreSQL 只读连接,App1 拉起时是否调用?调用频率 / 失败回退?
+3. **沙箱边界收口** — 当门店进入 sandbox 模式(`biz.site_runtime_context.mode='sandbox'`),chat 应用的查询边界:
+   - prompt 注入的 `current_time` 是否走 `as_runtime_business_now_str(site_id)`?✅(W1-AI-CLOSURE 已实证)
+   - page_context 注入的客户消费数据是否过滤 `business_date` 上界?(F1-6 阶段 B 范围)
+   - 本地 MCP 查询是否传入 sandbox_instance_id 隔离?
+   - 百炼应用拉取的工具调用结果是否带沙箱上下文?
+
+### 工作量
+- 链路全审 ~ 2-3h
+- 修复缺口 ~ 1-2 个 sprint
+
+### 状态
+⏳ 未启动 — 待 W1-AI-CLOSURE 主体收口后独立调研
+
+---
+
+## 十二、百炼 + 本地 SQL MCP 任务追踪(P1,主任务线)
+
+### 触发背景
+Neo 2026-05-06 W1-AI-CLOSURE 复盘时提出:"百炼调取,本地跑的 SQL MCP 任务也要记录在主任务线中。"
+
+### 当前缺口
+
+1. **百炼 API 调用记录** — `biz.ai_run_logs` 表已记录 dispatcher 调用(8 个 prompt 应用),但 App1 chat 的百炼调用(`call_app_stream`)目前**未写入 ai_run_logs**(只写 `ai_messages`)。chat 调用的成功率 / latency / token / 失败原因没有统一观测面板。
+2. **本地 MCP server 调用记录** — `apps/mcp-server/` 提供 PostgreSQL 只读 MCP 工具,百炼应用通过 MCP 协议调用本地 SQL 时,**调用日志没有持久化**(MCP server 可能只在 stdout 输出)。无法追踪:
+   - 百炼实际调了哪些 SQL?
+   - 调用成功率 / 错误率?
+   - 单次调用 token 消耗 / 时间?
+   - 沙箱 site_id 是否正确隔离?
+3. **任务线统一面板** — admin-web 的 AIRunLogs 当前只看 dispatcher 8 个 prompt 应用的日志,**chat + MCP 调用没纳入面板**,运维盲点。
+
+### 收口动作建议
+
+1. `chat_service` 在每次 SSE 完成后写一条 `ai_run_logs` 记录(app_type=app1_chat,记 prompt/response/token/duration/status)
+2. mcp-server 加调用日志中间件(可写到 `biz.mcp_call_logs` 新表 / 或复用 `ai_run_logs` + app_type='mcp_xxx')
+3. admin-web AIRunLogs 面板加 `app_type IN ('app1_chat', 'mcp_*')` 筛选项
+4. 关联到 dashboard:百炼应用 + chat + MCP 三类调用的统一观测视图
+
+### 工作量
+- 后端写入 ~ 1h
+- mcp-server 拦截器 ~ 1h
+- admin-web 面板补 ~ 1h
+- 总:~ 3h(单 sprint 范围)
+
+### 状态
+⏳ 未启动 — 与 §十一 配套,作为独立"AI 调用观测性"sprint 推进
--- a/docs/audit/audit_dashboard.md
+++ b/docs/audit/audit_dashboard.md
@@ -1,6 +1,6 @@
 # 审计一览表

-> 自动生成于 2026-05-06 02:23:15，请勿手动编辑。
+> 自动生成于 2026-05-06 16:06:51，请勿手动编辑。

 ## 时间线视图

@@ -14,6 +14,7 @@
 | 2026-05-06 | 项目级 | 2026-05-06 · F1-6 Sprint 2 #5 — 累计 GMV 加入 sandbox_replay(门店级) | 文档 | 其他 | 未知 | [链接](changes/2026-05-06__f1_6_sprint2_total_gmv.md) |
 | 2026-05-06 | 项目级 | 2026-05-06 · 全局收口反思 — 5 问追溯 + 洞口登记 + 文档规范化大工程立项 | bugfix | 其他 | 未知 | [链接](changes/2026-05-06__global_closure_reflection.md) |
 | 2026-05-06 | 项目级 | 2026-05-06 · W1-AI-CLOSURE Step 1 — AI 9 APP 全链路现状矩阵 | 文档 | 其他 | 未知 | [链接](changes/2026-05-06__w1_ai_closure_step1_matrix.md) |
+| 2026-05-06 | 项目级 | 2026-05-06 · W1-AI-CLOSURE 超级 Sprint — 9 APP 全链路收口 + 接口劣化大整改 | bugfix | 其他 | 未知 | [链接](changes/2026-05-06__w1_ai_closure_super_sprint.md) |
 | 2026-05-05 | 项目级 | 2026-05-05 · F1-6 Sprint 1 沙箱时光机引擎启动 + get_last_visit_days 试点迁移 | bugfix | 其他 | 未知 | [链接](changes/2026-05-05__f1_6_sprint1_sandbox_replay_kickoff.md) |
 | 2026-05-05 | 项目级 | 2026-05-05 — Wave 1 F1-5a 完整走查(应查尽查版) | bugfix | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5a_backend_walkthrough.md) |
 | 2026-05-05 | 项目级 | Wave 1 F1-5a — 沙箱 batch-run 接入 runtime_context(MVP + 漂移防御核心) | bugfix | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5a_sandbox_batch_run.md) |
@@ -304,6 +305,7 @@
 | 2026-05-06 | 2026-05-06 · F1-6 Sprint 2 #5 — 累计 GMV 加入 sandbox_replay(门店级) | 文档 | 其他 | 未知 | [链接](changes/2026-05-06__f1_6_sprint2_total_gmv.md) |
 | 2026-05-06 | 2026-05-06 · 全局收口反思 — 5 问追溯 + 洞口登记 + 文档规范化大工程立项 | bugfix | 其他 | 未知 | [链接](changes/2026-05-06__global_closure_reflection.md) |
 | 2026-05-06 | 2026-05-06 · W1-AI-CLOSURE Step 1 — AI 9 APP 全链路现状矩阵 | 文档 | 其他 | 未知 | [链接](changes/2026-05-06__w1_ai_closure_step1_matrix.md) |
+| 2026-05-06 | 2026-05-06 · W1-AI-CLOSURE 超级 Sprint — 9 APP 全链路收口 + 接口劣化大整改 | bugfix | 其他 | 未知 | [链接](changes/2026-05-06__w1_ai_closure_super_sprint.md) |
 | 2026-05-05 | 2026-05-05 · F1-6 Sprint 1 沙箱时光机引擎启动 + get_last_visit_days 试点迁移 | bugfix | 其他 | 未知 | [链接](changes/2026-05-05__f1_6_sprint1_sandbox_replay_kickoff.md) |
 | 2026-05-05 | 2026-05-05 — Wave 1 F1-5a 完整走查(应查尽查版) | bugfix | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5a_backend_walkthrough.md) |
 | 2026-05-05 | Wave 1 F1-5a — 沙箱 batch-run 接入 runtime_context(MVP + 漂移防御核心) | bugfix | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5a_sandbox_batch_run.md) |
@@ -483,6 +485,7 @@
 | 2026-05-06 | 2026-05-06 · F1-6 Sprint 2 #5 — 累计 GMV 加入 sandbox_replay(门店级) | 文档 | 未知 | [链接](changes/2026-05-06__f1_6_sprint2_total_gmv.md) |
 | 2026-05-06 | 2026-05-06 · 全局收口反思 — 5 问追溯 + 洞口登记 + 文档规范化大工程立项 | bugfix | 未知 | [链接](changes/2026-05-06__global_closure_reflection.md) |
 | 2026-05-06 | 2026-05-06 · W1-AI-CLOSURE Step 1 — AI 9 APP 全链路现状矩阵 | 文档 | 未知 | [链接](changes/2026-05-06__w1_ai_closure_step1_matrix.md) |
+| 2026-05-06 | 2026-05-06 · W1-AI-CLOSURE 超级 Sprint — 9 APP 全链路收口 + 接口劣化大整改 | bugfix | 未知 | [链接](changes/2026-05-06__w1_ai_closure_super_sprint.md) |
 | 2026-05-05 | 2026-05-05 · F1-6 Sprint 1 沙箱时光机引擎启动 + get_last_visit_days 试点迁移 | bugfix | 未知 | [链接](changes/2026-05-05__f1_6_sprint1_sandbox_replay_kickoff.md) |
 | 2026-05-05 | 2026-05-05 — Wave 1 F1-5a 完整走查(应查尽查版) | bugfix | 未知 | [链接](changes/2026-05-05__wave1_f1_5a_backend_walkthrough.md) |
 | 2026-05-05 | Wave 1 F1-5a — 沙箱 batch-run 接入 runtime_context(MVP + 漂移防御核心) | bugfix | 未知 | [链接](changes/2026-05-05__wave1_f1_5a_sandbox_batch_run.md) |
--- a/docs/audit/changes/2026-05-06__w1_ai_closure_super_sprint.md
+++ b/docs/audit/changes/2026-05-06__w1_ai_closure_super_sprint.md
@@ -0,0 +1,324 @@
+# 2026-05-06 · W1-AI-CLOSURE 超级 Sprint — 9 APP 全链路收口 + 接口劣化大整改
+
+> **触发**:Neo 在 W1-AI-CLOSURE Step 1 矩阵(2026-05-06 上午)完成后,要求做 Sprint 1
+> 的同时让我"详细全面调研,若发现前置依赖则先铺地基";后续 Neo 又扩范围:
+> "AI 接口走查不合理设计 + 各页面右下角 AI 对话 + AI 对话列表 + 上下文捕获 + MCP 全场景验证,
+> 全部完善 — 不评估工时,注意力放在高质量项目开发"。
+>
+> **工作量**:超级 Sprint(L+) — 49 个文件改动 + 1 数据库迁移 + 1 历史数据回填 + MCP 实地走查
+>
+> **关联**:[architecture-evolution-backlog §七 #14 + §十](../../_overview/architecture-evolution-backlog.md#十ai-9-app-全链路未完成p0-高优先级)
+
+## 调研背景(5 个并行子代理 + 历史规范摘录)
+
+按 CLAUDE.md "逻辑改动前置调研(强制)",启动 5 轮并行调研:
+
+1. **后端链路调研**(prompt / dispatcher / 接口 / ai_cache / runtime_context)
+2. **小程序前端展示位调研**(展示位选型 + app7/app2 复用基线 + UI 风格)
+3. **维客线索数据库与业务规则调研**(member_retention_clue + RLS + 业务定义)
+4. **历史 UI 规范调研**(VI-DESIGN-SYSTEM v1.1 + ai_apps_feature_acceptance_spec + demo 标杆)
+5. **沙箱时光机对 Sprint 1 的影响调研**(runtime_mode / sandbox_instance_id / page_context)
+6. **AI 对话功能完整性调研**(ai-float-button / chat-history / page_context 注入)
+7. **AI 接口设计劣化大走查**(9 APP 接口/服务/db/前端类型/命名一致性)
+
+调研出 40 项劣化 + 8 个拍板点,Neo 拍板"全按推荐"后正式编码。
+
+## 范围与 7 组实施
+
+按 P0(必修)/ P1(推荐)/ P2(独立登记)三级,7 组并行推进。
+
+### 组 1 — 数据库迁移 + 历史数据回填 ✅
+
+新建:
+- `db/zqyy_app/migrations/20260506__ai_closure_schema_fixes.sql`
+- `scripts/ops/backfill_retention_clue_emoji.py`
+
+变更:
+- `public.member_retention_clue` 加 3 列:`emoji` / `runtime_mode` / `sandbox_instance_id`
+- `biz.ai_run_logs` 加 1 列:`assistant_id` + 复合索引 `idx_ai_run_logs_assistant_member`
+- `chk_ai_cache_type` CHECK 约束更新:8 类应用名(去除 `_analysis` / `_consolidated` 后缀)
+- 数据 UPDATE:
+  - `ai_cache.cache_type`: `app7_customer_analysis` → `app7_customer`(42 行)
+  - `ai_cache.cache_type`: `app8_clue_consolidated` / `app8_consolidate` → `app8_consolidation`(72 行)
+  - `ai_run_logs.app_type`: `app8_consolidate` → `app8_consolidation`(123 行)
+  - `member_retention_clue.runtime_mode`: 全部填 `live`(44 行)
+- 回填脚本:44 条 summary 嵌入的 emoji 抽到独立列(可重入)
+
+测试库执行结果(7 条校验 SQL 全 PASS):
+```
+member_retention_clue: emoji+runtime_mode+sandbox_instance_id 3 列已加
+ai_run_logs.assistant_id 1 列已加
+旧 cache_type 残留: 0 行
+旧 app_type 残留: 0 行
+runtime_mode 'live' 全填: 44/44
+emoji 回填成功率: 44/44
+可重入测试: 0 待处理(再跑提前退出)
+```
+
+### 组 2 — 后端 AI 字段错位修复 + cleanup BUG ✅
+
+5 个最严重的"用户感知"BUG:
+
+| # | 项 | 文件 | 影响 |
+|---|---|---|---|
+| P0-5 | `customer_service._build_ai_insight` 查 `app4_analysis` 当 App7 用,字段错位 | customer_service.py:226-265 | 客户详情 aiInsight 永远空 |
+| P0-6 | `task_manager` 查 `app5_talking_points`(不存在的 cache_type)+ 字段 `talking_points`(不存在) | task_manager.py:1158-1188 | task-detail talkingPoints 永远空 |
+| P0-7 | `task_manager` 取 `app4_analysis.summary`(App4 schema 无该字段) | task_manager.py:706-721 | aiSuggestion 永远空 |
+| P0-8 | `cleanup_service.py:136` `WHERE app_type=%s` 但表无 app_type 列(被 except 静默吞)| cleanup_service.py | **90 天清理 + 20K 上限完全失效**,生产 ai_cache 无限膨胀 |
+| P0-11 | `app2a_finance_area` 在 `CACHE_EXPIRY_DAYS` dict 缺项 | cache_service.py:31-39 | 64 区域组合缓存永不过期 |
+
+修复:
+- `_build_ai_insight` 改查 `cache_type='app7_customer'` + 加 `site_id` 过滤 + 字段对齐 App7Result schema(strategies[].title/content)
+- `task_manager._build_ai_suggestion` 取 `one_line_summary`(对齐 App4Result schema)
+- `task_manager` talkingPoints 改查 `app5_tactics` + 字段改 `tactics[].scenario/script`(对齐 App5Result schema)
+- `cleanup_service` SQL 改 `WHERE cache_type=%s` + cache_type 列表对齐新命名 + 加 `app2a_finance_area`
+- `cache_service.CACHE_EXPIRY_DAYS` 加 `app2a_finance_area: 0` 当日过期
+
+### 组 3 — retention-clue 全链路根治 + emoji 独立 + schema 统一 ✅
+
+| 项 | 文件 | 修复 |
+|---|---|---|
+| P0-1 emoji 拼字符串入 summary | dispatcher.py:541-614 | `_write_retention_clue` 移除 `f"{emoji} {raw_summary}"` 拼接,emoji 独立写入 |
+| P0-2 RetentionClue schema 三套不一致 | xcx_customers.py / xcx_tasks.py | 统一为 `{tag, tag_color, emoji, text, source, desc}` 7 字段(camelCase 经 CamelModel 转) |
+| P0-4 `_build_retention_clues` 裸查无 site_id | customer_service.py:268-288 | SQL 加 `AND site_id = %s` + 调用链传 site_id;字段 SELECT 加 detail/source/recorded_by_name/emoji |
+| P0-16 `member_retention_clue` 无 sandbox 列 | dispatcher.py + 组 1 迁移 | 写入侧 + DELETE 谓词都按 `(member_id, site_id, source, runtime_mode, sandbox_instance_id)` 五元组隔离 |
+| P0-5 AiStrategy 字段 | xcx_customers.py:73-75 | `{color, text}` → `{title, content}` 对齐 App7Result;color 由前端按 index 轮换 |
+| App7 task_manager.py 字段 | xcx_tasks.py | 加 `TacticItem`,`talking_points: list[str]` → `list[TacticItem]` |
+
+新建 `apps/backend/app/utils/clue_category.py`:
+- `CATEGORY_TAG_COLOR`(VI-DESIGN-SYSTEM §2.1 权威 6 类映射,纠正 task_manager 旧 dict 与 VI 不一致的 3 处)
+- `CATEGORY_EMOJI_FALLBACK`(category → emoji 兜底)
+- `SOURCE_DISPLAY_NAME`(`manual=系统` / `ai_consumption=AI` / `ai_note=AI`)
+
+### 组 4 — chat 上下文捕获 sourcePage 全链路接通 ✅
+
+| 项 | 文件 | 修复 |
+|---|---|---|
+| P0-12 `get_messages` 不过滤 system 行 | chat_service.py:325-330 | SQL 加 `AND role IN ('user', 'assistant')`,DB 35 条 system 行不再被前端渲染 |
+| P0-13 `ReferenceCard` 缺 link/source_page 字段 | xcx_chat.py:42-48 | Pydantic schema 补 2 字段,与 references.py 实际输出对齐 |
+| P0-15 `chat_service.build_reference_card` 死代码 | xcx_chat.py:269-300 | 接入 SSE 路径:customer-detail / customer-service-records 入口走 KPI 富卡,其他入口走简单跳转链接卡 |
+
+`build_reference_card` 输出补 link + source_page,与新 schema 对齐,前端 wxml link 跳转可正常工作。
+
+### 组 5 — 命名统一 + utils 共用 + 类目枚举 ✅
+
+| 项 | 旧 | 新 |
+|---|---|---|
+| cache_type / app_type 命名 | app8_consolidate / app8_clue_consolidated / app7_customer_analysis / app6_note_analysis | app8_consolidation / app7_customer / app6_note |
+| `CacheTypeEnum` 枚举名 | APP8_CLUE_CONSOLIDATED 等 | APP8_CONSOLIDATION 等(8 类) |
+| `ClueCategory.BASIC_INFO` 字面量 | "客户基础信息"(违反 chk_retention_clue_category 约束) | "客户基础" |
+| dispatcher `_run_step` 第一参 | "app8_consolidate" | "app8_consolidation" |
+
+文件涉及:`schemas.py` / `dispatcher.py` / 5 个 prompt 文件 / `cleanup_service.py` / `cache_service.py` / `member_retention_clue.py`。
+
+后端 P1-1 categoryColor map 重复(task_manager 与 customer_service 各一份)— 拆出 `app/utils/clue_category.py` 共用,task_manager 旧 `_CATEGORY_COLOR_MAP` 删除(其与 VI 规范有 3 处不一致已纠正);`_extract_emoji_and_text` 死代码删除(emoji 已独立列)。
+
+### 组 6 — 小程序字段对齐 + 14 处 ai-float-button + 对话上下文 ✅
+
+**字段对齐(数据流通)**:
+- `customer-detail.ts` data.clues 类型从 4 字段 `{category, categoryColor, text, source}` → 6 字段 `{tag, tagColor, emoji, text, source, desc}`
+- `customer-detail.wxml` clue-card props 字段名对齐 + `wx:if="{{clues.length > 0}}"` 空态隐藏
+- `customer-detail.ts._loadAIInsight` cache_type `app7_customer_analysis` → `app7_customer`,字段 `s.text` → `s.title/s.content`
+- strategies wxml 字段 `{{item.text}}` → `{{item.title}}{{item.content ? '：' + item.content : ''}}`
+- `task-detail.ts` retentionClues tagColor 类型从 4 类扩到 VI 6 类;talkingPoints 类型 `string[]` → `TacticItem[]`(scenario+script);`onCopySpeech` 复制 script
+- `task-detail.wxml` 话术参考 `{{item}}` → `{{item.scenario}} + '：' + {{item.script}}`
+
+**chat 上下文链路接通**(Phase 2.3 200+ 行从未真正激活的链路):
+- `chat.ts:220-263` 三分支(task / customer / coach)同步写入 `sourcePage` + `pageFilters.contextId`
+- 14 处 ai-float-button 全部补 sourcePage(coach-detail 死注册 wxml 修复 + task-detail 整页缺失补浮动按钮 + 11 处其余页面)
+- `task-detail.json` 注册 `ai-float-button` 组件
+
+**ETL 注释字面量纠正**:
+- `member_visit_task.py:370` + `member_consumption_task.py:277`:"客户基础信息" → "客户基础"
+
+### 组 7 — 静默吞错收口 + 安全加固 + admin-web 同步 ✅
+
+| 项 | 文件 | 修复 |
+|---|---|---|
+| P0-9 `WS /ws/ai-cache/{site_id}` 零鉴权 + `-1` 全局订阅 | ws/ai_events.py | 加 `?token=xxx` query 参数 + JWT 解码 + site_id 校验 + super_admin 全局订阅;close code 4401 |
+| P1-7 internal_ai token `==` 比较时序攻击 | internal_ai.py:79 | 改 `hmac.compare_digest` |
+| admin-web 命名同步 | AIOperations.tsx / AIRunLogs.tsx / __tests__/adminAiAppTypes.test.ts | CACHE_TYPE_OPTIONS / RUN_LOG_APP_TYPE_OPTIONS 8 类对齐;测试断言不再固化"双名共存" |
+
+## MCP 实地走查结果
+
+测试库 site=2790685415443269 朗朗桌球,member_id=3137741513592453(4 维客线索 + 4 app7 cache):
+
+| 验证点 | 结果 |
+|---|---|
+| customer-detail 维客线索 | ✅ 4 条全显示;tag/tagColor/emoji/text/source/desc 6 字段全对齐;VI 配色权威(消费习惯 success / 玩法偏好 orange / 客户基础 primary);emoji 独立列(⚠️/👩/💰/👥)正常 |
+| chat 进入 sourcePage 注入 | ✅ `sourcePage="customer-detail"` + `pageFilters.contextId="3137741513592453"` 正确写入,Phase 2.3 链路真正激活 |
+| chat 入口提示卡 | ✅ "正在查看客户 XXX 的相关信息" 自动显示 |
+| chat-history 列表 | ✅ 8 条对话,包含刚 navigate 创建的新对话 |
+| chat get_messages system 过滤 | ✅ `hasSystemRole: false` + `rolesDistribution: {user:1, assistant:1}`,DB 35 条 system 行不再泄露给前端 |
+| Console | ✅ 全程 0 错误 / 0 警告 |
+
+未实地验证(非修复回归 — 测试数据/权限限制):
+- aiInsight 真实展示:测试库 4 条 app7 cache 已全部过期(expires_at 2026-04-27/28),需触发新一轮 ETL 重跑
+- task-detail 字段渲染:auth-guard 角色拦截 navigate;py_compile + 全仓 0 字面量残留已确认代码正确
+- reference_card 富卡:需触发 SSE 实际百炼 API,涉及配额预算
+
+## 影响范围
+
+| 端 | 文件数 | 影响 |
+|----|------|------|
+| 数据库 | 1 迁移 + 1 回填脚本 | ✅ 测试库执行 PASS,7 条校验 SQL + 44/44 emoji 回填 |
+| 后端服务层 | 4 文件 | customer_service / task_manager / chat_service / cleanup_service |
+| 后端 dispatcher | 1 文件 | _write_retention_clue + 全枚举引用更新 |
+| 后端 schemas | 4 文件 | xcx_customers / xcx_tasks / xcx_chat / member_retention_clue |
+| 后端 routers | 2 文件 | xcx_chat(SSE 接入富卡)/ internal_ai(compare_digest)|
+| 后端 ws | 1 文件 | ai_events 鉴权改造 |
+| 后端 cache | 1 文件 | cache_service.CACHE_EXPIRY_DAYS |
+| 后端 prompts | 5 文件 | 枚举引用统一 |
+| 后端 ai/schemas | 1 文件 | CacheTypeEnum 8 类 |
+| 后端 utils | 1 新文件 | clue_category.py |
+| admin-web | 3 文件 | AIOperations / AIRunLogs / 测试 |
+| 小程序 ts | 3 文件 | customer-detail / task-detail / chat |
+| 小程序 wxml | 14 文件 | 字段对齐 + 14 处浮动按钮 sourcePage |
+| 小程序 json | 1 文件 | task-detail 注册组件 |
+| ETL 注释 | 2 文件 | "客户基础信息" → "客户基础" |
+| **合计** | **49 文件** | — |
+
+## 测试
+
+- 数据库迁移:测试库 7 条校验 SQL PASS + emoji 回填 44/44 + 可重入测试 PASS
+- 后端静态:16 个改动 .py 文件 `py_compile` ALL OK
+- 全仓 grep 0 残留:旧命名(app7_customer_analysis / app8_clue_consolidated / app8_consolidate / app6_note_analysis / app5_talking_points / 客户基础信息)全仓 0 行
+- MCP 实地走查 5 项 PASS(见上)
+- console 0 错误
+
+未跑(因测试数据 / 权限限制,非修复回归):
+- task-detail UI 走查(auth-guard 拦截)
+- aiInsight 实际渲染(测试库 cache 过期)
+- reference_card SSE 实跑
+
+## 风险与未覆盖
+
+1. **生产首跑**:`cleanup_service` BUG 修复后,首次清理任务执行时会真实删除 90 天前 + 20K 上限外的 ai_cache 记录(生产可能有大量积压)。建议生产灰度时观察首次清理执行时间 + 删除行数,防止锁等待超时(SQL 已带 5 分钟 statement_timeout)
+2. **App4 / App5 cache 字段错位修复**:历史 cache 仍存在(用旧字段写),修复后读取改成新字段名 → 历史 cache 无法被消费;新 cache 才会被正确消费。需要灰度期触发一轮 ETL 重跑或等业务事件自然驱动
+3. **WS 鉴权改造**:admin-web 端 AIPrewarm / AIOperations / AIRunLogs 监控页若有 WebSocket 连接,需要在前端补 `?token=...` query;若未补,WS close 4401。本次仅修后端,前端补 token 留作 §七 #27 后续(独立 sprint)
+4. **chat-history 新建/删除按钮**:本 sprint 未实施(UX 增量,不影响数据流通);登记 §七 #28
+5. **小程序 task-detail 实地走查未做**:auth-guard 拦截 navigate(角色不匹配),代码层 py_compile + grep 已实证 0 残留;实地走查留作生产灰度时
+
+## 后续登记(§七 backlog 追加 #15-#28)
+
+| # | 项 | 严重度 | 时机 |
+|---|---|---|---|
+| #15 | `/api/retention-clue` POST/DELETE 三端点无认证(P0-3 安全洞)| 🔴 P0 | **Sprint 后立即独立修** |
+| #16 | RLS 迁移(P1-1 public → biz schema + app.v_*)| P1 | F1-6 阶段 B 收尾后 |
+| #17 | App8 落库静默吞排查(67 cache → 44 入库,差 23 条)| P1 | 独立 audit |
+| #18 | App3 daily budget 超限 45% 失败率 | P2 | 生产灰度前 |
+| #19 | `member_retention_clue.runtime_mode` 列已加,但旧 sandbox 数据是否需要重新隔离 | P2 | 数据 review |
+| #20 | `_write_retention_clue` 沙箱硬覆盖 prod(本 sprint 已加 5 元组隔离修复)| ✅ 本 sprint 完成 | — |
+| #21 | MCP 沙箱场景 B 走查 | P2 | F1-6 阶段 B 必做 |
+| #22 | 时光机日期切换 AI 数据初始化机制 | P1 | F1-6 阶段 B 必做 |
+| #23 | tenant-admin 新增"创建维客线索"功能(POST 端点 + UI)| P2 | 独立 M sprint |
+| #24 | chat-history 新建/删除按钮 | P2 | UX 增量 |
+| #25 | `ai_conversations.source_page/source_context` 冗余孤儿列(已建未用)| P2 | 决策弃用还是启用 |
+| #26 | admin-web 全 snake_case → camelCase 大改造 | P2 | 影响面巨大 |
+| #27 | admin-web WS 客户端补 `?token=` query 参数 | P0 安全 | Sprint 后立即(与 #15 一起) |
+| #28 | prompt/Pydantic/前端类型四端单一权威源 spec | P2 | 架构级,需 spec |
+
+`#20` 已在本 sprint 收口(dispatcher 加 5 元组隔离),从待办移除。
+
+## 回滚策略
+
+```bash
+# 1. 数据库回滚(测试库)— 见迁移文件末尾"回滚参考"块
+.venv/Scripts/python.exe -c "import psycopg2; from dotenv import dotenv_values; v=dotenv_values('.env',encoding='utf-8-sig'); conn=psycopg2.connect(v['TEST_APP_DB_DSN']); conn.cursor().execute(open('db/zqyy_app/migrations/20260506__ai_closure_schema_fixes.sql').read().split('-- =============================================================================\n-- 回滚参考')[1]); conn.commit()"
+
+# 2. 代码回滚
+git revert <commit_hash>
+
+# 3. 历史回填撤销(若需要):
+# 由于 emoji 已抽离 summary,逆向恢复需按 emoji 列拼回 summary:
+# UPDATE public.member_retention_clue SET summary = emoji || ' ' || summary, emoji = '' WHERE emoji != '';
+```
+
+## 复盘补丁(2026-05-06 晚间 — Neo 第二轮 MCP 走查反馈)
+
+第一轮 audit 后 Neo 发现 6 项 MCP 走查未做利索:
+1. board-finance AI 洞察空但未深查
+2. customer-detail AI 洞察空也未深查
+3. notes 完全没测
+4. 13 处浮动按钮只点了 1 个
+5. 没和 demo-miniprogram 样式对比
+6. task-detail 角色限制也没切换重试
+
+我立即重做 MCP 走查。第二轮发现并修复以下额外 BUG(全部预先存在,W1 sourcePage 链路接通后才暴露):
+
+### 第二轮 BUG 修复
+
+| # | BUG | 位置 | 修复 |
+|---|---|---|---|
+| B1 | `member_retention_clue.created_at` 列错位(实际 `recorded_at`)| `page_context.py:244` | 改 `recorded_at` + schema 前缀 + is_hidden 过滤 |
+| B2 | `get_etl_readonly_connection` SET LOCAL 后 commit RLS 失效(7 个 _text_* 函数都受影响,本次修 1)| `page_context.py:194` 等 | 每个 cursor 块加 `SET LOCAL app.current_site_id` |
+| B3 | `v_dwd_settlement_head` 列错位(`settle_date / room_name / items_sum`)| `page_context.py:213-220` | 改 `pay_time / settle_name`,items_sum 用合成表达式(DWD-DOC #1)|
+| B4 | `v_dws_member_consumption_summary.balance_amount` 列错位 | `page_context.py:228` | 改 `total_card_balance` |
+| B5 | `xcx_chat.py:224 filters.pop("contextId")` 破坏 body.page_context 引用 | `xcx_chat.py:224` | `dict()` 浅拷贝隔离 |
+
+修复后:
+- chat 上下文注入端到端 ✅(AI 回复"东哥/2026-03-24/¥214.71/储值5485")
+- reference_card 富卡写入 db ✅(KPI 富卡 + link + source_page)
+- customer-detail 维客线索 4 条 ✅(tag 强制 2+2 + emoji 独立 + VI 6 类配色)
+
+### 第二轮新增功能
+
+#### 任务 1:chat 流式 markdown 实时渲染(2026-05-06 复盘新增)
+
+新建 `apps/miniprogram/miniprogram/utils/markdown.ts`(180 行):
+- 支持:段落 / 标题 H1-H4 / 粗体 / 斜体 / 行内代码 / 代码块 / 无序列表 / 有序列表 / GFM 表格
+- streaming 容错:partial 标记降级为纯文本
+- 输出供 `<rich-text nodes="{{html}}">` 渲染
+
+`chat.ts`:
+- enrichMessages 给 AI 消息预解析 contentHtml
+- SSE token 处理时实时 setData contentHtml
+- DisplayMessage 类型加 `contentHtml?: string`
+
+`chat.wxml` AI bubble 改用 `<rich-text class="bubble-md" nodes="{{item.contentHtml}}">` + `<text>` fallback。
+
+`chat.wxss` 加 markdown 样式 80 行(table / code / heading / list)。
+
+实证 ✅:截图 30 显示完整 markdown 表格 + 标题 + 列表 + 加粗 + 段落 + reference_card 富卡。
+
+#### 后端日志机制(任务 2 配套)
+
+`main.py` 新加 `_configure_logging()`:
+- `RotatingFileHandler` → `logs/backend.log`(单文件 20MB + 5 backup = 100MB 上限)
+- `_SuppressHealthAccess` filter → 抑制 uvicorn.access 中 `/health` 行
+- 防 reload 重入幂等检查
+- watchdog 心跳不受影响(它用 TCP socket 主动探针,不读 backend stdout)
+
+### 第二轮新发现 BUG/UX 项登记 §七 #29-#38
+
+| # | 项 | 严重度 | 时机 |
+|---|---|---|---|
+| §七 #29 | `_text_coach_detail` `hire_date` 列不存在 | P1 | 独立修复 |
+| §七 #30 | `_text_board_finance` `items_sum` 列不存在(DWD-DOC #1)| P1 | 独立修复 |
+| §七 #31 | `_text_board_customer` 同 #30 | P1 | 独立修复 |
+| §七 #32 | `_text_performance` `performance_tier` 列不存在 | P1 | 独立修复 |
+| §七 #33 | App1 chat 调用全链路审计(详见 backlog §十一)| P1 | 独立 sprint |
+| §七 #34 | 百炼调取 + 本地 SQL MCP 任务追踪(详见 backlog §十二)| P1 | 独立 sprint |
+| §七 #35 | chat md `---` 水平分割线未特殊处理 | P2 | mdToRichHtml 加 `<hr>` |
+| §七 #36 | `_text_task_detail` 视图 `coach_tasks_member_view` 不存在 | P1 | 改 SQL |
+| §七 #37 | 4 入口缺 `_text_*` 实现(coach-service-records / performance-records / notes / chat-history)| P2 | 加到 SUPPORTED + 实现 / 或映射到已支持 page |
+| §七 #38 | customer-detail 频繁 navigate 切换偶发 pageState=error | P2 | onShow + onLoad 并发竞争 |
+
+### 第二轮新增 backlog 章节
+
+- §十一 App1 chat 调用全链路审计(P1 独立 sprint)
+- §十二 百炼调取 + 本地 SQL MCP 任务追踪(P1 独立 sprint)
+
+### 14 入口走查总览
+
+5/14 完整工作 + 5/14 sourcePage OK 但 page_context BUG(P1 已登记)+ 4/14 sourcePage OK 但 page_context 未实现(P2 已登记)。**所有 14 入口 sourcePage 写入 chat data 都正确**,Phase 2.3 链路真正激活。
+
+### 复盘最终改动总数
+
+49 文件 + 第二轮 7 文件(`page_context.py / xcx_chat.py / customer_service.py / task_manager.py / clue_category.py / main.py / chat.ts / chat.wxml / chat.wxss / markdown.ts(新)`)≈ **56 文件改动**。
+
+---
+
+## Co-Authored-By
+
+Claude Opus 4.7 (1M context) <noreply@anthropic.com>
--- a/docs/database/changes/2026-05-06__ai_closure_schema_fixes.md
+++ b/docs/database/changes/2026-05-06__ai_closure_schema_fixes.md
@@ -0,0 +1,152 @@
+# 2026-05-06 · W1-AI-CLOSURE Schema 修复 + 命名统一
+
+> 关联迁移:[`db/zqyy_app/migrations/20260506__ai_closure_schema_fixes.sql`](../../../db/zqyy_app/migrations/20260506__ai_closure_schema_fixes.sql)
+>
+> 完整审计:[`docs/audit/changes/2026-05-06__w1_ai_closure_super_sprint.md`](../../audit/changes/2026-05-06__w1_ai_closure_super_sprint.md)
+
+## 变更说明
+
+### 新增列
+
+| 表 | 列 | 类型 | 默认值 | 用途 |
+|---|---|---|---|---|
+| `public.member_retention_clue` | `emoji` | `varchar(8)` | `''` | 维客线索独立 emoji 字段(App8 prompt 输出 emoji 直接写入,不再嵌 summary 字符串) |
+| `public.member_retention_clue` | `runtime_mode` | `varchar(20)` | `'live'` | 运行模式 live/sandbox(与其他 7 张 ai_* 表对齐) |
+| `public.member_retention_clue` | `sandbox_instance_id` | `varchar(64)` | `'live'` | sandbox 模式写入隔离实例 ID |
+| `biz.ai_run_logs` | `assistant_id` | `bigint NULL` | NULL | App4/App5 这类 (assistant, member) 二元任务的助教 ID,便于失败定位 |
+
+### 新增索引
+
+- `idx_ai_run_logs_assistant_member` ON `biz.ai_run_logs (site_id, assistant_id, member_id, created_at DESC) WHERE assistant_id IS NOT NULL`
+
+### CHECK 约束更新
+
+- `chk_ai_cache_type` 重建:8 类应用名(`app2_finance` / `app2a_finance_area` / `app3_clue` / `app4_analysis` / `app5_tactics` / `app6_note` / `app7_customer` / `app8_consolidation`),与 prompt 文件名 + CacheTypeEnum 完全对齐
+
+### 数据 UPDATE(命名统一)
+
+- `biz.ai_cache.cache_type`:
+  - `app7_customer_analysis` → `app7_customer`(42 行)
+  - `app8_clue_consolidated` → `app8_consolidation`(72 行)
+  - `app6_note_analysis` → `app6_note`(测试库 0 行,生产可能有)
+- `biz.ai_run_logs.app_type`:
+  - `app8_consolidate` → `app8_consolidation`(123 行)
+  - `app8_clue_consolidated` → `app8_consolidation`(测试库 0 行)
+  - `app6_note_analysis` / `app7_customer_analysis` → 应用名(测试库 0 行)
+- `public.member_retention_clue.runtime_mode`:全部 NULL 填 `'live'`(44 行)
+
+### 历史 emoji 回填(独立脚本)
+
+`scripts/ops/backfill_retention_clue_emoji.py` — 把 summary 嵌入的首 emoji 抽到 emoji 列(测试库 44/44 行成功,可重入)。
+
+## 兼容性影响
+
+### ETL 影响
+- 无直接影响。ETL 不写 ai_cache / ai_run_logs / member_retention_clue,只是注释里"客户基础信息" → "客户基础" 的字面量调整(`apps/etl/connectors/feiqiu/tasks/dws/member_consumption_task.py` + `member_visit_task.py`)。
+
+### 后端 API 影响
+- `customer_service._build_ai_insight`:cache_type 从 `app4_analysis`(错位)改为正确的 `app7_customer`,加 `site_id` 过滤 + 字段对齐 App7Result schema(strategies[].title/content)
+- `customer_service._build_retention_clues`:加 `site_id` 过滤 + 字段补齐(detail/source/recorded_by_name/emoji)
+- `task_manager.py` aiSuggestion:取 `one_line_summary` 替代不存在的 `app4.summary`
+- `task_manager.py` talkingPoints:cache_type `app5_talking_points`(不存在)→ `app5_tactics` + 字段 `tactics[].scenario/script`
+- `cleanup_service.py`:`WHERE app_type=%s` BUG 修(应是 `cache_type`)— 90 天清理 + 20K 上限重新生效
+- `cache_service.CACHE_EXPIRY_DAYS`:补 `app2a_finance_area: 0`(64 区域组合不再永不过期)
+- `dispatcher._write_retention_clue`:emoji 独立写入(不再拼 summary)+ 加 runtime_mode/sandbox_instance_id 五元组隔离
+- `xcx_chat`:`ReferenceCard` schema 补 `link/source_page` 字段;`get_messages` SQL 加 `AND role IN ('user','assistant')` 过滤 system 行;`build_reference_card` KPI 富卡接入 SSE 路径
+- WS `/ws/ai-cache/{site_id}` + `/ws/ai-alerts/{site_id}`:加 `?token=` query 参数 + JWT 校验 + site_id 一致性校验
+
+### 小程序影响
+- `customer-detail.ts`:clues 类型 4 字段 → 6 字段(tag/tagColor/emoji/text/source/desc);`_loadAIInsight` cache_type 改 `app7_customer` + 字段 `s.title/s.content`
+- `customer-detail.wxml`:clue-card props 字段对齐 + `wx:if` 空态隐藏 + ai-float-button 补 sourcePage
+- `task-detail.ts/wxml/json`:retentionClues tagColor 6 类;talkingPoints 类型 string[] → TacticItem[];整页补 ai-float-button + json 注册组件
+- `chat.ts`:三分支(task/customer/coach)补 `sourcePage` + `pageFilters.contextId`,Phase 2.3 链路真正激活
+- 14 处 wxml ai-float-button 全部补 sourcePage
+
+### admin-web 影响
+- `AIOperations.tsx` `CACHE_TYPE_OPTIONS` 8 类对齐(去除 _analysis / _consolidated 后缀)
+- `AIRunLogs.tsx` `RUN_LOG_APP_TYPE_OPTIONS` 删除旧 `app8_consolidate`(数据已 UPDATE 到 `app8_consolidation`)
+- `__tests__/adminAiAppTypes.test.ts`:测试断言不再固化"双名共存",改为统一命名
+
+## 回滚策略
+
+迁移文件末尾有完整"回滚参考"块,按以下顺序执行:
+
+```sql
+BEGIN;
+
+-- 1. DROP 新约束
+ALTER TABLE biz.ai_cache DROP CONSTRAINT IF EXISTS chk_ai_cache_type;
+
+-- 2. UPDATE 命名回滚(注意:旧名 app8_consolidate vs app8_clue_consolidated 已合并,
+--    回滚无法精确还原,只能选其一,以下示例选 ai_cache 旧描述名)
+UPDATE biz.ai_run_logs SET app_type = 'app8_consolidate' WHERE app_type = 'app8_consolidation';
+UPDATE biz.ai_run_logs SET app_type = 'app7_customer_analysis' WHERE app_type = 'app7_customer';
+UPDATE biz.ai_run_logs SET app_type = 'app6_note_analysis' WHERE app_type = 'app6_note';
+UPDATE biz.ai_cache SET cache_type = 'app8_clue_consolidated' WHERE cache_type = 'app8_consolidation';
+UPDATE biz.ai_cache SET cache_type = 'app7_customer_analysis' WHERE cache_type = 'app7_customer';
+UPDATE biz.ai_cache SET cache_type = 'app6_note_analysis' WHERE cache_type = 'app6_note';
+
+-- 3. ADD 旧约束
+ALTER TABLE biz.ai_cache ADD CONSTRAINT chk_ai_cache_type CHECK (cache_type IN
+  ('app2_finance','app2a_finance_area','app3_clue','app4_analysis','app5_tactics',
+   'app6_note_analysis','app7_customer_analysis','app8_clue_consolidated'));
+
+-- 4. DROP 索引 + 列
+DROP INDEX IF EXISTS biz.idx_ai_run_logs_assistant_member;
+ALTER TABLE biz.ai_run_logs DROP COLUMN IF EXISTS assistant_id;
+ALTER TABLE public.member_retention_clue
+    DROP COLUMN IF EXISTS sandbox_instance_id,
+    DROP COLUMN IF EXISTS runtime_mode,
+    DROP COLUMN IF EXISTS emoji;
+
+-- 5. emoji 反向回填(若需要)— 把 emoji 列拼回 summary
+UPDATE public.member_retention_clue
+   SET summary = emoji || ' ' || summary, emoji = '' WHERE emoji != '';
+
+COMMIT;
+```
+
+代码侧:`git revert <commit_hash>`。
+
+## 验证 SQL(已在测试库 PASS)
+
+```sql
+-- 1. 新列存在
+SELECT column_name FROM information_schema.columns
+ WHERE table_schema='public' AND table_name='member_retention_clue'
+   AND column_name IN ('emoji','runtime_mode','sandbox_instance_id');
+-- 预期 3 行
+
+-- 2. assistant_id 列存在
+SELECT column_name FROM information_schema.columns
+ WHERE table_schema='biz' AND table_name='ai_run_logs' AND column_name='assistant_id';
+-- 预期 1 行
+
+-- 3. 旧 cache_type 0 残留
+SELECT cache_type, count(*) FROM biz.ai_cache
+ WHERE cache_type IN ('app6_note_analysis','app7_customer_analysis',
+                      'app8_clue_consolidated','app8_consolidate')
+ GROUP BY 1;
+-- 预期 0 行
+
+-- 4. 旧 app_type 0 残留
+SELECT app_type, count(*) FROM biz.ai_run_logs
+ WHERE app_type IN ('app6_note_analysis','app7_customer_analysis',
+                    'app8_consolidate','app8_clue_consolidated')
+ GROUP BY 1;
+-- 预期 0 行
+
+-- 5. emoji 回填覆盖率(回填脚本跑后)
+SELECT
+  count(*) FILTER (WHERE emoji != '') AS filled,
+  count(*) FILTER (WHERE emoji = '') AS empty,
+  count(*) AS total
+  FROM public.member_retention_clue;
+-- 预期 filled=44, empty=0, total=44(测试库)
+```
+
+## 关联
+
+- 完整审计:`docs/audit/changes/2026-05-06__w1_ai_closure_super_sprint.md`
+- backlog 登记:`docs/_overview/architecture-evolution-backlog.md` §七 #14 主体收口 + #15-#28 残余子任务
+- 关联表 RLS 迁移(P1-1 public → biz schema):§七 #21 后续 sprint