705 lines
30 KiB
Markdown
705 lines
30 KiB
Markdown
# 技术设计文档 — RNS1.4：CHAT 对齐与联调收尾
|
||
|
||
## 概述
|
||
|
||
RNS1.4 是 RNS1 系列的收尾 spec，覆盖三大块工作：
|
||
|
||
1. **CHAT 模块路径迁移与功能补全**（T4-1 ~ T4-3）：将现有 `/api/ai/*` 路由迁移到 `/api/xcx/chat/*`，实现 CHAT-1/2/3/4 四个端点，支持 referenceCard 和多入口参数路由
|
||
2. **FDW 端到端验证**（T4-4）：验证 `test_zqyy_app` → `test_etl_feiqiu` 链路上所有 FDW 视图可访问、性能达标、索引完备
|
||
3. **全量前后端联调**（T4-5）：13 个页面移除 mock 数据，连接真实后端，修复 notes 触底加载和 customer-service-records 按月请求
|
||
|
||
### 设计原则
|
||
|
||
- **复用优先**：现有 `biz.ai_conversations` / `biz.ai_messages` 表结构通过 DDL 迁移扩展，新增 CHAT 所需字段（`customer_id`、`title`、`last_message`、`reference_card`），不新建表
|
||
- **契约驱动**：所有端点严格遵循 `API-contract.md` 中 CHAT-1/2/3/4 的定义
|
||
- **权限一致**：所有 CHAT 端点使用 `require_approved()` 依赖，与 RNS1.1-1.3 保持一致
|
||
- **DWD-DOC 强制规则**：referenceCard 中涉及金额使用 `items_sum` 口径，会员信息通过 `member_id` JOIN `dim_member`
|
||
|
||
### 依赖关系
|
||
|
||
```mermaid
|
||
graph LR
|
||
RNS10[RNS1.0<br/>基础设施] --> RNS14[RNS1.4<br/>CHAT + 联调]
|
||
RNS11[RNS1.1<br/>任务/绩效] --> RNS14
|
||
RNS12[RNS1.2<br/>客户/助教] --> RNS14
|
||
RNS13[RNS1.3<br/>三看板] --> RNS14
|
||
style RNS14 fill:#f9f,stroke:#333
|
||
```
|
||
|
||
## 架构
|
||
|
||
### 整体架构
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "微信小程序 (apps/miniprogram/)"
|
||
FE_CHAT[pages/chat/chat.ts]
|
||
FE_HIST[pages/chat-history/chat-history.ts]
|
||
FE_API[services/api.ts]
|
||
FE_REQ[utils/request.ts]
|
||
FE_CHAT --> FE_API
|
||
FE_HIST --> FE_API
|
||
FE_API --> FE_REQ
|
||
end
|
||
|
||
subgraph "FastAPI 后端 (apps/backend/app/)"
|
||
MW[ResponseWrapperMiddleware<br/>SSE 自动跳过]
|
||
ROUTER[routers/xcx_chat.py<br/>CHAT-1/2/3/4]
|
||
SCHEMA[schemas/xcx_chat.py<br/>Pydantic CamelModel]
|
||
SVC[services/chat_service.py<br/>对话业务逻辑]
|
||
AI_SVC[ai/conversation_service.py<br/>AI 调用 + 持久化]
|
||
BAILIAN[ai/bailian_client.py<br/>百炼 API]
|
||
FDW_Q[services/fdw_queries.py<br/>FDW 查询]
|
||
DB[database.py]
|
||
|
||
MW --> ROUTER
|
||
ROUTER --> SCHEMA
|
||
ROUTER --> SVC
|
||
SVC --> AI_SVC
|
||
SVC --> FDW_Q
|
||
AI_SVC --> BAILIAN
|
||
SVC --> DB
|
||
end
|
||
|
||
subgraph "数据库"
|
||
APP_DB[(zqyy_app<br/>biz.ai_conversations<br/>biz.ai_messages)]
|
||
ETL_DB[(etl_feiqiu via FDW<br/>fdw_etl.v_dim_member<br/>fdw_etl.v_dws_member_*)]
|
||
end
|
||
|
||
FE_REQ -->|HTTP JSON / SSE| MW
|
||
DB --> APP_DB
|
||
FDW_Q --> ETL_DB
|
||
|
||
style ROUTER fill:#f9f,stroke:#333
|
||
style SVC fill:#f9f,stroke:#333
|
||
```
|
||
|
||
### 请求-响应流程（SSE 流式）
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant MP as 小程序 chat.ts
|
||
participant MW as ResponseWrapper
|
||
participant R as xcx_chat.py
|
||
participant S as chat_service.py
|
||
participant AI as BailianClient
|
||
participant DB as zqyy_app
|
||
|
||
MP->>MW: POST /api/xcx/chat/stream<br/>{chatId, content}
|
||
MW->>R: 透传（SSE 跳过包装）
|
||
R->>R: require_approved() + 验证 chatId 归属
|
||
R->>S: stream_chat(chatId, content, user)
|
||
S->>DB: INSERT user message → ai_messages
|
||
S->>AI: 流式调用百炼 API
|
||
|
||
loop 逐 token
|
||
AI-->>S: token 片段
|
||
S-->>R: SSEEvent(type=message, token=...)
|
||
R-->>MW: data: {"token": "..."}
|
||
MW-->>MP: 透传 SSE 事件
|
||
end
|
||
|
||
S->>DB: INSERT AI reply → ai_messages
|
||
S->>DB: UPDATE ai_conversations.last_message
|
||
S-->>R: SSEEvent(type=done, messageId, createdAt)
|
||
R-->>MW: data: {"messageId": "...", "createdAt": "..."}
|
||
MW-->>MP: 透传 done 事件
|
||
```
|
||
|
||
|
||
## 组件与接口
|
||
|
||
### 组件 1：xcx_chat 路由模块（路径迁移 + CHAT-1/2/3/4）
|
||
|
||
**位置**：`apps/backend/app/routers/xcx_chat.py`（新文件，替代 `xcx_ai_chat.py`）
|
||
|
||
**职责**：将现有 `/api/ai/*` 路由迁移到 `/api/xcx/chat/*`，并实现 CHAT-1/2/3/4 四个端点。
|
||
|
||
**迁移策略**：
|
||
- 新建 `xcx_chat.py`，prefix 为 `/api/xcx/chat`
|
||
- 从 `xcx_ai_chat.py` 迁移 SSE 流式对话、历史列表、消息查询三个端点
|
||
- 在 `main.py` 中替换路由注册：移除 `xcx_ai_chat.router`，注册 `xcx_chat.router`
|
||
- 删除 `xcx_ai_chat.py`（不保留旧路径兼容）
|
||
|
||
**端点定义**：
|
||
|
||
```python
|
||
router = APIRouter(prefix="/api/xcx/chat", tags=["小程序 CHAT"])
|
||
|
||
# CHAT-1: 对话历史列表
|
||
@router.get("/history")
|
||
async def list_chat_history(
|
||
page: int = Query(1, ge=1),
|
||
page_size: int = Query(20, ge=1, le=100),
|
||
user: CurrentUser = Depends(require_approved()),
|
||
) -> ChatHistoryResponse: ...
|
||
|
||
# CHAT-2a: 通过 chatId 查询消息
|
||
@router.get("/{chat_id}/messages")
|
||
async def get_chat_messages(
|
||
chat_id: int,
|
||
page: int = Query(1, ge=1),
|
||
page_size: int = Query(50, ge=1, le=100),
|
||
user: CurrentUser = Depends(require_approved()),
|
||
) -> ChatMessagesResponse: ...
|
||
|
||
# CHAT-2b: 通过上下文查询消息（自动查找/创建对话）
|
||
@router.get("/messages")
|
||
async def get_chat_messages_by_context(
|
||
context_type: str = Query(..., alias="contextType"), # task / customer / coach
|
||
context_id: str = Query(..., alias="contextId"),
|
||
page: int = Query(1, ge=1),
|
||
page_size: int = Query(50, ge=1, le=100),
|
||
user: CurrentUser = Depends(require_approved()),
|
||
) -> ChatMessagesResponse: ...
|
||
|
||
# CHAT-3: 发送消息（同步回复）
|
||
@router.post("/{chat_id}/messages")
|
||
async def send_message(
|
||
chat_id: int,
|
||
body: SendMessageRequest,
|
||
user: CurrentUser = Depends(require_approved()),
|
||
) -> SendMessageResponse: ...
|
||
|
||
# CHAT-4: SSE 流式端点
|
||
@router.post("/stream")
|
||
async def chat_stream(
|
||
body: ChatStreamRequest,
|
||
user: CurrentUser = Depends(require_approved()),
|
||
) -> StreamingResponse: ...
|
||
```
|
||
|
||
### 组件 2：chat_service 业务逻辑层
|
||
|
||
**位置**：`apps/backend/app/services/chat_service.py`（新文件）
|
||
|
||
**职责**：封装 CHAT 模块的核心业务逻辑，包括对话管理、消息持久化、referenceCard 组装。
|
||
|
||
**关键方法**：
|
||
|
||
```python
|
||
class ChatService:
|
||
"""CHAT 模块业务逻辑。"""
|
||
|
||
def get_chat_history(
|
||
self, user_id: int, site_id: int, page: int, page_size: int
|
||
) -> tuple[list[dict], int]:
|
||
"""CHAT-1: 查询对话历史列表，返回 (items, total)。"""
|
||
|
||
def get_or_create_session(
|
||
self, user_id: int, site_id: int,
|
||
context_type: str, context_id: str | None
|
||
) -> int:
|
||
"""按入口上下文查找或创建对话，返回 chat_id。
|
||
复用规则：
|
||
- context_type='task': 同一 taskId 始终复用（无时限）
|
||
- context_type='customer'/'coach': 最后消息 ≤ 3 天复用，> 3 天新建
|
||
- context_type='general': 始终新建
|
||
"""
|
||
|
||
def get_messages(
|
||
self, chat_id: int, user_id: int, site_id: int,
|
||
page: int, page_size: int
|
||
) -> tuple[list[dict], int, int]:
|
||
"""CHAT-2: 查询消息列表，返回 (messages, total, chat_id)。
|
||
验证 chat_id 归属当前用户。"""
|
||
|
||
def send_message_sync(
|
||
self, chat_id: int, content: str, user_id: int, site_id: int
|
||
) -> dict:
|
||
"""CHAT-3: 发送消息并获取同步 AI 回复。
|
||
1. 验证 chatId 归属
|
||
2. 存入用户消息
|
||
3. 调用 AI 获取回复
|
||
4. 存入 AI 回复
|
||
5. 更新 session 的 last_message / last_message_at
|
||
6. AI 失败时返回错误提示消息（HTTP 200）"""
|
||
|
||
def build_reference_card(
|
||
self, customer_id: int, site_id: int
|
||
) -> dict | None:
|
||
"""组装 referenceCard：从 FDW 查询客户关键指标。
|
||
遵循 DWD-DOC 规则：金额用 items_sum，会员信息通过 member_id JOIN dim_member。"""
|
||
|
||
def generate_title(self, session: dict) -> str:
|
||
"""生成对话标题：自定义标题 > 上下文名称 > 首条消息前20字。"""
|
||
```
|
||
|
||
**referenceCard 组装逻辑**：
|
||
|
||
```python
|
||
def build_reference_card(self, customer_id: int, site_id: int) -> dict | None:
|
||
"""从 FDW 查询客户指标，组装为 referenceCard 结构。"""
|
||
# 1. 通过 member_id JOIN fdw_etl.v_dim_member 获取客户姓名
|
||
# 2. 通过 fdw_etl.v_dws_member_consumption_summary 获取：
|
||
# - 余额（balance）
|
||
# - 近30天消费（items_sum 口径，非 consume_money）
|
||
# - 到店次数
|
||
# 3. 组装为 referenceCard 结构
|
||
return {
|
||
"type": "customer",
|
||
"title": f"{member_name} — 消费概览",
|
||
"summary": f"余额 ¥{balance}，近30天消费 ¥{consume_30d}",
|
||
"data": {
|
||
"余额": f"¥{balance}",
|
||
"近30天消费": f"¥{consume_30d}",
|
||
"到店次数": f"{visit_count}次",
|
||
}
|
||
}
|
||
```
|
||
|
||
### 组件 3：Pydantic Schema（CamelModel）
|
||
|
||
**位置**：`apps/backend/app/schemas/xcx_chat.py`（新文件）
|
||
|
||
**职责**：定义 CHAT 模块所有请求/响应的 Pydantic schema，继承 `CamelModel` 统一 camelCase 输出。
|
||
|
||
```python
|
||
from app.schemas.base import CamelModel
|
||
|
||
class ChatHistoryItem(CamelModel):
|
||
id: int
|
||
title: str
|
||
customer_name: str | None = None
|
||
last_message: str | None = None
|
||
timestamp: str # ISO 8601，最后消息时间
|
||
unread_count: int = 0
|
||
|
||
class ChatHistoryResponse(CamelModel):
|
||
items: list[ChatHistoryItem]
|
||
total: int
|
||
page: int
|
||
page_size: int
|
||
|
||
class ReferenceCard(CamelModel):
|
||
type: str # 'customer' | 'record'
|
||
title: str
|
||
summary: str
|
||
data: dict[str, str] # 键值对详情
|
||
|
||
class ChatMessageItem(CamelModel):
|
||
id: int
|
||
role: str # 'user' | 'assistant'
|
||
content: str
|
||
created_at: str # ISO 8601（统一字段名，替代 timestamp / created_at）
|
||
reference_card: ReferenceCard | None = None
|
||
|
||
class ChatMessagesResponse(CamelModel):
|
||
chat_id: int
|
||
items: list[ChatMessageItem]
|
||
total: int
|
||
page: int
|
||
page_size: int
|
||
|
||
class SendMessageRequest(CamelModel):
|
||
content: str
|
||
|
||
class SendMessageResponse(CamelModel):
|
||
user_message: MessageBrief
|
||
ai_reply: MessageBrief
|
||
|
||
class MessageBrief(CamelModel):
|
||
id: int
|
||
content: str
|
||
created_at: str
|
||
|
||
class ChatStreamRequest(CamelModel):
|
||
chat_id: int
|
||
content: str
|
||
```
|
||
|
||
### 组件 4：前端 chat 页面改造
|
||
|
||
**位置**：`apps/miniprogram/miniprogram/pages/chat/chat.ts`
|
||
|
||
**改造要点**：
|
||
|
||
1. **多入口参数路由**（GAP-49/50）：
|
||
```typescript
|
||
onLoad(options) {
|
||
if (options.historyId) {
|
||
// 从 chat-history 跳转：直接用 historyId 作为 chatId
|
||
this.chatId = options.historyId
|
||
this.loadMessages(this.chatId)
|
||
} else if (options.taskId) {
|
||
// 从 task-detail 跳转：同一 taskId 始终复用同一对话
|
||
this.loadMessagesByContext('task', options.taskId)
|
||
} else if (options.customerId) {
|
||
// 从 customer-detail 跳转：3 天内复用，超过 3 天新建
|
||
this.loadMessagesByContext('customer', options.customerId)
|
||
} else if (options.coachId) {
|
||
// 从 coach-detail 跳转：3 天内复用，超过 3 天新建
|
||
this.loadMessagesByContext('coach', options.coachId)
|
||
} else {
|
||
// 无参数：始终新建通用对话
|
||
this.loadMessagesByContext('general', '')
|
||
}
|
||
}
|
||
```
|
||
|
||
2. **SSE 替换 mock 流式输出**：
|
||
- 移除 `simulateStreamOutput()` 调用和 `mockAIReplies`
|
||
- 使用 `wx.request` + `enableChunked: true`（微信基础库 2.20.2+）接收 SSE
|
||
- 备选方案：轮询 CHAT-3 同步端点（不支持 chunked 的低版本基础库）
|
||
|
||
3. **referenceCard 渲染**：
|
||
- 消息列表中检测 `referenceCard` 字段，已有 `toDataList()` 和 WXML 模板，无需大改
|
||
- 确保从真实 API 返回的 `referenceCard` 结构与 mock 一致
|
||
|
||
### 组件 5：前端 chat-history 页面改造
|
||
|
||
**位置**：`apps/miniprogram/miniprogram/pages/chat-history/chat-history.ts`
|
||
|
||
**改造要点**：
|
||
- 移除 `mockChatHistory` 导入
|
||
- 调用 `fetchChatHistory()` 获取真实数据
|
||
- 响应字段映射：后端返回 `timestamp`（ISO 8601）→ 前端 `formatRelativeTime()` 处理
|
||
|
||
### 组件 6：前端 services/api.ts CHAT 模块对接
|
||
|
||
**位置**：`apps/miniprogram/miniprogram/services/api.ts`
|
||
|
||
**改造要点**：
|
||
- `fetchChatHistory()`：调用 `GET /api/xcx/chat/history`
|
||
- `fetchChatMessages()`：调用 `GET /api/xcx/chat/{chatId}/messages`
|
||
- `fetchChatMessagesByContext(contextType, contextId)`：新增，调用 `GET /api/xcx/chat/messages?contextType={type}&contextId={id}`
|
||
- `sendChatMessage()`：调用 `POST /api/xcx/chat/{chatId}/messages`
|
||
- 移除所有 CHAT 相关 mock 数据导入
|
||
- `USE_REAL_API` 开关对 CHAT 模块设为 `true`
|
||
|
||
### 组件 7：FDW 验证脚本
|
||
|
||
**位置**：`scripts/ops/verify_fdw_e2e.py`（新文件）
|
||
|
||
**职责**：一次性验证脚本，检查 `test_zqyy_app` → `test_etl_feiqiu` FDW 链路。
|
||
|
||
**验证项**：
|
||
1. 所有 `fdw_etl.*` 视图可访问（SELECT 1 FROM ... LIMIT 1）
|
||
2. 带典型过滤条件的查询响应时间 < 3s
|
||
3. 关键索引存在检查（`chat_sessions` 的 `(assistant_id, customer_id)` 等）
|
||
4. 结果输出为结构化报告（JSON），失败项标注需 DBA 介入
|
||
|
||
### 组件 8：联调修复 — notes 触底加载 & customer-service-records 按月请求
|
||
|
||
**notes 页面**（`pages/notes/notes.ts`）：
|
||
- 实现 `onReachBottom()` 生命周期函数
|
||
- 维护 `page` 状态，触底时 `page++` 调用 `fetchNotes({ page, pageSize })`
|
||
- 追加数据到已有列表，`hasMore === false` 时停止加载
|
||
|
||
**customer-service-records 页面**（`pages/customer-service-records/customer-service-records.ts`）：
|
||
- 月份切换时调用 `fetchCustomerRecords({ customerId, year, month })`
|
||
- 清空已有列表 → 显示 loading → 渲染新数据
|
||
- 首次加载默认当前月份
|
||
|
||
|
||
## 数据模型
|
||
|
||
### 表结构变更：扩展 `biz.ai_conversations`
|
||
|
||
现有 `biz.ai_conversations` 表需新增字段以支持 CHAT API 契约：
|
||
|
||
```sql
|
||
-- 迁移脚本：扩展 ai_conversations 支持 CHAT 模块
|
||
ALTER TABLE biz.ai_conversations
|
||
ADD COLUMN IF NOT EXISTS context_type varchar(20), -- 关联上下文类型：task / customer / coach / general
|
||
ADD COLUMN IF NOT EXISTS context_id varchar(50), -- 关联上下文 ID（taskId / customerId / coachId）
|
||
ADD COLUMN IF NOT EXISTS title varchar(200), -- 对话标题
|
||
ADD COLUMN IF NOT EXISTS last_message text, -- 最后一条消息摘要
|
||
ADD COLUMN IF NOT EXISTS last_message_at timestamptz; -- 最后消息时间
|
||
|
||
COMMENT ON COLUMN biz.ai_conversations.context_type IS '对话关联上下文类型：task（任务）/ customer（客户）/ coach（助教）/ general（通用）';
|
||
COMMENT ON COLUMN biz.ai_conversations.context_id IS '关联上下文 ID：task 入口为 taskId，customer 入口为 customerId，coach 入口为 coachId，general 为 NULL';
|
||
COMMENT ON COLUMN biz.ai_conversations.title IS '对话标题：自定义 > 上下文名称 > 首条消息前20字';
|
||
COMMENT ON COLUMN biz.ai_conversations.last_message IS '最后一条消息内容摘要（截断至100字）';
|
||
COMMENT ON COLUMN biz.ai_conversations.last_message_at IS '最后消息时间，用于历史列表排序和对话复用时限判断';
|
||
```
|
||
|
||
**新增索引**：
|
||
|
||
```sql
|
||
-- 上下文对话查找（按 context_type + context_id 查找可复用对话）
|
||
CREATE INDEX idx_ai_conv_context
|
||
ON biz.ai_conversations (user_id, site_id, context_type, context_id, last_message_at DESC NULLS LAST)
|
||
WHERE context_type IS NOT NULL;
|
||
|
||
-- 历史列表排序优化（CHAT-1: 按 last_message_at 倒序）
|
||
CREATE INDEX idx_ai_conv_last_msg
|
||
ON biz.ai_conversations (user_id, site_id, last_message_at DESC NULLS LAST);
|
||
```
|
||
|
||
### 对话复用规则
|
||
|
||
不同入口的对话创建/复用策略：
|
||
|
||
| 入口 | context_type | context_id | 复用规则 |
|
||
|------|-------------|-----------|---------|
|
||
| task-detail | `task` | taskId | **始终复用**：同一 taskId 归为同一个对话，无时限 |
|
||
| customer-detail | `customer` | customerId | **3 天时限**：最后一条消息 ≤ 3 天则复用，> 3 天则新建 |
|
||
| coach-detail | `coach` | coachId | **3 天时限**：最后一条消息 ≤ 3 天则复用，> 3 天则新建 |
|
||
| chat-history | — | — | **直接打开**：用 historyId 作为 chatId 加载已有对话 |
|
||
| 无参数（AI 按钮等） | `general` | NULL | **始终新建**：每次创建新对话 |
|
||
|
||
复用查找 SQL 模式：
|
||
```sql
|
||
-- task 入口：始终复用（无时限）
|
||
SELECT id FROM biz.ai_conversations
|
||
WHERE user_id = :user_id AND site_id = :site_id
|
||
AND context_type = 'task' AND context_id = :task_id
|
||
ORDER BY created_at DESC LIMIT 1;
|
||
|
||
-- customer / coach 入口：3 天时限复用
|
||
SELECT id FROM biz.ai_conversations
|
||
WHERE user_id = :user_id AND site_id = :site_id
|
||
AND context_type = :type AND context_id = :context_id
|
||
AND last_message_at > NOW() - INTERVAL '3 days'
|
||
ORDER BY last_message_at DESC LIMIT 1;
|
||
```
|
||
|
||
### 表结构变更：扩展 `biz.ai_messages`
|
||
|
||
```sql
|
||
-- 迁移脚本：扩展 ai_messages 支持 referenceCard
|
||
ALTER TABLE biz.ai_messages
|
||
ADD COLUMN IF NOT EXISTS reference_card jsonb; -- 引用卡片 JSON
|
||
|
||
COMMENT ON COLUMN biz.ai_messages.reference_card IS 'referenceCard JSON：{type, title, summary, data}';
|
||
```
|
||
|
||
### 变更后完整表结构
|
||
|
||
#### biz.ai_conversations（扩展后）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | bigint PK | 对话 ID（即 chatId） |
|
||
| `user_id` | varchar(50) | 用户 ID（助教） |
|
||
| `nickname` | varchar(100) | 用户昵称 |
|
||
| `app_id` | varchar(30) | AI 应用 ID（CHAT 模块固定为 `app1_chat`） |
|
||
| `site_id` | bigint | 门店 ID |
|
||
| `source_page` | varchar(100) | 来源页面 |
|
||
| `source_context` | jsonb | 来源上下文 |
|
||
| `created_at` | timestamptz | 创建时间 |
|
||
| `customer_id` | — | **已移除** — 改用 `context_type` + `context_id` 通用方案 |
|
||
| `context_type` | varchar(20) | **新增** — 对话关联上下文类型：task/customer/coach/general |
|
||
| `context_id` | varchar(50) | **新增** — 关联上下文 ID（taskId/customerId/coachId） |
|
||
| `title` | varchar(200) | **新增** — 对话标题 |
|
||
| `last_message` | text | **新增** — 最后消息摘要 |
|
||
| `last_message_at` | timestamptz | **新增** — 最后消息时间 |
|
||
|
||
#### biz.ai_messages（扩展后）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | bigint PK | 消息 ID |
|
||
| `conversation_id` | bigint FK | 对话 ID |
|
||
| `role` | varchar(10) | 角色：`user` / `assistant` |
|
||
| `content` | text | 消息内容 |
|
||
| `tokens_used` | integer | token 消耗量 |
|
||
| `created_at` | timestamptz | 创建时间 |
|
||
| `reference_card` | jsonb | **新增** — 引用卡片 |
|
||
|
||
### 字段映射：数据库 → API 响应
|
||
|
||
| 数据库字段 | API 响应字段（camelCase） | 说明 |
|
||
|-----------|------------------------|------|
|
||
| `ai_conversations.id` | `id` / `chatId` | 对话 ID |
|
||
| `ai_conversations.title` | `title` | 对话标题 |
|
||
| `ai_conversations.last_message` | `lastMessage` | 最后消息摘要 |
|
||
| `ai_conversations.last_message_at` | `timestamp` | CHAT-1 历史列表时间 |
|
||
| `ai_conversations.context_id` → 当 `context_type=customer` 时 JOIN `v_dim_member` | `customerName` | 客户姓名（仅 context_type=customer 时有值） |
|
||
| `ai_messages.id` | `id` | 消息 ID |
|
||
| `ai_messages.role` | `role` | 消息角色 |
|
||
| `ai_messages.content` | `content` | 消息内容 |
|
||
| `ai_messages.created_at` | `createdAt` | 统一时间字段名 |
|
||
| `ai_messages.reference_card` | `referenceCard` | 引用卡片 JSON |
|
||
|
||
### referenceCard JSON 结构
|
||
|
||
```json
|
||
{
|
||
"type": "customer",
|
||
"title": "张伟 — 消费概览",
|
||
"summary": "余额 ¥5,200，近30天消费 ¥2,380",
|
||
"data": {
|
||
"余额": "¥5,200",
|
||
"近30天消费": "¥2,380",
|
||
"到店次数": "8次",
|
||
"最近到店": "3天前"
|
||
}
|
||
}
|
||
```
|
||
|
||
### DWD-DOC 强制规则在数据模型中的体现
|
||
|
||
| 规则 | 影响范围 | 实施方式 |
|
||
|------|---------|---------|
|
||
| `items_sum` 口径 | referenceCard 中"近30天消费" | SQL 使用 `items_sum` 字段，禁用 `consume_money` |
|
||
| 助教费用拆分 | referenceCard 中如涉及助教费用 | 使用 `assistant_pd_money` + `assistant_cx_money` |
|
||
| 会员信息 JOIN | referenceCard 中客户姓名 | 通过 `member_id` JOIN `fdw_etl.v_dim_member`（`scd2_is_current=1`），禁用结算单冗余字段 |
|
||
|
||
|
||
## 正确性属性
|
||
|
||
*属性（Property）是一个在系统所有合法执行路径上都应成立的特征或行为——本质上是对"系统应该做什么"的形式化陈述。属性是人类可读规格与机器可验证正确性保证之间的桥梁。*
|
||
|
||
### Property 1: 路由迁移完整性
|
||
|
||
*For any* CHAT 端点路径（`/history`、`/{chatId}/messages`、`/messages`、`/{chatId}/messages` POST、`/stream`），以 `/api/xcx/chat` 为前缀的请求应返回非 404 响应（需认证），而以 `/api/ai` 为前缀的对应旧路径应返回 404。
|
||
|
||
**Validates: Requirements 1.1, 1.2**
|
||
|
||
### Property 2: CHAT API 响应结构完整性
|
||
|
||
*For any* CHAT-1 历史列表项，响应必须包含 `id`、`title`、`lastMessage`、`timestamp` 字段；*For any* CHAT-2 消息项，响应必须包含 `id`、`role`、`content`、`createdAt` 字段；*For any* CHAT-3 发送消息响应，必须包含 `userMessage` 和 `aiReply`，各含 `id`、`content`、`createdAt` 字段。
|
||
|
||
**Validates: Requirements 2.2, 3.3, 5.3**
|
||
|
||
### Property 3: 列表排序不变量
|
||
|
||
*For any* CHAT-1 返回的对话历史列表，相邻两项的 `timestamp` 应满足前项 ≥ 后项（按时间倒序）；*For any* CHAT-2 返回的消息列表，相邻两项的 `createdAt` 应满足前项 ≤ 后项（按时间正序）。
|
||
|
||
**Validates: Requirements 2.3, 3.5**
|
||
|
||
### Property 4: 对话标题生成优先级
|
||
|
||
*For any* 对话记录，标题生成应遵循优先级链：若 `title` 字段非空则使用 `title`；否则若 `customer_id` 关联的客户姓名非空则使用客户姓名；否则使用首条消息内容的前 20 个字符。生成结果应始终为非空字符串。
|
||
|
||
**Validates: Requirements 2.4**
|
||
|
||
### Property 5: 权限控制与数据隔离
|
||
|
||
*For any* CHAT 端点（CHAT-1/2/3/4），未通过审核的用户（status ≠ approved）应收到 HTTP 403 响应；*For any* 已认证用户请求的对话数据，返回的所有对话记录的 `user_id` 应等于当前用户 ID；*For any* 不属于当前用户的 `chatId`，CHAT-3 和 CHAT-4 应返回 HTTP 403。
|
||
|
||
**Validates: Requirements 2.6, 5.6, 11.1, 11.2, 11.3**
|
||
|
||
### Property 6: 对话复用规则正确性
|
||
|
||
*For any* `context_type='task'` 的入口，同一 `(user_id, site_id, context_id)` 多次调用 `get_or_create_session` 应始终返回同一个 `chatId`；*For any* `context_type='customer'` 或 `context_type='coach'` 的入口，若最后消息时间 ≤ 3 天则返回已有 `chatId`，若 > 3 天则返回新的 `chatId`；*For any* `context_type='general'` 的入口，每次调用应返回不同的 `chatId`。
|
||
|
||
**Validates: Requirements 3.8, 3.9, 3.10**
|
||
|
||
### Property 7: referenceCard 持久化 Round Trip
|
||
|
||
*For any* 合法的 referenceCard JSON 对象（包含 `type`、`title`、`summary`、`data` 字段），存入 `ai_messages.reference_card` 后再读取，应得到与原始对象结构等价的 JSON。
|
||
|
||
**Validates: Requirements 4.1, 4.3**
|
||
|
||
### Property 8: 消息持久化与会话元数据更新
|
||
|
||
*For any* 通过 CHAT-3 或 CHAT-4 发送的消息，用户消息和 AI 回复均应被持久化到 `ai_messages` 表；发送后对应 `ai_conversations` 记录的 `last_message` 应更新为最新消息内容，`last_message_at` 应更新为最新消息时间。
|
||
|
||
**Validates: Requirements 5.2, 5.4, 6.3, 6.4**
|
||
|
||
### Property 9: SSE 事件类型有效性
|
||
|
||
*For any* CHAT-4 SSE 流中的事件，其 `event` 字段应为 `message`、`done`、`error` 三者之一；`message` 事件的 `data` 应包含 `token` 字段；`done` 事件的 `data` 应包含 `messageId` 和 `createdAt` 字段；`error` 事件的 `data` 应包含 `message` 字段。
|
||
|
||
**Validates: Requirements 6.2**
|
||
|
||
|
||
## 错误处理
|
||
|
||
### 后端错误处理
|
||
|
||
所有 CHAT 端点的错误响应遵循 RNS1.0 全局异常处理器格式：`{ code: <HTTP状态码>, message: <错误详情> }`。
|
||
|
||
| 场景 | HTTP 状态码 | 响应 | 处理方式 |
|
||
|------|-----------|------|---------|
|
||
| 未认证（无 token / token 过期） | 401 | `{ code: 401, message: "无效的令牌" }` | `get_current_user` 依赖抛出 |
|
||
| 未通过审核（status ≠ approved） | 403 | `{ code: 403, message: "用户未通过审核，无法访问此资源" }` | `require_approved()` 依赖抛出 |
|
||
| chatId 不属于当前用户 | 403 | `{ code: 403, message: "无权访问此对话" }` | `chat_service` 验证后抛出 |
|
||
| chatId 不存在 | 404 | `{ code: 404, message: "对话不存在" }` | `chat_service` 查询后抛出 |
|
||
| 消息内容为空 | 422 | `{ code: 422, message: "消息内容不能为空" }` | 路由层 Pydantic 验证 |
|
||
| AI 服务调用失败（CHAT-3） | 200 | `aiReply.content = "抱歉，AI 助手暂时无法回复，请稍后重试"` | 用户消息仍保存，AI 回复为错误提示 |
|
||
| AI 服务调用失败（CHAT-4 SSE） | SSE error 事件 | `event: error\ndata: {"message": "AI 服务暂时不可用"}` | 流中发送 error 事件后关闭 |
|
||
| 数据库连接失败 | 500 | `{ code: 500, message: "Internal Server Error" }` | 全局 `unhandled_exception_handler` |
|
||
| FDW 查询失败（referenceCard） | 静默降级 | referenceCard 返回 `null` | 不影响消息本身，仅 referenceCard 缺失 |
|
||
|
||
### CHAT-3 AI 失败降级策略
|
||
|
||
```python
|
||
async def send_message_sync(self, chat_id, content, user_id, site_id):
|
||
# 1. 存入用户消息（无论 AI 是否成功）
|
||
user_msg_id = self._save_message(chat_id, "user", content)
|
||
|
||
# 2. 调用 AI
|
||
try:
|
||
ai_reply = await self._call_ai(content, chat_id)
|
||
except Exception as e:
|
||
logger.error("AI 服务调用失败: %s", e)
|
||
ai_reply = "抱歉，AI 助手暂时无法回复，请稍后重试"
|
||
|
||
# 3. 存入 AI 回复（包括错误提示）
|
||
ai_msg_id = self._save_message(chat_id, "assistant", ai_reply)
|
||
|
||
# 4. 更新 session 元数据
|
||
self._update_session_metadata(chat_id, ai_reply)
|
||
|
||
# 5. HTTP 200 返回（不抛异常）
|
||
return { "userMessage": {...}, "aiReply": {...} }
|
||
```
|
||
|
||
### 前端错误处理
|
||
|
||
| 场景 | 处理方式 |
|
||
|------|---------|
|
||
| CHAT API 返回 401 | 跳转登录页（`request()` 全局拦截） |
|
||
| CHAT API 返回 403 | Toast 提示"权限不足" |
|
||
| CHAT API 返回 404 | Toast 提示"对话不存在" |
|
||
| CHAT API 返回 500 | Toast 提示"服务暂时不可用" |
|
||
| SSE 连接中断 | 停止流式显示，显示"连接中断"提示，允许重试 |
|
||
| 网络超时 | `wx.request` fail 回调，显示网络错误提示 |
|
||
|
||
## 测试策略
|
||
|
||
### 双轨测试方法
|
||
|
||
RNS1.4 采用属性测试（Property-Based Testing）+ 单元测试（Unit Testing）双轨并行：
|
||
|
||
- **属性测试**：验证对话管理、消息持久化、权限控制、referenceCard round trip 等通用规则
|
||
- **单元测试**：验证具体端点行为、边界条件、AI 失败降级等
|
||
|
||
### 属性测试配置
|
||
|
||
- **测试库**：[Hypothesis](https://hypothesis.readthedocs.io/)（Python，项目已使用）
|
||
- **测试位置**：`tests/` 目录（Monorepo 级属性测试）
|
||
- **最小迭代次数**：每个属性测试 100 次（`@settings(max_examples=100)`）
|
||
- **标签格式**：每个测试函数的 docstring 中标注 `Feature: rns1-chat-integration, Property {N}: {property_text}`
|
||
|
||
### 属性测试清单
|
||
|
||
| Property | 测试函数 | 生成器 | 验证逻辑 |
|
||
|----------|---------|--------|---------|
|
||
| P3: 列表排序不变量 | `test_chat_list_ordering` | `st.lists(st.datetimes())` 生成随机时间戳列表 | 对话列表按时间倒序，消息列表按时间正序 |
|
||
| P4: 标题生成优先级 | `test_title_generation_priority` | `st.fixed_dictionaries({"title": st.one_of(st.none(), st.text(min_size=1)), "customer_name": st.one_of(st.none(), st.text(min_size=1)), "first_message": st.text(min_size=1)})` | 标题遵循优先级链，结果非空 |
|
||
| P6: customerId 幂等性 | `test_customer_id_get_or_create_idempotent` | `st.integers(min_value=1)` 生成随机 user_id 和 customer_id | 多次调用返回同一 chatId |
|
||
| P7: referenceCard Round Trip | `test_reference_card_roundtrip` | `st.fixed_dictionaries({"type": st.sampled_from(["customer", "record"]), "title": st.text(min_size=1), "summary": st.text(), "data": st.dictionaries(st.text(min_size=1), st.text())})` | JSON 序列化→存储→读取→反序列化等于原始对象 |
|
||
| P8: 消息持久化 | `test_message_persistence_after_send` | `st.text(min_size=1, max_size=500)` 生成随机消息内容 | 发送后 ai_messages 包含用户消息和 AI 回复，session 元数据已更新 |
|
||
| P9: SSE 事件类型 | `test_sse_event_type_validity` | `st.sampled_from(["message", "done", "error"])` + 对应 data 结构 | 事件类型为三者之一，data 结构符合定义 |
|
||
|
||
### 单元测试清单
|
||
|
||
| 测试目标 | 测试文件 | 关键用例 |
|
||
|---------|---------|---------|
|
||
| 路由迁移（P1） | `apps/backend/tests/unit/test_xcx_chat_routes.py` | `/api/xcx/chat/history` 返回 200；`/api/ai/conversations` 返回 404 |
|
||
| 响应结构（P2） | `apps/backend/tests/unit/test_xcx_chat_schema.py` | ChatHistoryItem / ChatMessageItem / SendMessageResponse 序列化验证 |
|
||
| 权限控制（P5） | `apps/backend/tests/unit/test_xcx_chat_auth.py` | 未审核用户 403；chatId 不属于当前用户 403 |
|
||
| AI 失败降级（edge case） | `apps/backend/tests/unit/test_xcx_chat_ai_fallback.py` | AI 超时时返回错误提示消息，HTTP 200 |
|
||
| SSE 跳过包装 | 已由 RNS1.0 测试覆盖 | `text/event-stream` 不经过 ResponseWrapper |
|
||
| FDW 验证 | `scripts/ops/verify_fdw_e2e.py` | 一次性运行，输出验证报告 |
|
||
| 联调验证 | 手动测试 | 13 页面逐一验证真实数据渲染 |
|
||
|
||
### 测试执行命令
|
||
|
||
```bash
|
||
# 属性测试（Hypothesis）
|
||
cd C:\NeoZQYY && pytest tests/ -v -k "rns1_chat"
|
||
|
||
# 单元测试
|
||
cd apps/backend && pytest tests/unit/ -v -k "xcx_chat"
|
||
|
||
# FDW 验证脚本
|
||
cd C:\NeoZQYY && uv run python scripts/ops/verify_fdw_e2e.py
|
||
```
|
||
|