@stephen-lord/docs 1.0.0 → 1.0.1

package/dist-repo/fastapi-backend/src/api/base/__init__.py

@@ -0,0 +1,8 @@
+from fastapi import APIRouter
+
+from .controller import limiter, router
+
+base_router = APIRouter()
+base_router.include_router(router, tags=["基础模块"])
+
+__all__ = ["base_router", "limiter"]

package/dist-repo/fastapi-backend/src/api/base/controller.py

@@ -0,0 +1,179 @@
+import os
+from datetime import UTC, datetime
+
+from fastapi import APIRouter, Request
+from slowapi import Limiter
+from slowapi.util import get_remote_address
+
+from api.user.model import User
+from api.user.repository import user_repository
+from api.user.schema import UserInfoVO
+from common.schemas.auth_schema import (
+    CredentialsSchema,
+    JWTOut,
+    RefreshTokenRequest,
+    TokenRefreshOut,
+)
+from common.schemas.response_schema import Fail, Success
+from config.settings import settings
+from core.contexts.constant import CTX_USER_ID
+from core.dependencies.auth_dependency import DependAuth
+from utils.jwt import create_token_pair, verify_token
+
+# 创建限流器实例
+limiter = Limiter(key_func=get_remote_address)
+
+router = APIRouter()
+
+
+def apply_rate_limit(rate="5/minute"):
+    """根据环境应用限流装饰器"""
+
+    def decorator(func):
+        import os
+
+        if os.getenv("TESTING", "false").lower() == "true":
+            return func  # 测试环境不应用限流
+        return limiter.limit(rate)(func)
+
+    return decorator
+
+
+@router.post("/access_token", summary="获取token", response_model=Success[JWTOut])
+@apply_rate_limit()
+async def login_access_token(request: Request, credentials: CredentialsSchema):
+    user: User = await user_repository.authenticate(credentials)
+    await user_repository.update_last_login(user.id)
+
+    # 创建访问令牌和刷新令牌
+    access_token, refresh_token = create_token_pair(user.id)
+
+    data = JWTOut(
+        access_token=access_token,
+        refresh_token=refresh_token,
+        username=user.username,
+        expires_in=settings.JWT_ACCESS_TOKEN_EXPIRE_MINUTES * 60,
+    )
+    return Success(data=data.model_dump())
+
+
+@router.post(
+    "/refresh_token", summary="刷新token", response_model=Success[TokenRefreshOut]
+)
+@apply_rate_limit("10/minute")
+async def refresh_access_token(request: Request, refresh_request: RefreshTokenRequest):
+    """
+    使用刷新令牌获取新的访问令牌和刷新令牌
+    """
+    try:
+        # 验证刷新令牌
+        payload = verify_token(refresh_request.refresh_token, token_type="refresh")
+
+        # 验证用户是否仍然存在且有效
+        user = await user_repository.get(id=payload.user_id)
+        if not user or not user.is_active:
+            return Fail(code=401, msg="用户不存在或已被禁用")
+
+        # 创建新的令牌对
+        access_token, refresh_token = create_token_pair(user_id=user.id)
+
+        data = TokenRefreshOut(
+            access_token=access_token,
+            refresh_token=refresh_token,
+            expires_in=settings.JWT_ACCESS_TOKEN_EXPIRE_MINUTES * 60,
+        )
+
+        return Success(data=data.model_dump())
+
+    except Exception:
+        return Fail(code=401, msg="令牌无效或已过期")
+
+
+@router.get("/userinfo", summary="查看用户信息", response_model=Success[UserInfoVO])
+async def get_userinfo(current_user: User = DependAuth):
+    user_id = CTX_USER_ID.get()
+    user_obj = await user_repository.get(id=user_id)
+    user_dict = await user_obj.to_dict(m2m=True, exclude_fields=["password"])
+    return Success(data=user_dict)
+
+
+@router.get("/health", summary="健康检查")
+async def health_check():
+    """系统健康检查"""
+    return {
+        "status": "healthy",
+        "timestamp": datetime.now(UTC).isoformat(),
+        "version": settings.VERSION,
+        "environment": settings.APP_ENV,
+        "service": "FastAPI Backend Template",
+    }
+
+
+@router.get("/version", summary="版本信息")
+async def get_version():
+    """获取API版本信息"""
+    return {
+        "version": settings.VERSION,
+        "app_title": settings.APP_TITLE,
+        "project_name": settings.PROJECT_NAME,
+        "build": os.getenv("BUILD_NUMBER", "dev"),
+        "commit": os.getenv("GIT_COMMIT", "unknown"),
+        "python_version": os.getenv("PYTHON_VERSION", "3.11+"),
+    }
+
+
+# @router.get("/usermenu", summary="查看用户菜单", dependencies=[DependAuth])
+# async def get_user_menu():
+#     user_id = CTX_USER_ID.get()
+#     user_obj = await User.filter(id=user_id).first()
+#     menus: list[Menu] = []
+#     if user_obj.is_superuser:
+#         menus = await Menu.all()
+#     else:
+#         role_objs: list[Role] = await user_obj.roles
+#         for role_obj in role_objs:
+#             menu = await role_obj.menus
+#             menus.extend(menu)
+#         menus = list(set(menus))
+#     parent_menus: list[Menu] = []
+#     for menu in menus:
+#         if menu.parent_id == 0:
+#             parent_menus.append(menu)
+#     res = []
+#     for parent_menu in parent_menus:
+#         parent_menu_dict = await parent_menu.to_dict()
+#         parent_menu_dict["children"] = []
+#         for menu in menus:
+#             if menu.parent_id == parent_menu.id:
+#                 parent_menu_dict["children"].append(await menu.to_dict())
+#         res.append(parent_menu_dict)
+#     return Success(data=res)
+
+
+# @router.get("/userapi", summary="查看用户API", dependencies=[DependAuth])
+# async def get_user_api():
+#     user_id = CTX_USER_ID.get()
+#     user_obj = await User.filter(id=user_id).first()
+#     if user_obj.is_superuser:
+#         api_objs: list[Api] = await Api.all()
+#         apis = [api.method.lower() + api.path for api in api_objs]
+#         return Success(data=apis)
+#     role_objs: list[Role] = await user_obj.roles
+#     apis = []
+#     for role_obj in role_objs:
+#         api_objs: list[Api] = await role_obj.apis
+#         apis.extend([api.method.lower() + api.path for api in api_objs])
+#     apis = list(set(apis))
+#     return Success(data=apis)
+
+
+# @router.post("/update_password", summary="修改密码", dependencies=[DependAuth])
+# async def update_user_password(req_in: UpdatePassword):
+#     user_id = CTX_USER_ID.get()
+#     user = await user_controller.get(user_id)
+#     verified = verify_password(req_in.old_password, user.password)
+#     if not verified:
+#         return Fail(msg="旧密码验证错误！")
+#     user.password = get_password_hash(req_in.new_password)
+#     await user.save()
+#     return Success(msg="修改成功")

