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

- 添加 `last_message_id` 字段至 `chat_sessions` 表，更新其关联索引
- 实现会话更新接口，支持修改名称与状态并添加验证逻辑
- 增加会话列表接口，支持状态过滤与关键字查询
- 提供会话和消息相关的资源类和请求验证类
- 扩展 `ChatService` 服务层逻辑以处理会话更新和消息附加
- 编写测试用例以验证新功能的正确性
- 增加接口文档及 OpenAPI 规范文件，覆盖新增功能
- 更新数据库播种器，添加默认用户

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"
+```