@stephen-lord/docs 1.0.0 → 1.0.1

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

@@ -0,0 +1,474 @@
+"""文件服务层 - 统一文件处理业务逻辑"""
+
+import os
+import uuid
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from fastapi import HTTPException, UploadFile
+from tortoise.expressions import Q
+
+from api.base.service import BaseService
+from api.file.repository import file_mapping_repository
+from api.user.repository import user_repository
+from common.schemas.response_schema import Fail, Success
+from core.contexts.constant import CTX_USER_ID
+from log import logger
+
+# 文件安全配置
+MAX_FILE_SIZE = 500 * 1024 * 1024  # 500MB
+UPLOADS_DIR = "uploads"
+
+ALLOWED_EXTENSIONS: set[str] = {
+    # 文档类型
+    ".txt",
+    ".pdf",
+    ".doc",
+    ".docx",
+    ".xls",
+    ".xlsx",
+    ".ppt",
+    ".pptx",
+    # 图片类型
+    ".jpg",
+    ".jpeg",
+    ".png",
+    ".gif",
+    ".bmp",
+    ".webp",
+    ".svg",
+    # 音视频类型
+    ".mp3",
+    ".wav",
+    ".flac",
+    ".aac",
+    ".ogg",
+    ".m4a",
+    ".mp4",
+    ".avi",
+    ".mkv",
+    ".mov",
+    ".wmv",
+    ".flv",
+    ".webm",
+    # 其他文件类型
+    ".json",
+    ".xml",
+    ".csv",
+    ".zip",
+    ".rar",
+    ".7z",
+}
+
+DANGEROUS_EXTENSIONS: set[str] = {
+    ".exe",
+    ".bat",
+    ".cmd",
+    ".com",
+    ".pif",
+    ".scr",
+    ".vbs",
+    ".js",
+    ".jar",
+    ".sh",
+    ".ps1",
+    ".php",
+    ".asp",
+    ".jsp",
+    ".py",
+    ".pl",
+    ".rb",
+}
+
+
+class FileService(BaseService):
+    """文件服务类 - 专门处理文件上传和安全验证逻辑"""
+
+    def __init__(self):
+        super().__init__(file_mapping_repository)
+        self.logger = logger
+        # 确保上传目录存在
+        self.uploads_dir = Path(UPLOADS_DIR)
+        self.uploads_dir.mkdir(exist_ok=True)
+
+    async def get_file_list(
+        self,
+        page: int = 1,
+        page_size: int = 10,
+        user_id: int | None = None,
+        file_type: str | None = None,
+    ) -> dict[str, Any]:
+        """
+        获取文件列表，支持分页和筛选
+
+        Args:
+            page: 页码，从1开始
+            page_size: 每页数量
+            user_id: 用户ID，如果提供则只返回该用户的文件
+            file_type: 文件类型，如果提供则只返回该类型的文件
+
+        Returns:
+            Dict: 包含文件列表和分页信息的字典
+        """
+        try:
+            # 获取当前用户ID（如果未指定）
+            if user_id is None:
+                current_user_id = CTX_USER_ID.get()
+                # 检查是否为管理员，管理员可以查看所有文件
+                if current_user_id:
+                    user = await user_repository.get(id=current_user_id)
+                    if not user or not user.is_superuser:
+                        # 非管理员只能查看自己的文件
+                        user_id = current_user_id
+
+            # 构建搜索条件
+            search_filters = Q()
+            if user_id:
+                search_filters &= Q(user_id=user_id)
+            if file_type:
+                search_filters &= Q(file_type=file_type)
+
+            # 使用 BaseService 的分页方法
+            async def transform_files(files):
+                """转换文件对象为字典"""
+                result = []
+                for file in files:
+                    file_dict = {
+                        "file_id": str(file.file_id),
+                        "original_filename": file.original_filename,
+                        "file_type": file.file_type,
+                        "file_size": file.file_size,
+                        "upload_user_id": file.upload_user_id,
+                        "created_at": file.created_at.isoformat(),
+                        "updated_at": file.updated_at.isoformat()
+                        if file.updated_at
+                        else None,
+                    }
+                    result.append(file_dict)
+                return result
+
+            # 使用 BaseService 的分页方法
+            result = await self.get_paginated_list(
+                page=page,
+                page_size=page_size,
+                search_filters=search_filters,
+                order=["-created_at"],
+                transform_func=transform_files,
+            )
+
+            return result
+
+        except Exception as e:
+            self.logger.error(f"获取文件列表失败: {str(e)}")
+            raise HTTPException(status_code=500, detail="获取文件列表失败") from e
+
+    async def upload_file(self, file: UploadFile) -> Success:
+        """
+        通用文件上传
+
+        Args:
+            file: 上传的文件
+
+        Returns:
+            Success: 上传结果响应
+        """
+        try:
+            # 直接从上下文获取用户 ID
+            user_id = CTX_USER_ID.get()
+            if not user_id:
+                raise HTTPException(status_code=401, detail="用户未认证")
+
+            # 文件安全验证
+            self._validate_file_security(file)
+
+            # 生成安全文件名(包含文件扩展名)
+            safe_filename = self._generate_safe_filename(file.filename)
+
+            # 读取并验证文件内容
+            content = await self._read_and_validate_file(file)
+
+            # 生成文件ID和保存路径
+            timeStamp = int(datetime.now().timestamp())
+            file_id = uuid.uuid4()
+
+            file_path = self.uploads_dir / f"{timeStamp}_{safe_filename}"
+
+            # 保存文件到本地
+            with open(file_path, "wb") as f:
+                f.write(content)
+
+            self.logger.info(f"文件已保存: {file_path}")
+
+            # 保存文件映射信息
+            await self._save_file_mapping(
+                {"file_id": file_id, "file_path": str(file_path)}, file, user_id
+            )
+
+            # 返回文件信息
+            response_data = {
+                "file_id": str(file_id),  # 将 UUID 转换为字符串
+                "original_filename": file.filename,
+                "file_type": self._determine_file_type(file.filename),
+                "file_size": len(content),
+                "file_path": str(file_path),
+            }
+
+            return Success(
+                data=response_data,
+                msg="文件上传成功",
+            )
+
+        except HTTPException:
+            raise
+        except Exception as e:
+            self.logger.error(f"文件上传失败: {str(e)}")
+            raise HTTPException(status_code=500, detail="文件上传失败") from e
+
+    async def delete_file(self, file_id: uuid.UUID) -> Success:
+        """
+        删除文件
+
+        Args:
+            file_id: 文件ID
+
+        Returns:
+            Success: 删除成功的响应
+        """
+        try:
+            # 获取当前用户ID
+            user_id = CTX_USER_ID.get()
+            if not user_id:
+                raise HTTPException(status_code=401, detail="用户未认证")
+
+            # 获取文件映射信息
+            file_mapping = await file_mapping_repository.get_file_mapping_by_file_id(
+                file_id
+            )
+            if not file_mapping:
+                return Fail(code=404, msg="文件不存在")
+
+            # 检查文件所有权
+            if file_mapping.get("upload_user_id") != user_id:
+                # 检查是否为管理员
+                user = await user_repository.get(id=user_id)
+                if not user or not user.is_superuser:
+                    return Fail(code=403, msg="无权删除此文件")
+
+            # 先删除数据库记录
+            relative_path = file_mapping.get("file_path")
+            file_path = Path(relative_path)
+            # 确保使用绝对路径
+            if not file_path.is_absolute():
+                file_path = Path(os.getcwd()) / relative_path
+
+            await file_mapping_repository.remove(file_mapping.get("id"))
+            self.logger.info(f"文件映射记录已删除: {file_id}")
+
+            # 成功删除数据库记录后，再删除物理文件
+            if file_path.exists():
+                os.remove(file_path)
+                self.logger.info(f"物理文件已删除: {file_path}")
+
+            return Success(msg="文件删除成功")
+
+        except HTTPException:
+            raise
+        except Exception as e:
+            self.logger.error(f"文件删除失败: {str(e)}")
+            raise HTTPException(status_code=500, detail="文件删除失败") from e
+
+    async def update_file(self, file_id: uuid.UUID, file: UploadFile) -> Success:
+        """
+        更新文件
+
+        Args:
+            file_id: 要更新的文件ID
+            file: 新的文件对象
+
+        Returns:
+            Success: 更新成功的响应
+        """
+        try:
+            # 获取当前用户ID
+            user_id = CTX_USER_ID.get()
+            if not user_id:
+                raise HTTPException(status_code=401, detail="用户未认证")
+
+            # 获取文件映射信息
+            file_mapping = await file_mapping_repository.get_file_mapping_by_file_id(
+                file_id
+            )
+            if not file_mapping:
+                return Fail(code=404, msg="文件不存在")
+
+            # 检查文件所有权
+            if file_mapping.get("upload_user_id") != user_id:
+                # 检查是否为管理员
+                user = await user_repository.get(id=user_id)
+                if not user or not user.is_superuser:
+                    return Fail(code=403, msg="无权更新此文件")
+
+            # 文件安全验证
+            self._validate_file_security(file)
+
+            # 生成安全文件名(包含文件扩展名)
+            safe_filename = self._generate_safe_filename(file.filename)
+
+            # 读取并验证文件内容
+            content = await self._read_and_validate_file(file)
+
+            # 删除旧文件
+            relative_path = file_mapping.get("file_path")
+            old_file_path = Path(relative_path)
+            # 确保使用绝对路径
+            if not old_file_path.is_absolute():
+                old_file_path = Path(os.getcwd()) / relative_path
+            if old_file_path.exists():
+                os.remove(old_file_path)
+                self.logger.info(f"旧文件已删除: {old_file_path}")
+
+            # 生成新的保存路径
+            timeStamp = int(datetime.now().timestamp())
+            new_file_path = self.uploads_dir / f"{timeStamp}_{safe_filename}"
+
+            # 保存新文件
+            with open(new_file_path, "wb") as f:
+                f.write(content)
+
+            self.logger.info(f"新文件已保存: {new_file_path}")
+
+            # 更新文件映射信息
+            file_mapping.update(
+                {
+                    "file_path": str(new_file_path),
+                    "original_filename": file.filename,
+                    "file_size": len(content),
+                    "file_type": self._determine_file_type(file.filename),
+                    "update_time": datetime.now(),
+                }
+            )
+
+            await file_mapping_repository.update(file_mapping.get("id"), file_mapping)
+
+            # 返回更新后的文件信息
+            response_data = {
+                "file_id": str(file_id),
+                "original_filename": file.filename,
+                "file_type": self._determine_file_type(file.filename),
+                "file_size": len(content),
+                "file_path": str(new_file_path),
+            }
+
+            return Success(
+                data=response_data,
+                msg="文件更新成功",
+            )
+
+        except HTTPException:
+            raise
+        except Exception as e:
+            self.logger.error(f"文件更新失败: {str(e)}")
+            raise HTTPException(status_code=500, detail="文件更新失败") from e
+
+    def _validate_file_security(self, file: UploadFile) -> None:
+        """验证文件安全性"""
+        if not file.filename:
+            raise HTTPException(status_code=400, detail="文件名不能为空")
+
+        # 获取文件扩展名
+        file_ext = Path(file.filename).suffix.lower()
+
+        # 检查危险文件类型
+        if file_ext in DANGEROUS_EXTENSIONS:
+            raise HTTPException(
+                status_code=400, detail=f"不允许上传的文件类型: {file_ext}"
+            )
+
+        # 检查是否在允许的扩展名列表中
+        if file_ext and file_ext not in ALLOWED_EXTENSIONS:
+            raise HTTPException(
+                status_code=400,
+                detail=f"不支持的文件类型: {file_ext}，允许的类型: {', '.join(sorted(ALLOWED_EXTENSIONS))}",
+            )
+
+    def _generate_safe_filename(self, original_filename: str) -> str:
+        """生成安全的文件名（防止路径遍历攻击）"""
+        file_ext = Path(original_filename).suffix.lower()
+        return f"{uuid.uuid4().hex}{file_ext}"
+
+    async def _read_and_validate_file(self, file: UploadFile) -> bytes:
+        """读取并验证文件内容"""
+        content = await file.read()
+
+        # 验证文件大小
+        if len(content) > MAX_FILE_SIZE:
+            raise HTTPException(
+                status_code=400,
+                detail=f"文件大小超过限制 {MAX_FILE_SIZE // (1024 * 1024)}MB",
+            )
+
+        return content
+
+    async def _save_file_mapping(
+        self,
+        response_data: dict,
+        file: UploadFile,
+        user_id: int,
+    ) -> None:
+        """保存文件映射信息"""
+        try:
+            # 从响应中获取文件ID
+            file_id = response_data.get("file_id")
+            if not file_id:
+                self.logger.warning("无法从响应中获取文件ID")
+                return
+
+            # 确定文件类型
+            file_type = self._determine_file_type(file.filename)
+
+            # 获取文件大小
+            file_size = file.size if hasattr(file, "size") else None
+
+            # 保存文件映射
+            await file_mapping_repository.create_file_mapping(
+                file_id=file_id,
+                original_name=file.filename,
+                file_type=file_type,
+                file_size=file_size,
+                user_id=user_id,
+                file_path=response_data.get("file_path"),  # 存储本地文件路径
+            )
+
+            self.logger.info(f"已保存文件映射: {file_id} -> {file.filename}")
+
+        except Exception as e:
+            # 文件映射保存失败不应该影响上传流程
+            self.logger.warning(f"保存文件映射失败: {str(e)}")
+
+    def _determine_file_type(self, filename: str) -> str:
+        """确定文件类型"""
+        if not filename:
+            return "unknown"
+
+        file_ext = filename.lower().split(".")[-1] if "." in filename else ""
+
+        # 图片类型
+        image_exts = ["jpg", "jpeg", "png", "gif", "bmp", "webp", "svg"]
+        # 音频类型
+        audio_exts = ["mp3", "wav", "flac", "aac", "ogg", "m4a"]
+        # 视频类型
+        video_exts = ["mp4", "avi", "mkv", "mov", "wmv", "flv", "webm"]
+
+        if file_ext in image_exts:
+            return "image"
+        elif file_ext in audio_exts:
+            return "audio"
+        elif file_ext in video_exts:
+            return "video"
+        else:
+            return "document"
+
+
+# 全局实例
+file_service = FileService()

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

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

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

