main: 增强会话功能，支持消息管理和接口文档

- 添加 `last_message_id` 字段至 `chat_sessions` 表，更新其关联索引 - 实现会话更新接口，支持修改名称与状态并添加验证逻辑 - 增加会话列表接口，支持状态过滤与关键字查询 - 提供会话和消息相关的资源类和请求验证类 - 扩展 `ChatService` 服务层逻辑以处理会话更新和消息附加 - 编写测试用例以验证新功能的正确性 - 增加接口文档及 OpenAPI 规范文件，覆盖新增功能 - 更新数据库播种器，添加默认用户
2025-12-14 20:20:27 +08:00
parent c6d6534b63
commit 6356baacc0
14 changed files with 852 additions and 4 deletions
--- a/docs/ChatSession/chat-session-api.md
+++ b/docs/ChatSession/chat-session-api.md
@@ -0,0 +1,96 @@
+# 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"
+```
--- a/docs/ChatSession/chat-session-openapi.yaml
+++ b/docs/ChatSession/chat-session-openapi.yaml
@@ -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