package/dist-repo/fastapi-backend/src/api/base/service.py

@@ -0,0 +1,259 @@
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from fastapi import HTTPException
+from tortoise.expressions import Q
+from tortoise.models import Model
+
+from api.role.model import Role
+from api.user.model import User
+from common.repositories import CRUDBase
+from common.schemas.response_schema import Fail, Success, SuccessPagination
+from log import logger
+
+T = TypeVar("T", bound=Model)
+
+
+class BaseService:
+    """基础服务类 - 统一公共逻辑"""
+
+    def __init__(self, repository: CRUDBase):
+        self.repository = repository
+        self.logger = logger
+
+    async def get_paginated_list(
+        self,
+        page: int = 1,
+        page_size: int = 10,
+        search_filters: Q | None = None,
+        order: list[str] | None = None,
+        exclude_fields: list[str] | None = None,
+        include_m2m: bool = False,
+        transform_func: Callable | None = None,
+    ) -> SuccessPagination:
+        """获取分页列表 - 统一版本
+
+        Args:
+            page: 页码
+            page_size: 每页数量
+            search_filters: 搜索条件
+            order: 排序字段
+            exclude_fields: 排除字段
+            include_m2m: 是否包含多对多关系
+            transform_func: 数据转换函数
+
+        Returns:
+            SuccessPagination: 分页响应
+        """
+        try:
+            total, items = await self.repository.list(
+                page=page,
+                page_size=page_size,
+                search=search_filters or Q(),
+                order=order or ["-created_at"],
+            )
+
+            # 转换数据
+            if transform_func:
+                data = await transform_func(items)
+            else:
+                data = [
+                    await item.to_dict(
+                        m2m=include_m2m, exclude_fields=exclude_fields or []
+                    )
+                    for item in items
+                ]
+
+            return SuccessPagination(
+                data=data, total=total, page=page, page_size=page_size
+            )
+
+        except Exception as e:
+            self.logger.error(f"获取分页列表失败: {str(e)}")
+            return Fail(msg="获取列表失败")
+
+    async def get_by_id(
+        self,
+        item_id: int,
+        exclude_fields: list[str] | None = None,
+        include_m2m: bool = False,
+        not_found_msg: str = "记录不存在",
+    ) -> Success:
+        """根据ID获取单个记录
+
+        Args:
+            item_id: 记录ID
+            exclude_fields: 排除字段
+            include_m2m: 是否包含多对多关系
+            not_found_msg: 未找到时的错误消息
+
+        Returns:
+            Success: 成功响应
+        """
+        try:
+            item = await self.repository.get(item_id)
+            if not item:
+                raise HTTPException(status_code=404, detail=not_found_msg)
+
+            data = await item.to_dict(
+                m2m=include_m2m, exclude_fields=exclude_fields or []
+            )
+            return Success(data=data)
+
+        except HTTPException:
+            raise
+        except Exception as e:
+            self.logger.error(f"获取记录失败: {str(e)}")
+            return Fail(msg="获取记录失败")
+
+    async def create_item(
+        self,
+        item_data: dict[str, Any],
+        success_msg: str = "创建成功",
+        exclude_fields: list[str] | None = None,
+    ) -> Success:
+        """创建记录
+
+        Args:
+            item_data: 创建数据
+            success_msg: 成功消息
+            exclude_fields: 排除字段
+
+        Returns:
+            Success: 成功响应
+        """
+        try:
+            item = await self.repository.create(item_data)
+            data = await item.to_dict(exclude_fields=exclude_fields or [])
+            return Success(data=data, msg=success_msg)
+
+        except Exception as e:
+            self.logger.error(f"创建记录失败: {str(e)}")
+            return Fail(msg="创建失败")
+
+    async def update_item(
+        self,
+        item_id: int,
+        item_data: dict[str, Any],
+        success_msg: str = "更新成功",
+        not_found_msg: str = "记录不存在",
+        exclude_fields: list[str] | None = None,
+    ) -> Success:
+        """更新记录
+
+        Args:
+            item_id: 记录ID
+            item_data: 更新数据
+            success_msg: 成功消息
+            not_found_msg: 未找到消息
+            exclude_fields: 排除字段
+
+        Returns:
+            Success: 成功响应
+        """
+        try:
+            item = await self.repository.get(item_id)
+            if not item:
+                raise HTTPException(status_code=404, detail=not_found_msg)
+
+            updated_item = await self.repository.update(item_id, item_data)
+            data = await updated_item.to_dict(exclude_fields=exclude_fields or [])
+            return Success(data=data, msg=success_msg)
+
+        except HTTPException:
+            raise
+        except Exception as e:
+            self.logger.error(f"更新记录失败: {str(e)}")
+            return Fail(msg="更新失败")
+
+    async def delete_item(
+        self,
+        item_id: int,
+        success_msg: str = "删除成功",
+        not_found_msg: str = "记录不存在",
+    ) -> Success:
+        """删除记录
+
+        Args:
+            item_id: 记录ID
+            success_msg: 成功消息
+            not_found_msg: 未找到消息
+
+        Returns:
+            Success: 成功响应
+        """
+        try:
+            item = await self.repository.get(item_id)
+            if not item:
+                raise HTTPException(status_code=404, detail=not_found_msg)
+
+            await self.repository.remove(item_id)
+            return Success(msg=success_msg)
+
+        except HTTPException:
+            raise
+        except Exception as e:
+            self.logger.error(f"删除记录失败: {str(e)}")
+            return Fail(msg="删除失败")
+
+
+class PermissionService:
+    """权限服务 - 统一权限检查逻辑"""
+
+    @staticmethod
+    async def check_superuser(
+        user: User, error_msg: str = "权限不足，需要超级管理员权限"
+    ):
+        """检查超级管理员权限"""
+        if not user.is_superuser:
+            return Fail(code=403, msg=error_msg)
+        return None
+
+    @staticmethod
+    async def get_user_agent_ids(user: User) -> set:
+        """获取用户有权限的智能体ID集合"""
+        if user.is_superuser:
+            return set()  # 超级管理员无限制
+
+        # 预加载角色的 agents 关系，避免 N+1 查询
+        roles: list[Role] = await user.roles.all().prefetch_related("agents")
+        if not roles:
+            return set()
+
+        allowed_agent_ids = set()
+        for role in roles:
+            # agents 已经预加载到内存，不会触发额外查询
+            allowed_agent_ids.update(agent.id for agent in role.agents)
+
+        return allowed_agent_ids
+
+    @staticmethod
+    def build_search_filters(
+        keyword: str | None = None,
+        search_fields: list[str] | None = None,
+        extra_filters: dict[str, Any] | None = None,
+    ) -> Q:
+        """构建搜索过滤条件"""
+        filters = Q()
+
+        # 关键词搜索
+        if keyword and search_fields:
+            keyword_filters = Q()
+            for field in search_fields:
+                keyword_filters |= Q(**{f"{field}__icontains": keyword})
+            filters &= keyword_filters
+
+        # 额外过滤条件
+        if extra_filters:
+            for field, value in extra_filters.items():
+                if value is not None:
+                    if field.endswith("__icontains"):
+                        filters &= Q(**{field: value})
+                    else:
+                        filters &= Q(**{field: value})
+
+        return filters
+
+
+# 全局实例
+permission_service = PermissionService()

