Neo-ZQYY/.kiro/specs/05-miniapp-ai-integration/requirements.md

# 需求文档：P5 AI 集成层（miniapp-ai-integration）

## 简介

本文档定义小程序 AI 集成层的需求规格，覆盖 P5-A 阶段（管道 + 骨架）。系统为台球门店助教和管理者提供 8 个 AI 应用，包括通用对话、财务洞察、客户数据分析、关系分析、话术参考、备注分析、客户分析和维客线索整理。技术栈为 FastAPI 后端 + 微信小程序前端 + PostgreSQL（zqyy_app 业务库），通过阿里云百炼 API（通义千问）提供 AI 能力。

P5-A 阶段交付"管道"：建表、百炼封装、缓存 API、SSE 框架，以及 Prompt 已完全确定的应用（应用 2、应用 8）。应用 3/4/5/6/7 只实现触发机制和调用骨架（Prompt 拼接函数留接口）。

> P5-B 阶段（Prompt 细化）不在本 spec 范围，将分散到 P6（task-detail）和 P9（customer-detail）的对应任务中完成。

## 术语表

- **AI_Integration_System**：P5 AI 集成层系统整体，包含后端 API、百炼封装、事件调度、缓存管理等
- **Bailian_Client**：百炼 API 统一封装层，负责与阿里云通义千问 API 的通信（流式/非流式）
- **SSE_Endpoint**：Server-Sent Events 流式返回端点，用于应用 1 通用对话的逐字推送
- **AI_Cache_Service**：AI 缓存读写服务，管理 `biz.ai_cache` 表的 CRUD 和保留策略
- **Event_Dispatcher**：事件调度器，负责根据业务事件（消费、备注、任务分配）触发对应 AI 应用调用链
- **Clue_Writer**：维客线索写入器，负责将应用 8 整合后的线索全量替换写入 `member_retention_clue` 表
- **App1_Chat**：应用 1 通用对话，用户主动发起的流式对话
- **App2_Finance**：应用 2 财务洞察，每日自动生成 8 个时间维度的财务分析
- **App3_Clue**：应用 3 客户数据维客线索分析，客户新增消费时自动触发
- **App4_Analysis**：应用 4 关系分析/任务建议，助教参与新结算或任务分配时触发
- **App5_Tactics**：应用 5 话术参考，联动应用 4 自动触发
- **App6_Note**：应用 6 备注分析，备注提交时自动触发
- **App7_Customer**：应用 7 客户分析，消费事件链中应用 8 完成后触发
- **App8_Consolidation**：应用 8 维客线索整理，应用 3 或应用 6 产出后触发
- **items_sum**：校准后的消费金额口径，= table_charge_money + goods_money + assistant_pd_money + assistant_cx_money + electricity_money，禁止使用 consume_money
- **ai_conversations**：AI 对话表，记录每次对话的元信息
- **ai_messages**：AI 消息表，记录对话中的每条消息
- **ai_cache**：AI 缓存表，存储各应用的结构化输出结果
- **member_retention_clue**：维客线索表，存储整合后的客户维护线索
- **营业日分界点**：每日 08:00，用于时间维度计算的日切点

## 需求

### 需求 1：数据库表结构

**用户故事：** 作为系统，我需要持久化存储所有 AI 对话记录和缓存结果，以便支撑 8 个 AI 应用的数据读写需求。

#### 验收标准

1. THE AI_Integration_System SHALL 在 `biz` schema 下创建 `ai_conversations` 表，包含字段：id、user_id、nickname、app_id、site_id、source_page、source_context（JSON）、created_at
2. THE AI_Integration_System SHALL 在 `biz` schema 下创建 `ai_messages` 表，包含字段：id、conversation_id（外键关联 ai_conversations）、role（user/assistant/system）、content、tokens_used、created_at
3. THE AI_Integration_System SHALL 在 `biz` schema 下创建 `ai_cache` 表，包含字段：id、cache_type（枚举：app2_finance / app3_clue / app4_analysis / app5_tactics / app6_note_analysis / app7_customer_analysis / app8_clue_consolidated）、site_id、target_id、result_json、score（应用 6 专用）、triggered_by（trigger_job_id）、created_at、expires_at
4. THE AI_Integration_System SHALL 对 ai_cache 表的 target_id 按应用约定存储：应用 2 存时间维度编码、应用 3/6/7/8 存 member_id、应用 4/5 存 `{assistant_id}_{member_id}` 格式
5. THE AI_Integration_System SHALL 对所有三张表启用 site_id 字段以支持多门店隔离