@@ -0,0 +1,70 @@
+import logging
+
+from fastapi import APIRouter, Query
+
+from common.schemas import Fail, Success, SuccessPagination
+
+from .repository import menu_repository
+from .schema import MenuCreateDTO, MenuUpdateDTO, MenuVO
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+@router.get("/list", summary="查看菜单列表", response_model=SuccessPagination[MenuVO])
+async def list_menu(
+    page: int = Query(1, description="页码"),
+    page_size: int = Query(10, description="每页数量"),
+):
+    async def get_menu_with_children(menu_id: int):
+        menu = await menu_repository.model.get(id=menu_id)
+        menu_dict = await menu.to_dict()
+        child_menus = await menu_repository.model.filter(parent_id=menu_id).order_by(
+            "order"
+        )
+        menu_dict["children"] = [
+            await get_menu_with_children(child.id) for child in child_menus
+        ]
+        return menu_dict
+
+    parent_menus = await menu_repository.model.filter(parent_id=0).order_by("order")
+    res_menu = [await get_menu_with_children(menu.id) for menu in parent_menus]
+    return SuccessPagination(
+        data=res_menu, total=len(res_menu), page=page, page_size=page_size
+    )
+
+
+@router.get("/get", summary="查看菜单", response_model=Success[MenuVO])
+async def get_menu(
+    menu_id: int = Query(..., description="菜单id"),
+):
+    result = await menu_repository.get(id=menu_id)
+    return Success(data=result)
+
+
+@router.post("/create", summary="创建菜单", response_model=Success[None])
+async def create_menu(
+    menu_in: MenuCreateDTO,
+):
+    await menu_repository.create(obj_in=menu_in)
+    return Success(msg="Created Success")
+
+
+@router.post("/update", summary="更新菜单", response_model=Success[None])
+async def update_menu(
+    menu_in: MenuUpdateDTO,
+):
+    await menu_repository.update(id=menu_in.id, obj_in=menu_in)
+    return Success(msg="Updated Success")
+
+
+@router.delete("/delete", summary="删除菜单", response_model=Success[None])
+async def delete_menu(
+    id: int = Query(..., description="菜单id"),
+):
+    child_menu_count = await menu_repository.model.filter(parent_id=id).count()
+    if child_menu_count > 0:
+        return Fail(msg="Cannot delete a menu with child menus")
+    await menu_repository.remove(id=id)
+    return Success(msg="Deleted Success")

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

