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

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

.env.example

@@ -8,6 +8,7 @@ OCTANE_SERVER=frankenphp
 APP_LOCALE=en
 APP_FALLBACK_LOCALE=en
 APP_FAKER_LOCALE=en_US
+AUTH_GUARD=api
 
 APP_MAINTENANCE_DRIVER=file
 # APP_MAINTENANCE_STORE=database
@@ -28,7 +29,7 @@ DB_DATABASE=ars_backend
 DB_USERNAME=ars
 DB_PASSWORD=secret
 
-SESSION_DRIVER=database
+SESSION_DRIVER=array
 SESSION_LIFETIME=120
 SESSION_ENCRYPT=false
 SESSION_PATH=/
@@ -47,6 +48,8 @@ REDIS_CLIENT=phpredis
 REDIS_HOST=redis
 REDIS_PASSWORD=null
 REDIS_PORT=6379
+JWT_SECRET=
+CORS_ALLOWED_ORIGINS=http://localhost:5173
 
 MAIL_MAILER=log
 MAIL_SCHEME=null

README.md

@@ -22,6 +22,10 @@ Notes:
 - Config sets `OCTANE_SERVER=frankenphp` by default (see `.env` and `config/octane.php`).
 - PostgreSQL service: host `pgsql`, port `5432`, database `ars_backend`, user `ars`, password `secret` (see `.env.example`).
 - Redis service: host `redis`, port `6379`, default no password, client `phpredis`.
+- API 默认使用 JWT：`AUTH_GUARD=api`，会话驱动为 `array`（无状态）。首次运行如需重置密钥：`docker compose run --rm --entrypoint=php app artisan jwt:secret --force`。
+- API 说明文档：`docs/user/user-api.md`（中文）；OpenAPI/Swagger 规范：`docs/user/user-openapi.yaml`（可导入 Swagger UI / Postman）。
+- ChatSession 接口文档：`docs/ChatSession/chat-session-api.md`；OpenAPI：`docs/ChatSession/chat-session-openapi.yaml`。
+- CORS：通过全局中间件开启，允许域名由环境变量 `CORS_ALLOWED_ORIGINS` 配置（默认 `http://localhost:5173`，多域名用逗号分隔）。
 - 项目沟通与自然语言默认使用中文。
 
 ## About Laravel

app/Enums/ChatSessionStatus.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace App\Enums;
+
+class ChatSessionStatus
+{
+    public const OPEN = 'OPEN';
+    public const LOCKED = 'LOCKED';
+    public const CLOSED = 'CLOSED';
+
+    public static function all(): array
+    {
+        return [self::OPEN, self::LOCKED, self::CLOSED];
+    }
+}

app/Exceptions/ChatSessionStatusException.php

@@ -0,0 +1,9 @@
+<?php
+
+namespace App\Exceptions;
+
+use RuntimeException;
+
+class ChatSessionStatusException extends RuntimeException
+{
+}

app/Http/Controllers/AuthController.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Http\Requests\LoginRequest;
+use App\Models\User;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Support\Facades\Hash;
+
+class AuthController extends Controller
+{
+    public function login(LoginRequest $request): JsonResponse
+    {
+        $credentials = $request->validated();
+
+        $user = User::whereEmail($credentials['email'])->first();
+
+        if (! $user || ! Hash::check($credentials['password'], $user->password)) {
+            return response()->json(['message' => '凭证无效'], 401);
+        }
+
+        if (! $user->is_active) {
+            return response()->json(['message' => '用户已停用'], 403);
+        }
+
+        $token = auth('api')->login($user);
+
+        return response()->json([
+            'token' => $token,
+            'token_type' => 'bearer',
+            'expires_in' => auth('api')->factory()->getTTL() * 60,
+            'user' => [
+                'id' => $user->id,
+                'name' => $user->name,
+                'email' => $user->email,
+                'is_active' => $user->is_active,
+            ],
+        ]);
+    }
+}

app/Http/Controllers/ChatSessionController.php

@@ -0,0 +1,112 @@
+<?php
+
+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\Services\ChatService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+
+class ChatSessionController extends Controller
+{
+    public function __construct(private readonly ChatService $service)
+    {
+    }
+
+    /**
+     * 存储新的会话。
+     *
+     * @param CreateSessionRequest $request 包含会话信息的请求实例。
+     * @return JsonResponse 返回包含新创建会话信息的 JSON 响应，状态码为 201。
+     */
+    public function store(CreateSessionRequest $request): JsonResponse
+    {
+        $session = $this->service->createSession($request->input('session_name'));
+
+        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 {
+            $message = $this->service->appendMessage([
+                'session_id' => $sessionId,
+                ...$request->validated(),
+            ]);
+        } catch (ChatSessionStatusException $e) {
+            return response()->json(['message' => $e->getMessage()], 403);
+        }
+
+        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);
+        $limit = (int) $request->query('limit', 50);
+        $limit = $limit > 0 && $limit <= 200 ? $limit : 50;
+
+        $messages = $this->service->listMessagesBySeq($sessionId, $afterSeq, $limit);
+
+        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/Controllers/UserController.php

@@ -0,0 +1,54 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Http\Requests\StoreUserRequest;
+use App\Http\Requests\UpdateUserRequest;
+use App\Http\Resources\UserResource;
+use App\Models\User;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+
+class UserController extends Controller
+{
+    public function index(Request $request): JsonResponse
+    {
+        $perPage = (int) $request->query('per_page', 15);
+        $perPage = $perPage > 0 && $perPage <= 100 ? $perPage : 15;
+
+        $users = User::orderBy('id')->paginate($perPage);
+
+        return UserResource::collection($users)->response();
+    }
+
+    public function store(StoreUserRequest $request): JsonResponse
+    {
+        $payload = $request->validated();
+        $payload['is_active'] = true;
+
+        $user = User::create($payload);
+
+        return (new UserResource($user))->response()->setStatusCode(201);
+    }
+
+    public function update(UpdateUserRequest $request, User $user): JsonResponse
+    {
+        $user->update($request->validated());
+
+        return (new UserResource($user))->response();
+    }
+
+    public function deactivate(User $user): JsonResponse
+    {
+        $user->update(['is_active' => false]);
+
+        return (new UserResource($user))->response();
+    }
+
+    public function activate(User $user): JsonResponse
+    {
+        $user->update(['is_active' => true]);
+
+        return (new UserResource($user))->response();
+    }
+}

app/Http/Requests/AppendMessageRequest.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace App\Http\Requests;
+
+use App\Models\Message;
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+class AppendMessageRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function rules(): array
+    {
+        return [
+            'role' => ['required', 'string', Rule::in([
+                Message::ROLE_USER,
+                Message::ROLE_AGENT,
+                Message::ROLE_TOOL,
+                Message::ROLE_SYSTEM,
+            ])],
+            'type' => ['required', 'string', 'max:64'],
+            'content' => ['nullable', 'string'],
+            'payload' => ['nullable', 'array'],
+            'reply_to' => ['nullable', 'uuid'],
+            'dedupe_key' => ['nullable', 'string', 'max:128'],
+        ];
+    }
+}

app/Http/Requests/CreateSessionRequest.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace App\Http\Requests;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class CreateSessionRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function rules(): array
+    {
+        return [
+            'session_name' => ['nullable', 'string', 'max:255'],
+        ];
+    }
+}

app/Http/Requests/LoginRequest.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace App\Http\Requests;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class LoginRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function rules(): array
+    {
+        return [
+            'email' => ['required', 'email'],
+            'password' => ['required', 'string'],
+        ];
+    }
+}

app/Http/Requests/StoreUserRequest.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace App\Http\Requests;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class StoreUserRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function rules(): array
+    {
+        return [
+            'name' => ['required', 'string', 'max:255'],
+            'email' => ['required', 'email', 'max:255', 'unique:users,email'],
+            'password' => ['required', 'string', 'min:8'],
+        ];
+    }
+}

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/Requests/UpdateUserRequest.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace App\Http\Requests;
+
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+class UpdateUserRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function rules(): array
+    {
+        return [
+            'name' => ['sometimes', 'required', 'string', 'max:255'],
+            'email' => [
+                'sometimes',
+                'required',
+                'email',
+                'max:255',
+                Rule::unique('users', 'email')->ignore($this->route('user')),
+            ],
+            'password' => ['sometimes', 'required', 'string', 'min:8'],
+        ];
+    }
+}

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/Http/Resources/MessageResource.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace App\Http\Resources;
+
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+/** @mixin \App\Models\Message */
+class MessageResource extends JsonResource
+{
+    /**
+     * Transform the resource into an array.
+     *
+     * @return array<string, mixed>
+     */
+    public function toArray(Request $request): array
+    {
+        return [
+            'message_id' => $this->message_id,
+            'session_id' => $this->session_id,
+            'seq' => $this->seq,
+            'role' => $this->role,
+            'type' => $this->type,
+            'content' => $this->content,
+            'payload' => $this->payload,
+            'reply_to' => $this->reply_to,
+            'dedupe_key' => $this->dedupe_key,
+            'created_at' => $this->created_at,
+        ];
+    }
+}

