# 变更审计记录：P5 AI 集成需求审视 — 7 项歧义修补 + category 枚举对齐

| 字段 | 值 |
|------|-----|
| 日期 | 2026-03-08 03:01:14 |
| Prompt-ID | P20260308-023933 |
| Session-ID | — |
| Session 路径 | — |

## 操作摘要

对 P5 小程序 AI 集成需求（`P5-miniapp-ai-integration.md`）进行全面审视，修补 7 项歧义并对齐 category 枚举值。核心变更：
1. 分类标签枚举统一：`客户基础信息` → `客户基础`，`促销接受` → `促销偏好`
2. 调用链改为严格串行：消费事件 → 应用3 → 应用8 → 应用7；应用4 等待应用8完成
3. 应用4 缓存不存在保底方案：reference 传空对象，Prompt 标注"暂无历史线索"
4. emoji 不需要单独字段，拼接在 summary 前面存储
5. 应用8 → member_retention_clue 字段映射表
6. 应用2 调度机制：ETL 调度器、08:00 后首次任务、8 次独立调用
7. 应用1 对话历史：时间倒序、20/页懒加载、不可删除、每次新建
8. 所有 8 个应用首条 Prompt 加入 current_time（精确到秒）
9. ai_cache target_id 约定表

同步执行了 `member_retention_clue.category` CHECK 约束的 DDL 迁移，将 `客户基础信息` 更新为 `客户基础`，已在 test_zqyy_app 验证通过。

## 变更文件清单

| 文件 | 变更类型 | 说明 |
|------|---------|------|
| `docs/prd/specs/P5-miniapp-ai-integration.md` | 修改 | P5 spec 大量补充：两阶段交付策略、8 应用详细设计、调用链时序、Prompt 数据结构、字段映射 |
| `db/zqyy_app/migrations/2026-03-08__align_retention_clue_category_enum.sql` | 新增 | 迁移脚本：category CHECK 约束枚举对齐 |
| `docs/database/ddl/zqyy_app__public.sql` | 修改 | DDL 基线同步：添加 chk_retention_clue_category CHECK 约束（6 个枚举值） |
| `docs/prd/ai-app-prompts.md` | 修改 | Prompt 文档枚举同步：应用6/8 `促销接受` → `促销偏好` |
| `scripts/ops/_run_migration_align_category.py` | 新增 | 一次性迁移执行脚本（已完成使命） |

## DB Schema 变更详情

### member_retention_clue.category CHECK 约束

- 旧枚举值：`客户基础信息`、消费习惯、玩法偏好、促销偏好、社交关系、重要反馈
- 新枚举值：`客户基础`、消费习惯、玩法偏好、促销偏好、社交关系、重要反馈
- 变更原因：P5 spec 评审决定统一为短名称，与 AI 应用 Prompt 枚举值一致
- 已有数据：`category='客户基础信息'` 的行已 UPDATE 为 `客户基础`
- 迁移状态：✅ 已在 test_zqyy_app 执行成功
- DDL 基线：✅ `docs/database/ddl/zqyy_app__public.sql` 已同步

### 验证结果

- `category='客户基础信息'` 残留行数 = 0 ✅
- CHECK 约束 `chk_retention_clue_category` 包含 `客户基础`（非 `客户基础信息`）✅

## 影响范围

- **数据库**：test_zqyy_app.member_retention_clue 表 CHECK 约束已更新
- **后端 API**：`POST /api/retention-clue` 的 category 校验需在开发时对齐新枚举
- **AI 应用**：百炼平台 8 个应用的 System Prompt 中枚举值需同步更新
- **前端**：无直接影响（枚举值由后端/AI 返回）
- **ETL**：无影响

## 回滚策略

- DDL：迁移脚本中包含回滚 SQL（恢复 `客户基础信息` 枚举值）
- 文档：`git revert` 即可

## 改动注解

### `docs/prd/specs/P5-miniapp-ai-integration.md`
- 变更类型：修改
- 原始原因：P5 AI 集成需求在首次编写时存在多处歧义和未定义行为，需要在开发前逐项审视并补齐
- 思路分析：采用"两阶段交付策略"（P5-A 搭骨架 + P5-B 随页面细化 Prompt），避免在页面 API 未开发前强行猜测 Prompt 结构。调用链从并行改为串行，确保数据一致性。补充了所有 8 个应用的首条 Prompt JSON 结构、返回格式、字段映射、缓存策略等关键设计细节
- 修改结果：P5 spec 从概要级提升为可执行级，7 项歧义全部闭环，开发团队可直接按 spec 实施

### `db/zqyy_app/migrations/2026-03-08__align_retention_clue_category_enum.sql`
- 变更类型：新增
- 原始原因：P5 spec 评审决定将 `客户基础信息` 缩短为 `客户基础`，需同步更新数据库 CHECK 约束
- 思路分析：幂等迁移脚本，先 UPDATE 已有数据再 DROP/ADD 约束，包含回滚 SQL 和 4 条验证 SQL
- 修改结果：test_zqyy_app 中 member_retention_clue 表的 category 枚举已对齐，正式库待部署时执行

### `docs/database/ddl/zqyy_app__public.sql`
- 变更类型：修改
- 原始原因：DDL 基线需与实际数据库结构保持同步
- 思路分析：直接在 DDL 基线中更新 CHECK 约束定义
- 修改结果：DDL 基线反映最新的 6 个枚举值

### `docs/prd/ai-app-prompts.md`
- 变更类型：修改
- 原始原因：Prompt 文档中应用6/8 的分类标签使用了旧名称 `促销接受`，需对齐为 `促销偏好`
- 思路分析：全文搜索替换，确保所有应用的枚举值一致
- 修改结果：Prompt 文档与 P5 spec、数据库 CHECK 约束三方枚举值完全一致

### `scripts/ops/_run_migration_align_category.py`
- 变更类型：新增
- 原始原因：需要一个安全的一次性脚本在测试库执行迁移
- 思路分析：强制校验 DSN 指向 test_zqyy_app，执行后自动验证结果
- 修改结果：迁移已成功执行，脚本完成使命