feat(client): 新增会话管理与消息落库能力

补齐客户端会话生命周期接口(创建、列表、消息分页、改名、删除),并在流式 chat 中强制绑定 sessionId 与落库消息,确保会话标题和历史可追踪,同时统一 Swagger 文档为 DTO 驱动以减少重复维护。

Made-with: Cursor
This commit is contained in:
2026-04-22 23:32:10 +08:00
parent bc13417efd
commit 32303d099a
16 changed files with 833 additions and 146 deletions

View File

@@ -197,33 +197,57 @@ chat-one-service/
### 4.2 客户端 AI Chat 接口(流式)
- `POST /api/client/v1/chat/completions/stream`
- 说明:统一接口,后台自动路由平台
- 说明:统一接口,后台自动路由平台;支持会话续聊
- 入参示例:
```json
{
"model": "gpt-4o-mini-like",
"model": "qwen-plus",
"messages": [
{ "role": "system", "content": "你是助手" },
{ "role": "user", "content": "介绍一下NestJS" }
],
"temperature": 0.7,
"platform": "auto"
"platform": "auto",
"sessionId": "1"
}
```
- 备注:
- `sessionId` 必填,需先调用创建会话接口;
- `meta` 会返回 `sessionId`(字符串),前端可缓存用于后续续聊。
- `done` 前会先落库用户消息与会话标题,便于列表即时刷新。
- 返回:`text/event-stream`SSE
- `POST /api/client/v1/chat/completions/stream/:platform`
- 说明:指定平台(`qwen | volc | deepseek`
- 其余参数同上
### 4.3 客户端会话接口
### 4.3 建议统一 SSE 事件格式
- `POST /api/client/v1/chat/sessions`
- 说明:创建空会话(推荐在首次发送前调用)
- 入参:`{ title? }`
- 出参:`{ id, userId, title, createdAt, updatedAt }`
- `GET /api/client/v1/chat/sessions?limit=&offset=`
- 说明:会话列表(按 `updatedAt desc`
- 出参:`{ items, total, limit, offset }`
- `GET /api/client/v1/chat/sessions/:sessionId/messages?limit=&offset=`
- 说明:分页查询会话消息
- 出参:`{ sessionId, items, total, limit, offset }`
- `DELETE /api/client/v1/chat/sessions/:sessionId`
- 说明:删除会话并级联删除该会话下全部消息
- 出参:删除成功后返回被删除会话信息
- `PATCH /api/client/v1/chat/sessions/:sessionId/title`
- 说明:修改会话标题(可传空字符串清空)
- 入参:`{ title }`
- 出参:更新后的会话信息
### 4.4 建议统一 SSE 事件格式
```text
event: meta
data: {"requestId":"xxx","platform":"qwen","model":"qwen-turbo"}
data: {"requestId":"xxx","platform":"qwen","model":"qwen-plus","sessionId":"1"}
event: delta
data: {"content":"你好"}
data: {"delta":"你好"}
event: usage
data: {"promptTokens":120,"completionTokens":80,"totalTokens":200}
@@ -235,7 +259,7 @@ event: error
data: {"code":"PLATFORM_TIMEOUT","message":"upstream timeout"}
```
### 4.4 管理端认证接口(邮箱)
### 4.5 管理端认证接口(邮箱)
- `POST /api/admin/v1/auth/login`
- 入参:`{ email, password }`
@@ -244,21 +268,21 @@ data: {"code":"PLATFORM_TIMEOUT","message":"upstream timeout"}
- `POST /api/admin/v1/auth/refresh`
- `POST /api/admin/v1/auth/logout`
### 4.5 管理端用户管理
### 4.6 管理端用户管理
- `GET /api/admin/v1/users`
- `GET /api/admin/v1/users/:id`
- `PATCH /api/admin/v1/users/:id/status`(启用/禁用)
- `PATCH /api/admin/v1/users/:id/role`
### 4.6 管理端平台管理
### 4.7 管理端平台管理
- `GET /api/admin/v1/platforms`
- `POST /api/admin/v1/platforms`
- `PATCH /api/admin/v1/platforms/:id`
- `PATCH /api/admin/v1/platforms/:id/health-check`
### 4.7 管理端统计
### 4.8 管理端统计
- `GET /api/admin/v1/stats/overview?startDate=&endDate=`
- `GET /api/admin/v1/stats/platforms`
@@ -434,13 +458,14 @@ REDIS_KEY_PREFIX_ADMIN=chatone:admin
- `enabled` (bool)
- unique(platform_id, biz_model)
### 8.3 会话与消息(可选落库)
### 8.3 会话与消息(落库)
- `chat_sessions`
- `id`
- `user_id` (fk)
- `title`
- `created_at`, `updated_at`
- index: `user_id`
- `chat_messages`
- `id`
@@ -450,6 +475,8 @@ REDIS_KEY_PREFIX_ADMIN=chatone:admin
- `token_count` (int)
- `provider` (varchar)
- `created_at`
- index: `session_id`
- `session_id` 外键 `onDelete: Cascade`
### 8.4 请求审计与统计