package/dist-repo/fastapi-backend/src/api/dept/__init__.py

@@ -0,0 +1,8 @@
+from fastapi import APIRouter
+
+from .controller import router
+
+dept_router = APIRouter()
+dept_router.include_router(router, tags=["部门模块"])
+
+__all__ = ["dept_router"]

package/dist-repo/fastapi-backend/src/api/dept/controller.py

@@ -0,0 +1,49 @@
+from fastapi import APIRouter, Query
+
+from common.schemas.response_schema import Success
+
+from .repository import dept_repository
+from .schema import DeptCreateDTO, DeptUpdateDTO, DeptVO
+
+router = APIRouter()
+
+
+@router.get("/list", summary="查看部门列表", response_model=Success[list[DeptVO]])
+async def list_dept(
+    name: str = Query(None, description="部门名称"),
+):
+    dept_tree = await dept_repository.get_dept_tree(name)
+    return Success(data=dept_tree)
+
+
+@router.get("/get", summary="查看部门", response_model=Success[DeptVO])
+async def get_dept(
+    id: int = Query(..., description="部门ID"),
+):
+    dept_obj = await dept_repository.get(id=id)
+    data = await dept_obj.to_dict()
+    return Success(data=data)
+
+
+@router.post("/create", summary="创建部门", response_model=Success[None])
+async def create_dept(
+    dept_in: DeptCreateDTO,
+):
+    await dept_repository.create_dept(obj_in=dept_in)
+    return Success(msg="Created Successfully")
+
+
+@router.post("/update", summary="更新部门", response_model=Success[None])
+async def update_dept(
+    dept_in: DeptUpdateDTO,
+):
+    await dept_repository.update_dept(obj_in=dept_in)
+    return Success(msg="Update Successfully")
+
+
+@router.delete("/delete", summary="删除部门", response_model=Success[None])
+async def delete_dept(
+    dept_id: int = Query(..., description="部门ID"),
+):
+    await dept_repository.delete_dept(dept_id=dept_id)
+    return Success(msg="Deleted Success")