app/Http/Resources/UserResource.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace App\Http\Resources;
+
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+/** @mixin \App\Models\User */
+class UserResource extends JsonResource
+{
+    /**
+     * Transform the resource into an array.
+     *
+     * @return array<string, mixed>
+     */
+    public function toArray(Request $request): array
+    {
+        return [
+            'id' => $this->id,
+            'name' => $this->name,
+            'email' => $this->email,
+            'is_active' => $this->is_active,
+            'created_at' => $this->created_at,
+            'updated_at' => $this->updated_at,
+        ];
+    }
+}

app/Models/ChatSession.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace App\Models;
+
+use App\Enums\ChatSessionStatus;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+
+class ChatSession extends Model
+{
+    use HasFactory;
+
+    protected $primaryKey = 'session_id';
+
+    public $incrementing = false;
+
+    protected $keyType = 'string';
+
+    protected $fillable = [
+        'session_id',
+        'session_name',
+        'status',
+        'last_seq',
+        'last_message_id',
+    ];
+
+    protected function casts(): array
+    {
+        return [
+            'last_seq' => 'integer',
+        ];
+    }
+
+    public function messages(): HasMany
+    {
+        return $this->hasMany(Message::class, 'session_id', 'session_id');
+    }
+
+    public function isClosed(): bool
+    {
+        return $this->status === ChatSessionStatus::CLOSED;
+    }
+
+    public function isLocked(): bool
+    {
+        return $this->status === ChatSessionStatus::LOCKED;
+    }
+}

app/Models/Message.php

@@ -0,0 +1,52 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+class Message extends Model
+{
+    use HasFactory;
+
+    public const ROLE_USER = 'USER';
+    public const ROLE_AGENT = 'AGENT';
+    public const ROLE_TOOL = 'TOOL';
+    public const ROLE_SYSTEM = 'SYSTEM';
+
+    protected $primaryKey = 'message_id';
+
+    public $incrementing = false;
+
+    protected $keyType = 'string';
+
+    public $timestamps = false;
+
+    protected $fillable = [
+        'message_id',
+        'session_id',
+        'role',
+        'type',
+        'content',
+        'payload',
+        'seq',
+        'reply_to',
+        'dedupe_key',
+        'created_at',
+    ];
+
+    protected function casts(): array
+    {
+        return [
+            'payload' => 'array',
+            'seq' => 'integer',
+            'created_at' => 'datetime',
+        ];
+    }
+
+    public function session(): BelongsTo
+    {
+        return $this->belongsTo(ChatSession::class, 'session_id', 'session_id');
+    }
+}

app/Models/User.php

@@ -6,8 +6,9 @@ namespace App\Models;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Foundation\Auth\User as Authenticatable;
 use Illuminate\Notifications\Notifiable;
+use PHPOpenSourceSaver\JWTAuth\Contracts\JWTSubject;
 