### 需求 2：百炼 API 统一封装层

**用户故事：** 作为开发者，我需要一个统一的百炼 API 封装层，以便所有 AI 应用通过一致的接口调用阿里云通义千问，降低重复代码和维护成本。

#### 验收标准

1. THE Bailian_Client SHALL 支持流式调用模式（用于应用 1 SSE 推送）和非流式调用模式（用于应用 2-8 结构化输出）
2. THE Bailian_Client SHALL 在 API 调用失败时执行自动重试（含指数退避策略）
3. THE Bailian_Client SHALL 记录每次 API 调用的 tokens_used 统计信息
4. THE Bailian_Client SHALL 支持 JSON 输出模式，确保应用 2-8 返回的内容可解析为结构化 JSON
5. IF 百炼 API 返回非预期格式或解析失败，THEN THE Bailian_Client SHALL 记录错误日志并返回明确的错误信息
6. THE Bailian_Client SHALL 在每次调用的首条 Prompt JSON 中统一注入 `current_time` 字段（精确到秒）

### 需求 3：应用 1 通用对话（SSE 流式）

**用户故事：** 作为助教，我可以在任意页面点击 AI 按钮，跳转到对话页面与 AI 交流，AI 了解当前页面上下文。

#### 验收标准

1. THE SSE_Endpoint SHALL 以 Server-Sent Events 协议向前端推送 AI 回复，实现逐字展示效果
2. WHEN 用户从任意页面进入 chat 页面时，THE App1_Chat SHALL 始终新建一条 ai_conversations 记录（不复用已有对话）
3. THE App1_Chat SHALL 在首条消息中注入页面上下文，包含 source_page（来源页面标识）、page_context（页面上下文摘要）、screen_content（屏幕可见内容文本化描述）
4. WHEN 用户发送消息时，THE App1_Chat SHALL 立即将用户消息写入 ai_messages（role=user）
5. WHEN 流式返回完成后，THE App1_Chat SHALL 将完整的 assistant 回复写入 ai_messages（role=assistant），包含 tokens_used
6. THE App1_Chat SHALL 通过 `biz_params.user_prompt_params` 传入 User_ID、Role（助教/管理者）、Nickname 实现信息隔离
7. THE App1_Chat SHALL 提供历史对话列表接口，按时间倒序展示，每页 20 条懒加载
8. THE App1_Chat SHALL 搭建上下文注入框架，页面文本化工具留接口（P5-B 阶段各页面逐步实现）

### 需求 4：应用 2 财务洞察

**用户故事：** 作为管理者，我在财务看板能看到 AI 生成的财务洞察分析，覆盖多个时间维度。

#### 验收标准

1. THE App2_Finance SHALL 由 ETL 调度器在每日 08:00（营业日分界点）后的首次任务执行时触发
2. THE App2_Finance SHALL 在 DWS 日更数据更新完成后，依次对 8 个时间维度发起独立调用（共 8 次百炼 API 调用）
3. THE App2_Finance SHALL 覆盖 8 个时间维度：本月（this_month）、上月（last_month）、本周（this_week）、上周（last_week）、前 3 月不含本月（last_3_months）、本季（this_quarter）、上季（last_quarter）、近 6 月不含本月（last_6_months）
4. THE App2_Finance SHALL 返回结构化 JSON，格式为序号 + 标题 + 正文的数组
5. THE App2_Finance SHALL 在 Prompt 中包含当期和上期的收入结构（table_fee、assistant_pd、assistant_cx、goods、recharge）、储值资产、费用汇总、平台结算数据
6. THE App2_Finance SHALL 使用已校准的收入结构字段映射：table_fee = table_charge_money、assistant_pd = assistant_pd_money、assistant_cx = assistant_cx_money、goods = goods_money、recharge = 充值 pay_amount（settle_type=5）
7. THE App2_Finance SHALL 将每次调用结果写入 ai_cache（cache_type=app2_finance，target_id=时间维度编码）
8. IF ETL 调度器中尚无应用 2 的调度逻辑，THEN THE AI_Integration_System SHALL 在 P5-A 阶段补充该调度任务

### 需求 5：应用 3 客户数据维客线索分析（骨架）

**用户故事：** 作为系统，客户新增消费时自动通过 AI 分析客户数据，提取维客线索。

#### 验收标准

