微信小程序页面迁移校验之前 P5任务处理之前

This commit is contained in:
Neo
2026-03-09 01:19:21 +08:00
parent 263bf96035
commit 6e20987d2f
1112 changed files with 153824 additions and 219694 deletions

View File

@@ -0,0 +1,257 @@
# 需求文档P5 AI 集成层miniapp-ai-integration
## 简介
本文档定义小程序 AI 集成层的需求规格,覆盖 P5-A 阶段(管道 + 骨架)。系统为台球门店助教和管理者提供 8 个 AI 应用,包括通用对话、财务洞察、客户数据分析、关系分析、话术参考、备注分析、客户分析和维客线索整理。技术栈为 FastAPI 后端 + 微信小程序前端 + PostgreSQLzqyy_app 业务库),通过阿里云百炼 API通义千问提供 AI 能力。
P5-A 阶段交付"管道":建表、百炼封装、缓存 API、SSE 框架,以及 Prompt 已完全确定的应用(应用 2、应用 8。应用 3/4/5/6/7 只实现触发机制和调用骨架Prompt 拼接函数留接口)。
> P5-B 阶段Prompt 细化)不在本 spec 范围,将分散到 P6task-detail和 P9customer-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_contextJSON、created_at
2. THE AI_Integration_System SHALL 在 `biz` schema 下创建 `ai_messages`包含字段id、conversation_id外键关联 ai_conversations、roleuser/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_bytrigger_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_messagesrole=user
5. WHEN 流式返回完成后THE App1_Chat SHALL 将完整的 assistant 回复写入 ai_messagesrole=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_amountsettle_type=5
7. THE App2_Finance SHALL 将每次调用结果写入 ai_cachecache_type=app2_financetarget_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_cachecache_type=app3_cluetarget_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_cachecache_type=app4_analysistarget_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_cachecache_type=app5_tacticstarget_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_cachecache_type=app6_note_analysistarget_id=member_idscore 字段存储评分
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_cachecache_type=app7_customer_analysistarget_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_cluecategory → category、emoji + summary → summaryemoji 拼接在前,如"📅 偏好周末下午时段消费"、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_cachecache_type=app8_clue_consolidatedtarget_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 记录错误日志,后续应用使用已有缓存继续执行(不阻塞整条链)
### 需求 12AI 缓存读写 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 隔离
### 需求 13AI 调用记录持久化
**用户故事:** 作为系统,所有 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包含 roleuser/assistant/system、content、tokens_used、created_at
3. THE AI_Integration_System SHALL 在 ai_conversations 中记录 source_page 和 source_contextJSON标识调用来源
### 需求 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-T1customer-detail API
- T7-完整:应用 4 Prompt JSON 细化 → P6-T4task-detail API
- T8-完整:应用 5 Prompt JSON 细化 → P6-T4task-detail API
- T9-完整:应用 6 Prompt JSON 细化 → P9-T1customer-detail API
- T10-完整:应用 7 Prompt JSON 细化 → P9-T1customer-detail API