@stephen-lord/docs 1.0.0 → 1.0.1

package/dist-repo/fastapi-backend/src/config/settings.py

@@ -0,0 +1,206 @@
+import json
+import os
+import secrets
+
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=True,
+        extra="ignore",
+    )
+
+    # ==================== 应用配置 ====================
+    VERSION: str = "0.0.1"
+    APP_TITLE: str
+    PROJECT_NAME: str
+    APP_DESCRIPTION: str
+    APP_ENV: str = "development"
+    DEBUG: bool = True
+
+    # ==================== 安全配置 ====================
+    SECRET_KEY: str = Field(default_factory=lambda: secrets.token_urlsafe(32))
+    JWT_ALGORITHM: str = "HS256"
+    JWT_ACCESS_TOKEN_EXPIRE_MINUTES: int = 240
+    JWT_REFRESH_TOKEN_EXPIRE_DAYS: int = 7
+
+    # ==================== 数据库配置 ====================
+    DB_ENGINE: str
+    DB_HOST: str
+    DB_PORT: int | None = Field(default=None, validate_default=True)
+    DB_USER: str = "postgres"
+    DB_PASSWORD: str = ""
+    DB_NAME: str
+
+    # ==================== CORS配置 ====================
+    CORS_ORIGINS: str = "http://localhost:3000,http://localhost:8080"
+    CORS_ALLOW_CREDENTIALS: bool = True
+    CORS_ALLOW_METHODS: list = ["GET", "POST", "PUT", "DELETE", "OPTIONS"]
+    CORS_ALLOW_HEADERS: list = ["Content-Type", "Authorization", "X-Requested-With"]
+
+    # ==================== Swagger配置 ====================
+    SWAGGER_UI_USERNAME: str = "admin"
+    SWAGGER_UI_PASSWORD: str = ""
+
+    # ==================== Redis配置 ====================
+    REDIS_URL: str = "redis://localhost:6379/0"
+    CACHE_TTL: int = 3600
+
+    # ==================== 其他配置 ====================
+    DATETIME_FORMAT: str = "%Y-%m-%d %H:%M:%S"
+    COMPANY_ROLE_MAPPING: dict[str, list[int]] = {"default": []}
+
+    # ==================== 路径配置 ====================
+    @property
+    def PROJECT_ROOT(self) -> str:
+        return os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir))
+
+    @property
+    def BASE_DIR(self) -> str:
+        return os.path.abspath(os.path.join(self.PROJECT_ROOT, os.pardir))
+
+    @property
+    def LOGS_ROOT(self) -> str:
+        return os.path.join(self.BASE_DIR, "app/logs")
+
+    @property
+    def CORS_ORIGINS_LIST(self) -> list[str]:
+        """将CORS_ORIGINS字符串转换为列表"""
+        return [origin.strip() for origin in self.CORS_ORIGINS.split(",")]
+
+    @property
+    def TORTOISE_ORM(self) -> dict:
+        """动态生成Tortoise ORM配置"""
+        if self.DB_ENGINE == "postgres":
+            return {
+                "connections": {
+                    "default": {
+                        "engine": "tortoise.backends.asyncpg",
+                        "credentials": {
+                            "host": self.DB_HOST,
+                            "port": self.DB_PORT,
+                            "user": self.DB_USER,
+                            "password": self.DB_PASSWORD,
+                            "database": self.DB_NAME,
+                            # 连接池配置
+                            "minsize": 1,
+                            "maxsize": 20,
+                            "max_queries": 50000,
+                            "max_inactive_connection_lifetime": 900,
+                            "timeout": 60,
+                            "command_timeout": 60,
+                        },
+                    }
+                },
+                "apps": {
+                    "models": {
+                        "models": [
+                            "aerich.models",
+                            "api.api.model",
+                            "api.auditlog.model",
+                            "api.dept.model",
+                            "api.file.model",
+                            "api.menu.model",
+                            "api.role.model",
+                            "api.user.model",
+                        ],
+                        "default_connection": "default",
+                    },
+                },
+                "use_tz": False,
+                "timezone": "Asia/Shanghai",
+            }
+        else:
+            # SQLite fallback configuration
+            return {
+                "connections": {
+                    "default": {
+                        "engine": "tortoise.backends.sqlite",
+                        "credentials": {"file_path": f"{self.BASE_DIR}/db.sqlite3"},
+                    }
+                },
+                "apps": {
+                    "models": {
+                        "models": ["models", "aerich.models"],
+                        "default_connection": "default",
+                    },
+                },
+                "use_tz": False,
+                "timezone": "Asia/Shanghai",
+            }
+
+    # ==================== 验证器 ====================
+    @field_validator("DB_PORT", mode="before")
+    @classmethod
+    def validate_db_port(cls, v):
+        if v == "" or v is None:
+            return None
+        try:
+            return int(v)
+        except (ValueError, TypeError):
+            return 5432
+
+    @field_validator("COMPANY_ROLE_MAPPING", mode="before")
+    @classmethod
+    def parse_company_role_mapping(cls, v):
+        """解析 COMPANY_ROLE_MAPPING 环境变量"""
+        if isinstance(v, str):
+            try:
+                return json.loads(v)
+            except json.JSONDecodeError:
+                return {"default": []}
+        return v
+
+    @field_validator("DB_PASSWORD")
+    @classmethod
+    def validate_db_password(cls, v):
+        """验证数据库密码"""
+        # 测试和开发环境允许空密码
+        if not v and os.getenv("APP_ENV") == "production":
+            raise ValueError("生产环境必须设置数据库密码")
+        return v
+
+    @field_validator("SECRET_KEY")
+    @classmethod
+    def validate_secret_key(cls, v):
+        """验证SECRET_KEY强度"""
+        if len(v) < 32:
+            raise ValueError("SECRET_KEY长度至少32字符")
+        return v
+
+    @field_validator("SWAGGER_UI_PASSWORD")
+    @classmethod
+    def validate_swagger_password(cls, v):
+        """验证Swagger访问密码"""
+        # 测试环境允许空密码
+        if os.getenv("APP_ENV") == "testing":
+            return v or "test_password"
+        if not v:
+            raise ValueError("SWAGGER_UI_PASSWORD必须设置")
+        if len(v) < 8:
+            raise ValueError("Swagger访问密码长度至少8位")
+        return v
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        # 额外的环境特定验证
+        if self.APP_ENV == "production":
+            self._validate_production_config()
+
+    def _validate_production_config(self):
+        """生产环境特定配置验证"""
+        if self.DEBUG:
+            raise ValueError("生产环境不能启用DEBUG模式")
+
+        if self.DB_ENGINE == "sqlite":
+            raise ValueError("生产环境建议使用PostgreSQL而非SQLite")
+
+        if "localhost" in self.CORS_ORIGINS:
+            raise ValueError("生产环境不应允许localhost的CORS访问")
+
+
+settings = Settings()