-class User extends Authenticatable
+class User extends Authenticatable implements JWTSubject
 {
     /** @use HasFactory<\Database\Factories\UserFactory> */
     use HasFactory, Notifiable;
@@ -21,6 +22,7 @@ class User extends Authenticatable
         'name',
         'email',
         'password',
+        'is_active',
     ];
 
     /**
@@ -43,6 +45,17 @@ class User extends Authenticatable
         return [
             'email_verified_at' => 'datetime',
             'password' => 'hashed',
+            'is_active' => 'boolean',
         ];
     }
+
+    public function getJWTIdentifier(): mixed
+    {
+        return $this->getKey();
+    }
+
+    public function getJWTCustomClaims(): array
+    {
+        return [];
+    }
 }

app/Services/ChatService.php

@@ -0,0 +1,250 @@
+<?php
+
+namespace App\Services;
+
+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;
+use Illuminate\Support\Str;
+
+class ChatService
+{
+
+    /**
+     * 创建一个新聊天会话。
+     * @param string|null $name
+     * @return ChatSession
+     */
+    public function createSession(string $name = null): ChatSession
+    {
+        return ChatSession::create([
+            'session_id' => (string) Str::uuid(),
+            'session_name' => $name,
+            'status' => ChatSessionStatus::OPEN,
+            'last_seq' => 0,
+        ]);
+    }
+
+   /**
+     * 根据会话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 包含消息详细信息的数据传输对象，包括以下键：
+     *                                  - session_id: 聊天会话的唯一标识符
+     *                                  - role: 消息角色（如发件人或收件人）
+     *                                  - type: 消息类型
+     *                                  - content: 消息内容（可选）
+     *                                  - payload: 附加信息（可选）
+     *                                  - reply_to: 被回复的消息 ID（可选）
+     *                                  - dedupe_key: 消息去重键（可选）
+     * @return Message 返回成功追加的消息实例。如果存在去重键并已存在重复消息，则返回现有的消息。
+     */
+    public function appendMessage(array $dto): Message
+    {
+        return DB::transaction(function () use ($dto) {
+            /** @var ChatSession $session */
+            $session = ChatSession::query()
+                ->whereKey($dto['session_id'])
+                ->lockForUpdate()
+                ->firstOrFail();
+
+            $this->ensureCanAppend($session, $dto['role'], $dto['type']);
+
+            $dedupeKey = $dto['dedupe_key'] ?? null;
+            if ($dedupeKey) {
+                $existing = Message::query()
+                    ->where('session_id', $session->session_id)
+                    ->where('dedupe_key', $dedupeKey)
+                    ->first();
+
+                if ($existing) {
+                    return $existing;
+                }
+            }
+
+            $newSeq = $session->last_seq + 1;
+
+            $message = new Message([
+                'message_id' => (string) Str::uuid(),
+                'session_id' => $session->session_id,
+                'role' => $dto['role'],
+                'type' => $dto['type'],
+                'content' => $dto['content'] ?? null,
+                'payload' => $dto['payload'] ?? null,
+                'reply_to' => $dto['reply_to'] ?? null,
+                'dedupe_key' => $dedupeKey,
+                'seq' => $newSeq,
+                'created_at' => now(),
+            ]);
+
+            try {
+                $message->save();
+            } catch (QueryException $e) {
+                if ($this->isUniqueConstraint($e) && $dedupeKey) {
+                    $existing = Message::query()
+                        ->where('session_id', $session->session_id)
+                        ->where('dedupe_key', $dedupeKey)
+                        ->first();
+
+                    if ($existing) {
+                        return $existing;
+                    }
+                }
+
+                throw $e;
+            }
+
+            $session->update([
+                'last_seq' => $newSeq,
+                'last_message_id' => $message->message_id,
+                'updated_at' => now(),
+            ]);
+
+            return $message;
+        });
+    }
+
+    /**
+     * 列出指定会话中指定序号之后的消息。
+     *
+     * @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
+
+        return Message::query()
+            ->where('session_id', $sessionId)
+            ->where('seq', '>', $afterSeq)
+            ->orderBy('seq')
+            ->limit($limit)
+            ->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) {
+            $allowed = $role === Message::ROLE_SYSTEM && in_array($type, ['run.status', 'error'], true);
+            if (! $allowed) {
+                throw new ChatSessionStatusException('Session is closed');
+            }
+        }
+
+        if ($session->status === ChatSessionStatus::LOCKED) {
+            if ($role === Message::ROLE_USER && $type === 'user.prompt') {
+                throw new ChatSessionStatusException('Session is locked');
+            }
+        }
+    }
+
+    private function isUniqueConstraint(QueryException $e): bool
+    {
+        $sqlState = $e->getCode() ?: ($e->errorInfo[0] ?? null);
+
+        return $sqlState === '23505';
+    }
+}

bootstrap/app.php

@@ -3,15 +3,23 @@
 use Illuminate\Foundation\Application;
 use Illuminate\Foundation\Configuration\Exceptions;
 use Illuminate\Foundation\Configuration\Middleware;
+use Illuminate\Http\Middleware\HandleCors;
+use PHPOpenSourceSaver\JWTAuth\Http\Middleware\Authenticate as JwtAuthenticate;
+use PHPOpenSourceSaver\JWTAuth\Http\Middleware\RefreshToken as JwtRefreshToken;
 
 return Application::configure(basePath: dirname(__DIR__))
     ->withRouting(
         web: __DIR__.'/../routes/web.php',
+        api: __DIR__.'/../routes/api.php',
         commands: __DIR__.'/../routes/console.php',
         health: '/up',
     )
     ->withMiddleware(function (Middleware $middleware): void {
-        //
+        $middleware->append(HandleCors::class);
+        $middleware->alias([
+            'auth.jwt' => JwtAuthenticate::class,
+            'auth.jwt.refresh' => JwtRefreshToken::class,
+        ]);
     })
     ->withExceptions(function (Exceptions $exceptions): void {
         //

composer.json

@@ -9,7 +9,8 @@
         "php": "^8.2",
         "laravel/framework": "^12.0",
         "laravel/octane": "^2.13",
-        "laravel/tinker": "^2.10.1"
+        "laravel/tinker": "^2.10.1",
+        "php-open-source-saver/jwt-auth": "^2.8"
     },
     "require-dev": {
         "fakerphp/faker": "^1.23",

composer.lock

@@ -4,7 +4,7 @@
         "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
         "This file is @generated automatically"
     ],
-    "content-hash": "814e29ecc172cfe807c128b7df10ae19",
+    "content-hash": "79f1e234537460fac440cd9aa68d3e6b",
     "packages": [
         {
             "name": "brick/math",
@@ -1638,6 +1638,79 @@
             },
             "time": "2025-11-20T16:29:12+00:00"
         },
+        {
+            "name": "lcobucci/jwt",
+            "version": "5.6.0",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/lcobucci/jwt.git",
+                "reference": "bb3e9f21e4196e8afc41def81ef649c164bca25e"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/lcobucci/jwt/zipball/bb3e9f21e4196e8afc41def81ef649c164bca25e",
+                "reference": "bb3e9f21e4196e8afc41def81ef649c164bca25e",
+                "shasum": ""
+            },
+            "require": {
+                "ext-openssl": "*",
+                "ext-sodium": "*",
+                "php": "~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0",
+                "psr/clock": "^1.0"
+            },
+            "require-dev": {
+                "infection/infection": "^0.29",
+                "lcobucci/clock": "^3.2",
+                "lcobucci/coding-standard": "^11.0",
+                "phpbench/phpbench": "^1.2",
+                "phpstan/extension-installer": "^1.2",
+                "phpstan/phpstan": "^1.10.7",
+                "phpstan/phpstan-deprecation-rules": "^1.1.3",
+                "phpstan/phpstan-phpunit": "^1.3.10",
+                "phpstan/phpstan-strict-rules": "^1.5.0",
+                "phpunit/phpunit": "^11.1"
+            },
+            "suggest": {
+                "lcobucci/clock": ">= 3.2"
+            },
+            "type": "library",
+            "autoload": {
+                "psr-4": {
+                    "Lcobucci\\JWT\\": "src"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "BSD-3-Clause"
+            ],
+            "authors": [
+                {
+                    "name": "Luís Cobucci",
+                    "email": "lcobucci@gmail.com",
+                    "role": "Developer"
+                }
+            ],
+            "description": "A simple library to work with JSON Web Token and JSON Web Signature",
+            "keywords": [
+                "JWS",
+                "jwt"
+            ],
+            "support": {
+                "issues": "https://github.com/lcobucci/jwt/issues",
+                "source": "https://github.com/lcobucci/jwt/tree/5.6.0"
+            },
+            "funding": [
+                {
+                    "url": "https://github.com/lcobucci",
+                    "type": "github"
+                },
+                {
+                    "url": "https://www.patreon.com/lcobucci",
+                    "type": "patreon"
+                }
+            ],
+            "time": "2025-10-17T11:30:53+00:00"
+        },
         {
             "name": "league/commonmark",
             "version": "2.8.0",
@@ -2300,6 +2373,73 @@
             ],
             "time": "2025-03-24T10:02:05+00:00"
         },
+        {
+            "name": "namshi/jose",
+            "version": "7.2.3",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/namshi/jose.git",
+                "reference": "89a24d7eb3040e285dd5925fcad992378b82bcff"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/namshi/jose/zipball/89a24d7eb3040e285dd5925fcad992378b82bcff",
+                "reference": "89a24d7eb3040e285dd5925fcad992378b82bcff",
+                "shasum": ""
+            },
+            "require": {
+                "ext-date": "*",
+                "ext-hash": "*",
+                "ext-json": "*",
+                "ext-pcre": "*",
+                "ext-spl": "*",
+                "php": ">=5.5",
+                "symfony/polyfill-php56": "^1.0"
+            },
+            "require-dev": {
+                "phpseclib/phpseclib": "^2.0",
+                "phpunit/phpunit": "^4.5|^5.0",
+                "satooshi/php-coveralls": "^1.0"
+            },
+            "suggest": {
+                "ext-openssl": "Allows to use OpenSSL as crypto engine.",
+                "phpseclib/phpseclib": "Allows to use Phpseclib as crypto engine, use version ^2.0."
+            },
+            "type": "library",
+            "autoload": {
+                "psr-4": {
+                    "Namshi\\JOSE\\": "src/Namshi/JOSE/"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Alessandro Nadalin",
+                    "email": "alessandro.nadalin@gmail.com"
+                },
+                {
+                    "name": "Alessandro Cinelli (cirpo)",
+                    "email": "alessandro.cinelli@gmail.com"
+                }
+            ],
+            "description": "JSON Object Signing and Encryption library for PHP.",
+            "keywords": [
+                "JSON Web Signature",
+                "JSON Web Token",
+                "JWS",
+                "json",
+                "jwt",
+                "token"
+            ],
+            "support": {
+                "issues": "https://github.com/namshi/jose/issues",
+                "source": "https://github.com/namshi/jose/tree/master"
+            },
+            "time": "2016-12-05T07:27:31+00:00"
+        },
         {
             "name": "nesbot/carbon",
             "version": "3.11.0",
@@ -2704,6 +2844,102 @@
             ],
             "time": "2025-11-20T02:34:59+00:00"
         },
+        {
+            "name": "php-open-source-saver/jwt-auth",
+            "version": "v2.8.3",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/PHP-Open-Source-Saver/jwt-auth.git",
+                "reference": "563f7dc025f48b9ecbacc271da509bbb4c6b3b23"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/PHP-Open-Source-Saver/jwt-auth/zipball/563f7dc025f48b9ecbacc271da509bbb4c6b3b23",
+                "reference": "563f7dc025f48b9ecbacc271da509bbb4c6b3b23",
+                "shasum": ""
+            },
+            "require": {
+                "ext-json": "*",
+                "illuminate/auth": "^10|^11|^12",
+                "illuminate/contracts": "^10|^11|^12",
+                "illuminate/http": "^10|^11|^12",
+                "illuminate/support": "^10|^11|^12",
+                "lcobucci/jwt": "^5.4",
+                "namshi/jose": "^7.0",
+                "nesbot/carbon": "^2.0|^3.0",
+                "php": "^8.2"
+            },
+            "require-dev": {
+                "friendsofphp/php-cs-fixer": "^3",
+                "illuminate/console": "^10|^11|^12",
+                "illuminate/routing": "^10|^11|^12",
+                "mockery/mockery": "^1.6",
+                "orchestra/testbench": "^8|^9|^10",
+                "phpstan/phpstan": "^2",
+                "phpunit/phpunit": "^10.5|^11"
+            },
+            "type": "library",
+            "extra": {
+                "laravel": {
+                    "aliases": {
+                        "JWTAuth": "PHPOpenSourceSaver\\JWTAuth\\Facades\\JWTAuth",
+                        "JWTFactory": "PHPOpenSourceSaver\\JWTAuth\\Facades\\JWTFactory"
+                    },
+                    "providers": [
+                        "PHPOpenSourceSaver\\JWTAuth\\Providers\\LaravelServiceProvider"
+                    ]
+                },
+                "branch-alias": {
+                    "dev-develop": "2.0-dev"
+                }
+            },
+            "autoload": {
+                "psr-4": {
+                    "PHPOpenSourceSaver\\JWTAuth\\": "src/"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Sean Tymon",
+                    "email": "tymon148@gmail.com",
+                    "homepage": "https://tymon.xyz",
+                    "role": "Forked package creator | Developer"
+                },
+                {
+                    "name": "Eric Schricker",
+                    "email": "eric.schricker@adiutabyte.de",
+                    "role": "Developer"
+                },
+                {
+                    "name": "Fabio William Conceição",
+                    "email": "messhias@gmail.com",
+                    "role": "Developer"
+                },
+                {
+                    "name": "Max Snow",
+                    "email": "contact@maxsnow.me",
+                    "role": "Developer"
+                }
+            ],
+            "description": "JSON Web Token Authentication for Laravel and Lumen",
+            "homepage": "https://github.com/PHP-Open-Source-Saver/jwt-auth",
+            "keywords": [
+                "Authentication",
+                "JSON Web Token",
+                "auth",
+                "jwt",
+                "laravel"
+            ],
+            "support": {
+                "issues": "https://github.com/PHP-Open-Source-Saver/jwt-auth/issues",
+                "source": "https://github.com/PHP-Open-Source-Saver/jwt-auth"
+            },
+            "time": "2025-10-15T12:02:51+00:00"
+        },
         {
             "name": "phpoption/phpoption",
             "version": "1.9.4",
@@ -4887,6 +5123,74 @@
             ],
             "time": "2024-12-23T08:48:59+00:00"
         },
+        {
+            "name": "symfony/polyfill-php56",
+            "version": "v1.20.0",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/symfony/polyfill-php56.git",
+                "reference": "54b8cd7e6c1643d78d011f3be89f3ef1f9f4c675"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/symfony/polyfill-php56/zipball/54b8cd7e6c1643d78d011f3be89f3ef1f9f4c675",
+                "reference": "54b8cd7e6c1643d78d011f3be89f3ef1f9f4c675",
+                "shasum": ""
+            },
+            "require": {
+                "php": ">=7.1"
+            },
+            "type": "metapackage",
+            "extra": {
+                "thanks": {
+                    "url": "https://github.com/symfony/polyfill",
+                    "name": "symfony/polyfill"
+                },
+                "branch-alias": {
+                    "dev-main": "1.20-dev"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Nicolas Grekas",
+                    "email": "p@tchwork.com"
+                },
+                {
+                    "name": "Symfony Community",
+                    "homepage": "https://symfony.com/contributors"
+                }
+            ],
+            "description": "Symfony polyfill backporting some PHP 5.6+ features to lower PHP versions",
+            "homepage": "https://symfony.com",
+            "keywords": [
+                "compatibility",
+                "polyfill",
+                "portable",
+                "shim"
+            ],
+            "support": {
+                "source": "https://github.com/symfony/polyfill-php56/tree/v1.20.0"
+            },
+            "funding": [
+                {
+                    "url": "https://symfony.com/sponsor",
+                    "type": "custom"
+                },
+                {
+                    "url": "https://github.com/fabpot",
+                    "type": "github"
+                },
+                {
+                    "url": "https://tidelift.com/funding/github/packagist/symfony/symfony",
+                    "type": "tidelift"
+                }
+            ],
+            "time": "2020-10-23T14:02:19+00:00"
+        },
         {
             "name": "symfony/polyfill-php80",
             "version": "v1.33.0",

config/auth.php

@@ -14,7 +14,7 @@ return [
     */
 
     'defaults' => [
-        'guard' => env('AUTH_GUARD', 'web'),
+        'guard' => env('AUTH_GUARD', 'api'),
         'passwords' => env('AUTH_PASSWORD_BROKER', 'users'),
     ],
 
