Neo-ZQYY/docs/database/changes/2026-05-06__ai_closure_schema_fixes.md

2026-05-06 · W1-AI-CLOSURE Schema 修复 + 命名统一

关联迁移:db/zqyy_app/migrations/20260506__ai_closure_schema_fixes.sql

完整审计:docs/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:测试断言不再固化"双名共存",改为统一命名

回滚策略

迁移文件末尾有完整"回滚参考"块,按以下顺序执行:

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)

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