package/dist-repo/fastapi-backend/src/core/contexts/constant.py

@@ -0,0 +1,14 @@
+from contextvars import ContextVar
+
+from starlette.background import BackgroundTasks
+
+# 延迟导入，避免循环导入
+# from log import logger
+
+# 上下文变量
+request_id_var: ContextVar[str] = ContextVar("request_id", default="-")
+user_id_var: ContextVar[str] = ContextVar("user_id", default="-")
+
+
+CTX_USER_ID: ContextVar[int] = ContextVar("user_id", default=0)
+CTX_BG_TASKS: ContextVar[BackgroundTasks] = ContextVar("bg_task", default=None)

package/dist-repo/fastapi-backend/src/core/contexts/log_context.py

@@ -0,0 +1,57 @@
+"""
+日志上下文管理器
+提供请求追踪和用户关联功能
+"""
+
+import uuid
+
+from .constant import request_id_var, user_id_var
+
+
+class LogContext:
+    """日志上下文管理器"""
+
+    @staticmethod
+    def generate_request_id() -> str:
+        """生成唯一请求ID"""
+        return str(uuid.uuid4())[:8]
+
+    @staticmethod
+    def set_request_id(request_id: str | None = None) -> str:
+        """设置请求ID"""
+        if not request_id:
+            request_id = LogContext.generate_request_id()
+        request_id_var.set(request_id)
+        return request_id
+
+    @staticmethod
+    def set_user_id(user_id: str | None) -> None:
+        """设置用户ID"""
+        user_id_var.set(str(user_id) if user_id else "-")
+
+    @staticmethod
+    def get_request_id() -> str:
+        """获取当前请求ID"""
+        return request_id_var.get()
+
+    @staticmethod
+    def get_user_id() -> str:
+        """获取当前用户ID"""
+        return user_id_var.get()
+
+    @staticmethod
+    def get_logger():
+        """获取带上下文的logger"""
+        # 延迟导入避免循环导入
+        from log.log import logger
+
+        return logger.bind(
+            request_id=LogContext.get_request_id(),
+            user_id=LogContext.get_user_id(),
+        )
+
+    @staticmethod
+    def clear():
+        """清除上下文"""
+        request_id_var.set("-")
+        user_id_var.set("-")