1. WHEN 客户新增消费（结账单出现）时，THE Event_Dispatcher SHALL 触发 App3_Clue 调用
2. THE App3_Clue SHALL 返回 JSON 格式的线索数组，每条线索包含 category（分类标签）、summary（摘要）、detail（详情）、emoji
3. THE App3_Clue SHALL 将分类标签限定为 3 个枚举值：客户基础、消费习惯、玩法偏好
4. THE App3_Clue SHALL 将线索提供者统一标记为"系统"
5. THE App3_Clue SHALL 使用 items_sum 作为消费金额口径（= table_charge_money + goods_money + assistant_pd_money + assistant_cx_money + electricity_money），禁止使用 consume_money
6. THE App3_Clue SHALL 将结果写入 ai_cache（cache_type=app3_clue，target_id=member_id）
7. THE App3_Clue SHALL 实现触发机制和调用框架，Prompt 拼接函数留接口（consumption_records 等字段待 P9-T1 细化）
8. THE App3_Clue SHALL 在 Prompt 的 reference 中包含应用 6 的线索结果（如有）和最近 2 套应用 8 的历史信息（附 generated_at 时间）

### 需求 6：应用 4 关系分析/任务建议（骨架）

**用户故事：** 作为系统，助教参与新结算或被分配召回任务时，自动生成关系分析和任务建议。

#### 验收标准

1. WHEN 助教参与新结算时，THE Event_Dispatcher SHALL 在消费事件链中等待应用 3 → 应用 8 完成后触发 App4_Analysis
2. WHEN 优先召回任务分配或高优先召回任务分配时，THE Event_Dispatcher SHALL 直接触发 App4_Analysis（读取应用 8 已有缓存）
3. THE App4_Analysis SHALL 返回 JSON 格式，包含任务描述、行动建议数组、一句话总结
4. THE App4_Analysis SHALL 在 Prompt 的 reference 中包含应用 8 当前最新维客线索和最近 2 套历史信息（附 generated_at 时间）
5. IF 应用 8 缓存不存在（如新客户首次结算），THEN THE App4_Analysis SHALL 在 reference 中传空对象，Prompt 中标注"暂无历史线索"
6. THE App4_Analysis SHALL 将结果写入 ai_cache（cache_type=app4_analysis，target_id=`{assistant_id}_{member_id}`）
7. THE App4_Analysis SHALL 实现触发机制和调用框架，Prompt 拼接函数留接口（service_history、assistant_info 等字段待 P6-T4 细化）

### 需求 7：应用 5 话术参考（骨架）

**用户故事：** 作为系统，应用 4 生成任务建议后，自动联动生成沟通话术参考。

#### 验收标准

1. WHEN App4_Analysis 调用完成后，THE Event_Dispatcher SHALL 自动触发 App5_Tactics
2. THE App5_Tactics SHALL 接收应用 4 的完整返回结果作为 Prompt 中的 task_suggestion 字段
3. THE App5_Tactics SHALL 返回 JSON 格式的话术内容数组
4. THE App5_Tactics SHALL 在 Prompt 的 reference 中包含最近 2 套应用 8 的历史信息（附 generated_at 时间）
5. THE App5_Tactics SHALL 将结果写入 ai_cache（cache_type=app5_tactics，target_id=`{assistant_id}_{member_id}`）
6. THE App5_Tactics SHALL 实现联动框架，Prompt 拼接函数留接口（service_history、assistant_info 等字段随应用 4 同步在 P6-T4 细化）

### 需求 8：应用 6 备注分析（骨架）

**用户故事：** 作为系统，助教提交备注后，自动通过 AI 分析备注内容，提取维客线索并评分。

#### 验收标准

1. WHEN 备注提交时，THE Event_Dispatcher SHALL 触发 App6_Note 调用
2. THE App6_Note SHALL 返回 JSON 格式，包含 score（评分 1-10）和 clues（线索数组，每条含 category、summary、detail、emoji）
3. THE App6_Note SHALL 将分类标签限定为 6 个枚举值：客户基础、消费习惯、玩法偏好、促销偏好、社交关系、重要反馈
4. THE App6_Note SHALL 将线索提供者标记为当前备注提供人
5. THE App6_Note SHALL 使用 6 分为标准分的评分规则：重复信息/低价值/时效性低酌情扣分，高价值信息酌情加分
6. THE App6_Note SHALL 将结果写入 ai_cache（cache_type=app6_note_analysis，target_id=member_id），score 字段存储评分
7. THE App6_Note SHALL 实现触发机制和调用框架，Prompt 拼接函数留接口（consumption_data 等字段待 P9-T1 细化）
8. THE App6_Note SHALL 在 Prompt 的 reference 中包含应用 3 的线索结果（如有）和最近 2 套应用 8 的历史信息（附 generated_at 时间）

