# 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)