package/dist-repo/fastapi-backend/src/core/contexts/request_log_context.py

@@ -0,0 +1,28 @@
+from .constant import request_id_var, user_id_var
+from .log_context import LogContext
+
+
+class RequestLogContext:
+    """请求级别的日志上下文管理器"""
+
+    def __init__(self, request_id: str | None = None, user_id: str | None = None):
+        self.request_id = request_id
+        self.user_id = user_id
+        self.old_request_id = None
+        self.old_user_id = None
+
+    def __enter__(self):
+        # 保存旧值
+        self.old_request_id = LogContext.get_request_id()
+        self.old_user_id = LogContext.get_user_id()
+
+        # 设置新值
+        LogContext.set_request_id(self.request_id)
+        LogContext.set_user_id(self.user_id)
+
+        return LogContext.get_logger()
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        # 恢复旧值
+        request_id_var.set(self.old_request_id)
+        user_id_var.set(self.old_user_id)

package/dist-repo/fastapi-backend/src/core/contexts/utils.py

@@ -0,0 +1,13 @@
+# 便捷函数
+def get_context_logger():
+    from core.contexts import LogContext
+
+    """获取带上下文的logger"""
+    return LogContext.get_logger()
+
+
+def with_request_context(request_id: str | None = None, user_id: str | None = None):
+    """创建请求上下文管理器"""
+    from core.contexts import RequestLogContext
+
+    return RequestLogContext(request_id, user_id)

package/dist-repo/fastapi-backend/src/core/dependencies/auth_dependency.py