@@ -0,0 +1,22 @@
+from tortoise import fields
+
+from common.models import BaseModel, TimestampModel
+
+from .schema import MenuType
+
+
+class Menu(BaseModel, TimestampModel):
+    name = fields.CharField(max_length=20, description="菜单名称", db_index=True)
+    remark = fields.JSONField(null=True, description="保留字段")
+    menu_type = fields.CharEnumField(MenuType, null=True, description="菜单类型")
+    icon = fields.CharField(max_length=100, null=True, description="菜单图标")
+    path = fields.CharField(max_length=100, description="菜单路径", db_index=True)
+    order = fields.IntField(default=0, description="排序", db_index=True)
+    parent_id = fields.IntField(default=0, description="父菜单ID", db_index=True)
+    is_hidden = fields.BooleanField(default=False, description="是否隐藏")
+    component = fields.CharField(max_length=100, description="组件")
+    keepalive = fields.BooleanField(default=True, description="存活")
+    redirect = fields.CharField(max_length=100, null=True, description="重定向")
+
+    class Meta:
+        table = "menu"

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

@@ -0,0 +1,17 @@
+from typing import Optional
+
+from common.repositories import CRUDBase
+
+from .model import Menu
+from .schema import MenuCreateDTO, MenuUpdateDTO
+
+
+class MenuRepository(CRUDBase[Menu, MenuCreateDTO, MenuUpdateDTO]):
+    def __init__(self):
+        super().__init__(model=Menu)
+
+    async def get_by_menu_path(self, path: str) -> Optional["Menu"]:
+        return await self.model.filter(path=path).first()
+
+
+menu_repository = MenuRepository()

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

