@stephen-lord/docs 1.0.0 → 1.0.1

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

@@ -0,0 +1,82 @@
+import logging
+
+from fastapi import APIRouter, Query
+from fastapi.exceptions import HTTPException
+from tortoise.expressions import Q
+
+from api.role.repository import role_repository
+from api.role.schema import (
+    RoleCreateDTO,
+    RoleUpdateDTO,
+    RoleUpdateMenusApisDTO,
+    RoleVO,
+)
+from common.schemas.response_schema import Success, SuccessPagination
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+
+@router.get("/list", summary="查看角色列表", response_model=SuccessPagination[RoleVO])
+async def list_role(
+    page: int = Query(1, description="页码"),
+    page_size: int = Query(10, description="每页数量"),
+    role_name: str = Query("", description="角色名称，用于查询"),
+):
+    q = Q()
+    if role_name:
+        q = Q(name__contains=role_name)
+    total, role_objs = await role_repository.list(
+        page=page, page_size=page_size, search=q
+    )
+    data = [await obj.to_dict() for obj in role_objs]
+    return SuccessPagination(data=data, total=total, page=page, page_size=page_size)
+
+
+@router.get("/get", summary="查看角色", response_model=Success[RoleVO])
+async def get_role(
+    role_id: int = Query(..., description="角色ID"),
+):
+    role_obj = await role_repository.get(id=role_id)
+    return Success(data=await role_obj.to_dict())
+
+
+@router.post("/create", summary="创建角色", response_model=Success[None])
+async def create_role(role_in: RoleCreateDTO):
+    if await role_repository.is_exist(name=role_in.name):
+        raise HTTPException(
+            status_code=400,
+            detail="The role with this rolename already exists in the system.",
+        )
+    await role_repository.create(obj_in=role_in)
+    return Success(msg="Created Successfully")
+
+
+@router.post("/update", summary="更新角色", response_model=Success[None])
+async def update_role(role_in: RoleUpdateDTO):
+    await role_repository.update(id=role_in.id, obj_in=role_in)
+    return Success(msg="Updated Successfully")
+
+
+@router.delete("/delete", summary="删除角色", response_model=Success[None])
+async def delete_role(
+    role_id: int = Query(..., description="角色ID"),
+):
+    await role_repository.remove(id=role_id)
+    return Success(msg="Deleted Success")
+
+
+@router.get("/authorized", summary="查看角色权限", response_model=Success[RoleVO])
+async def get_role_authorized(id: int = Query(..., description="角色ID")):
+    role_obj = await role_repository.get(id=id)
+    data = await role_obj.to_dict(m2m=True)
+    return Success(data=data)
+
+
+@router.post("/authorized", summary="更新角色权限", response_model=Success[None])
+async def update_role_authorized(role_in: RoleUpdateMenusApisDTO):
+    role_obj = await role_repository.get(id=role_in.id)
+    await role_repository.update_roles(
+        role=role_obj, menu_ids=role_in.menu_ids, api_infos=role_in.api_infos
+    )
+    return Success(msg="Updated Successfully")

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

@@ -0,0 +1,19 @@
+from tortoise import fields
+
+from common.models import BaseModel, TimestampModel
+
+
+class Role(BaseModel, TimestampModel):
+    name = fields.CharField(
+        max_length=20, unique=True, description="角色名称", db_index=True
+    )
+    desc = fields.CharField(max_length=500, null=True, description="角色描述")
+    menus = fields.ManyToManyField(
+        "models.Menu", related_name="role_menus", db_constraint=False
+    )
+    apis = fields.ManyToManyField(
+        "models.Api", related_name="role_apis", db_constraint=False
+    )
+
+    class Meta:
+        table = "role"

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