@@ -40,6 +40,11 @@ return [
             'driver' => 'session',
             'provider' => 'users',
         ],
+        'api' => [
+            'driver' => 'jwt',
+            'provider' => 'users',
+            'hash' => false,
+        ],
     ],
 
     /*

config/cors.php

@@ -0,0 +1,34 @@
+<?php
+
+return [
+
+    /*
+    |--------------------------------------------------------------------------
+    | Cross-Origin Resource Sharing (CORS) Configuration
+    |--------------------------------------------------------------------------
+    |
+    | Here you may configure your settings for cross-origin resource sharing
+    | or "CORS". This determines what cross-origin operations may execute
+    | in web browsers. You are free to adjust these settings as needed.
+    |
+    | Learn more: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS
+    |
+    */
+
+    'paths' => ['api/*', 'up', 'octane'],
+
+    'allowed_methods' => ['*'],
+
+    'allowed_origins' => array_filter(array_map('trim', explode(',', env('CORS_ALLOWED_ORIGINS', 'http://localhost:5173')))),
+
+    'allowed_origins_patterns' => [],
+
+    'allowed_headers' => ['*'],
+
+    'exposed_headers' => [],
+
+    'max_age' => 0,
+
+    'supports_credentials' => false,
+
+];

config/jwt.php