### 需求 9：应用 7 客户分析（骨架）

**用户故事：** 作为系统，客户结账单出现后自动生成客户全量分析与运营建议。

#### 验收标准

1. WHEN 消费事件链中 App8_Consolidation 完成后，THE Event_Dispatcher SHALL 串行触发 App7_Customer（确保读到本次消费触发的最新线索）
2. THE App7_Customer SHALL 返回 JSON 格式，包含 strategies 数组（每条含 title 和 content）和 summary（一句话总结）
3. THE App7_Customer SHALL 使用 items_sum 作为消费金额口径，禁止使用 consume_money
4. THE App7_Customer SHALL 对主观信息（来自备注）标注【来源：XXX，请甄别信息真实性】
5. THE App7_Customer SHALL 将结果写入 ai_cache（cache_type=app7_customer_analysis，target_id=member_id）
6. THE App7_Customer SHALL 实现触发机制和调用框架，Prompt 拼接函数留接口（objective_data 等字段待 P9-T1 细化）
7. THE App7_Customer SHALL 在 Prompt 的 reference 中包含最新 + 最近 2 套应用 8 的历史信息（附 generated_at 时间）

### 需求 10：应用 8 维客线索整理

**用户故事：** 作为系统，应用 3 或应用 6 产出新线索后，自动整合去重生成统一维客线索，并写入 member_retention_clue 表。

#### 验收标准

1. WHEN App3_Clue 产出新线索后，THE Event_Dispatcher SHALL 立即触发 App8_Consolidation
2. WHEN App6_Note 产出新线索后，THE Event_Dispatcher SHALL 立即触发 App8_Consolidation
3. THE App8_Consolidation SHALL 接收应用 3 和应用 6 的全部线索内容作为输入（附 generated_at 时间）
4. THE App8_Consolidation SHALL 返回 JSON 格式的整合后线索数组，每条含 category、summary、detail、emoji、providers
5. THE App8_Consolidation SHALL 将分类标签限定为 6 个枚举值：客户基础、消费习惯、玩法偏好、促销偏好、社交关系、重要反馈（与 member_retention_clue 表 CHECK 约束一致）
6. THE App8_Consolidation SHALL 合并相似线索（多提供者以逗号分隔），其余线索原文返回，遵循最小改动原则
7. THE App8_Consolidation SHALL 将整合后的线索全量替换该客户在 member_retention_clue 中的所有 AI 来源线索（source IN ('ai_consumption', 'ai_note')），人工线索（source='manual'）不受影响
8. THE Clue_Writer SHALL 按以下字段映射写入 member_retention_clue：category → category、emoji + summary → summary（emoji 拼接在前，如"📅 偏好周末下午时段消费"）、detail → detail、providers → recorded_by_name、source 根据线索来源判断（纯应用 3 → ai_consumption，纯应用 6 → ai_note，混合来源 → ai_consumption）
9. THE Clue_Writer SHALL 对系统触发的线索将 recorded_by_assistant_id 填 NULL
10. THE App8_Consolidation SHALL 将结果同时写入 ai_cache（cache_type=app8_clue_consolidated，target_id=member_id）

### 需求 11：事件调度与调用链编排

**用户故事：** 作为系统，我需要根据业务事件（消费、备注、任务分配）自动编排 AI 应用调用链，确保执行顺序和数据依赖正确。

#### 验收标准

1. WHEN 消费事件（结账单）发生时，THE Event_Dispatcher SHALL 按严格串行顺序执行：应用 3 → 应用 8 → 应用 7
2. WHEN 消费事件中该结算单有助教参与时，THE Event_Dispatcher SHALL 在应用 8 完成后额外执行：应用 4 → 应用 5
3. WHEN 备注提交事件发生时，THE Event_Dispatcher SHALL 按串行顺序执行：应用 6 → 应用 8
4. WHEN 任务分配事件（优先召回/高优先召回）发生时，THE Event_Dispatcher SHALL 执行：应用 4 → 应用 5（直接读取应用 8 已有缓存）
5. THE Event_Dispatcher SHALL 确保消费事件链中应用 7 等待应用 8 完成后再启动，保证读到本次消费触发的最新线索
6. THE Event_Dispatcher SHALL 确保消费事件链中应用 4 等待应用 3 → 应用 8 完成后再执行，确保读到本次消费的最新线索
7. IF 调用链中某个应用调用失败，THEN THE Event_Dispatcher SHALL 记录错误日志，后续应用使用已有缓存继续执行（不阻塞整条链）

