标签
+ s = s.replace(/\[\[MDCODE(\d+)MDCODE\]\]/g, (_m, i) => {
+ const c = codeStash[Number(i)] || ""
+ return `${escapeHtml(c)}`
+ })
+
+ // 步骤 4:粗体 **xx**(确保有闭合)
+ s = s.replace(/\*\*([^\n*][^\n*]*?)\*\*/g, "$1")
+
+ // 步骤 5:斜体 *xx*(避免 **)
+ s = s.replace(/(^|[^*])\*([^\n*][^\n*]*?)\*(?!\*)/g, "$1$2")
+
+ return s
+}
+
+/**
+ * 主入口:Markdown 转 rich-text 兼容 HTML 字符串。
+ */
+export function mdToRichHtml(md: string): string {
+ if (!md) return ""
+ const lines = md.split("\n")
+ const out: string[] = []
+ let i = 0
+ let inCodeBlock = false
+ let codeBuf: string[] = []
+
+ while (i < lines.length) {
+ const line = lines[i]
+
+ // 代码块 ```xx```
+ if (line.trim().startsWith("```")) {
+ if (!inCodeBlock) {
+ inCodeBlock = true
+ codeBuf = []
+ } else {
+ out.push(
+ `${escapeHtml(
+ codeBuf.join("\n"),
+ )}
`,
+ )
+ inCodeBlock = false
+ }
+ i++
+ continue
+ }
+ if (inCodeBlock) {
+ codeBuf.push(line)
+ i++
+ continue
+ }
+
+ // 标题 #
+ const h = line.match(/^(#{1,4})\s+(.+)$/)
+ if (h) {
+ const level = h[1].length
+ out.push(`${parseInline(h[2])} `)
+ i++
+ continue
+ }
+
+ // GFM 表格(连续 2 行,第二行为分隔)
+ if (
+ line.trim().startsWith("|") &&
+ i + 1 < lines.length &&
+ /^\s*\|[\s\-:|]+\|\s*$/.test(lines[i + 1])
+ ) {
+ const headers = line.split("|").slice(1, -1).map((c) => c.trim())
+ i += 2
+ const rows: string[][] = []
+ while (
+ i < lines.length &&
+ lines[i].trim().startsWith("|") &&
+ lines[i].trim().endsWith("|")
+ ) {
+ rows.push(lines[i].split("|").slice(1, -1).map((c) => c.trim()))
+ i++
+ }
+ let html = ''
+ for (const h0 of headers) html += `${parseInline(h0)} `
+ html += " "
+ for (const r of rows) {
+ html += ""
+ for (const c of r) html += `${parseInline(c)} `
+ html += " "
+ }
+ html += "
"
+ out.push(html)
+ continue
+ }
+
+ // 无序列表
+ if (/^\s*[-*]\s+/.test(line)) {
+ const items: string[] = []
+ while (i < lines.length && /^\s*[-*]\s+/.test(lines[i])) {
+ items.push(lines[i].replace(/^\s*[-*]\s+/, ""))
+ i++
+ }
+ out.push(
+ `${items
+ .map((it) => `- ${parseInline(it)}
`)
+ .join("")}
`,
+ )
+ continue
+ }
+
+ // 有序列表
+ if (/^\s*\d+\.\s+/.test(line)) {
+ const items: string[] = []
+ while (i < lines.length && /^\s*\d+\.\s+/.test(lines[i])) {
+ items.push(lines[i].replace(/^\s*\d+\.\s+/, ""))
+ i++
+ }
+ out.push(
+ `${items
+ .map((it) => `- ${parseInline(it)}
`)
+ .join("")}
`,
+ )
+ continue
+ }
+
+ // 空行 → 段落分隔
+ if (line.trim() === "") {
+ i++
+ continue
+ }
+
+ // 普通段落(连续非空行合并,内部用
保留软换行)
+ const para: string[] = [line]
+ i++
+ while (
+ i < lines.length &&
+ lines[i].trim() !== "" &&
+ !lines[i].trim().startsWith("#") &&
+ !lines[i].trim().startsWith("|") &&
+ !/^\s*[-*]\s+/.test(lines[i]) &&
+ !/^\s*\d+\.\s+/.test(lines[i]) &&
+ !lines[i].trim().startsWith("```")
+ ) {
+ para.push(lines[i])
+ i++
+ }
+ out.push(`${parseInline(para.join("
"))}
`)
+ }
+
+ // 流未闭合的代码块降级为纯文本 pre
+ if (inCodeBlock && codeBuf.length > 0) {
+ out.push(
+ `${escapeHtml(
+ codeBuf.join("\n"),
+ )}
`,
+ )
+ }
+
+ return out.join("")
+}
diff --git a/db/zqyy_app/migrations/20260506__ai_closure_schema_fixes.sql b/db/zqyy_app/migrations/20260506__ai_closure_schema_fixes.sql
new file mode 100644
index 0000000..b8d3161
--- /dev/null
+++ b/db/zqyy_app/migrations/20260506__ai_closure_schema_fixes.sql
@@ -0,0 +1,172 @@
+-- 2026-05-06
+-- W1-AI-CLOSURE 超级 Sprint 组 1 — Schema 修复 + 命名统一
+--
+-- 背景:
+-- AI 9 APP 全链路调研发现以下劣化:
+-- 1. emoji 嵌入 summary 字符串(dispatcher.py:582-584),数据库 member_retention_clue
+-- 表无独立 emoji 列,违反"字段独立性"哲学
+-- 2. member_retention_clue 表无 runtime_mode / sandbox_instance_id,沙箱模式下 App8
+-- 写入会污染 prod 视图(其他 7 张 ai_* 表都有这两列,本表是唯一例外)
+-- 3. ai_run_logs 缺 assistant_id 列,App4/App5 这种 (assistant, member) 二元任务
+-- 失败定位困难
+-- 4. cache_type / app_type 双名长期共存:
+-- ai_cache.cache_type = app7_customer_analysis / app8_clue_consolidated
+-- ai_run_logs.app_type = app7_customer / app8_consolidate
+-- 违反"schema 一致性"哲学,统一为应用名(与 prompt 文件名一致):
+-- app7_customer / app8_consolidation
+--
+-- 影响范围:
+-- - public.member_retention_clue:加 3 列(emoji + runtime_mode + sandbox_instance_id)
+-- - biz.ai_run_logs:加 assistant_id 列 + 复合索引补建
+-- - biz.ai_cache + biz.ai_run_logs:cache_type / app_type 命名统一
+-- - 后端 dispatcher / cleanup_service / cache_service 代码相应修改(组 2-5)
+--
+-- 兼容性:
+-- - emoji 列默认空字符串,新写入由 dispatcher 移除拼字符串后独立写入(组 3)
+-- - runtime_mode / sandbox_instance_id 默认 'live',与其他 ai_* 表一致
+-- - 命名 UPDATE 后,旧字符串 'app7_customer_analysis' / 'app8_clue_consolidated' /
+-- 'app8_consolidate' 在数据库中绝迹,代码侧必须同步更新
+-- - 回填脚本 scripts/ops/backfill_retention_clue_emoji.py 抽取 summary 嵌入的 emoji
+-- 到 emoji 列,本迁移不做该回填(脚本走 dry-run + 实跑两步)
+--
+-- 回滚策略:见末尾"回滚参考"块。
+--
+-- 验证 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. SELECT column_name FROM information_schema.columns
+-- WHERE table_schema='biz' AND table_name='ai_run_logs'
+-- AND column_name='assistant_id';
+-- 预期 1 行
+-- 3. 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. 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. SELECT runtime_mode, count(*) FROM public.member_retention_clue GROUP BY 1;
+-- 预期 'live' 一行覆盖全部历史
+
+BEGIN;
+
+-- ── 1) public.member_retention_clue: 加 emoji + runtime_mode + sandbox_instance_id ──
+
+ALTER TABLE public.member_retention_clue
+ ADD COLUMN IF NOT EXISTS emoji character varying(8) NOT NULL DEFAULT '';
+
+ALTER TABLE public.member_retention_clue
+ ADD COLUMN IF NOT EXISTS runtime_mode character varying(20) NOT NULL DEFAULT 'live',
+ ADD COLUMN IF NOT EXISTS sandbox_instance_id character varying(64) NOT NULL DEFAULT 'live';
+
+UPDATE public.member_retention_clue
+ SET runtime_mode = 'live', sandbox_instance_id = 'live'
+ WHERE runtime_mode IS NULL OR sandbox_instance_id IS NULL;
+
+COMMENT ON COLUMN public.member_retention_clue.emoji IS
+ '维客线索独立 emoji 字段(由 App8 prompt 输出 emoji 字段直接写入,不嵌 summary);本字段于 W1-AI-CLOSURE 引入,历史数据由 backfill_retention_clue_emoji.py 回填。';
+COMMENT ON COLUMN public.member_retention_clue.runtime_mode IS
+ '运行模式:live / sandbox;sandbox 模式写入隔离实例 ID,live 与其他门店共享 prod 视图。';
+COMMENT ON COLUMN public.member_retention_clue.sandbox_instance_id IS
+ 'sandbox 模式写入隔离实例 ID;live 模式固定为 live。';
+
+-- ── 2) biz.ai_run_logs: 加 assistant_id 列 + 复合索引 ──
+
+ALTER TABLE biz.ai_run_logs
+ ADD COLUMN IF NOT EXISTS assistant_id bigint;
+
+COMMENT ON COLUMN biz.ai_run_logs.assistant_id IS
+ 'App4/App5 这类 (assistant, member) 二元关系任务的助教 ID,便于失败定位;App2/App3/App6/App7/App8 类任务为 NULL。';
+
+CREATE INDEX IF NOT EXISTS 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;
+
+-- ── 3) cache_type / app_type 命名统一(app6 + app7 + app8) ──
+-- 双名长期共存违反 schema 一致性,统一为与 prompt 文件名一致的应用名:
+-- app6_note_analysis -> app6_note
+-- app7_customer_analysis -> app7_customer
+-- app8_clue_consolidated / app8_consolidate -> app8_consolidation
+-- 注意:cache_type 有 chk_ai_cache_type CHECK 约束,需先 DROP 再 UPDATE 再 ADD 新约束。
+
+ALTER TABLE biz.ai_cache DROP CONSTRAINT IF EXISTS chk_ai_cache_type;
+
+UPDATE biz.ai_cache
+ SET cache_type = 'app6_note'
+ WHERE cache_type = 'app6_note_analysis';
+
+UPDATE biz.ai_cache
+ SET cache_type = 'app7_customer'
+ WHERE cache_type = 'app7_customer_analysis';
+
+UPDATE biz.ai_cache
+ SET cache_type = 'app8_consolidation'
+ WHERE cache_type IN ('app8_clue_consolidated', 'app8_consolidate');
+
+UPDATE biz.ai_run_logs
+ SET app_type = 'app8_consolidation'
+ WHERE app_type IN ('app8_consolidate', 'app8_clue_consolidated');
+
+UPDATE biz.ai_run_logs
+ SET app_type = 'app6_note'
+ WHERE app_type = 'app6_note_analysis';
+
+UPDATE biz.ai_run_logs
+ SET app_type = 'app7_customer'
+ WHERE app_type = 'app7_customer_analysis';
+
+-- 注意:ai_run_logs 中 app7 测试库已经是 'app7_customer'(102 行),app6 在测试库
+-- 无数据;UPDATE 旧名字若不存在则 0 行影响,幂等安全。
+
+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',
+ 'app7_customer',
+ 'app8_consolidation'
+ ));
+
+COMMENT ON CONSTRAINT chk_ai_cache_type ON biz.ai_cache IS
+ 'AI 8 个写缓存的应用类型(app1_chat 走 ai_messages 不进缓存);命名与 prompt 文件名一致。';
+
+-- ── 4) 索引收尾(若旧索引引用旧 cache_type 字符串,无影响 — 索引按当前值重建) ──
+
+COMMIT;
+
+-- =============================================================================
+-- 回滚参考(测试库回滚先跑此块,正式库回滚需评估业务影响):
+-- =============================================================================
+-- BEGIN;
+--
+-- -- 命名 UPDATE 回滚(注意:旧名字 app8_consolidate vs app8_clue_consolidated 已合并,
+-- -- 回滚无法精确还原,只能选其一;以下示例选 ai_cache 的旧描述名)
+-- -- ALTER TABLE biz.ai_cache DROP CONSTRAINT IF EXISTS chk_ai_cache_type;
+-- -- 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';
+-- -- 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'));
+--
+-- 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;
+--
+-- COMMIT;
diff --git a/docs/_overview/architecture-evolution-backlog.md b/docs/_overview/architecture-evolution-backlog.md
index bd84bf5..807a73a 100644
--- 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` 加 `
` 处理(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 推进
diff --git a/docs/audit/audit_dashboard.md b/docs/audit/audit_dashboard.md
index b0eccec..fd3cdab 100644
--- 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) |
diff --git 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
new file mode 100644
index 0000000..53bf051
--- /dev/null
+++ 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
+
+# 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 标记降级为纯文本
+- 输出供 `` 渲染
+
+`chat.ts`:
+- enrichMessages 给 AI 消息预解析 contentHtml
+- SSE token 处理时实时 setData contentHtml
+- DisplayMessage 类型加 `contentHtml?: string`
+
+`chat.wxml` AI bubble 改用 `` + `` 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 加 `
` |
+| §七 #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)
diff --git a/docs/database/changes/2026-05-06__ai_closure_schema_fixes.md b/docs/database/changes/2026-05-06__ai_closure_schema_fixes.md
new file mode 100644
index 0000000..94075d4
--- /dev/null
+++ 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 `。
+
+## 验证 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
diff --git a/scripts/ops/backfill_retention_clue_emoji.py b/scripts/ops/backfill_retention_clue_emoji.py
new file mode 100644
index 0000000..9dc0528
--- /dev/null
+++ b/scripts/ops/backfill_retention_clue_emoji.py
@@ -0,0 +1,222 @@
+# -*- coding: utf-8 -*-
+"""W1-AI-CLOSURE 组 1 — 维客线索 emoji 回填脚本。
+
+背景:
+ historic dispatcher._write_retention_clue 把 App8 prompt 输出的独立 emoji 字段
+ 拼到 summary 字符串(`f"{emoji} {raw_summary}"`),违反字段独立性哲学。
+ 20260506__ai_closure_schema_fixes.sql 已加 emoji 独立列。
+
+ 本脚本回填历史数据:扫描 member_retention_clue 全表,把 summary 开头的 emoji
+ 提取到 emoji 列,并把 summary 去掉 emoji 前缀。
+
+用法:
+ cd C:\\Project\\NeoZQYY
+ .venv\\Scripts\\python.exe scripts/ops/backfill_retention_clue_emoji.py --dry-run
+ .venv\\Scripts\\python.exe scripts/ops/backfill_retention_clue_emoji.py
+
+设计:
+ - 默认 --dry-run 模式下打印 diff,不写库
+ - 实跑模式下逐条 UPDATE,事务包裹
+ - 仅处理 emoji = '' 的行,已回填的不重复处理(可重入)
+ - 失败行单独打印,不影响其他行
+"""
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+import psycopg2
+from dotenv import load_dotenv
+
+# ── 加载根 .env(BOM 兼容) ─────────────────────────────
+_ROOT = Path(__file__).resolve().parent.parent.parent
+load_dotenv(_ROOT / ".env", override=False, encoding="utf-8-sig")
+
+_DSN = os.environ.get("APP_DB_DSN")
+if not _DSN:
+ sys.exit("ERROR: APP_DB_DSN 环境变量未设置,请检查根 .env")
+
+logger = logging.getLogger("backfill_retention_clue_emoji")
+
+# ── emoji 前缀正则(覆盖常见 BMP + SMP 符号 + ZWJ 序列) ──
+# 匹配:summary 开头的 1 个或多个 emoji 字符 + 紧跟的空白(0 或多个)
+_EMOJI_PREFIX = re.compile(
+ r"^("
+ r"[\U0001F300-\U0001F9FF]" # Misc Symbols and Pictographs / Emoticons / Symbols and Pictographs Extended-A
+ r"|[\U0001FA70-\U0001FAFF]" # Symbols and Pictographs Extended-B
+ r"|[☀-➿]" # Misc Symbols + Dingbats
+ r"|[⌀-⏿]" # Misc Technical
+ r"|[⬀-⯿]" # Misc Symbols and Arrows
+ r"|[\U0001F1E6-\U0001F1FF]" # 区域旗(国旗)
+ r"|️" # Variation Selector-16
+ r"|" # Zero Width Joiner
+ r")+\s*"
+)
+
+
+@dataclass(frozen=True)
+class ClueRow:
+ """member_retention_clue 表中需要回填的一行(只读 DTO)。"""
+
+ id: int
+ summary: str
+
+
+@dataclass(frozen=True)
+class BackfillResult:
+ """单行回填结果:从 summary 抽出的 emoji + 剩余 summary。"""
+
+ id: int
+ extracted_emoji: str
+ new_summary: str
+ original_summary: str
+
+ @property
+ def changed(self) -> bool:
+ """是否真的发生了变化(emoji 非空且 summary 不同)。"""
+ return bool(self.extracted_emoji) and self.new_summary != self.original_summary
+
+
+def extract_emoji_prefix(summary: str) -> tuple[str, str]:
+ """从 summary 开头抽取 emoji 前缀。
+
+ Args:
+ summary: 原始 summary 文本,可能含或不含 emoji 前缀
+
+ Returns:
+ (extracted_emoji, remaining_summary):
+ - extracted_emoji: 抽出的 emoji 字符串(可能多个 + ZWJ),空表示无 emoji 前缀
+ - remaining_summary: 去掉 emoji 前缀后的 summary(已 strip 前导空白)
+ """
+ match = _EMOJI_PREFIX.match(summary)
+ if not match:
+ return "", summary
+ emoji_part = match.group(0).rstrip() # emoji 本身,不带尾随空白
+ remaining = summary[match.end():].lstrip() # 去掉 emoji + 空白后的剩余文本
+ return emoji_part, remaining
+
+
+def fetch_pending_rows(conn: psycopg2.extensions.connection) -> list[ClueRow]:
+ """查询所有 emoji='' 的行。
+
+ 可重入:已回填(emoji 非空)的不重复处理。
+ """
+ with conn.cursor() as cur:
+ cur.execute(
+ """
+ SELECT id, summary
+ FROM public.member_retention_clue
+ WHERE emoji = ''
+ ORDER BY id
+ """
+ )
+ return [ClueRow(id=r[0], summary=r[1]) for r in cur.fetchall()]
+
+
+def apply_backfill(
+ conn: psycopg2.extensions.connection,
+ result: BackfillResult,
+) -> None:
+ """对单行执行 UPDATE。"""
+ with conn.cursor() as cur:
+ cur.execute(
+ """
+ UPDATE public.member_retention_clue
+ SET emoji = %s, summary = %s
+ WHERE id = %s
+ """,
+ (result.extracted_emoji, result.new_summary, result.id),
+ )
+
+
+def run(dry_run: bool) -> int:
+ """执行回填。
+
+ Returns:
+ 退出码:0 成功,1 有失败行
+ """
+ conn = psycopg2.connect(_DSN)
+ failed_count = 0
+ try:
+ rows = fetch_pending_rows(conn)
+ logger.info("待处理行数: %d (emoji = '' 的所有行)", len(rows))
+
+ if not rows:
+ logger.info("无待处理行,提前退出")
+ return 0
+
+ results: list[BackfillResult] = []
+ for row in rows:
+ emoji, new_summary = extract_emoji_prefix(row.summary)
+ results.append(BackfillResult(
+ id=row.id,
+ extracted_emoji=emoji,
+ new_summary=new_summary,
+ original_summary=row.summary,
+ ))
+
+ changed = [r for r in results if r.changed]
+ unchanged = [r for r in results if not r.changed]
+
+ logger.info("将抽取 emoji 的行: %d", len(changed))
+ logger.info("无 emoji 前缀的行: %d (跳过 UPDATE)", len(unchanged))
+
+ # 打印前 5 条 diff 给用户审阅
+ for r in changed[:5]:
+ logger.info(
+ " id=%d emoji=%r summary: %r -> %r",
+ r.id, r.extracted_emoji, r.original_summary, r.new_summary,
+ )
+ if len(changed) > 5:
+ logger.info(" ... (省略剩余 %d 行)", len(changed) - 5)
+
+ if dry_run:
+ logger.info("[DRY-RUN] 不执行 UPDATE,正式回填请去掉 --dry-run")
+ return 0
+
+ # 实跑:逐行 UPDATE,失败单独记录
+ for r in changed:
+ try:
+ apply_backfill(conn, r)
+ except psycopg2.Error as exc:
+ logger.exception("UPDATE 失败 id=%d: %s", r.id, exc)
+ failed_count += 1
+ conn.rollback()
+ continue
+ conn.commit()
+
+ logger.info(
+ "回填完成: 成功 %d 行 / 失败 %d 行",
+ len(changed) - failed_count, failed_count,
+ )
+ return 0 if failed_count == 0 else 1
+ finally:
+ conn.close()
+
+
+def main() -> None:
+ parser = argparse.ArgumentParser(
+ description="W1-AI-CLOSURE 维客线索 emoji 回填(从 summary 抽取到独立列)",
+ )
+ parser.add_argument(
+ "--dry-run",
+ action="store_true",
+ help="试运行模式,打印 diff 不写库",
+ )
+ args = parser.parse_args()
+
+ logging.basicConfig(
+ level=logging.INFO,
+ format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+ )
+
+ sys.exit(run(dry_run=args.dry_run))
+
+
+if __name__ == "__main__":
+ main()