Merge branch 'refactor/backend-architecture' into development

2026-03-18 17:18:23 +08:00
parent 2070a03d35
commit 48b70e1350
266 changed files with 12386 additions and 9690 deletions
--- a/api/app/core/redis.py
+++ b/api/app/core/redis.py
@@ -0,0 +1,151 @@
+"""
+Redis 客户端与会话/缓存能力：供应用生命周期、会话历史、任务追踪等使用。
+配置从 app.core.config.settings 读取，禁止业务层散落 os.getenv。
+"""
+import json
+from app.core.logging import get_logger
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+import redis.asyncio as aioredis
+
+from app.core.config import settings
+
+logger = get_logger(__name__)
+
+
+class RedisService:
+    """Redis 服务：连接管理、对话历史、通用缓存。"""
+
+    def __init__(self) -> None:
+        self.redis_url = settings.redis_url
+        self._client: Optional[aioredis.Redis] = None
+        self.session_ttl = settings.redis_session_ttl
+
+    async def get_client(self) -> aioredis.Redis:
+        """获取 Redis 客户端（延迟初始化）。"""
+        if self._client is None:
+            try:
+                self._client = await aioredis.from_url(
+                    self.redis_url,
+                    encoding="utf-8",
+                    decode_responses=True,
+                )
+                await self._client.ping()
+                logger.info("Redis 连接成功: %s", self.redis_url)
+            except Exception as e:
+                logger.error("Redis 连接失败: %s", e)
+                raise
+        return self._client
+
+    async def close(self) -> None:
+        """关闭 Redis 连接。"""
+        if self._client:
+            await self._client.close()
+            self._client = None
+
+    def _conversation_key(self, conversation_id: str) -> str:
+        return f"conversation:history:{conversation_id}"
+
+    async def get_conversation_history(self, conversation_id: str) -> List[Dict[str, Any]]:
+        try:
+            client = await self.get_client()
+            key = self._conversation_key(conversation_id)
+            data = await client.get(key)
+            if data:
+                return json.loads(data)
+            return []
+        except Exception as e:
+            logger.error("获取对话历史失败: %s", e)
+            return []
+
+    async def add_message(
+        self,
+        conversation_id: str,
+        role: str,
+        content: str,
+        message_type: str = "text",
+        voice_session_id: str | None = None,
+        timestamp: str | int | None = None,
+    ) -> bool:
+        try:
+            client = await self.get_client()
+            key = self._conversation_key(conversation_id)
+            history = await self.get_conversation_history(conversation_id)
+            item = {
+                "role": role,
+                "content": content,
+                "messageType": message_type,
+                "timestamp": timestamp or datetime.now(timezone.utc).isoformat(),
+            }
+            if voice_session_id:
+                item["voiceSessionId"] = voice_session_id
+            history.append(item)
+            await client.setex(key, self.session_ttl, json.dumps(history, ensure_ascii=False))
+            return True
+        except Exception as e:
+            logger.error("添加消息失败: %s", e)
+            return False
+
+    async def clear_conversation_history(self, conversation_id: str) -> bool:
+        try:
+            client = await self.get_client()
+            key = self._conversation_key(conversation_id)
+            await client.delete(key)
+            return True
+        except Exception as e:
+            logger.error("清除对话历史失败: %s", e)
+            return False
+
+    async def extend_session_ttl(self, conversation_id: str) -> bool:
+        try:
+            client = await self.get_client()
+            key = self._conversation_key(conversation_id)
+            await client.expire(key, self.session_ttl)
+            return True
+        except Exception as e:
+            logger.error("延长会话TTL失败: %s", e)
+            return False
+
+    async def set_cache(self, key: str, value: Any, ttl: Optional[int] = None) -> bool:
+        try:
+            client = await self.get_client()
+            data = json.dumps(value, ensure_ascii=False) if not isinstance(value, str) else value
+            if ttl:
+                await client.setex(key, ttl, data)
+            else:
+                await client.set(key, data)
+            return True
+        except Exception as e:
+            logger.error("设置缓存失败: %s", e)
+            return False
+
+    async def get_cache(self, key: str) -> Optional[Any]:
+        try:
+            client = await self.get_client()
+            data = await client.get(key)
+            if data:
+                try:
+                    return json.loads(data)
+                except json.JSONDecodeError:
+                    return data
+            return None
+        except Exception as e:
+            logger.error("获取缓存失败: %s", e)
+            return None
+
+    async def delete_cache(self, key: str) -> bool:
+        try:
+            client = await self.get_client()
+            await client.delete(key)
+            return True
+        except Exception as e:
+            logger.error("删除缓存失败: %s", e)
+            return False
+
+    def is_available(self) -> bool:
+        return self._client is not None
+
+
+# 全局单例，供 main 生命周期与各 feature 通过 get_redis_service 或直接引用使用
+redis_service = RedisService()