### 需求 12：AI 缓存读写 API

**用户故事：** 作为前端，我需要通过 API 读取各 AI 应用的缓存结果，以便在对应页面展示 AI 分析内容。

#### 验收标准

1. THE AI_Cache_Service SHALL 提供按 cache_type + site_id + target_id 查询最新缓存结果的 API
2. THE AI_Cache_Service SHALL 支持以下前端消费场景：应用 2 结果展示在 board-finance 财务看板、应用 4/5 结果展示在 task-detail 任务详情页、应用 6 的 score 以打星方式展示在备注卡片、应用 7 结果展示在 customer-detail 客户详情页、应用 8 结果通过 member_retention_clue 表展示
3. THE AI_Cache_Service SHALL 对每个 (cache_type, site_id, target_id) 组合保留最近 500 条记录，超过时删除最旧的
4. WHEN 写入新缓存记录后，THE AI_Cache_Service SHALL 异步检查并清理超限记录
5. THE AI_Cache_Service SHALL 对所有查询和写入操作执行 site_id 隔离

### 需求 13：AI 调用记录持久化

**用户故事：** 作为系统，所有 AI 对话（含用户主动和系统自动调用）都要持久化记录，以便追溯和统计。

#### 验收标准

1. THE AI_Integration_System SHALL 对所有 8 个应用的每次 AI 调用创建 ai_conversations 记录，包含 conversation_id、app_id、user_id（系统调用时为系统标识）、nickname、site_id
2. THE AI_Integration_System SHALL 对每次 AI 调用的输入和输出分别写入 ai_messages，包含 role（user/assistant/system）、content、tokens_used、created_at
3. THE AI_Integration_System SHALL 在 ai_conversations 中记录 source_page 和 source_context（JSON），标识调用来源

### 需求 14：百炼技术方案确认

**用户故事：** 作为开发者，我需要确认百炼 API 的流式返回技术方案和 JSON 输出最佳实践，以便正确实现封装层。

#### 验收标准

1. THE AI_Integration_System SHALL 查阅百炼官方文档，确认流式返回的技术方案（SSE vs WebSocket）
2. THE AI_Integration_System SHALL 确认百炼 API 的 JSON 输出模式配置方式（response_format 参数或 System Prompt 约束）
3. THE AI_Integration_System SHALL 基于确认结果输出技术方案文档，作为 Bailian_Client 实现的依据

---

## 范围说明

### P5-A 阶段（本 spec 覆盖）

| 任务 | 对应需求 | 说明 |
|------|---------|------|
| T1 | 需求 1 | 建表：ai_conversations + ai_messages + ai_cache |
| T2 | 需求 2 | 百炼 API 统一封装层 |
| T3 | 需求 3 | 应用 1 通用对话 SSE |
| T5 | 需求 4 | 应用 2 财务洞察（Prompt 已确定） |
| T6-骨架 | 需求 5 | 应用 3 触发机制 + 调用框架 |
| T7-骨架 | 需求 6 | 应用 4 触发机制 + 调用框架 |
| T8-骨架 | 需求 7 | 应用 5 联动框架 |
| T9-骨架 | 需求 8 | 应用 6 触发机制 + 调用框架 |
| T10-骨架 | 需求 9 | 应用 7 触发机制 + 调用框架 |
| T11 | 需求 10 | 应用 8 维客线索整理（Prompt 已确定） |
| T12 | 需求 12 | AI 缓存读写 API |
| T13 | 需求 14 | 百炼技术方案确认 |
| — | 需求 11 | 事件调度与调用链编排（贯穿 T6-T11） |
| — | 需求 13 | AI 调用记录持久化（贯穿所有应用） |

### P5-B 阶段（不在本 spec 范围）

以下任务将分散到对应页面的开发 spec 中完成：

- T4：页面内容文本化工具 → 随 P6-P9 各页面逐步实现
- T6-完整：应用 3 Prompt JSON 细化 → P9-T1（customer-detail API）
- T7-完整：应用 4 Prompt JSON 细化 → P6-T4（task-detail API）
- T8-完整：应用 5 Prompt JSON 细化 → P6-T4（task-detail API）
- T9-完整：应用 6 Prompt JSON 细化 → P9-T1（customer-detail API）
- T10-完整：应用 7 Prompt JSON 细化 → P9-T1（customer-detail API）