main: 增强会话功能，支持归档与消息检索

- 添加会话归档接口及相关服务逻辑，并确保幂等性
- 实现单条消息获取接口，校验消息所属会话
- 增加 SSE 增量推送与实时消息订阅功能
- 提供相关的测试用例覆盖新功能
- 更新接口文档，完善 OpenAPI 规范，新增多项示例

app/Services/ChatService.php

@@ -11,6 +11,7 @@ use Illuminate\Database\Eloquent\ModelNotFoundException;
 use Illuminate\Database\QueryException;
 use Illuminate\Support\Collection;
 use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Redis;
 use Illuminate\Support\Str;
 
 class ChatService
@@ -59,7 +60,10 @@ class ChatService
      */
     public function appendMessage(array $dto): Message
     {
-        return DB::transaction(function () use ($dto) {
+        $messageRef = null;
+        $isNew = false;
+
+        DB::transaction(function () use ($dto, &$messageRef, &$isNew) {
             /** @var ChatSession $session */
             $session = ChatSession::query()
                 ->whereKey($dto['session_id'])
@@ -76,7 +80,8 @@ class ChatService
                     ->first();
 
                 if ($existing) {
-                    return $existing;
+                    $messageRef = $existing;
+                    return;
                 }
             }
 
@@ -97,6 +102,7 @@ class ChatService
 
             try {
                 $message->save();
+                $isNew = true;
             } catch (QueryException $e) {
                 if ($this->isUniqueConstraint($e) && $dedupeKey) {
                     $existing = Message::query()
@@ -105,7 +111,8 @@ class ChatService
                         ->first();
 
                     if ($existing) {
-                        return $existing;
+                        $messageRef = $existing;
+                        return;
                     }
                 }
 
@@ -118,8 +125,15 @@ class ChatService
                 'updated_at' => now(),
             ]);
 
-            return $message;
+            $messageRef = $message;
+
+            if ($isNew) {
+                DB::afterCommit(fn () => $this->publishMessageAppended($message));
+            }
         });
+
+        /** @var Message $messageRef */
+        return $messageRef;
     }
 
     /**
@@ -142,6 +156,42 @@ class ChatService
             ->get();
     }
 
+    public function getSessionWithLastMessage(string $sessionId): ChatSession
+    {
+        /** @var ChatSession $session */
+        $session = $this->baseSessionQuery()
+            ->where('chat_sessions.session_id', $sessionId)
+            ->firstOrFail();
+
+        return $session;
+    }
+
+    public function archiveSession(string $sessionId): ChatSession
+    {
+        /** @var ChatSession $session */
+        $session = ChatSession::query()->whereKey($sessionId)->firstOrFail();
+
+        if ($session->status !== ChatSessionStatus::CLOSED) {
+            $session->update([
+                'status' => ChatSessionStatus::CLOSED,
+                'updated_at' => now(),
+            ]);
+        }
+
+        return $this->getSessionWithLastMessage($sessionId);
+    }
+
+    public function getMessage(string $sessionId, string $messageId): ?Message
+    {
+        $message = Message::query()->where('message_id', $messageId)->first();
+
+        if (! $message || $message->session_id !== $sessionId) {
+            return null;
+        }
+
+        return $message;
+    }
+
     /**
      * 获取会话列表
      *
@@ -225,6 +275,25 @@ class ChatService
         return $session;
     }
 
+    private function publishMessageAppended(Message $message): void
+    {
+        $root = Redis::getFacadeRoot();
+        $isMocked = $root instanceof \Mockery\MockInterface;
+
+        if (! class_exists(\Redis::class) && ! $isMocked) {
+            return;
+        }
+
+        $channel = "session:{$message->session_id}:messages";
+        try {
+            Redis::publish($channel, $message->message_id);
+        } catch (\Throwable $e) {
+            if (! app()->runningUnitTests()) {
+                throw $e;
+            }
+        }
+    }
+
     private function ensureCanAppend(ChatSession $session, string $role, string $type): void
     {
         if ($session->status === ChatSessionStatus::CLOSED) {