@@ -0,0 +1,210 @@
+import re
+import secrets
+from typing import TYPE_CHECKING, Any
+
+import jwt
+from fastapi import Depends, HTTPException, Request, status
+from fastapi.security import HTTPBasic, HTTPBasicCredentials, HTTPBearer
+
+from config.settings import settings
+from core.contexts.constant import CTX_USER_ID
+
+# 避免在模块级别导入模型
+# 使用TYPE_CHECKING可以保持类型提示而不实际导入
+if TYPE_CHECKING:
+    from api.role.model import Role
+
+security = HTTPBasic()
+bearer_scheme = HTTPBearer()
+
+
+def get_current_username(
+    credentials: HTTPBasicCredentials = Depends(security),
+):
+    correct_username = secrets.compare_digest(
+        credentials.username, settings.SWAGGER_UI_USERNAME
+    )
+    correct_password = secrets.compare_digest(
+        credentials.password, settings.SWAGGER_UI_PASSWORD
+    )
+    if not (correct_username and correct_password):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Authentication Required",
+            headers={"WWW-Authenticate": "Basic"},
+        )
+    return credentials.username
+
+
+class AuthControl:
+    @classmethod
+    async def is_authed(cls, token: str = Depends(bearer_scheme)) -> Any | None:
+        # Depends(bearer_scheme) 如果没有Bear token, 返回直接是 Fail(code=403, msg="Not authenticated")
+        # 不会进入到这个函数内的逻辑
+        try:
+            # 延迟导入 User 模型
+            from api.user.model import User
+
+            # 直接使用 HTTPBearer 提供的 token (已经去掉了 Bearer 前缀)
+            if not token:
+                raise HTTPException(
+                    status_code=401, detail="Missing authentication token"
+                )
+
+            decode_data = jwt.decode(
+                token.credentials,
+                settings.SECRET_KEY,
+                algorithms=settings.JWT_ALGORITHM,
+            )
+            user_id = decode_data.get("user_id")
+            user = await User.filter(id=user_id).first()
+            if not user:
+                raise HTTPException(status_code=401, detail="Authentication failed")
+            CTX_USER_ID.set(int(user_id))
+            return user
+        except jwt.DecodeError as e:
+            raise HTTPException(status_code=401, detail="无效的Token") from e
+        except jwt.ExpiredSignatureError as e:
+            raise HTTPException(status_code=401, detail="登录已过期") from e
+        except Exception as e:
+            # 记录详细错误信息到日志，但不返回给用户
+            raise HTTPException(status_code=401, detail="认证失败") from e
+
+
+class PermissionControl:
+    @classmethod
+    async def has_permission(
+        cls,
+        request: Request,
+        current_user: Any = Depends(AuthControl.is_authed),
+    ) -> None:
+        """检查用户是否有访问指定API的权限
+
+        Args:
+            request: FastAPI请求对象
+            current_user: 当前认证用户
+
+        Raises:
+            HTTPException: 当用户无权限时抛出403错误
+        """
+        # 延迟导入 Role 模型
+        from api.role.model import Role
+
+        if current_user.is_superuser:
+            return
+
+        method = request.method
+        path = request.url.path
+        roles: list[Role] = await current_user.roles.all()
+
+        if not roles:
+            raise HTTPException(
+                status_code=403, detail="The user is not bound to a role"
+            )
+
+        # 获取用户所有角色的API权限
+        apis = [await role.apis.all() for role in roles]
+        permission_apis = [(api.method, api.path) for api in sum(apis, [])]
+
+        # 检查权限匹配（支持路径参数）
+        for perm_method, perm_path in permission_apis:
+            if method == perm_method:
+                # 将路径参数占位符转换为正则表达式
+                # 例如: /api/v1/agent/{agent_id} -> /api/v1/agent/[^/]+
+                pattern = re.sub(r"\{[^}]+\}", r"[^/]+", perm_path)
+                pattern = f"^{pattern}$"
+                if re.match(pattern, path):
+                    return
+
+        raise HTTPException(
+            status_code=403,
+            detail=f"Permission denied method:{method} path:{path}",
+        )
+
+
+class AgentPermissionControl:
+    """智能体权限控制类"""
+
+    @classmethod
+    async def has_agent_permission(
+        cls,
+        request: Request,
+        current_user: Any = Depends(AuthControl.is_authed),
+    ) -> Any:
+        """检查用户是否有访问智能体的权限
+
+        Args:
+            request: FastAPI请求对象
+            current_user: 当前认证用户
+
+        Returns:
+            Any: 当前用户对象
+
+        Raises:
+            HTTPException: 当用户无权限时抛出403错误
+        """
+        # 超级管理员拥有所有权限
+        if current_user.is_superuser:
+            return current_user
+
+        # 从URL路径中提取agent_id
+        path_params = request.path_params
+        agent_id = path_params.get("agent_id")
+
+        if not agent_id:
+            raise HTTPException(status_code=400, detail="缺少智能体ID参数")
+
+        try:
+            agent_id = int(agent_id)
+        except (ValueError, TypeError) as e:
+            raise HTTPException(status_code=400, detail="无效的智能体ID") from e
+
+        # 获取用户角色
+        roles: list[Role] = await current_user.roles.all()
+        if not roles:
+            raise HTTPException(
+                status_code=403, detail="用户未绑定角色，无权限访问智能体"
+            )
+
+        # 检查用户角色是否有权限访问该智能体
+        for role in roles:
+            role_agents = await role.agents.all()
+            if any(agent.id == agent_id for agent in role_agents):
+                return current_user
+
+        raise HTTPException(status_code=403, detail="无权限访问该智能体")
+
+    @classmethod
+    async def filter_agents_by_permission(
+        cls,
+        current_user: Any = Depends(AuthControl.is_authed),
+    ) -> set[int]:
+        """获取用户有权限访问的智能体ID集合
+
+        Args:
+            current_user: 当前认证用户
+
+        Returns:
+            set[int]: 用户有权限访问的智能体ID集合，超级管理员返回空集合表示无限制
+        """
+        # 超级管理员拥有所有权限，返回空集合表示无限制
+        if current_user.is_superuser:
+            return set()
+
+        # 获取用户角色关联的所有智能体ID
+        roles: list[Role] = await current_user.roles.all()
+        if not roles:
+            return set()  # 没有角色，返回空集合
+
+        allowed_agent_ids = set()
+        for role in roles:
+            role_agents = await role.agents.all()
+            allowed_agent_ids.update(agent.id for agent in role_agents)
+
+        return allowed_agent_ids
+
+
+DependAuth = Depends(AuthControl.is_authed)
+DependPermisson = Depends(PermissionControl.has_permission)
+DependAgentPermission = Depends(AgentPermissionControl.has_agent_permission)
+DependAgentFilter = Depends(AgentPermissionControl.filter_agents_by_permission)

