main: 增强会话功能，支持消息管理和接口文档
- 添加 `last_message_id` 字段至 `chat_sessions` 表，更新其关联索引 - 实现会话更新接口，支持修改名称与状态并添加验证逻辑 - 增加会话列表接口，支持状态过滤与关键字查询 - 提供会话和消息相关的资源类和请求验证类 - 扩展 `ChatService` 服务层逻辑以处理会话更新和消息附加 - 编写测试用例以验证新功能的正确性 - 增加接口文档及 OpenAPI 规范文件，覆盖新增功能 - 更新数据库播种器，添加默认用户
This commit is contained in:
344
docs/ChatSession/chat-session-openapi.yaml
Normal file
344
docs/ChatSession/chat-session-openapi.yaml
Normal file
@@ -0,0 +1,344 @@
|
||||
openapi: 3.0.3
|
||||
info:
|
||||
title: ChatSession & Message API
|
||||
version: 1.0.0
|
||||
description: |
|
||||
ChatSession & Message MVP-1，支持会话创建、消息追加、增量查询。自然语言：中文。
|
||||
servers:
|
||||
- url: http://localhost:8000/api
|
||||
description: 本地开发（FrankenPHP / Docker）
|
||||
tags:
|
||||
- name: ChatSession
|
||||
description: 会话管理与消息
|
||||
paths:
|
||||
/sessions:
|
||||
post:
|
||||
tags: [ChatSession]
|
||||
summary: 创建会话
|
||||
security:
|
||||
- bearerAuth: []
|
||||
requestBody:
|
||||
required: false
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/CreateSessionRequest'
|
||||
responses:
|
||||
"201":
|
||||
description: 创建成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ChatSession'
|
||||
"401":
|
||||
description: 未授权
|
||||
get:
|
||||
tags: [ChatSession]
|
||||
summary: 会话列表
|
||||
security:
|
||||
- bearerAuth: []
|
||||
parameters:
|
||||
- in: query
|
||||
name: page
|
||||
schema:
|
||||
type: integer
|
||||
default: 1
|
||||
- in: query
|
||||
name: per_page
|
||||
schema:
|
||||
type: integer
|
||||
default: 15
|
||||
maximum: 100
|
||||
- in: query
|
||||
name: status
|
||||
schema:
|
||||
type: string
|
||||
enum: [OPEN, LOCKED, CLOSED]
|
||||
- in: query
|
||||
name: q
|
||||
schema:
|
||||
type: string
|
||||
description: 模糊匹配 session_name
|
||||
responses:
|
||||
"200":
|
||||
description: 分页会话列表
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
data:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/ChatSession'
|
||||
links:
|
||||
$ref: '#/components/schemas/PaginationLinks'
|
||||
meta:
|
||||
$ref: '#/components/schemas/PaginationMeta'
|
||||
"401":
|
||||
description: 未授权
|
||||
/sessions/{session_id}/messages:
|
||||
post:
|
||||
tags: [ChatSession]
|
||||
summary: 追加消息（含幂等与状态门禁）
|
||||
security:
|
||||
- bearerAuth: []
|
||||
parameters:
|
||||
- in: path
|
||||
name: session_id
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
format: uuid
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/AppendMessageRequest'
|
||||
responses:
|
||||
"201":
|
||||
description: 追加成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/MessageResource'
|
||||
"403":
|
||||
description: 状态门禁禁止
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
"401":
|
||||
description: 未授权
|
||||
get:
|
||||
tags: [ChatSession]
|
||||
summary: 按 seq 增量查询消息
|
||||
security:
|
||||
- bearerAuth: []
|
||||
parameters:
|
||||
- in: path
|
||||
name: session_id
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
format: uuid
|
||||
- in: query
|
||||
name: after_seq
|
||||
schema:
|
||||
type: integer
|
||||
default: 0
|
||||
description: 仅返回 seq 大于该值的消息
|
||||
- in: query
|
||||
name: limit
|
||||
schema:
|
||||
type: integer
|
||||
default: 50
|
||||
maximum: 200
|
||||
description: 返回数量上限
|
||||
responses:
|
||||
"200":
|
||||
description: 按 seq 升序的消息列表
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
data:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/MessageResource'
|
||||
"401":
|
||||
description: 未授权
|
||||
/sessions/{session_id}:
|
||||
patch:
|
||||
tags: [ChatSession]
|
||||
summary: 更新会话（重命名/状态）
|
||||
security:
|
||||
- bearerAuth: []
|
||||
parameters:
|
||||
- in: path
|
||||
name: session_id
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
format: uuid
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/UpdateSessionRequest'
|
||||
responses:
|
||||
"200":
|
||||
description: 更新成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ChatSession'
|
||||
"403":
|
||||
description: 状态门禁禁止
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
"422":
|
||||
description: 校验失败
|
||||
"401":
|
||||
description: 未授权
|
||||
components:
|
||||
securitySchemes:
|
||||
bearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: JWT
|
||||
schemas:
|
||||
ChatSession:
|
||||
type: object
|
||||
properties:
|
||||
session_id:
|
||||
type: string
|
||||
format: uuid
|
||||
session_name:
|
||||
type: string
|
||||
nullable: true
|
||||
status:
|
||||
type: string
|
||||
enum: [OPEN, LOCKED, CLOSED]
|
||||
last_seq:
|
||||
type: integer
|
||||
last_message_id:
|
||||
type: string
|
||||
format: uuid
|
||||
nullable: true
|
||||
last_message_at:
|
||||
type: string
|
||||
format: date-time
|
||||
nullable: true
|
||||
last_message_preview:
|
||||
type: string
|
||||
last_message_role:
|
||||
type: string
|
||||
nullable: true
|
||||
last_message_type:
|
||||
type: string
|
||||
nullable: true
|
||||
created_at:
|
||||
type: string
|
||||
format: date-time
|
||||
updated_at:
|
||||
type: string
|
||||
format: date-time
|
||||
CreateSessionRequest:
|
||||
type: object
|
||||
properties:
|
||||
session_name:
|
||||
type: string
|
||||
maxLength: 255
|
||||
UpdateSessionRequest:
|
||||
type: object
|
||||
properties:
|
||||
session_name:
|
||||
type: string
|
||||
minLength: 1
|
||||
maxLength: 255
|
||||
status:
|
||||
type: string
|
||||
enum: [OPEN, LOCKED, CLOSED]
|
||||
AppendMessageRequest:
|
||||
type: object
|
||||
required: [role, type]
|
||||
properties:
|
||||
role:
|
||||
type: string
|
||||
enum: [USER, AGENT, TOOL, SYSTEM]
|
||||
type:
|
||||
type: string
|
||||
maxLength: 64
|
||||
example: user.prompt
|
||||
content:
|
||||
type: string
|
||||
nullable: true
|
||||
payload:
|
||||
type: object
|
||||
nullable: true
|
||||
reply_to:
|
||||
type: string
|
||||
format: uuid
|
||||
nullable: true
|
||||
dedupe_key:
|
||||
type: string
|
||||
maxLength: 128
|
||||
nullable: true
|
||||
MessageResource:
|
||||
type: object
|
||||
properties:
|
||||
message_id:
|
||||
type: string
|
||||
format: uuid
|
||||
session_id:
|
||||
type: string
|
||||
format: uuid
|
||||
seq:
|
||||
type: integer
|
||||
role:
|
||||
type: string
|
||||
enum: [USER, AGENT, TOOL, SYSTEM]
|
||||
type:
|
||||
type: string
|
||||
content:
|
||||
type: string
|
||||
nullable: true
|
||||
payload:
|
||||
type: object
|
||||
nullable: true
|
||||
reply_to:
|
||||
type: string
|
||||
format: uuid
|
||||
nullable: true
|
||||
dedupe_key:
|
||||
type: string
|
||||
nullable: true
|
||||
created_at:
|
||||
type: string
|
||||
format: date-time
|
||||
Error:
|
||||
type: object
|
||||
properties:
|
||||
message:
|
||||
type: string
|
||||
example: Session is closed
|
||||
PaginationLinks:
|
||||
type: object
|
||||
properties:
|
||||
first:
|
||||
type: string
|
||||
example: http://localhost:8000/api/sessions?page=1
|
||||
last:
|
||||
type: string
|
||||
example: http://localhost:8000/api/sessions?page=1
|
||||
prev:
|
||||
type: string
|
||||
nullable: true
|
||||
next:
|
||||
type: string
|
||||
nullable: true
|
||||
PaginationMeta:
|
||||
type: object
|
||||
properties:
|
||||
current_page:
|
||||
type: integer
|
||||
from:
|
||||
type: integer
|
||||
nullable: true
|
||||
last_page:
|
||||
type: integer
|
||||
path:
|
||||
type: string
|
||||
per_page:
|
||||
type: integer
|
||||
to:
|
||||
type: integer
|
||||
nullable: true
|
||||
total:
|
||||
type: integer
|
||||
Reference in New Issue
Block a user