202 lines
18 KiB
Markdown
202 lines
18 KiB
Markdown
# 需求文档 — RNS1.4：CHAT 对齐与联调收尾
|
||
|
||
## 简介
|
||
|
||
RNS1.4 是 NS1 小程序后端 API 补全项目的最后一个子 spec，负责 CHAT 模块路径迁移和功能补全、FDW 端到端验证、以及全量前后端联调。本 spec 依赖 RNS1.0-1.3 全部完成，是整个 RNS1 系列的收尾阶段，确保 13 个页面全部连接真实后端运行，无 mock 数据残留。
|
||
|
||
### 依赖
|
||
|
||
- RNS1.0（基础设施与契约重写）— 全局响应包装中间件、camelCase 转换、重写后的 API 契约
|
||
- RNS1.1（任务与绩效接口）— TASK-1/2、PERF-1/2、PIN 接口已实现
|
||
- RNS1.2（客户与助教接口）— CUST-1/2、COACH-1 接口已实现
|
||
- RNS1.3（三看板接口）— BOARD-1/2/3、CONFIG-1 接口已实现
|
||
- 后端已有 `xcx_ai.py`（现有 `/api/ai/*` 路由，需迁移）
|
||
- 前端已有 chat.ts 和 chat-history.ts 页面（P5.2 交付），当前使用 mock 数据和模拟流式输出
|
||
|
||
### 来源文档
|
||
|
||
- `docs/prd/Neo_Specs/RNS1-split-plan.md` — 拆分计划主文档
|
||
- `docs/miniprogram-dev/API-contract.md` — API 契约（RNS1.0 T0-5 重写后版本）
|
||
- `docs/prd/Neo_Specs/storyboard-walkthrough-assistant-view.md` — 助教视角走查报告（GAP-45~51）
|
||
|
||
## 术语表
|
||
|
||
- **Backend**：FastAPI 后端应用，位于 `apps/backend/`
|
||
- **Miniprogram**：微信小程序前端应用，位于 `apps/miniprogram/`
|
||
- **CHAT_1_API**：对话历史列表接口 `GET /api/xcx/chat/history`，返回分页的对话列表
|
||
- **CHAT_2_API**：对话消息接口 `GET /api/xcx/chat/{chatId}/messages` 或 `GET /api/xcx/chat/messages?customerId={customerId}`，返回指定对话的消息列表
|
||
- **CHAT_3_API**：发送消息接口 `POST /api/xcx/chat/{chatId}/messages`，发送用户消息并获取 AI 同步回复
|
||
- **CHAT_4_SSE**：SSE 流式端点 `POST /api/xcx/chat/stream`，通过 Server-Sent Events 逐 token 返回 AI 回复
|
||
- **SSE**：Server-Sent Events，服务端推送事件协议，用于 AI 流式回复的逐 token 输出
|
||
- **referenceCard**：引用卡片，消息中附带的结构化上下文数据（类型/标题/摘要/键值对），用于展示客户概览等信息
|
||
- **FDW**：PostgreSQL Foreign Data Wrapper，用于从业务库 `zqyy_app` 访问 ETL 库 `etl_feiqiu` 的数据
|
||
- **chat_sessions**：业务库 `zqyy_app` 中的对话会话表，存储对话元数据
|
||
- **chat_messages**：业务库 `zqyy_app` 中的消息表，存储对话消息内容
|
||
- **Response_Wrapper**：RNS1.0 实现的全局响应包装中间件，`text/event-stream` 响应自动跳过包装
|
||
- **items_sum**：DWD-DOC 强制使用的消费金额口径
|
||
- **联调**：前后端联合调试，验证所有页面使用真实后端数据正常运行
|
||
|
||
## 需求
|
||
|
||
### 需求 1：CHAT 路径迁移（T4-1）
|
||
|
||
**用户故事：** 作为前后端开发者，我希望 CHAT 模块的 API 路径从 `/api/ai/*` 统一迁移到 `/api/xcx/chat/*`，以便与其他小程序接口保持一致的路径命名规范。
|
||
|
||
#### 验收标准
|
||
|
||
1. THE Backend SHALL 将现有 `/api/ai/*` 路由全部迁移到 `/api/xcx/chat/*` 路径下，包括同步端点和 SSE 流式端点
|
||
2. THE Backend SHALL 在迁移后移除原 `/api/ai/*` 路径，不保留旧路径的兼容映射
|
||
3. THE Backend SHALL 将迁移后的路由注册到 `xcx_chat` router（或等效命名），与其他 `xcx_*` 路由模块保持一致的组织结构
|
||
4. THE Miniprogram SHALL 更新 `services/api.ts` 中所有 CHAT 相关的 API 调用路径，从 `/api/ai/*` 改为 `/api/xcx/chat/*`
|
||
5. WHEN CHAT_4_SSE 端点迁移到 `/api/xcx/chat/stream` 后，THE Response_Wrapper SHALL 继续对 `text/event-stream` 响应跳过包装（RNS1.0 已实现的行为不受路径变更影响）
|
||
|
||
### 需求 2：实现 CHAT-1 对话历史列表（T4-2 历史列表部分）
|
||
|
||
**用户故事：** 作为助教，我希望在对话历史页面看到所有对话记录（含对话标题和最后消息摘要），以便快速找到并继续之前的对话。
|
||
|
||
#### 验收标准
|
||
|
||
1. THE CHAT_1_API SHALL 实现 `GET /api/xcx/chat/history` 端点，接受 `page`（默认 1）和 `pageSize`（默认 20）查询参数，返回分页的对话历史列表
|
||
2. THE CHAT_1_API SHALL 为每条对话记录返回以下字段：`id`（对话 ID）、`title`（对话标题）、`customerName`（关联客户姓名，可选）、`lastMessage`（最后一条消息摘要）、`timestamp`（最后消息时间，ISO 8601 格式）、`unreadCount`（未读消息数）
|
||
3. THE CHAT_1_API SHALL 从 `zqyy_app.chat_sessions` 查询对话列表，按最后消息时间倒序排列
|
||
4. THE CHAT_1_API SHALL 为 `title` 字段生成对话标题：优先使用对话会话中存储的自定义标题，若无自定义标题则使用关联客户姓名，若均无则使用首条消息内容的前 20 个字符作为标题
|
||
5. THE CHAT_1_API SHALL 返回标准分页字段：`total`（总记录数）、`page`（当前页码）、`pageSize`（每页条数）
|
||
6. THE CHAT_1_API SHALL 通过当前登录用户的身份过滤对话列表，确保每位助教只能看到自己的对话记录
|
||
|
||
### 需求 3：实现 CHAT-2 对话消息查看（T4-2 消息查看部分）
|
||
|
||
**用户故事：** 作为助教，我希望查看指定对话的消息列表，以便回顾与 AI 助手的对话内容。
|
||
|
||
#### 验收标准
|
||
|
||
1. THE CHAT_2_API SHALL 实现两个等效的消息查询端点：`GET /api/xcx/chat/{chatId}/messages`（通过对话 ID 查询）和 `GET /api/xcx/chat/messages?contextType={type}&contextId={id}`（通过上下文类型和 ID 查询）
|
||
2. THE CHAT_2_API SHALL 接受 `page`（默认 1）和 `pageSize`（默认 50）查询参数，返回分页的消息列表
|
||
3. THE CHAT_2_API SHALL 为每条消息返回以下字段：`id`（消息 ID）、`role`（`user` 或 `assistant`）、`content`（消息内容）、`createdAt`（创建时间，ISO 8601 格式）、`referenceCard`（引用卡片，可选）
|
||
4. THE CHAT_2_API SHALL 统一使用 `createdAt` 作为消息时间字段名（替代前端使用的 `timestamp` 和旧契约的 `created_at`，遵循 camelCase 规范）
|
||
5. THE CHAT_2_API SHALL 从 `zqyy_app.chat_messages` 查询消息列表，按 `createdAt` 正序排列（最早的消息在前）
|
||
6. THE CHAT_2_API SHALL 在响应中返回 `chatId` 字段，供前端后续发送消息时使用（尤其是通过上下文入口时，前端需要获取对应的 `chatId`）
|
||
7. THE CHAT_2_API SHALL 返回标准分页字段：`total`（总记录数）、`page`（当前页码）、`pageSize`（每页条数）
|
||
|
||
#### 3.2 上下文对话复用规则
|
||
|
||
8. WHEN 通过 `contextType` 和 `contextId` 查询参数调用消息端点时，THE CHAT_2_API SHALL 按以下规则查找或创建对话：
|
||
- `contextType='task'`：查找同一用户、同一 `contextId`（taskId）的已有对话，找到则复用（无时限），找不到则新建
|
||
- `contextType='customer'` 或 `contextType='coach'`：查找同一用户、同一 `contextId` 的已有对话，若最后消息时间 ≤ 3 天则复用，> 3 天或不存在则新建
|
||
- `contextType='general'`：始终新建对话
|
||
9. THE CHAT_2_API SHALL 在 `ai_conversations` 中记录 `context_type` 和 `context_id` 字段，用于后续对话查找
|
||
10. THE CHAT_2_API SHALL 确保对话复用查找基于 `(user_id, site_id, context_type, context_id)` 组合，不同用户的对话互不影响
|
||
|
||
|
||
### 需求 4：CHAT referenceCard 支持（T4-3）
|
||
|
||
**用户故事：** 作为助教，我希望在与 AI 助手对话时，消息中能附带客户概览卡片（含余额、消费、到店频次等键值对数据），以便在对话上下文中快速查看客户关键信息。
|
||
|
||
#### 验收标准
|
||
|
||
1. THE CHAT_2_API SHALL 为消息返回可选的 `referenceCard` 字段，结构包含：`type`（引用类型，`customer` 或 `record` 枚举）、`title`（卡片标题，如 `"张伟 — 消费概览"`）、`summary`（摘要文字）、`data`（`Record<string, string>` 键值对详情，如 `{ "近30天消费": "¥2,380", "到店次数": "8次" }`）
|
||
2. WHEN AI 助手回复消息涉及特定客户时，THE Backend SHALL 从 FDW 查询该客户的关键指标（余额、近期消费、到店频次等），组装为 `referenceCard` 附加到 AI 回复消息中
|
||
3. THE Backend SHALL 将 `referenceCard` 数据持久化存储到 `chat_messages` 表中（作为 JSON 字段），以便历史消息查看时仍能展示引用卡片
|
||
4. THE Miniprogram SHALL 在 chat 页面的消息列表中，检测消息的 `referenceCard` 字段，若存在则渲染为结构化卡片组件（标题 + 摘要 + 键值对列表）
|
||
|
||
#### 4.2 多入口参数路由（GAP-50）
|
||
|
||
5. THE Miniprogram SHALL 在 chat 页面的 `onLoad(options)` 中实现多入口参数路由逻辑，按以下优先级处理入口参数：
|
||
- 若 `options.historyId` 存在（从 chat-history 跳转），使用 `historyId` 作为 `chatId` 直接加载历史消息
|
||
- 若 `options.taskId` 存在（从 task-detail 跳转），使用 `contextType=task` + `contextId=taskId` 调用 CHAT_2_API，由后端查找同一任务的已有对话（始终复用，无时限）
|
||
- 若 `options.customerId` 存在（从 customer-detail 跳转），使用 `contextType=customer` + `contextId=customerId` 调用 CHAT_2_API，由后端按 3 天时限判断复用或新建
|
||
- 若 `options.coachId` 存在（从 coach-detail 跳转），使用 `contextType=coach` + `contextId=coachId` 调用 CHAT_2_API，由后端按 3 天时限判断复用或新建
|
||
6. WHEN 通过上下文入口进入对话后，THE Miniprogram SHALL 将后端返回的 `chatId` 缓存到页面 data 中，后续发送消息和 SSE 流式请求均使用该 `chatId`
|
||
7. IF chat 页面未收到任何入口参数（`historyId`/`taskId`/`customerId`/`coachId` 均为空），THEN THE Miniprogram SHALL 使用 `contextType=general` 调用 CHAT_2_API 创建一个通用对话
|
||
|
||
### 需求 5：CHAT-3 发送消息（T4-2 发送部分）
|
||
|
||
**用户故事：** 作为助教，我希望在对话页面发送消息后能立即收到 AI 的同步回复，以便在不支持 SSE 的场景下也能正常使用 AI 助手。
|
||
|
||
#### 验收标准
|
||
|
||
1. THE CHAT_3_API SHALL 实现 `POST /api/xcx/chat/{chatId}/messages` 端点，接受请求体 `{ content: string }`
|
||
2. THE CHAT_3_API SHALL 将用户消息存入 `chat_messages` 表，调用 AI 服务获取回复，将 AI 回复也存入 `chat_messages` 表
|
||
3. THE CHAT_3_API SHALL 返回包含用户消息和 AI 回复的响应：`userMessage`（含 `id`/`content`/`createdAt`）和 `aiReply`（含 `id`/`content`/`createdAt`）
|
||
4. THE CHAT_3_API SHALL 在发送消息后更新 `chat_sessions` 表的 `lastMessage` 和最后消息时间字段
|
||
5. IF AI 服务调用失败或超时，THEN THE CHAT_3_API SHALL 仍保存用户消息，并返回 AI 回复为错误提示消息（如 `{ content: "抱歉，AI 助手暂时无法回复，请稍后重试" }`），HTTP 状态码保持 200
|
||
6. THE CHAT_3_API SHALL 验证请求的 `chatId` 属于当前登录助教，不属于时返回 HTTP 403
|
||
|
||
### 需求 6：CHAT-4 SSE 流式端点（T4-1 SSE 部分）
|
||
|
||
**用户故事：** 作为助教，我希望 AI 助手的回复能以流式方式逐字显示，以便获得更自然的对话体验，减少等待感。
|
||
|
||
#### 验收标准
|
||
|
||
1. THE CHAT_4_SSE SHALL 实现 `POST /api/xcx/chat/stream` 端点，接受请求体 `{ chatId: string, content: string }`，响应内容类型为 `text/event-stream`
|
||
2. THE CHAT_4_SSE SHALL 发送以下三种 SSE 事件类型：
|
||
- `event: message` — 逐 token 输出，`data` 为 `{"token": "<文本片段>"}`
|
||
- `event: done` — 流结束，`data` 为 `{"messageId": "<完整消息ID>", "createdAt": "<ISO 8601>"}`
|
||
- `event: error` — 错误，`data` 为 `{"message": "<错误描述>"}`
|
||
3. THE CHAT_4_SSE SHALL 在流开始前将用户消息存入 `chat_messages` 表，在流结束后将完整的 AI 回复存入 `chat_messages` 表
|
||
4. THE CHAT_4_SSE SHALL 在流结束后更新 `chat_sessions` 表的 `lastMessage` 和最后消息时间字段
|
||
5. THE Response_Wrapper SHALL 对 `text/event-stream` 响应跳过全局包装，直接透传 SSE 事件流（RNS1.0 已实现）
|
||
6. THE CHAT_4_SSE SHALL 验证请求的 `chatId` 属于当前登录助教，不属于时返回 HTTP 403（此时响应为普通 JSON 错误，非 SSE）
|
||
7. THE Miniprogram SHALL 将 chat 页面现有的 `simulateStreamOutput()`（模拟逐字输出）替换为真实的 SSE 连接，通过 `wx.request` 或兼容方案接收 `text/event-stream` 响应
|
||
|
||
|
||
### 需求 7：FDW 端到端验证（T4-4）
|
||
|
||
**用户故事：** 作为后端开发者，我希望验证所有 FDW 查询在测试环境链路（`test_zqyy_app` → `test_etl_feiqiu`）上正常工作，以便确保 RNS1.1-1.3 实现的所有接口在真实数据链路上不会因 FDW 连接、权限或性能问题而失败。
|
||
|
||
#### 验收标准
|
||
|
||
1. THE Backend SHALL 验证所有 `fdw_etl.*` 视图在 `test_zqyy_app` 数据库中可正常访问，包括但不限于：`v_dws_assistant_salary_calc`、`v_dwd_assistant_service_log`、`v_dim_member`、`v_dim_assistant`、`v_dws_member_consumption_summary`、`v_dws_member_assistant_relation_index`、`v_dws_finance_*` 系列视图
|
||
2. THE Backend SHALL 验证每个 FDW 视图的查询响应时间在可接受范围内（单次查询不超过 3 秒），对超时的查询记录慢查询日志并评估是否需要添加索引
|
||
3. THE Backend SHALL 验证 FDW 查询在带有典型过滤条件（如 `assistant_id`、`member_id`、日期范围）时能正确返回数据，且结果集与直接查询 `test_etl_feiqiu` 的结果一致
|
||
4. IF 某个 FDW 视图不存在或权限不足，THEN THE Backend SHALL 记录具体的错误信息（视图名、错误类型），并在验证报告中标注需要 DBA 介入修复
|
||
5. THE Backend SHALL 检查 FDW 链路上的关键索引是否存在：`chat_sessions` 表的 `(assistant_id, customer_id)` 索引、`chat_messages` 表的 `(session_id, created_at)` 索引
|
||
|
||
### 需求 8：前端联调修复 — notes 页触底加载（T4-5 F11）
|
||
|
||
**用户故事：** 作为助教，我希望在备注列表页面滚动到底部时自动加载更多备注，以便查看全部备注记录而不需要手动翻页。
|
||
|
||
#### 验收标准
|
||
|
||
1. THE Miniprogram SHALL 在 notes 页面实现 `onReachBottom()` 生命周期函数，当用户滚动到页面底部时自动请求下一页备注数据
|
||
2. WHEN 触底加载触发时，THE Miniprogram SHALL 将 `page` 参数加 1，调用 `fetchNotes({ page, pageSize })` 接口，将返回的备注追加到已有列表末尾
|
||
3. WHEN 后端返回的 `hasMore` 为 `false` 或返回的备注数量小于 `pageSize` 时，THE Miniprogram SHALL 停止触底加载，显示"没有更多了"提示
|
||
4. THE Miniprogram SHALL 在触底加载过程中显示加载状态指示器，防止重复触发请求
|
||
|
||
### 需求 9：前端联调修复 — customer-service-records 按月请求（T4-5 F10）
|
||
|
||
**用户故事：** 作为助教，我希望客户服务记录页面在切换月份时向后端请求对应月份的数据，以便在数据量大时页面仍能快速响应，而不是全量加载后本地过滤。
|
||
|
||
#### 验收标准
|
||
|
||
1. THE Miniprogram SHALL 修改 customer-service-records 页面的月份切换逻辑，从当前的"全量加载后本地过滤"改为"按月请求 API"
|
||
2. WHEN 用户切换月份时，THE Miniprogram SHALL 使用新的 `year`/`month` 参数调用 `fetchCustomerRecords({ customerId, year, month })` 接口，加载对应月份的服务记录
|
||
3. THE Miniprogram SHALL 在月份切换时清空已有记录列表，显示加载状态，待新数据返回后渲染
|
||
4. THE Miniprogram SHALL 在首次加载时默认请求当前月份的数据，而非全量数据
|
||
5. THE Backend SHALL 确保 CUST-2 接口支持 `year` 和 `month` 查询参数，仅返回指定月份的服务记录（RNS1.2 T2-4 已实现按月查询能力）
|
||
|
||
### 需求 10：全量前后端联调（T4-5 联调部分）
|
||
|
||
**用户故事：** 作为开发团队，我们希望 13 个小程序页面全部连接真实后端运行，无 mock 数据残留，以便确认整个应用在真实数据环境下功能完整、交互正常。
|
||
|
||
#### 验收标准
|
||
|
||
1. THE Miniprogram SHALL 移除所有页面中的内联 mock 数据和 mock 数据导入（`import { mockXxx } from '../../utils/mock-data'`），全部替换为真实 API 调用
|
||
2. THE Miniprogram SHALL 确保以下 13 个页面均能使用真实后端数据正常渲染：`task-list`、`task-detail`、`notes`、`performance`、`performance-records`、`customer-detail`、`customer-service-records`、`coach-detail`、`board-coach`、`board-customer`、`board-finance`、`chat-history`、`chat`
|
||
3. WHEN 某个页面的 API 调用失败时，THE Miniprogram SHALL 显示友好的错误提示（如 Toast 或空状态占位），不出现白屏或未捕获异常
|
||
4. THE Miniprogram SHALL 验证所有页面间的跳转参数传递正确（RNS1.0 T0-6 已修复的跨页面参数），确保目标页面能正确加载对应数据
|
||
5. THE Miniprogram SHALL 验证 chat 页面从 4 个入口（task-detail、customer-detail、coach-detail、chat-history）进入时均能正确关联上下文并加载对应对话
|
||
6. IF 联调过程中发现新的 Bug 或数据不一致问题，THEN THE Miniprogram 和 Backend SHALL 在本 spec 范围内修复，修复内容记录到联调问题清单中
|
||
|
||
### 需求 11：全局约束与权限控制
|
||
|
||
**用户故事：** 作为系统管理员，我希望所有 CHAT 接口遵循统一的权限控制和数据隔离规则，以确保每位助教只能访问自己的对话数据。
|
||
|
||
#### 验收标准
|
||
|
||
1. THE Backend SHALL 对所有 RNS1.4 CHAT 接口（CHAT-1、CHAT-2、CHAT-3、CHAT-4）执行 `require_approved()` 权限检查，确保用户状态为 `approved`
|
||
2. THE Backend SHALL 通过当前登录用户的身份信息过滤对话数据，确保每位助教只能访问自己创建的或与自己关联的对话
|
||
3. IF 当前用户未通过审核（状态非 `approved`），THEN THE Backend SHALL 返回 HTTP 403 `{ code: 403, message: "用户未通过审核，无法访问此资源" }`
|
||
4. THE Backend SHALL 对所有 CHAT 接口的响应字段名统一使用 camelCase 格式（与 RNS1.0 的 CamelCase_Converter 一致）
|
||
5. THE Backend SHALL 确保 CHAT 模块的错误响应格式与全局异常处理器一致：`{ code: <HTTP状态码>, message: <错误详情> }`
|
||
6. WHEN CHAT 模块查询 FDW 数据（如为 referenceCard 获取客户指标）时，THE Backend SHALL 遵循 DWD-DOC 强制规则：金额使用 `items_sum` 口径，会员信息通过 `member_id` JOIN `dim_member` 获取
|