@@ -0,0 +1,44 @@
+from api.api.model import Api
+from api.menu.model import Menu
+from api.role.model import Role
+from api.role.schema import RoleCreateDTO, RoleUpdateDTO
+from common.repositories import CRUDBase
+
+
+class RoleRepository(CRUDBase[Role, RoleCreateDTO, RoleUpdateDTO]):
+    def __init__(self):
+        super().__init__(model=Role)
+
+    async def is_exist(self, name: str) -> bool:
+        return await self.model.filter(name=name).exists()
+
+    async def update_roles(
+        self, role: Role, menu_ids: list[int], api_infos: list[dict]
+    ) -> None:
+        from tortoise.expressions import Q
+
+        # 使用 prefetch_related 避免 N+1 查询
+        role = await Role.get(id=role.id).prefetch_related("menus", "apis")
+
+        # 批量更新菜单关联
+        await role.menus.clear()
+        if menu_ids:
+            menu_objs = await Menu.filter(id__in=menu_ids)
+            if menu_objs:
+                await role.menus.add(*menu_objs)
+
+        # 批量更新API关联
+        await role.apis.clear()
+        if api_infos:
+            # 构建查询条件：匹配所有 (path, method) 组合
+            paths = [item.get("path") for item in api_infos if item.get("path")]
+            methods = [item.get("method") for item in api_infos if item.get("method")]
+
+            if paths and methods:
+                q = Q(path__in=paths) & Q(method__in=methods)
+                api_objs = await Api.filter(q)
+                if api_objs:
+                    await role.apis.add(*api_objs)
+
+
+role_repository = RoleRepository()

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

@@ -0,0 +1,40 @@
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+
+class RoleVO(BaseModel):
+    """角色响应模型"""
+
+    id: int
+    name: str
+    desc: str = ""
+    users: list | None = []
+    menus: list | None = []
+    apis: list | None = []
+    created_at: datetime | None
+    updated_at: datetime | None
+    deleted_at: datetime | None
+
+
+class RoleCreateDTO(BaseModel):
+    """创建角色请求参数"""
+
+    name: str = Field(example="管理员")
+    desc: str = Field("", example="管理员角色")
+
+
+class RoleUpdateDTO(BaseModel):
+    """更新角色请求参数"""
+
+    id: int = Field(example=1)
+    name: str = Field(example="管理员")
+    desc: str = Field("", example="管理员角色")
+
+
+class RoleUpdateMenusApisDTO(BaseModel):
+    """更新角色权限请求参数"""
+
+    id: int
+    menu_ids: list[int] = []
+    api_infos: list[dict] = []

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

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

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

@@ -0,0 +1,59 @@
+from fastapi import APIRouter, Body, Query
+
+from api.user.schema import UserVO
+from common.schemas.response_schema import Success, SuccessPagination
+
+from .schema import UserCreateDTO, UserUpdateDTO
+from .service import user_service
+
+router = APIRouter()
+
+
+@router.get("/list", summary="查看用户列表", response_model=SuccessPagination[UserVO])
+async def list_user(
+    page: int = Query(1, description="页码"),
+    page_size: int = Query(10, description="每页数量"),
+    username: str = Query("", description="用户名称，用于搜索"),
+    email: str = Query("", description="邮箱地址"),
+    dept_id: int = Query(None, description="部门ID"),
+):
+    return await user_service.get_user_list(
+        page=page,
+        page_size=page_size,
+        username=username,
+        email=email,
+        dept_id=dept_id,
+    )
+
+
+@router.get("/get", summary="查看用户", response_model=Success[UserVO])
+async def get_user(
+    user_id: int = Query(..., description="用户ID"),
+):
+    return await user_service.get_user_detail(user_id)
+
+
+@router.post("/create", summary="创建用户", response_model=Success[None])
+async def create_user(
+    user_in: UserCreateDTO,
+):
+    return await user_service.create_user(user_in)
+
+
+@router.post("/update", summary="更新用户", response_model=Success[None])
+async def update_user(
+    user_in: UserUpdateDTO,
+):
+    return await user_service.update_user(user_in)
+
+
+@router.delete("/delete", summary="删除用户", response_model=Success[None])
+async def delete_user(
+    user_id: int = Query(..., description="用户ID"),
+):
+    return await user_service.delete_user(user_id)
+
+
+@router.post("/reset_password", summary="重置密码", response_model=Success[None])
+async def reset_password(user_id: int = Body(..., description="用户ID", embed=True)):
+    return await user_service.reset_user_password(user_id)

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

@@ -0,0 +1,39 @@
+from tortoise import fields
+
+from common.models import BaseModel, TimestampModel
+
+
+class User(BaseModel, TimestampModel):
+    username = fields.CharField(
+        max_length=20, unique=True, description="用户名称", db_index=True
+    )
+    nickname = fields.CharField(
+        max_length=30, null=True, description="昵称/姓名", db_index=True
+    )
+    email = fields.CharField(
+        max_length=255, unique=True, description="邮箱", db_index=True
+    )
+    phone = fields.CharField(
+        max_length=20, null=True, description="电话", db_index=True
+    )
+    password = fields.CharField(max_length=128, null=True, description="密码")
+    is_active = fields.BooleanField(default=True, description="是否激活", db_index=True)
+    is_superuser = fields.BooleanField(
+        default=False, description="是否为超级管理员", db_index=True
+    )
+    last_login = fields.DatetimeField(
+        null=True, description="最后登录时间", db_index=True
+    )
+    roles = fields.ManyToManyField(
+        "models.Role", related_name="user_roles", db_constraint=False
+    )
+    dept = fields.ForeignKeyField(
+        "models.Dept",
+        related_name="users",
+        null=True,
+        description="部门",
+        db_constraint=False,
+    )
+
+    class Meta:
+        table = "user"

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

