Neo-ZQYY/docs/audit/changes/2026-05-06__w1_ai_closure_super_sprint.md

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 + §十

调研背景(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 元组隔离),从待办移除。

回滚策略

# 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