@@ -0,0 +1,321 @@
+<?php
+
+return [
+    /*
+    |--------------------------------------------------------------------------
+    | JWT Authentication Secret
+    |--------------------------------------------------------------------------
+    |
+    | Don't forget to set this in your .env file, as it will be used to sign
+    | your tokens. A helper command is provided for this:
+    | `php artisan jwt:secret`
+    |
+    | Note: This will be used for Symmetric algorithms only (HMAC),
+    | since RSA and ECDSA use a private/public key combo (See below).
+    |
+    */
+
+    'secret' => env('JWT_SECRET'),
+
+    /*
+    |--------------------------------------------------------------------------
+    | JWT Authentication Keys
+    |--------------------------------------------------------------------------
+    |
+    | The algorithm you are using, will determine whether your tokens are
+    | signed with a random string (defined in `JWT_SECRET`) or using the
+    | following public & private keys.
+    |
+    | Symmetric Algorithms:
+    | HS256, HS384 & HS512 will use `JWT_SECRET`.
+    |
+    | Asymmetric Algorithms:
+    | RS256, RS384 & RS512 / ES256, ES384 & ES512 will use the keys below.
+    |
+    */
+
+    'keys' => [
+        /*
+        |--------------------------------------------------------------------------
+        | Public Key
+        |--------------------------------------------------------------------------
+        |
+        | A path or resource to your public key.
+        |
+        | E.g. 'file://path/to/public/key'
+        |
+        */
+
+        'public' => env('JWT_PUBLIC_KEY'),
+
+        /*
+        |--------------------------------------------------------------------------
+        | Private Key
+        |--------------------------------------------------------------------------
+        |
+        | A path or resource to your private key.
+        |
+        | E.g. 'file://path/to/private/key'
+        |
+        */
+
+        'private' => env('JWT_PRIVATE_KEY'),
+
+        /*
+        |--------------------------------------------------------------------------
+        | Passphrase
+        |--------------------------------------------------------------------------
+        |
+        | The passphrase for your private key. Can be null if none set.
+        |
+        */
+
+        'passphrase' => env('JWT_PASSPHRASE'),
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | JWT time to live
+    |--------------------------------------------------------------------------
+    |
+    | Specify the length of time (in minutes) that the token will be valid for.
+    | Defaults to 1 hour.
+    |
+    | You can also set this to null, to yield a never expiring token.
+    | Some people may want this behaviour for e.g. a mobile app.
+    | This is not particularly recommended, so make sure you have appropriate
+    | systems in place to revoke the token if necessary.
+    | Notice: If you set this to null you should remove 'exp' element from 'required_claims' list.
+    |
+    */
+
+    'ttl' => (int) env('JWT_TTL', 60),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Refresh time to live
+    |--------------------------------------------------------------------------
+    |
+    | Specify the length of time (in minutes) that the token can be refreshed within.
+    | This defines the refresh window, during which the user can refresh their token
+    | before re-authentication is required.
+    |
+    | By default, a refresh will NOT issue a new "iat" (issued at) timestamp. If changed
+    | to true, each refresh will issue a new "iat" timestamp, extending the refresh
+    | period from the most recent refresh. This results in a rolling refresh
+    |
+    | To retain a fluid refresh window from the last refresh action (i.e., the behavior between
+    | version 2.5.0 and 2.8.2), set "refresh_iat" to true. With this setting, the refresh
+    | window will renew with each subsequent refresh.
+    |
+    | The refresh ttl defaults to 2 weeks.
+    |
+    | You can also set this to null, to yield an infinite refresh time.
+    | Some may want this instead of never expiring tokens for e.g. a mobile app.
+    | This is not particularly recommended, so make sure you have appropriate
+    | systems in place to revoke the token if necessary.
+    |
+    */
+
+    'refresh_iat' => env('JWT_REFRESH_IAT', false),
+    'refresh_ttl' => (int) env('JWT_REFRESH_TTL', 20160),
+
+    /*
+    |--------------------------------------------------------------------------
+    | JWT hashing algorithm
+    |--------------------------------------------------------------------------
+    |
+    | Specify the hashing algorithm that will be used to sign the token.
+    |
+    | See here: https://github.com/namshi/jose/tree/master/src/Namshi/JOSE/Signer/OpenSSL
+    | for possible values.
+    |
+    */
+
+    'algo' => env('JWT_ALGO', 'HS256'),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Required Claims
+    |--------------------------------------------------------------------------
+    |
+    | Specify the required claims that must exist in any token.
+    | A TokenInvalidException will be thrown if any of these claims are not
+    | present in the payload.
+    |
+    */
+
+    'required_claims' => [
+        'iss',
+        'iat',
+        'exp',
+        'nbf',
+        'sub',
+        'jti',
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Persistent Claims
+    |--------------------------------------------------------------------------
+    |
+    | Specify the claim keys to be persisted when refreshing a token.
+    | `sub` and `iat` will automatically be persisted, in
+    | addition to the these claims.
+    |
+    | Note: If a claim does not exist then it will be ignored.
+    |
+    */
+
+    'persistent_claims' => [
+        // 'foo',
+        // 'bar',
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Lock Subject
+    |--------------------------------------------------------------------------
+    |
+    | This will determine whether a `prv` claim is automatically added to
+    | the token. The purpose of this is to ensure that if you have multiple
+    | authentication models e.g. `App\User` & `App\OtherPerson`, then we
+    | should prevent one authentication request from impersonating another,
+    | if 2 tokens happen to have the same id across the 2 different models.
+    |
+    | Under specific circumstances, you may want to disable this behaviour
+    | e.g. if you only have one authentication model, then you would save
+    | a little on token size.
+    |
+    */
+
+    'lock_subject' => true,
+
+    /*
+    |--------------------------------------------------------------------------
+    | Leeway
+    |--------------------------------------------------------------------------
+    |
+    | This property gives the jwt timestamp claims some "leeway".
+    | Meaning that if you have any unavoidable slight clock skew on
+    | any of your servers then this will afford you some level of cushioning.
+    |
+    | This applies to the claims `iat`, `nbf` and `exp`.
+    |
+    | Specify in seconds - only if you know you need it.
+    |
+    */
+
+    'leeway' => (int) env('JWT_LEEWAY', 0),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Blacklist Enabled
+    |--------------------------------------------------------------------------
+    |
+    | In order to invalidate tokens, you must have the blacklist enabled.
+    | If you do not want or need this functionality, then set this to false.
+    |
+    */
+
+    'blacklist_enabled' => env('JWT_BLACKLIST_ENABLED', true),
+
+    /*
+    | -------------------------------------------------------------------------
+    | Blacklist Grace Period
+    | -------------------------------------------------------------------------
+    |
+    | When multiple concurrent requests are made with the same JWT,
+    | it is possible that some of them fail, due to token regeneration
+    | on every request.
+    |
+    | Set grace period in seconds to prevent parallel request failure.
+    |
+    */
+
+    'blacklist_grace_period' => (int) env('JWT_BLACKLIST_GRACE_PERIOD', 0),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Show blacklisted token option
+    |--------------------------------------------------------------------------
+    |
+    | Specify if you want to show black listed token exception on the laravel logs.
+    |
+    */
+
+    'show_black_list_exception' => env('JWT_SHOW_BLACKLIST_EXCEPTION', true),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Cookies encryption
+    |--------------------------------------------------------------------------
+    |
+    | By default Laravel encrypt cookies for security reason.
+    | If you decide to not decrypt cookies, you will have to configure Laravel
+    | to not encrypt your cookie token by adding its name into the $except
+    | array available in the middleware "EncryptCookies" provided by Laravel.
+    | see https://laravel.com/docs/master/responses#cookies-and-encryption
+    | for details.
+    |
+    | Set it to true if you want to decrypt cookies.
+    |
+    */
+
+    'decrypt_cookies' => false,
+
+    /*
+    |--------------------------------------------------------------------------
+    | Cookie key name
+    |--------------------------------------------------------------------------
+    |
+    | Specify the cookie key name that you would like to use for the cookie token.
+    |
+    */
+
+    'cookie_key_name' => 'token',
+
+    /*
+    |--------------------------------------------------------------------------
+    | Providers
+    |--------------------------------------------------------------------------
+    |
+    | Specify the various providers used throughout the package.
+    |
+    */
+
+    'providers' => [
+        /*
+        |--------------------------------------------------------------------------
+        | JWT Provider
+        |--------------------------------------------------------------------------
+        |
+        | Specify the provider that is used to create and decode the tokens.
+        |
+        */
+
+        'jwt' => PHPOpenSourceSaver\JWTAuth\Providers\JWT\Lcobucci::class,
+
+        /*
+        |--------------------------------------------------------------------------
+        | Authentication Provider
+        |--------------------------------------------------------------------------
+        |
+        | Specify the provider that is used to authenticate users.
+        |
+        */
+
+        'auth' => PHPOpenSourceSaver\JWTAuth\Providers\Auth\Illuminate::class,
+
+        /*
+        |--------------------------------------------------------------------------
+        | Storage Provider
+        |--------------------------------------------------------------------------
+        |
+        | Specify the provider that is used to store tokens in the blacklist.
+        |
+        */
+
+        'storage' => PHPOpenSourceSaver\JWTAuth\Providers\Storage\Illuminate::class,
+    ],
+];

config/session.php

@@ -18,7 +18,7 @@ return [
     |
     */
 
-    'driver' => env('SESSION_DRIVER', 'database'),
+    'driver' => env('SESSION_DRIVER', 'array'),
 
     /*
     |--------------------------------------------------------------------------

database/factories/UserFactory.php

@@ -29,6 +29,7 @@ class UserFactory extends Factory
             'email_verified_at' => now(),
             'password' => static::$password ??= Hash::make('password'),
             'remember_token' => Str::random(10),
+            'is_active' => true,
         ];
     }
 

database/migrations/0001_01_01_000000_create_users_table.php

@@ -17,6 +17,7 @@ return new class extends Migration
             $table->string('email')->unique();
             $table->timestamp('email_verified_at')->nullable();
             $table->string('password');
+            $table->boolean('is_active')->default(true);
             $table->rememberToken();
             $table->timestamps();
         });

database/migrations/2025_02_14_000003_create_chat_tables.php

@@ -0,0 +1,43 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('chat_sessions', function (Blueprint $table) {
+            $table->uuid('session_id')->primary();
+            $table->string('session_name', 255)->nullable();
+            $table->string('status', 16)->default('OPEN');
+            $table->unsignedBigInteger('last_seq')->default(0);
+            $table->timestamps();
+        });
+
+        Schema::create('messages', function (Blueprint $table) {
+            $table->uuid('message_id')->primary();
+            $table->uuid('session_id');
+            $table->string('role', 32);
+            $table->string('type', 64);
+            $table->text('content')->nullable();
+            $table->jsonb('payload')->nullable();
+            $table->timestamp('created_at')->useCurrent();
+            $table->unsignedBigInteger('seq');
+            $table->uuid('reply_to')->nullable();
+            $table->string('dedupe_key', 128)->nullable();
+
+            $table->foreign('session_id')->references('session_id')->on('chat_sessions')->onDelete('cascade');
+            $table->unique(['session_id', 'seq']);
+            $table->unique(['session_id', 'dedupe_key']);
+            $table->index(['session_id', 'seq']);
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('messages');
+        Schema::dropIfExists('chat_sessions');
+    }
+};

database/migrations/2025_02_14_000004_add_last_message_to_chat_sessions.php

@@ -0,0 +1,28 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('chat_sessions', function (Blueprint $table) {
+            $table->uuid('last_message_id')->nullable()->after('last_seq');
+            $table->index('updated_at');
+            $table->index('status');
+            $table->index('last_message_id');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('chat_sessions', function (Blueprint $table) {
+            $table->dropIndex(['updated_at']);
+            $table->dropIndex(['status']);
+            $table->dropIndex(['last_message_id']);
+            $table->dropColumn('last_message_id');
+        });
+    }
+};

database/seeders/DatabaseSeeder.php

@@ -5,6 +5,7 @@ namespace Database\Seeders;
 use App\Models\User;
 use Illuminate\Database\Console\Seeds\WithoutModelEvents;
 use Illuminate\Database\Seeder;
+use Illuminate\Support\Facades\Hash;
 
 class DatabaseSeeder extends Seeder
 {
@@ -15,11 +16,24 @@ class DatabaseSeeder extends Seeder
      */
     public function run(): void
     {
-        // User::factory(10)->create();
+        User::updateOrCreate(
+            ['email' => 'root@example.com'],
+            [
+                'name' => 'root',
+                'password' => Hash::make('Root@123456'),
+                'is_active' => true,
+                'email_verified_at' => now(),
+            ],
+        );
 
-        User::factory()->create([
+        User::updateOrCreate(
-            'name' => 'Test User',
+            ['email' => 'guxinpei@qq.com'],
-            'email' => 'test@example.com',
+            [
-        ]);
+                'name' => 'roog',
+                'password' => Hash::make('w2021976'),
+                'is_active' => true,
+                'email_verified_at' => now(),
+            ],
+        );
     }
 }

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

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

docs/User/user-api.md

@@ -0,0 +1,84 @@
+# 接口文档（JWT，无状态 API）
+
+基地址：`http://localhost:8000/api`（容器默认映射 8000 端口）  
+自然语言：中文
+
+- 认证方式：在请求头添加 `Authorization: Bearer {token}`。
+- 默认账号（来自 `php artisan db:seed`）：`root@example.com` / `Root@123456`。
+- 所有接口均返回 JSON；失败时返回 `{ "message": "错误信息" }`。
+- 跨域：默认允许 `http://localhost:5173`，可通过环境变量 `CORS_ALLOWED_ORIGINS`（逗号分隔多个域名）调整。
+
+## 健康检查
+- `GET /health`  
+  响应：`{ "status": "ok" }`
+
+## 登录
+- `POST /login`
+- 请求体：
+```json
+{ "email": "user@example.com", "password": "Password123" }
+```
+- 响应 200：
+```json
+{
+  "token": "jwt-token",
+  "token_type": "bearer",
+  "expires_in": 3600,
+  "user": { "id": 1, "name": "root", "email": "root@example.com", "is_active": true }
+}
+```
+- 401：凭证无效；403：用户已停用。
+
+## 当前用户
+- `GET /me`（需要 JWT）
+- 响应 200：当前登录用户信息。
+
+## 用户管理（需 JWT）
+字段约束：`name` 必填字符串（<=255）、`email` 邮箱唯一、`password` 最少 8 字符。
+
+### 用户列表
+- `GET /users`
+- 查询参数：`page`（默认 1）、`per_page`（默认 15，最大 100）
+- 响应 200：分页列表，`data` 为用户数组，包含 `id/name/email/is_active/created_at/updated_at`。
+
+### 创建用户
+- `POST /users`
+- 请求体：
+```json
+{ "name": "Alice", "email": "alice@example.com", "password": "Password123" }
+```
+- 响应 201：新建用户（含 `is_active: true`）。
+
+### 更新用户
+- `PUT /users/{id}`
+- 请求体（任意字段可选）：
+```json
+{ "name": "New Name", "email": "new@example.com", "password": "NewPass123" }
+```
+- 响应 200：更新后的用户。
+
+### 停用用户
+- `POST /users/{id}/deactivate`
+- 响应 200：`is_active` 为 `false`。
+
+### 启用用户
+- `POST /users/{id}/activate`
+- 响应 200：`is_active` 为 `true`。
+
+## 示例（cURL）
+```bash
+# 登录
+curl -X POST http://localhost:8000/api/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"root@example.com","password":"Root@123456"}'
+
+# 创建用户（替换 TOKEN）
+curl -X POST http://localhost:8000/api/users \
+  -H "Authorization: Bearer TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"Alice","email":"alice@example.com","password":"Password123"}'
+
+# 获取用户列表（替换 TOKEN）
+curl -X GET http://localhost:8000/api/users \
+  -H "Authorization: Bearer TOKEN"
+```

docs/User/user-openapi.yaml

@@ -0,0 +1,365 @@
+openapi: 3.0.3
+info:
+  title: ars-backend API (JWT)
+  version: 1.0.0
+  description: |
+    ars-backend 无状态 API，认证方式为 JWT Bearer。自然语言：中文。
+servers:
+  - url: http://localhost:8000/api
+    description: 本地开发（FrankenPHP Octane，Docker）
+tags:
+  - name: System
+    description: 系统与健康检查
+  - name: Auth
+    description: 认证相关接口
+  - name: Users
+    description: 用户管理接口（需 JWT）
+paths:
+  /health:
+    get:
+      tags: [System]
+      summary: 健康检查
+      responses:
+        "200":
+          description: 服务可用
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                    example: ok
+  /login:
+    post:
+      tags: [Auth]
+      summary: 用户登录
+      description: 使用邮箱和密码换取 JWT，停用用户返回 403。
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/LoginRequest'
+      responses:
+        "200":
+          description: 登录成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AuthResponse'
+        "401":
+          description: 凭证无效
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        "403":
+          description: 用户已停用
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /me:
+    get:
+      tags: [Auth]
+      summary: 获取当前用户
+      security:
+        - bearerAuth: []
+      responses:
+        "200":
+          description: 当前登录用户
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+        "401":
+          description: 未授权或 token 失效
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /users:
+    get:
+      tags: [Users]
+      summary: 用户列表
+      security:
+        - bearerAuth: []
+      parameters:
+        - in: query
+          name: page
+          schema:
+            type: integer
+            default: 1
+          description: 页码（默认 1）
+        - in: query
+          name: per_page
+          schema:
+            type: integer
+            default: 15
+            maximum: 100
+          description: 每页数量（1-100，默认 15）
+      responses:
+        "200":
+          description: 分页用户列表
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserPagination'
+        "401":
+          description: 未授权
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+    post:
+      tags: [Users]
+      summary: 创建用户
+      security:
+        - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateUserRequest'
+      responses:
+        "201":
+          description: 创建成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+        "401":
+          description: 未授权
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        "422":
+          description: 参数校验失败
+  /users/{id}:
+    put:
+      tags: [Users]
+      summary: 更新用户
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: integer
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateUserRequest'
+      responses:
+        "200":
+          description: 更新成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+        "401":
+          description: 未授权
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        "422":
+          description: 参数校验失败
+  /users/{id}/deactivate:
+    post:
+      tags: [Users]
+      summary: 停用用户
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: integer
+      responses:
+        "200":
+          description: 已停用
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+        "401":
+          description: 未授权
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /users/{id}/activate:
+    post:
+      tags: [Users]
+      summary: 启用用户
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: integer
+      responses:
+        "200":
+          description: 已启用
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+        "401":
+          description: 未授权
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+  schemas:
+    User:
+      type: object
+      properties:
+        id:
+          type: integer
+          example: 1
+        name:
+          type: string
+          example: root
+        email:
+          type: string
+          format: email
+          example: root@example.com
+        is_active:
+          type: boolean
+          example: true
+        created_at:
+          type: string
+          format: date-time
+          example: 2025-12-14T05:37:47.000000Z
+        updated_at:
+          type: string
+          format: date-time
+          example: 2025-12-14T05:37:47.000000Z
+    LoginRequest:
+      type: object
+      required: [email, password]
+      properties:
+        email:
+          type: string
+          format: email
+          example: root@example.com
+        password:
+          type: string
+          format: password
+          example: Root@123456
+    CreateUserRequest:
+      type: object
+      required: [name, email, password]
+      properties:
+        name:
+          type: string
+          example: Alice
+        email:
+          type: string
+          format: email
+          example: alice@example.com
+        password:
+          type: string
+          format: password
+          example: Password123
+    UpdateUserRequest:
+      type: object
+      properties:
+        name:
+          type: string
+          example: Alice Updated
+        email:
+          type: string
+          format: email
+          example: alice.updated@example.com
+        password:
+          type: string
+          format: password
+          example: NewPassword123
+    AuthResponse:
+      type: object
+      properties:
+        token:
+          type: string
+          example: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
+        token_type:
+          type: string
+          example: bearer
+        expires_in:
+          type: integer
+          example: 3600
+        user:
+          $ref: '#/components/schemas/User'
+    Error:
+      type: object
+      properties:
+        message:
+          type: string
+          example: 凭证无效
+    UserPagination:
+      type: object
+      properties:
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/User'
+        links:
+          $ref: '#/components/schemas/PaginationLinks'
+        meta:
+          $ref: '#/components/schemas/PaginationMeta'
+    PaginationLinks:
+      type: object
+      properties:
+        first:
+          type: string
+          example: http://localhost:8000/api/users?page=1
+        last:
+          type: string
+          example: http://localhost:8000/api/users?page=1
+        prev:
+          type: string
+          nullable: true
+        next:
+          type: string
+          nullable: true
+    PaginationMeta:
+      type: object
+      properties:
+        current_page:
+          type: integer
+          example: 1
+        from:
+          type: integer
+          example: 1
+        last_page:
+          type: integer
+          example: 1
+        path:
+          type: string
+          example: http://localhost:8000/api/users
+        per_page:
+          type: integer
+          example: 15
+        to:
+          type: integer
+          example: 3
+        total:
+          type: integer
+          example: 3

routes/api.php

@@ -0,0 +1,29 @@
+<?php
+
+use App\Http\Controllers\AuthController;
+use App\Http\Controllers\ChatSessionController;
+use App\Http\Controllers\UserController;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Route;
+
+Route::get('/health', fn () => ['status' => 'ok']);
+
+Route::post('/login', [AuthController::class, 'login']);
+
+Route::middleware('auth.jwt')->group(function () {
+    Route::get('/me', function (Request $request) {
+        return $request->user();
+    });
+
+    Route::get('/users', [UserController::class, 'index']);
+    Route::post('/users', [UserController::class, 'store']);
+    Route::put('/users/{user}', [UserController::class, 'update']);
+    Route::post('/users/{user}/deactivate', [UserController::class, 'deactivate']);
+    Route::post('/users/{user}/activate', [UserController::class, 'activate']);
+
+    Route::get('/sessions', [ChatSessionController::class, 'index']);
+    Route::post('/sessions', [ChatSessionController::class, 'store']);
+    Route::post('/sessions/{session_id}/messages', [ChatSessionController::class, 'append']);
+    Route::get('/sessions/{session_id}/messages', [ChatSessionController::class, 'listMessages']);
+    Route::patch('/sessions/{session_id}', [ChatSessionController::class, 'update']);
+});

routes/web.php

@@ -2,6 +2,4 @@
 
 use Illuminate\Support\Facades\Route;
 
-Route::get('/', function () {
+Route::get('/', fn () => response()->json(['message' => 'ARS API', 'docs' => '/api']));
-    return view('welcome');
-});

tests/Feature/ChatSessionTest.php

@@ -0,0 +1,221 @@
+<?php
+
+namespace Tests\Feature;
+
+use App\Enums\ChatSessionStatus;
+use App\Models\User;
+use App\Services\ChatService;
+use Illuminate\Support\Carbon;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use PHPOpenSourceSaver\JWTAuth\Facades\JWTAuth;
+use Tests\TestCase;
+
+class ChatSessionTest extends TestCase
+{
+    use RefreshDatabase;
+
+    private function authHeader(User $user): array
+    {
+        return ['Authorization' => 'Bearer '.JWTAuth::fromUser($user)];
+    }
+
+    public function test_append_messages_sequential_seq_and_last_seq(): void
+    {
+        $service = app(ChatService::class);
+        $session = $service->createSession('Test Session');
+
+        $messages = collect(range(1, 20))->map(function ($i) use ($service, $session) {
+            return $service->appendMessage([
+                'session_id' => $session->session_id,
+                'role' => 'USER',
+                'type' => 'user.prompt',
+                'content' => 'msg '.$i,
+            ]);
+        });
+
+        $seqs = $messages->pluck('seq')->all();
+        $this->assertEquals(range(1, 20), $seqs);
+
+        $session->refresh();
+        $this->assertEquals(20, $session->last_seq);
+    }
+
+    public function test_dedupe_returns_existing_message(): void
+    {
+        $service = app(ChatService::class);
+        $session = $service->createSession('Test Session');
+
+        $first = $service->appendMessage([
+            'session_id' => $session->session_id,
+            'role' => 'USER',
+            'type' => 'user.prompt',
+            'content' => 'hello',
+            'dedupe_key' => 'k1',
+        ]);
+
+        $second = $service->appendMessage([
+            'session_id' => $session->session_id,
+            'role' => 'USER',
+            'type' => 'user.prompt',
+            'content' => 'hello again',
+            'dedupe_key' => 'k1',
+        ]);
+
+        $this->assertEquals($first->message_id, $second->message_id);
+        $this->assertEquals($first->seq, $second->seq);
+        $this->assertCount(1, $session->messages()->get());
+    }
+
+    public function test_closed_session_blocks_append_except_whitelisted(): void
+    {
+        $service = app(ChatService::class);
+        $session = $service->createSession('Test Session');
+        $session->update(['status' => ChatSessionStatus::CLOSED]);
+
+        $this->expectExceptionMessage('Session is closed');
+        $service->appendMessage([
+            'session_id' => $session->session_id,
+            'role' => 'USER',
+            'type' => 'user.prompt',
+            'content' => 'blocked',
+        ]);
+    }
+
+    public function test_http_append_and_list_messages(): void
+    {
+        $user = User::factory()->create();
+        $headers = $this->authHeader($user);
+
+        $createSession = $this->withHeaders($headers)->postJson('/api/sessions', [
+            'session_name' => 'API Session',
+        ])->assertCreated();
+
+        $sessionId = $createSession->json('data.session_id');
+
+        $append = $this->withHeaders($headers)->postJson("/api/sessions/{$sessionId}/messages", [
+            'role' => 'USER',
+            'type' => 'user.prompt',
+            'content' => 'hello api',
+        ])->assertCreated();
+
+        $this->assertEquals(1, $append->json('data.seq'));
+
+        $list = $this->withHeaders($headers)->getJson("/api/sessions/{$sessionId}/messages?after_seq=0&limit=10")
+            ->assertOk();
+
+        $this->assertEquals(1, $list->json('data.0.seq'));
+        $this->assertEquals('hello api', $list->json('data.0.content'));
+    }
+
+    public function test_session_list_sorted_and_last_message_preview(): void
+    {
+        $user = User::factory()->create();
+        $headers = $this->authHeader($user);
+        $service = app(ChatService::class);
+
+        Carbon::setTestNow('2025-01-01 00:00:00');
+        $s1 = $service->createSession('First');
+        $service->appendMessage([
+            'session_id' => $s1->session_id,
+            'role' => 'USER',
+            'type' => 'user.prompt',
+            'content' => 'hello first',
+        ]);
+
+        Carbon::setTestNow('2025-01-01 00:00:10');
+        $s2 = $service->createSession('Second');
+        $service->appendMessage([
+            'session_id' => $s2->session_id,
+            'role' => 'USER',
+            'type' => 'user.prompt',
+            'content' => 'hello second',
+        ]);
+
+        Carbon::setTestNow();
+
+        $resp = $this->withHeaders($headers)->getJson('/api/sessions?per_page=10')
+            ->assertOk();
+
+        $this->assertEquals($s2->session_id, $resp->json('data.0.session_id'));
+        $this->assertEquals('hello second', $resp->json('data.0.last_message_preview'));
+        $this->assertEquals('hello first', $resp->json('data.1.last_message_preview'));
+        $this->assertNotNull($resp->json('data.0.last_message_at'));
+    }
+
+    public function test_session_list_filters_status_and_query(): void
+    {
+        $user = User::factory()->create();
+        $headers = $this->authHeader($user);
+        $service = app(ChatService::class);
+
+        $open = $service->createSession('Alpha');
+        $locked = $service->createSession('Beta');
+        $locked->update(['status' => ChatSessionStatus::LOCKED]);
+        $closed = $service->createSession('Gamma');
+        $closed->update(['status' => ChatSessionStatus::CLOSED]);
+
+        $respStatus = $this->withHeaders($headers)->getJson('/api/sessions?status=LOCKED')
+            ->assertOk();
+        $this->assertCount(1, $respStatus->json('data'));
+        $this->assertEquals($locked->session_id, $respStatus->json('data.0.session_id'));
+
+        $respQuery = $this->withHeaders($headers)->getJson('/api/sessions?q=Alpha')
+            ->assertOk();
+        $this->assertCount(1, $respQuery->json('data'));
+        $this->assertEquals($open->session_id, $respQuery->json('data.0.session_id'));
+    }
+
+    public function test_patch_updates_session_name(): void
+    {
+        $user = User::factory()->create();
+        $headers = $this->authHeader($user);
+        $service = app(ChatService::class);
+        $session = $service->createSession('Old Name');
+
+        $resp = $this->withHeaders($headers)->patchJson("/api/sessions/{$session->session_id}", [
+            'session_name' => 'New Name',
+        ])->assertOk();
+
+        $this->assertEquals('New Name', $resp->json('data.session_name'));
+    }
+
+    public function test_patch_updates_status_transitions(): void
+    {
+        $user = User::factory()->create();
+        $headers = $this->authHeader($user);
+        $service = app(ChatService::class);
+        $session = $service->createSession('Status Session');
+
+        $this->withHeaders($headers)->patchJson("/api/sessions/{$session->session_id}", [
+            'status' => ChatSessionStatus::LOCKED,
+        ])->assertOk()->assertJsonFragment(['status' => ChatSessionStatus::LOCKED]);
+
+        $this->withHeaders($headers)->patchJson("/api/sessions/{$session->session_id}", [
+            'status' => ChatSessionStatus::OPEN,
+        ])->assertOk()->assertJsonFragment(['status' => ChatSessionStatus::OPEN]);
+    }
+
+    public function test_closed_session_cannot_reopen(): void
+    {
+        $user = User::factory()->create();
+        $headers = $this->authHeader($user);
+        $service = app(ChatService::class);
+        $session = $service->createSession('Closed Session');
+        $session->update(['status' => ChatSessionStatus::CLOSED]);
+
+        $this->withHeaders($headers)->patchJson("/api/sessions/{$session->session_id}", [
+            'status' => ChatSessionStatus::OPEN,
+        ])->assertStatus(403);
+    }
+
+    public function test_empty_patch_rejected(): void
+    {
+        $user = User::factory()->create();
+        $headers = $this->authHeader($user);
+        $service = app(ChatService::class);
+        $session = $service->createSession('Patch Empty');
+
+        $this->withHeaders($headers)->patchJson("/api/sessions/{$session->session_id}", [])
+            ->assertStatus(422);
+    }
+}

tests/Feature/CorsTest.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Tests\Feature;
+
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
+class CorsTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_allows_configured_origin(): void
+    {
+        $origin = 'http://localhost:5173';
+
+        $response = $this->withHeaders(['Origin' => $origin])->get('/api/health');
+
+        $response->assertOk();
+        $this->assertEquals($origin, $response->headers->get('Access-Control-Allow-Origin'));
+    }
+}

tests/Feature/UserManagementTest.php

@@ -0,0 +1,161 @@
+<?php
+
+namespace Tests\Feature;
+
+use App\Models\User;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Support\Facades\Hash;
+use PHPOpenSourceSaver\JWTAuth\Facades\JWTAuth;
+use Tests\TestCase;
+
+class UserManagementTest extends TestCase
+{
+    use RefreshDatabase;
+
+    private function authHeader(User $user): array
+    {
+        return ['Authorization' => 'Bearer '.JWTAuth::fromUser($user)];
+    }
+
+    public function test_can_create_user(): void
+    {
+        $admin = User::factory()->create();
+
+        $response = $this->withHeaders($this->authHeader($admin))->postJson('/api/users', [
+            'name' => 'Alice',
+            'email' => 'alice@example.com',
+            'password' => 'Password123',
+        ]);
+
+        $response->assertCreated()->assertJsonFragment([
+            'name' => 'Alice',
+            'email' => 'alice@example.com',
+            'is_active' => true,
+        ]);
+
+        $this->assertDatabaseHas('users', [
+            'email' => 'alice@example.com',
+            'is_active' => true,
+        ]);
+
+        $user = User::whereEmail('alice@example.com')->first();
+        $this->assertNotNull($user);
+        $this->assertTrue(Hash::check('Password123', $user->password));
+    }
+
+    public function test_can_list_users(): void
+    {
+        $admin = User::factory()->create(['name' => 'Admin']);
+        $activeUser = User::factory()->create(['name' => 'Active User', 'email' => 'active@example.com']);
+        $inactiveUser = User::factory()->create(['name' => 'Inactive User', 'email' => 'inactive@example.com', 'is_active' => false]);
+
+        $response = $this->withHeaders($this->authHeader($admin))->getJson('/api/users');
+
+        $response->assertOk()->assertJsonStructure([
+            'data' => [
+                ['id', 'name', 'email', 'is_active', 'created_at', 'updated_at'],
+            ],
+            'links',
+            'meta',
+        ]);
+
+        $response->assertJsonCount(3, 'data');
+        $response->assertJsonFragment(['email' => $activeUser->email, 'is_active' => true]);
+        $response->assertJsonFragment(['email' => $inactiveUser->email, 'is_active' => false]);
+    }
+
+    public function test_can_update_user(): void
+    {
+        $admin = User::factory()->create();
+        $user = User::factory()->create();
+
+        $response = $this->withHeaders($this->authHeader($admin))->putJson("/api/users/{$user->id}", [
+            'name' => 'Updated User',
+            'email' => 'updated@example.com',
+            'password' => 'NewPassword123',
+        ]);
+
+        $response->assertOk()->assertJsonFragment([
+            'id' => $user->id,
+            'name' => 'Updated User',
+            'email' => 'updated@example.com',
+            'is_active' => true,
+        ]);
+
+        $user->refresh();
+        $this->assertEquals('Updated User', $user->name);
+        $this->assertEquals('updated@example.com', $user->email);
+        $this->assertTrue(Hash::check('NewPassword123', $user->password));
+    }
+
+    public function test_can_deactivate_and_activate_user(): void
+    {
+        $admin = User::factory()->create();
+        $user = User::factory()->create();
+
+        $deactivate = $this->withHeaders($this->authHeader($admin))->postJson("/api/users/{$user->id}/deactivate");
+        $deactivate->assertOk()->assertJsonFragment(['is_active' => false]);
+
+        $this->assertDatabaseHas('users', [
+            'id' => $user->id,
+            'is_active' => false,
+        ]);
+
+        $activate = $this->withHeaders($this->authHeader($admin))->postJson("/api/users/{$user->id}/activate");
+        $activate->assertOk()->assertJsonFragment(['is_active' => true]);
+
+        $this->assertDatabaseHas('users', [
+            'id' => $user->id,
+            'is_active' => true,
+        ]);
+    }
+
+    public function test_user_can_login_and_receive_jwt(): void
+    {
+        $password = 'Password123';
+        $user = User::factory()->create([
+            'password' => Hash::make($password),
+        ]);
+
+        $response = $this->postJson('/api/login', [
+            'email' => $user->email,
+            'password' => $password,
+        ]);
+
+        $response->assertOk()->assertJsonStructure([
+            'token',
+            'token_type',
+            'expires_in',
+            'user' => ['id', 'name', 'email', 'is_active'],
+        ]);
+    }
+
+    public function test_inactive_user_cannot_login(): void
+    {
+        $user = User::factory()->create([
+            'password' => Hash::make('Password123'),
+            'is_active' => false,
+        ]);
+
+        $response = $this->postJson('/api/login', [
+            'email' => $user->email,
+            'password' => 'Password123',
+        ]);
+
+        $response->assertForbidden()->assertJson([
+            'message' => '用户已停用',
+        ]);
+    }
+
+    public function test_database_seeder_creates_root_user(): void
+    {
+        $this->seed();
+
+        $root = User::whereEmail('root@example.com')->first();
+
+        $this->assertNotNull($root);
+        $this->assertEquals('root', $root->name);
+        $this->assertTrue($root->is_active);
+        $this->assertTrue(Hash::check('Root@123456', $root->password));
+    }
+}