ROOG
6356baacc0
- 添加 `last_message_id` 字段至 `chat_sessions` 表，更新其关联索引 - 实现会话更新接口，支持修改名称与状态并添加验证逻辑 - 增加会话列表接口，支持状态过滤与关键字查询 - 提供会话和消息相关的资源类和请求验证类 - 扩展 `ChatService` 服务层逻辑以处理会话更新和消息附加 - 编写测试用例以验证新功能的正确性 - 增加接口文档及 OpenAPI 规范文件，覆盖新增功能 - 更新数据库播种器，添加默认用户
97 lines
4.1 KiB
Markdown
97 lines
4.1 KiB
Markdown
# ChatSession & Message API（MVP-1）
|
||
|
||
基地址：`http://localhost:8000/api`（FrankenPHP 容器 8000 端口）
|
||
认证方式：JWT，`Authorization: Bearer {token}`
|
||
自然语言：中文
|
||
|
||
## 变更记录
|
||
- 2025-02-14：新增 ChatSession 创建、消息追加、增量查询接口；支持状态门禁与 dedupe 幂等。
|
||
- 2025-02-14：MVP-1.1 增加会话列表、会话更新（重命名/状态变更），列表附带最后一条消息摘要。
|
||
|
||
## 领域模型
|
||
- `ChatSession`：`session_id`(UUID)、`session_name`、`status`(`OPEN`/`LOCKED`/`CLOSED`)、`last_seq`
|
||
- `Message`：`message_id`(UUID)、`session_id`、`role`(`USER`/`AGENT`/`TOOL`/`SYSTEM`)、`type`(字符串)、`content`、`payload`(json)、`seq`(会话内递增)、`reply_to`(UUID)、`dedupe_key`
|
||
- 幂等：`UNIQUE (session_id, dedupe_key)`；同一 dedupe_key 返回已有消息。
|
||
- 状态门禁：`CLOSED` 禁止追加，例外 `role=SYSTEM && type in [run.status, error]`；`LOCKED` 禁止 `role=USER && type=user.prompt`。
|
||
- 会话缓存：`chat_sessions.last_message_id` 记录最后一条消息；`appendMessage` 事务内同步更新 `last_seq`、`last_message_id`、`updated_at`。
|
||
|
||
## 接口
|
||
### 创建会话
|
||
- `POST /sessions`
|
||
- 请求体字段：
|
||
- `session_name` (string, 可选，<=255)：会话名称。
|
||
- 响应 201 字段：
|
||
- `session_id` (uuid)
|
||
- `session_name` (string|null)
|
||
- `status` (`OPEN|LOCKED|CLOSED`)
|
||
- `last_seq` (int)
|
||
- `last_message_id` (uuid|null)
|
||
- `created_at` / `updated_at`
|
||
|
||
### 追加消息
|
||
- `POST /sessions/{session_id}/messages`
|
||
- 请求体字段：
|
||
- `role` (required, `USER|AGENT|TOOL|SYSTEM`)
|
||
- `type` (required, string, <=64)，如 `user.prompt`/`agent.message` 等。
|
||
- `content` (string|null)
|
||
- `payload` (object|null) 作为 jsonb 存储。
|
||
- `reply_to` (uuid|null)
|
||
- `dedupe_key` (string|null, <=128) 幂等键。
|
||
- 响应 201 字段：
|
||
- `message_id` (uuid)
|
||
- `session_id` (uuid)
|
||
- `seq` (int，会话内递增)
|
||
- `role` / `type` / `content` / `payload` / `reply_to` / `dedupe_key`
|
||
- `created_at`
|
||
- 403：违反状态门禁（CLOSED 禁止，LOCKED 禁止 user.prompt）。
|
||
- 幂等：同 session + dedupe_key 返回已有消息（同 `message_id/seq`）。
|
||
|
||
### 按序增量查询
|
||
- `GET /sessions/{session_id}/messages?after_seq=0&limit=50`
|
||
- 查询参数：
|
||
- `after_seq` (int, 默认 0)：仅返回大于该 seq 的消息。
|
||
- `limit` (int, 默认 50，<=200)。
|
||
- 响应 200：`data` 数组，元素字段同“追加消息”响应。
|
||
|
||
### 会话列表
|
||
- `GET /sessions?page=1&per_page=15&status=OPEN&q=keyword`
|
||
- 查询参数：
|
||
- `page` (int, 默认 1)
|
||
- `per_page` (int, 默认 15，<=100)
|
||
- `status` (`OPEN|LOCKED|CLOSED`，可选)
|
||
- `q` (string，可选，对 `session_name` ILIKE 模糊匹配)
|
||
- 响应 200：分页结构（`data/links/meta`），`data` 每项字段：
|
||
- `session_id, session_name, status, last_seq, created_at, updated_at`
|
||
- `last_message_id`
|
||
- `last_message_at`
|
||
- `last_message_preview`（content 截断 120，content 为空则空字符串）
|
||
- `last_message_role, last_message_type`
|
||
- 排序：`updated_at` DESC
|
||
|
||
### 会话更新
|
||
- `PATCH /sessions/{session_id}`
|
||
- 请求体（至少提供一项，否则 422）：
|
||
- `session_name` (string, 1..255，可选，自动 trim)
|
||
- `status` (`OPEN|LOCKED|CLOSED`，可选)
|
||
- 规则：
|
||
- `CLOSED` 不可改回 `OPEN`（返回 403）。
|
||
- 任意更新都会刷新 `updated_at`。
|
||
- 响应 200 字段：同会话列表项字段。
|
||
|
||
## cURL 示例
|
||
```bash
|
||
# 创建会话
|
||
SESSION_ID=$(curl -s -X POST http://localhost:8000/api/sessions \
|
||
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
|
||
-d '{"session_name":"Demo"}' | jq -r '.data.session_id')
|
||
|
||
# 追加消息（支持 dedupe_key 幂等）
|
||
curl -s -X POST http://localhost:8000/api/sessions/$SESSION_ID/messages \
|
||
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
|
||
-d '{"role":"USER","type":"user.prompt","content":"hello","dedupe_key":"k1"}'
|
||
|
||
# 增量查询
|
||
curl -s "http://localhost:8000/api/sessions/$SESSION_ID/messages?after_seq=0&limit=50" \
|
||
-H "Authorization: Bearer $TOKEN"
|
||
```
|