package/dist-repo/fastapi-backend/src/core/exceptions/__init__.py

@@ -0,0 +1,15 @@
+from .does_not_exist_handle import DoesNotExistHandle
+from .http_exc_handle import HttpExcHandle
+from .integrity_handle import IntegrityHandle
+from .request_validation_handle import RequestValidationHandle
+from .response_validation_handle import ResponseValidationHandle
+from .setting_not_found import SettingNotFound
+
+__all__ = [
+    "DoesNotExistHandle",
+    "HttpExcHandle",
+    "IntegrityHandle",
+    "RequestValidationHandle",
+    "ResponseValidationHandle",
+    "SettingNotFound",
+]

package/dist-repo/fastapi-backend/src/core/exceptions/does_not_exist_handle.py

@@ -0,0 +1,16 @@
+from fastapi import Request
+from fastapi.responses import JSONResponse
+from tortoise.exceptions import DoesNotExist
+
+from config.settings import settings
+
+
+async def DoesNotExistHandle(req: Request, exc: DoesNotExist) -> JSONResponse:
+    # 根据环境决定错误信息详细程度
+    if settings.DEBUG:
+        msg = f"Object not found: {exc}, query_params: {req.query_params}"
+    else:
+        msg = "请求的资源不存在"
+
+    content = {"code": 404, "msg": msg}
+    return JSONResponse(content=content, status_code=404)

package/dist-repo/fastapi-backend/src/core/exceptions/http_exc_handle.py

@@ -0,0 +1,12 @@
+from fastapi import HTTPException, Request
+from fastapi.responses import JSONResponse
+from starlette.responses import Response
+
+
+async def HttpExcHandle(request: Request, exc: HTTPException):
+    if exc.status_code == 401 and exc.headers and "WWW-Authenticate" in exc.headers:
+        return Response(status_code=exc.status_code, headers=exc.headers)
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={"code": exc.status_code, "msg": exc.detail, "data": None},
+    )

package/dist-repo/fastapi-backend/src/core/exceptions/integrity_handle.py

@@ -0,0 +1,16 @@
+from fastapi import Request
+from fastapi.responses import JSONResponse
+from tortoise.exceptions import IntegrityError
+
+from config.settings import settings
+
+
+async def IntegrityHandle(request: Request, exc: IntegrityError):
+    # 根据环境决定错误信息详细程度
+    if settings.DEBUG:
+        msg = f"IntegrityError: {exc}"
+    else:
+        msg = "数据完整性错误，请检查输入数据"
+
+    content = {"code": 500, "msg": msg}
+    return JSONResponse(content=content, status_code=500)

package/dist-repo/fastapi-backend/src/core/exceptions/request_validation_handle.py

@@ -0,0 +1,18 @@
+from fastapi import Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+
+from config.settings import settings
+
+
+async def RequestValidationHandle(
+    _: Request, exc: RequestValidationError
+) -> JSONResponse:
+    # 根据环境决定错误信息详细程度
+    if settings.DEBUG:
+        msg = f"RequestValidationError: {exc}"
+    else:
+        msg = "请求参数验证失败，请检查输入格式"
+
+    content = {"code": 422, "msg": msg}
+    return JSONResponse(content=content, status_code=422)

package/dist-repo/fastapi-backend/src/core/exceptions/response_validation_handle.py

@@ -0,0 +1,18 @@
+from fastapi import Request
+from fastapi.exceptions import ResponseValidationError
+from fastapi.responses import JSONResponse
+
+from config.settings import settings
+
+
+async def ResponseValidationHandle(
+    _: Request, exc: ResponseValidationError
+) -> JSONResponse:
+    # 根据环境决定错误信息详细程度
+    if settings.DEBUG:
+        msg = f"ResponseValidationError: {exc}"
+    else:
+        msg = "服务器响应格式错误"
+
+    content = {"code": 500, "msg": msg}
+    return JSONResponse(content=content, status_code=500)

package/dist-repo/fastapi-backend/src/core/exceptions/setting_not_found.py

@@ -0,0 +1,2 @@
+class SettingNotFound(Exception):
+    pass