roog/ars-backend
1
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6356baacc0cec756b8ae0f02c86a9e65ff2f3d1c
ars-backend/docs/ChatSession/chat-session-api.md
ROOG 6356baacc0 main: 增强会话功能，支持消息管理和接口文档 
- 添加 `last_message_id` 字段至 `chat_sessions` 表，更新其关联索引
- 实现会话更新接口，支持修改名称与状态并添加验证逻辑
- 增加会话列表接口，支持状态过滤与关键字查询
- 提供会话和消息相关的资源类和请求验证类
- 扩展 `ChatService` 服务层逻辑以处理会话更新和消息附加
- 编写测试用例以验证新功能的正确性
- 增加接口文档及 OpenAPI 规范文件，覆盖新增功能
- 更新数据库播种器，添加默认用户
2025-12-14 20:20:27 +08:00

4.1 KiB
Raw Blame History

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 示例

# 创建会话
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"