@@ -0,0 +1,89 @@
+import secrets
+import string
+from datetime import datetime
+from typing import Optional
+
+from fastapi.exceptions import HTTPException
+from tortoise.transactions import atomic
+
+from api.dept.model import Dept
+from api.user.model import User
+from api.user.schema import UserCreateDTO, UserUpdateDTO
+from common.repositories import CRUDBase
+from common.schemas.auth_schema import CredentialsSchema
+from utils.password import get_password_hash, verify_password
+
+
+class UserRepository(CRUDBase[User, UserCreateDTO, UserUpdateDTO]):
+    def __init__(self):
+        super().__init__(model=User)
+
+    async def get_by_email(self, email: str) -> User | None:
+        return await self.model.filter(email=email).first()
+
+    async def get_by_username(self, username: str) -> User | None:
+        return await self.model.filter(username=username).first()
+
+    @atomic()
+    async def create_user(self, obj_in: UserCreateDTO) -> User:
+        """创建用户，包含引用完整性校验"""
+        # 校验部门是否存在（如果指定了部门）
+        if hasattr(obj_in, "dept_id") and obj_in.dept_id is not None:
+            dept_exists = await Dept.filter(id=obj_in.dept_id).exists()
+            if not dept_exists:
+                raise ValueError(f"部门 {obj_in.dept_id} 不存在")
+
+        obj_in.password = get_password_hash(password=obj_in.password)
+        obj = await self.create(obj_in)
+        return obj
+
+    async def update_last_login(self, id: int) -> None:
+        await self.model.filter(id=id).update(last_login=datetime.now())
+
+    async def authenticate(self, credentials: CredentialsSchema) -> Optional["User"]:
+        user = await self.model.filter(username=credentials.username).first()
+        if not user:
+            raise HTTPException(status_code=400, detail="无效的用户名")
+        verified = verify_password(credentials.password, user.password)
+        if not verified:
+            raise HTTPException(status_code=400, detail="密码错误!")
+        if not user.is_active:
+            raise HTTPException(status_code=400, detail="用户已被禁用")
+        return user
+
+    async def update_roles(self, user: User, role_ids: list[int]) -> None:
+        from api.role.model import Role
+
+        # 使用 prefetch_related 避免 N+1 查询
+        user = await User.get(id=user.id).prefetch_related("roles")
+        await user.roles.clear()
+        if role_ids:
+            # 校验角色是否存在
+            existing_role_ids = await Role.filter(id__in=role_ids).values_list(
+                "id", flat=True
+            )
+            if len(existing_role_ids) != len(role_ids):
+                raise ValueError("部分角色不存在")
+            role_objs = await Role.filter(id__in=role_ids)
+            if role_objs:
+                await user.roles.add(*role_objs)
+
+    async def reset_password(self, user_id: int) -> str:
+        """重置用户密码，返回新密码"""
+        user_obj = await self.get(id=user_id)
+        if user_obj.is_superuser:
+            raise HTTPException(status_code=403, detail="不允许重置超级管理员密码")
+        # 生成安全的随机密码
+        new_password = self._generate_secure_password()
+        user_obj.password = get_password_hash(password=new_password)
+        await user_obj.save()
+        return new_password
+
+    def _generate_secure_password(self, length: int = 12) -> str:
+        """生成安全的随机密码"""
+        alphabet = string.ascii_letters + string.digits + "!@#$%^&*"
+        password = "".join(secrets.choice(alphabet) for _ in range(length))
+        return password
+
+
+user_repository = UserRepository()

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

