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,
+        ];
+    }
+}