package/dist-repo/fastapi-backend/src/api/dept/model.py

@@ -0,0 +1,24 @@
+from tortoise import fields
+
+from common.models import BaseModel, TimestampModel
+
+
+class Dept(BaseModel, TimestampModel):
+    name = fields.CharField(
+        max_length=20, unique=True, description="部门名称", db_index=True
+    )
+    desc = fields.CharField(max_length=500, null=True, description="备注")
+    is_deleted = fields.BooleanField(
+        default=False, description="软删除标记", db_index=True
+    )
+    order = fields.IntField(default=0, description="排序", db_index=True)
+    parent_id = fields.IntField(default=0, description="父部门ID", db_index=True)
+
+    class Meta:
+        table = "dept"
+
+
+class DeptClosure(BaseModel, TimestampModel):
+    ancestor = fields.IntField(description="父代", db_index=True)
+    descendant = fields.IntField(description="子代", db_index=True)
+    level = fields.IntField(default=0, description="深度", db_index=True)

package/dist-repo/fastapi-backend/src/api/dept/repository.py

@@ -0,0 +1,109 @@
+from tortoise.expressions import Q
+from tortoise.transactions import atomic
+
+from common.repositories import CRUDBase
+from log import logger
+
+from .model import Dept, DeptClosure
+from .schema import DeptCreateDTO, DeptUpdateDTO
+
+
+class DeptRepository(CRUDBase[Dept, DeptCreateDTO, DeptUpdateDTO]):
+    def __init__(self):
+        super().__init__(model=Dept)
+
+    async def get_dept_tree(self, name):
+        q = Q()
+        # 获取所有未被软删除的部门 - 只查询需要的字段
+        q &= Q(is_deleted=False)
+        if name:
+            q &= Q(name__contains=name)
+        all_depts = (
+            await self.model.filter(q)
+            .order_by("order")
+            .values("id", "name", "desc", "order", "parent_id")
+        )
+
+        # 辅助函数，用于递归构建部门树
+        def build_tree(parent_id):
+            return [
+                {
+                    "id": dept.id,
+                    "name": dept.name,
+                    "desc": dept.desc,
+                    "order": dept.order,
+                    "parent_id": dept.parent_id,
+                    "children": build_tree(dept.id),  # 递归构建子部门
+                }
+                for dept in all_depts
+                if dept.parent_id == parent_id
+            ]
+
+        # 从顶级部门（parent_id=0）开始构建部门树
+        dept_tree = build_tree(0)
+        return dept_tree
+
+    async def get_dept_info(self):
+        pass
+
+    async def update_dept_closure(self, obj: Dept):
+        parent_depts = await DeptClosure.filter(descendant=obj.parent_id)
+        for i in parent_depts:
+            logger.debug(
+                f"Processing dept closure: ancestor={i.ancestor}, descendant={i.descendant}"
+            )
+        dept_closure_objs: list[DeptClosure] = []
+        # 插入父级关系
+        for item in parent_depts:
+            dept_closure_objs.append(
+                DeptClosure(
+                    ancestor=item.ancestor,
+                    descendant=obj.id,
+                    level=item.level + 1,
+                )
+            )
+        # 插入自身x
+        dept_closure_objs.append(
+            DeptClosure(ancestor=obj.id, descendant=obj.id, level=0)
+        )
+        # 创建关系，使用 batch_size 优化性能
+        await DeptClosure.bulk_create(dept_closure_objs, batch_size=100)
+
+    @atomic()
+    async def create_dept(self, obj_in: DeptCreateDTO):
+        # 创建
+        if obj_in.parent_id != 0:
+            await self.get(id=obj_in.parent_id)
+        new_obj = await self.create(obj_in=obj_in)
+        await self.update_dept_closure(new_obj)
+
+    @atomic()
+    async def update_dept(self, obj_in: DeptUpdateDTO):
+        dept_obj = await self.get(id=obj_in.id)
+
+        # 校验父部门是否存在（如果不是顶级部门）
+        if obj_in.parent_id != 0:
+            parent_exists = await Dept.filter(
+                id=obj_in.parent_id, is_deleted=False
+            ).exists()
+            if not parent_exists:
+                raise ValueError(f"父部门 {obj_in.parent_id} 不存在或已删除")
+
+        # 更新部门关系
+        if dept_obj.parent_id != obj_in.parent_id:
+            await DeptClosure.filter(ancestor=dept_obj.id).delete()
+            await DeptClosure.filter(descendant=dept_obj.id).delete()
+            await self.update_dept_closure(dept_obj)
+        # 更新部门信息
+        dept_obj.update_from_dict(obj_in.model_dump(exclude_unset=True))
+        await dept_obj.save()
+
+    @atomic()
+    async def delete_dept(self, dept_id: int):
+        # 原子操作：软删除部门
+        await self.model.filter(id=dept_id).update(is_deleted=True)
+        # 删除关系
+        await DeptClosure.filter(descendant=dept_id).delete()
+
+
+dept_repository = DeptRepository()