@@ -0,0 +1,127 @@
+import re
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, EmailStr, Field, field_validator
+
+
+class UserVO(BaseModel):
+    """用户响应模型"""
+
+    id: int
+    email: EmailStr | None = None
+    username: str | None = None
+    nickname: str | None = None
+    is_active: bool | None = True
+    is_superuser: bool | None = False
+    last_login: datetime | None
+    roles: list | None = []
+    created_at: datetime | None
+    updated_at: datetime | None
+    deleted_at: datetime | None
+
+    model_config = ConfigDict(from_attributes=True)
+
+
+class UserCreateDTO(BaseModel):
+    """创建用户请求参数"""
+
+    email: EmailStr = Field(example="admin@qq.com")
+    username: str = Field(
+        example="admin",
+        min_length=3,
+        max_length=20,
+        pattern="^[a-zA-Z0-9_]+$",
+        description="用户名（3-20位字母数字下划线）",
+    )
+    password: str = Field(
+        example="AdminPass123",
+        min_length=8,
+        description="密码（至少8位，包含字母和数字）",
+    )
+    is_active: bool | None = True
+    is_superuser: bool | None = False
+    role_ids: list[int] | None = []
+    dept_id: int | None = Field(0, description="部门ID")
+
+    @field_validator("password")
+    @classmethod
+    def validate_password_strength(cls, v):
+        """验证密码强度"""
+        if len(v) < 8:
+            raise ValueError("密码长度至少8位")
+
+        if not re.search(r"[A-Za-z]", v):
+            raise ValueError("密码必须包含字母")
+
+        if not re.search(r"\d", v):
+            raise ValueError("密码必须包含数字")
+
+        # 可选：检查特殊字符
+        # if not re.search(r'[!@#$%^&*(),.?":{}|<>]', v):
+        #     raise ValueError('密码建议包含特殊字符')
+
+        return v
+
+    @field_validator("username")
+    @classmethod
+    def validate_username(cls, v):
+        """验证用户名格式"""
+        if not re.match(r"^[a-zA-Z0-9_]+$", v):
+            raise ValueError("用户名只能包含字母、数字和下划线")
+        return v
+
+    def create_dict(self):
+        return self.model_dump(exclude_unset=True, exclude={"role_ids"})
+
+
+class UserUpdateDTO(BaseModel):
+    """更新用户请求参数"""
+
+    id: int
+    email: EmailStr
+    username: str
+    is_active: bool | None = True
+    is_superuser: bool | None = False
+    role_ids: list[int] | None = []
+    dept_id: int | None = 0
+
+
+class UpdatePasswordDTO(BaseModel):
+    """修改密码请求参数"""
+
+    old_password: str = Field(description="旧密码")
+    new_password: str = Field(
+        min_length=8, description="新密码（至少8位，包含字母和数字）"
+    )
+
+    @field_validator("new_password")
+    @classmethod
+    def validate_new_password_strength(cls, v):
+        """验证新密码强度"""
+        if len(v) < 8:
+            raise ValueError("新密码长度至少8位")
+
+        if not re.search(r"[A-Za-z]", v):
+            raise ValueError("新密码必须包含字母")
+
+        if not re.search(r"\d", v):
+            raise ValueError("新密码必须包含数字")
+
+        return v
+
+
+class UserInfoVO(BaseModel):
+    """用户信息响应模型（用于 /userinfo 端点）"""
+
+    id: int
+    username: str | None = None
+    nickname: str | None = None
+    email: EmailStr | None = None
+    phone: str | None = None
+    is_active: bool | None = True
+    is_superuser: bool | None = False
+    last_login: datetime | None = None
+    roles: list | None = []
+    dept: dict | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None

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