@@ -0,0 +1,57 @@
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+
+class MenuType(StrEnum):
+    CATALOG = "catalog"  # 目录
+    MENU = "menu"  # 菜单
+
+
+class MenuVO(BaseModel):
+    """菜单响应模型"""
+
+    id: int
+    name: str
+    path: str
+    remark: dict | None
+    menu_type: MenuType | None
+    icon: str | None
+    order: int
+    parent_id: int
+    is_hidden: bool
+    component: str
+    keepalive: bool
+    redirect: str | None
+    children: list["MenuVO"] | None
+
+
+class MenuCreateDTO(BaseModel):
+    """创建菜单请求参数"""
+
+    menu_type: MenuType = Field(default=MenuType.CATALOG.value)
+    name: str = Field(example="用户管理")
+    icon: str | None = "ph:user-list-bold"
+    path: str = Field(example="/system/user")
+    order: int | None = Field(example=1)
+    parent_id: int | None = Field(example=0, default=0)
+    is_hidden: bool | None = False
+    component: str = Field(default="Layout", example="/system/user")
+    keepalive: bool | None = True
+    redirect: str | None = ""
+
+
+class MenuUpdateDTO(BaseModel):
+    """更新菜单请求参数"""
+
+    id: int
+    menu_type: MenuType | None = Field(example=MenuType.CATALOG.value)
+    name: str | None = Field(example="用户管理")
+    icon: str | None = "ph:user-list-bold"
+    path: str | None = Field(example="/system/user")
+    order: int | None = Field(example=1)
+    parent_id: int | None = Field(example=0)
+    is_hidden: bool | None = False
+    component: str = Field(example="/system/user")
+    keepalive: bool | None = False
+    redirect: str | None = ""

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

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