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

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

app/Http/Controllers/ChatSessionController.php

@@ -5,8 +5,9 @@ namespace App\Http\Controllers;
 use App\Exceptions\ChatSessionStatusException;
 use App\Http\Requests\AppendMessageRequest;
 use App\Http\Requests\CreateSessionRequest;
+use App\Http\Requests\UpdateSessionRequest;
+use App\Http\Resources\ChatSessionResource;
 use App\Http\Resources\MessageResource;
-use App\Models\Message;
 use App\Services\ChatService;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
@@ -17,13 +18,26 @@ class ChatSessionController extends Controller
     {
     }
 
+    /**
+     * 存储新的会话。
+     *
+     * @param CreateSessionRequest $request 包含会话信息的请求实例。
+     * @return JsonResponse 返回包含新创建会话信息的 JSON 响应，状态码为 201。
+     */
     public function store(CreateSessionRequest $request): JsonResponse
     {
         $session = $this->service->createSession($request->input('session_name'));
 
-        return response()->json($session, 201);
+        return (new ChatSessionResource($session))->response()->setStatusCode(201);
     }
 
+    /**
+     * 追加一条消息。
+     *
+     * @param string $sessionId 会话 ID。
+     * @param AppendMessageRequest $request 追加消息的请求实例。
+     * @return JsonResponse 添加消息的响应，包含添加的消息信息。
+     */
     public function append(string $sessionId, AppendMessageRequest $request): JsonResponse
     {
         try {
@@ -38,6 +52,13 @@ class ChatSessionController extends Controller
         return (new MessageResource($message))->response()->setStatusCode(201);
     }
 
+    /**
+     * 获取指定会话的消息列表。
+     *
+     * @param Request $request 包含查询参数的请求实例，其中包括 after_seq 和 limit。
+     * @param string $sessionId 会话的唯一标识符。
+     * @return JsonResponse 返回包含消息列表的 JSON 响应。
+     */
     public function listMessages(Request $request, string $sessionId): JsonResponse
     {
         $afterSeq = (int) $request->query('after_seq', 0);
@@ -48,4 +69,44 @@ class ChatSessionController extends Controller
 
         return MessageResource::collection($messages)->response();
     }
+
+    /**
+     * 获取会话列表。
+     *
+     * @param Request $request 获取会话列表的请求实例。
+     * @return JsonResponse 获取的会话列表的 JSON 响应。
+     */
+    public function index(Request $request): JsonResponse
+    {
+        $page = (int) $request->query('page', 1);
+        $perPage = (int) $request->query('per_page', 15);
+        $perPage = $perPage > 0 && $perPage <= 100 ? $perPage : 15;
+
+        $filter = [
+            'status' => $request->query('status'),
+            'q' => $request->query('q'),
+        ];
+
+        $paginator = $this->service->listSessions($filter, $page, $perPage);
+
+        return ChatSessionResource::collection($paginator)->response();
+    }
+
+    /**
+     * 更新会话。
+     *
+     * @param string $sessionId 会话的唯一标识符。
+     * @param UpdateSessionRequest $request 更新会话的请求实例。
+     * @return JsonResponse 更新后的会话的 JSON 响应。
+     */
+    public function update(string $sessionId, UpdateSessionRequest $request): JsonResponse
+    {
+        try {
+            $session = $this->service->updateSession($sessionId, $request->validated());
+        } catch (ChatSessionStatusException $e) {
+            return response()->json(['message' => $e->getMessage()], 403);
+        }
+
+        return (new ChatSessionResource($session))->response();
+    }
 }

app/Http/Requests/UpdateSessionRequest.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace App\Http\Requests;
+
+use App\Enums\ChatSessionStatus;
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+class UpdateSessionRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function rules(): array
+    {
+        return [
+            'session_name' => ['sometimes', 'string', 'min:1', 'max:255'],
+            'status' => ['sometimes', 'string', Rule::in(ChatSessionStatus::all())],
+        ];
+    }
+
+    protected function prepareForValidation(): void
+    {
+        if ($this->has('session_name') && is_string($this->input('session_name'))) {
+            $this->merge(['session_name' => trim($this->input('session_name'))]);
+        }
+    }
+
+    public function withValidator($validator)
+    {
+        $validator->after(function ($v) {
+            if (! $this->has('session_name') && ! $this->has('status')) {
+                $v->errors()->add('payload', '至少提供一个可更新字段');
+            }
+        });
+    }
+}

app/Http/Resources/ChatSessionResource.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace App\Http\Resources;
+
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+use Illuminate\Support\Str;
+
+/** @mixin \App\Models\ChatSession */
+class ChatSessionResource extends JsonResource
+{
+    /**
+     * @return array<string, mixed>
+     */
+    public function toArray(Request $request): array
+    {
+        $preview = $this->last_message_content ?? '';
+
+        return [
+            'session_id' => $this->session_id,
+            'session_name' => $this->session_name,
+            'status' => $this->status,
+            'last_seq' => $this->last_seq,
+            'created_at' => $this->created_at,
+            'updated_at' => $this->updated_at,
+            'last_message_at' => $this->last_message_at,
+            'last_message_preview' => $preview ? Str::limit($preview, 120) : '',
+            'last_message_role' => $this->last_message_role,
+            'last_message_type' => $this->last_message_type,
+        ];
+    }
+}

app/Models/ChatSession.php

@@ -22,6 +22,7 @@ class ChatSession extends Model
         'session_name',
         'status',
         'last_seq',
+        'last_message_id',
     ];
 
     protected function casts(): array

app/Services/ChatService.php

@@ -6,6 +6,8 @@ use App\Enums\ChatSessionStatus;
 use App\Exceptions\ChatSessionStatusException;
 use App\Models\ChatSession;
 use App\Models\Message;