@@ -0,0 +1,180 @@
+"""用户服务层 - 统一用户业务逻辑"""
+
+from tortoise.expressions import Q
+
+from api.base.service import BaseService
+from api.dept.repository import dept_repository
+from api.user.repository import user_repository
+from common.schemas.response_schema import Fail, Success, SuccessPagination
+from utils.cache import cached, clear_user_cache
+
+from .schema import UserCreateDTO, UserUpdateDTO
+
+
+class UserService(BaseService):
+    """用户服务类 - 专门处理用户相关业务逻辑"""
+
+    def __init__(self):
+        super().__init__(user_repository)
+
+    async def get_user_list(
+        self,
+        page: int = 1,
+        page_size: int = 10,
+        username: str = "",
+        email: str = "",
+        dept_id: int | None = None,
+    ) -> SuccessPagination:
+        """获取用户列表 - 包含搜索过滤和部门信息关联"""
+        try:
+            # 构建搜索过滤条件
+            search_filters = self._build_user_search_filters(
+                username=username, email=email, dept_id=dept_id
+            )
+
+            # 获取分页数据
+            total, items = await self.repository.list(
+                page=page,
+                page_size=page_size,
+                search=search_filters,
+                order=["-created_at"],
+            )
+
+            # 转换数据并关联部门信息
+            data = await self._transform_user_list_with_dept(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="获取用户列表失败")
+
+    @cached(
+        "user_detail", ttl=300, key_func=lambda self, user_id: f"user_detail:{user_id}"
+    )
+    async def get_user_detail(self, user_id: int) -> Success:
+        """获取用户详情 - 带缓存"""
+        try:
+            user_obj = await user_repository.get(id=user_id)
+            if not user_obj:
+                return Fail(msg="用户不存在")
+
+            user_dict = await user_obj.to_dict(m2m=True, exclude_fields=["password"])
+            return Success(data=user_dict)
+
+        except Exception as e:
+            self.logger.error(f"获取用户详情失败: {str(e)}")
+            return Fail(msg="获取用户详情失败")
+
+    async def create_user(self, user_in: UserCreateDTO) -> Success:
+        """创建用户 - 包含邮箱唯一性检查和角色分配"""
+        try:
+            # 检查邮箱是否已存在
+            existing_user = await user_repository.get_by_email(user_in.email)
+            if existing_user:
+                return Fail(
+                    code=400,
+                    msg="The user with this email already exists in the system.",
+                )
+
+            # 创建用户
+            new_user = await user_repository.create_user(obj_in=user_in)
+
+            # 更新用户角色
+            await user_repository.update_roles(new_user, user_in.role_ids)
+
+            return Success(msg="Created Successfully")
+
+        except Exception as e:
+            self.logger.error(f"创建用户失败: {str(e)}")
+            return Fail(msg="创建用户失败")
+
+    async def update_user(self, user_in: UserUpdateDTO) -> Success:
+        """更新用户 - 包含角色更新和缓存清理"""
+        try:
+            # 更新用户基础信息
+            user = await user_repository.update(id=user_in.id, obj_in=user_in)
+
+            # 更新用户角色
+            await user_repository.update_roles(user, user_in.role_ids)
+
+            # 清除相关缓存
+            await clear_user_cache(user_in.id)
+
+            return Success(msg="Updated Successfully")
+
+        except Exception as e:
+            self.logger.error(f"更新用户失败: {str(e)}")
+            return Fail(msg="更新用户失败")
+
+    async def delete_user(self, user_id: int) -> Success:
+        """删除用户 - 包含缓存清理"""
+        try:
+            await user_repository.remove(id=user_id)
+
+            # 清除相关缓存
+            await clear_user_cache(user_id)
+
+            return Success(msg="Deleted Successfully")
+
+        except Exception as e:
+            self.logger.error(f"删除用户失败: {str(e)}")
+            return Fail(msg="删除用户失败")
+
+    async def reset_user_password(self, user_id: int) -> Success:
+        """重置用户密码"""
+        try:
+            await user_repository.reset_password(user_id)
+            return Success(msg="密码已重置")
+
+        except Exception as e:
+            self.logger.error(f"重置密码失败: {str(e)}")
+            return Fail(msg="重置密码失败")
+
+    def _build_user_search_filters(
+        self,
+        username: str = "",
+        email: str = "",
+        dept_id: int | None = None,
+    ) -> Q:
+        """构建用户搜索过滤条件"""
+        filters = Q()
+
+        if username:
+            filters &= Q(username__contains=username)
+
+        if email:
+            filters &= Q(email__contains=email)
+
+        if dept_id is not None:
+            filters &= Q(dept_id=dept_id)
+
+        return filters
+
+    async def _transform_user_list_with_dept(self, items) -> list[dict]:
+        """转换用户列表数据并关联部门信息"""
+        if not items:
+            return []
+
+        # 批量获取所有需要的部门ID
+        dept_ids = {obj.dept_id for obj in items if obj.dept_id}
+        dept_map = {}
+        if dept_ids:
+            dept_objs = await dept_repository.model.filter(id__in=dept_ids)
+            dept_map = {dept.id: await dept.to_dict() for dept in dept_objs}
+
+        data = []
+        for obj in items:
+            # 转换用户数据，排除密码字段
+            user_dict = await obj.to_dict(m2m=True, exclude_fields=["password"])
+            dept_id = user_dict.pop("dept_id", None)
+            user_dict["dept"] = dept_map.get(dept_id, {})
+            data.append(user_dict)
+
+        return data
+
+
+# 全局实例
+user_service = UserService()