package/dist-repo/fastapi-backend/src/api/dept/schema.py

@@ -0,0 +1,37 @@
+from pydantic import BaseModel, Field
+
+
+class DeptVO(BaseModel):
+    """部门响应模型"""
+
+    id: int
+    name: str = Field(..., description="部门名称", example="研发中心")
+    desc: str = Field("", description="备注", example="研发中心")
+    order: int = Field(0, description="排序")
+    parent_id: int = Field(0, description="父部门ID")
+    created_at: str | None = None
+    updated_at: str | None = None
+
+
+class DeptBaseDTO(BaseModel):
+    """部门基础字段"""
+
+    name: str = Field(..., description="部门名称", example="研发中心")
+    desc: str = Field("", description="备注", example="研发中心")
+    order: int = Field(0, description="排序")
+    parent_id: int = Field(0, description="父部门ID")
+
+
+class DeptCreateDTO(DeptBaseDTO):
+    """创建部门请求参数"""
+
+    pass
+
+
+class DeptUpdateDTO(DeptBaseDTO):
+    """更新部门请求参数"""
+
+    id: int
+
+    def update_dict(self):
+        return self.model_dump(exclude_unset=True, exclude={"id"})

package/dist-repo/fastapi-backend/src/api/file/__init__.py

@@ -0,0 +1,8 @@
+from fastapi import APIRouter
+
+from .controller import router
+
+file_router = APIRouter()
+file_router.include_router(router, tags=["上传文件"])
+
+__all__ = ["file_router"]