+use Illuminate\Contracts\Pagination\LengthAwarePaginator;
+use Illuminate\Database\Eloquent\ModelNotFoundException;
 use Illuminate\Database\QueryException;
 use Illuminate\Support\Collection;
 use Illuminate\Support\Facades\DB;
@@ -13,6 +15,12 @@ use Illuminate\Support\Str;
 
 class ChatService
 {
+
+    /**
+     * 创建一个新聊天会话。
+     * @param string|null $name
+     * @return ChatSession
+     */
     public function createSession(string $name = null): ChatSession
     {
         return ChatSession::create([
@@ -23,13 +31,31 @@ class ChatService
         ]);
     }
 
+   /**
+     * 根据会话ID获取聊天会话对象
+     *
+     * @param string $sessionId 会话唯一标识符
+     * @return ChatSession 返回对应的聊天会话对象
+     * @throws ModelNotFoundException 当找不到指定会话时抛出异常
+     */
     public function getSession(string $sessionId): ChatSession
     {
         return ChatSession::query()->whereKey($sessionId)->firstOrFail();
     }
 
+
     /**
-     * @param array<string, mixed> $dto
+     * 将消息追加到指定的聊天会话中。
+     *
+     * @param array<string, mixed> $dto 包含消息详细信息的数据传输对象，包括以下键：
+     *                                  - session_id: 聊天会话的唯一标识符
+     *                                  - role: 消息角色（如发件人或收件人）
+     *                                  - type: 消息类型
+     *                                  - content: 消息内容（可选）
+     *                                  - payload: 附加信息（可选）
+     *                                  - reply_to: 被回复的消息 ID（可选）
+     *                                  - dedupe_key: 消息去重键（可选）
+     * @return Message 返回成功追加的消息实例。如果存在去重键并已存在重复消息，则返回现有的消息。
      */
     public function appendMessage(array $dto): Message
     {
@@ -88,6 +114,7 @@ class ChatService
 
             $session->update([
                 'last_seq' => $newSeq,
+                'last_message_id' => $message->message_id,
                 'updated_at' => now(),
             ]);
 
@@ -95,6 +122,14 @@ class ChatService
         });
     }
 
+    /**
+     * 列出指定会话中指定序号之后的消息。
+     *
+     * @param string $sessionId 会话唯一标识符
+     * @param int $afterSeq 指定序号之后的消息将被列出
+     * @param int $limit 最多返回的消息数量，默认为 50
+     * @return Collection 返回指定序号之后的消息列表
+     */
     public function listMessagesBySeq(string $sessionId, int $afterSeq, int $limit = 50): Collection
     {
         $this->getSession($sessionId); // ensure exists
@@ -107,6 +142,89 @@ class ChatService
             ->get();
     }
 
+    /**
+     * 获取会话列表
+     *
+     * @param array $filter 过滤条件数组，支持status状态过滤和q关键字搜索
+     * @param int $page 页码
+     * @param int $perPage 每页数量
+     * @return LengthAwarePaginator 分页结果
+     */
+    public function listSessions(array $filter, int $page, int $perPage): LengthAwarePaginator
+    {
+        // 构建基础查询
+        $query = $this->baseSessionQuery();
+
+        // 根据状态过滤会话
+        if (! empty($filter['status'])) {
+            $query->where('chat_sessions.status', $filter['status']);
+        }
+
+        // 根据会话名称进行模糊搜索
+        if (! empty($filter['q'])) {
+            $q = $filter['q'];
+            $query->where('chat_sessions.session_name', 'ilike', '%'.$q.'%');
+        }
+
+        // 按更新时间倒序排列
+        $query->orderByDesc('chat_sessions.updated_at');
+
+        // 执行分页查询
+        return $query->paginate($perPage, ['*'], 'page', $page);
+    }
+
+
+    /**
+     * 更新聊天会话信息
+     *
+     * @param string $sessionId 会话ID
+     * @param array $patch 需要更新的字段数据
+     * @return ChatSession 更新后的聊天会话对象
+     * @throws ChatSessionStatusException 当尝试重新打开已关闭的会话时抛出异常
+     */
+    public function updateSession(string $sessionId, array $patch): ChatSession
+    {
+        // 查找包含最后一条消息的会话
+        $session = $this->findSessionWithLastMessage($sessionId);
+
+        // 检查会话状态变更合法性：已关闭的会话不能重新打开
+        if (isset($patch['status']) && $session->status === ChatSessionStatus::CLOSED && $patch['status'] !== ChatSessionStatus::CLOSED) {
+            throw new ChatSessionStatusException('Closed session cannot be reopened');
+        }
+
+        // 填充更新数据并保存
+        $session->fill($patch);
+        $session->updated_at = now();
+        $session->save();
+
+        // 返回更新后的会话信息
+        return $this->findSessionWithLastMessage($sessionId);
+    }
+
+
+    private function baseSessionQuery()
+    {
+        return ChatSession::query()
+            ->leftJoin('messages as lm', 'lm.message_id', '=', 'chat_sessions.last_message_id')
+            ->select('chat_sessions.*')
+            ->addSelect([
+                'lm.created_at as last_message_at',
+                'lm.content as last_message_content',
+                'lm.role as last_message_role',
+                'lm.type as last_message_type',
+            ]);
+    }
+
+    private function findSessionWithLastMessage(string $sessionId): ChatSession
+    {
+        /** @var ChatSession $session */
+        $session = $this->baseSessionQuery()
+            ->where('chat_sessions.session_id', $sessionId)
+            ->firstOrFail();
+
+        return $session;
+    }
+
     private function ensureCanAppend(ChatSession $session, string $role, string $type): void
     {
         if ($session->status === ChatSessionStatus::CLOSED) {