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