Neo-ZQYY/docs/prd/specs/P5-miniapp-ai-integration.md

P5：AI 集成层 — miniapp-ai-integration

优先级：P5（依赖 P3 + P4） 预估工作量：大

---

需求（Requirements）

用户故事

1. 作为助教，我可以在任意页面点击 AI 按钮，跳转到对话页面与 AI 交流，AI 了解当前页面上下文。
2. 作为助教，我在任务详情页能看到 AI 生成的消费习惯分析、关系分析、话术参考。
3. 作为助教，我提交回访备注后，系统自动通过 AI 评估备注含金量。
4. 作为管理者，我在财务看板能看到 AI 生成的财务洞察分析。
5. 作为系统，所有 AI 对话（含系统调用）都要持久化记录。

验收标准

• AC1：应用 1 通用对话支持流式返回（SSE），前端逐字展示
• AC2：应用 2 财务洞察每日自动更新，覆盖 8 个时间维度
• AC3：应用 3 消费习惯在客户新增消费时自动更新
• AC4：应用 4+5 在助教参与新结算时联动更新
• AC5：应用 6 在回访备注提交后自动评分，返回 1-10 分 + 评价文本
• AC6：所有 AI 调用记录持久化（conversation_id, message_id, app_id, user_id/系统, role, content, tokens_used, nickname, created_at, site_id）

---

设计要点

6 个 AI 应用

应用	用途	调用方式	触发条件
应用 1	通用对话	用户主动（流式）	点击 AI 入口
应用 2	财务洞察	后台轮询	每日
应用 3	消费习惯分析	后台轮询	客户新增消费
应用 4	关系分析/任务建议	后台轮询	助教参与新结算
应用 5	话术参考	后台联动	应用 4 调用时
应用 6	备注含金量	后台事件	回访任务完成时

信息隔离

应用 1 通过 biz_params.user_prompt_params 传入：

• User_ID：当前用户 ID
• Role：身份（助教/管理者）
• Nickname：昵称

百炼平台侧根据参数做数据查询隔离。

AI 入口汇总

所有入口统一使用应用 1，跳转 chat.html，第一条消息为页面上下文：

来源页面	触发方式	上下文内容
task-list	长按任务 → AI	任务详情 + 客户-助教关系
task-detail / coach-detail / customer-detail	"问问助手"	页面完整内容
board-* / performance-* / customer-service-records / my-profile	右下角 AI 按钮	页面内容摘要

表结构

biz.ai_conversations
  - id, user_id, nickname, app_id, site_id
  - source_page, source_context (JSON)
  - created_at

biz.ai_messages
  - id, conversation_id, role (user/assistant/system)
  - content, tokens_used
  - created_at

biz.ai_cache
  - id, cache_type (app2_finance/app3_habit/app4_analysis/app5_tactics/app6_score)
  - site_id, target_id (member_id 或 assistant_id 或 pair)
  - result_json, score (应用6专用)
  - triggered_by (trigger_job_id)
  - created_at, expires_at

---

任务清单

• T1：创建 biz.ai_conversations + biz.ai_messages + biz.ai_cache 表
• T2：实现百炼 API 统一封装层（流式/非流式、重试、日志）
• T3：实现应用 1 通用对话 API（SSE 流式返回）
• T4：实现页面内容文本化工具（各页面数据 → AI 可读文本）
• T5：实现应用 2 财务洞察轮询任务
• T6：实现应用 3 消费习惯分析轮询任务
• T7：实现应用 4 关系分析轮询任务
• T8：实现应用 5 话术参考联动任务
• T9：实现应用 6 备注含金量评分（集成到回访完成事件）
• T10：实现 AI 缓存读写 API（前端读取缓存结果）
• T11：查阅百炼文档确认流式返回技术方案（SSE vs WebSocket）