@stephen-lord/docs 1.0.0 → 1.0.1

package/dist-repo/fastapi-backend/scripts/lint.py

@@ -0,0 +1,251 @@
+#!/usr/bin/env python3
+"""
+Ruff Lint Script for FastAPI Project
+
+使用 Ruff 进行代码检查和格式化的脚本工具
+支持指定文件、文件夹、不同的检查模式等功能
+"""
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+
+class RuffLinter:
+    """Ruff 代码检查器"""
+
+    def __init__(self, project_root: Path):
+        self.project_root = project_root
+        self.src_dir = project_root / "src"
+
+    def run_command(self, cmd: list[str], description: str) -> bool:
+        """执行命令并返回是否成功"""
+        print(f"🔍 {description}")
+        print(f"   命令: {' '.join(cmd)}")
+
+        try:
+            result = subprocess.run(
+                cmd, cwd=self.project_root, capture_output=True, text=True, check=False
+            )
+
+            if result.stdout:
+                print(result.stdout)
+            if result.stderr:
+                print(result.stderr, file=sys.stderr)
+
+            if result.returncode == 0:
+                print(f"✅ {description} - 成功")
+                return True
+            else:
+                print(f"❌ {description} - 失败 (退出码: {result.returncode})")
+                return False
+
+        except FileNotFoundError:
+            print("❌ 错误: 找不到 ruff 命令，请确保已安装 ruff")
+            return False
+        except Exception as e:
+            print(f"❌ 执行命令时出错: {e}")
+            return False
+
+    def check(
+        self, targets: list[str], fix: bool = False, unsafe_fixes: bool = False
+    ) -> bool:
+        """运行 ruff check"""
+        cmd = ["ruff", "check"]
+
+        if fix:
+            cmd.append("--fix")
+        if unsafe_fixes:
+            cmd.append("--unsafe-fixes")
+
+        cmd.extend(targets)
+
+        description = f"代码检查 ({'自动修复' if fix else '仅检查'})"
+        return self.run_command(cmd, description)
+
+    def format(self, targets: list[str], check_only: bool = False) -> bool:
+        """运行 ruff format"""
+        cmd = ["ruff", "format"]
+
+        if check_only:
+            cmd.append("--check")
+
+        cmd.extend(targets)
+
+        description = f"代码格式化 ({'检查格式' if check_only else '格式化'})"
+        return self.run_command(cmd, description)
+
+    def show_statistics(self, targets: list[str]) -> bool:
+        """显示代码统计信息"""
+        cmd = ["ruff", "check", "--statistics"] + targets
+        return self.run_command(cmd, "代码统计信息")
+
+    def show_rules(self, rule_codes: list[str] | None = None) -> bool:
+        """显示规则信息"""
+        cmd = ["ruff", "rule"]
+        if rule_codes:
+            cmd.extend(rule_codes)
+        else:
+            cmd.append("--all")
+        return self.run_command(cmd, "规则信息")
+
+
+def parse_arguments() -> argparse.Namespace:
+    """解析命令行参数"""
+    parser = argparse.ArgumentParser(
+        description="FastAPI 项目的 Ruff 代码检查工具",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+使用示例:
+  %(prog)s                          # 检查整个 src 目录
+  %(prog)s --fix                    # 检查并自动修复问题
+  %(prog)s --format                 # 格式化代码
+  %(prog)s --target src/core        # 检查指定目录
+  %(prog)s --target main.py         # 检查指定文件
+  %(prog)s --check-format           # 仅检查格式，不修改
+  %(prog)s --stats                  # 显示统计信息
+  %(prog)s --rules E501 F401        # 显示指定规则信息
+  %(prog)s --all                    # 运行所有检查（check + format）
+        """,
+    )
+
+    # 目标文件/目录
+    parser.add_argument(
+        "--target",
+        "-t",
+        action="append",
+        dest="targets",
+        help="指定要检查的文件或目录（可多次使用）",
+    )
+
+    # 检查选项
+    parser.add_argument("--fix", "-f", action="store_true", help="自动修复可修复的问题")
+
+    parser.add_argument(
+        "--unsafe-fixes", action="store_true", help="启用不安全的自动修复"
+    )
+
+    # 格式化选项
+    parser.add_argument("--format", action="store_true", help="格式化代码")
+
+    parser.add_argument(
+        "--check-format", action="store_true", help="检查代码格式，但不修改文件"
+    )
+
+    # 信息选项
+    parser.add_argument("--stats", action="store_true", help="显示代码统计信息")
+
+    parser.add_argument(
+        "--rules", nargs="*", help="显示规则信息（不指定则显示所有规则）"
+    )
+
+    # 组合选项
+    parser.add_argument(
+        "--all", "-a", action="store_true", help="运行所有检查（等同于 --fix --format）"
+    )
+
+    # 预设模式
+    parser.add_argument(
+        "--mode",
+        choices=["check", "fix", "format", "ci"],
+        help="预设模式: check(仅检查), fix(检查+修复), format(格式化), ci(CI模式)",
+    )
+
+    return parser.parse_args()
+
+
+def get_default_targets(project_root: Path) -> list[str]:
+    """获取默认的检查目标"""
+    targets = []
+
+    # 添加 src 目录
+    src_dir = project_root / "src"
+    if src_dir.exists():
+        targets.append(str(src_dir))
+
+    # 添加根目录的 Python 文件
+    for py_file in project_root.glob("*.py"):
+        targets.append(str(py_file))
+
+    # 添加 scripts 目录
+    scripts_dir = project_root / "scripts"
+    if scripts_dir.exists():
+        targets.append(str(scripts_dir))
+
+    return targets
+
+
+def main():
+    """主函数"""
+    args = parse_arguments()
+
+    # 获取项目根目录
+    project_root = Path(__file__).parent.parent
+    linter = RuffLinter(project_root)
+
+    # 确定检查目标
+    targets = args.targets or get_default_targets(project_root)
+
+    if not targets:
+        print("❌ 错误: 没有找到要检查的文件或目录")
+        sys.exit(1)
+
+    print("🚀 开始 Ruff 代码检查")
+    print(f"📁 项目根目录: {project_root}")
+    print(f"🎯 检查目标: {', '.join(targets)}")
+    print("-" * 60)
+
+    success = True
+
+    # 处理预设模式
+    if args.mode:
+        if args.mode == "check":
+            success &= linter.check(targets, fix=False)
+        elif args.mode == "fix":
+            success &= linter.check(targets, fix=True)
+            success &= linter.format(targets)
+        elif args.mode == "format":
+            success &= linter.format(targets)
+        elif args.mode == "ci":
+            success &= linter.check(targets, fix=False)
+            success &= linter.format(targets, check_only=True)
+
+    # 处理组合选项
+    elif args.all:
+        success &= linter.check(targets, fix=True, unsafe_fixes=args.unsafe_fixes)
+        success &= linter.format(targets)
+
+    # 处理单独选项
+    else:
+        # 显示规则信息
+        if args.rules is not None:
+            success &= linter.show_rules(args.rules if args.rules else None)
+
+        # 显示统计信息
+        if args.stats:
+            success &= linter.show_statistics(targets)
+
+        # 代码检查
+        if not args.format and not args.check_format and args.rules is None:
+            success &= linter.check(
+                targets, fix=args.fix, unsafe_fixes=args.unsafe_fixes
+            )
+
+        # 代码格式化
+        if args.format:
+            success &= linter.format(targets)
+        elif args.check_format:
+            success &= linter.format(targets, check_only=True)
+
+    print("-" * 60)
+    if success:
+        print("🎉 所有检查完成，没有发现问题！")
+        sys.exit(0)
+    else:
+        print("⚠️  检查完成，发现了一些问题，请查看上面的输出")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,83 @@
+import asyncio
+from contextlib import asynccontextmanager
+
+from fastapi import Depends, FastAPI
+from fastapi.openapi.docs import get_redoc_html, get_swagger_ui_html
+from fastapi.openapi.utils import get_openapi
+from tortoise import Tortoise
+
+from core.dependencies.auth_dependency import get_current_username
+from core.exceptions import SettingNotFound
+from core.init_app import (
+    make_middlewares,
+    register_exceptions,
+    register_routers,
+    shutdown,
+    startup,
+)
+
+try:
+    from config.settings import settings
+except ImportError as e:
+    raise SettingNotFound("Can not import settings") from e
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await startup()
+    yield
+    await asyncio.gather(
+        shutdown(),
+        Tortoise.close_connections(),
+    )
+
+
+def create_app() -> FastAPI:
+    app = FastAPI(
+        title=settings.APP_TITLE,
+        description=settings.APP_DESCRIPTION,
+        version=settings.VERSION,
+        docs_url=None,
+        redoc_url=None,
+        openapi_url="/openapi.json",
+        middleware=make_middlewares(),
+        lifespan=lifespan,
+    )
+
+    @app.get("/docs", include_in_schema=False)
+    async def custom_swagger_ui_html(
+        username: str = Depends(get_current_username),
+    ):
+        return get_swagger_ui_html(
+            openapi_url="/openapi.json",
+            title=app.title + " - Swagger UI",
+            swagger_js_url="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js",
+            swagger_css_url="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css",
+        )
+
+    @app.get("/redoc", include_in_schema=False)
+    async def redoc_html(username: str = Depends(get_current_username)):
+        return get_redoc_html(
+            openapi_url="/openapi.json",
+            title=app.title + " - ReDoc",
+        )
+
+    @app.get("/openapi.json", include_in_schema=False)
+    async def get_open_api_endpoint(
+        username: str = Depends(get_current_username),
+    ):
+        openapi_schema = get_openapi(
+            title=app.title,
+            version=app.version,
+            description=app.description,
+            routes=app.routes,
+        )
+
+        return openapi_schema
+
+    register_exceptions(app)
+    register_routers(app)
+    return app
+
+
+app = create_app()

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

@@ -0,0 +1,25 @@
+from fastapi import APIRouter
+
+from core.dependencies.auth_dependency import DependPermisson
+
+from .api import api_router as apis_router
+from .auditlog import auditlog_router
+from .base import base_router
+from .dept import dept_router
+from .file import file_router
+from .menu import menu_router
+from .role import role_router
+from .user import user_router
+
+api_router = APIRouter(prefix="/api")
+
+api_router.include_router(base_router, prefix="/base")
+api_router.include_router(user_router, prefix="/user", dependencies=[DependPermisson])
+api_router.include_router(role_router, prefix="/role", dependencies=[DependPermisson])
+api_router.include_router(apis_router, prefix="/api", dependencies=[DependPermisson])
+api_router.include_router(
+    auditlog_router, prefix="/auditlog", dependencies=[DependPermisson]
+)
+api_router.include_router(dept_router, prefix="/dept", dependencies=[DependPermisson])
+api_router.include_router(file_router, prefix="/file", dependencies=[DependPermisson])
+api_router.include_router(menu_router, prefix="/menu", dependencies=[DependPermisson])

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

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

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

@@ -0,0 +1,70 @@
+from fastapi import APIRouter, Query
+from tortoise.expressions import Q
+
+from common.schemas.response_schema import Success, SuccessPagination
+
+from .repository import api_repository
+from .schema import ApiCreateDTO, ApiUpdateDTO, ApiVO
+
+router = APIRouter()
+
+
+@router.get("/list", summary="查看API列表", response_model=SuccessPagination[ApiVO])
+async def list_api(
+    page: int = Query(1, description="页码"),
+    page_size: int = Query(10, description="每页数量"),
+    path: str = Query(None, description="API路径"),
+    summary: str = Query(None, description="API简介"),
+    tags: str = Query(None, description="API模块"),
+):
+    q = Q()
+    if path:
+        q &= Q(path__contains=path)
+    if summary:
+        q &= Q(summary__contains=summary)
+    if tags:
+        q &= Q(tags__contains=tags)
+    total, api_objs = await api_repository.list(
+        page=page, page_size=page_size, search=q, order=["tags", "id"]
+    )
+    data = [await obj.to_dict() for obj in api_objs]
+    return SuccessPagination(data=data, total=total, page=page, page_size=page_size)
+
+
+@router.get("/get", summary="查看Api", response_model=Success[ApiVO])
+async def get_api(
+    id: int = Query(..., description="Api"),
+):
+    api_obj = await api_repository.get(id=id)
+    data = await api_obj.to_dict()
+    return Success(data=data)
+
+
+@router.post("/create", summary="创建Api", response_model=Success[None])
+async def create_api(
+    api_in: ApiCreateDTO,
+):
+    await api_repository.create(obj_in=api_in)
+    return Success(msg="Created Successfully")
+
+
+@router.post("/update", summary="更新Api", response_model=Success[None])
+async def update_api(
+    api_in: ApiUpdateDTO,
+):
+    await api_repository.update(id=api_in.id, obj_in=api_in)
+    return Success(msg="Update Successfully")
+
+
+@router.delete("/delete", summary="删除Api", response_model=Success[None])
+async def delete_api(
+    api_id: int = Query(..., description="ApiID"),
+):
+    await api_repository.remove(id=api_id)
+    return Success(msg="Deleted Success")
+
+
+@router.post("/refresh", summary="刷新API列表", response_model=Success[None])
+async def refresh_api():
+    await api_repository.refresh_api()
+    return Success(msg="OK")

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

@@ -0,0 +1,14 @@
+from tortoise import fields
+
+from common.enums import MethodType
+from common.models import BaseModel, TimestampModel
+
+
+class Api(BaseModel, TimestampModel):
+    path = fields.CharField(max_length=100, description="API路径", db_index=True)
+    method = fields.CharEnumField(MethodType, description="请求方法", db_index=True)
+    summary = fields.CharField(max_length=500, description="请求简介", db_index=True)
+    tags = fields.CharField(max_length=100, description="API标签", db_index=True)
+
+    class Meta:
+        table = "api"

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

@@ -0,0 +1,65 @@
+from fastapi.routing import APIRoute
+
+from common.repositories import CRUDBase
+from log import logger
+
+from .model import Api
+from .schema import ApiCreateDTO, ApiUpdateDTO
+
+
+class ApiRepository(CRUDBase[Api, ApiCreateDTO, ApiUpdateDTO]):
+    def __init__(self):
+        super().__init__(model=Api)
+
+    async def refresh_api(self):
+        from src import app
+
+        routes = app.routes
+
+        # 删除废弃API数据
+        all_api_list = []
+        for route in app.routes:
+            # 只更新有鉴权的API
+            if isinstance(route, APIRoute) and len(route.dependencies) > 0:
+                all_api_list.append((list(route.methods)[0], route.path_format))
+
+        # 只查询 method 和 path 字段
+        existing_apis = await Api.all().values("method", "path")
+        existing_api_set = {(api["method"], api["path"]) for api in existing_apis}
+        delete_api_set = existing_api_set - set(all_api_list)
+
+        # 批量删除废弃API
+        for method, path in delete_api_set:
+            logger.debug(f"API Deleted {method} {path}")
+            await Api.filter(method=method, path=path).delete()
+
+        # 更新或创建API
+        for route in routes:
+            if isinstance(route, APIRoute) and len(route.dependencies) > 0:
+                method = list(route.methods)[0]
+                path = route.path_format
+                summary = route.summary
+                tags = list(route.tags)[0]
+                api_obj = await Api.filter(method=method, path=path).first()
+                if api_obj:
+                    await api_obj.update_from_dict(
+                        {
+                            "method": method,
+                            "path": path,
+                            "summary": summary,
+                            "tags": tags,
+                        }
+                    ).save()
+                else:
+                    logger.debug(f"API Created {method} {path}")
+                    await Api.create(
+                        **{
+                            "method": method,
+                            "path": path,
+                            "summary": summary,
+                            "tags": tags,
+                        }
+                    )
+
+
+api_repository = ApiRepository()

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

@@ -0,0 +1,39 @@
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+from common.enums import MethodType
+
+
+class ApiVO(BaseModel):
+    """API响应模型"""
+
+    id: int
+    path: str = Field(..., description="API路径", example="/api/v1/user/list")
+    summary: str = Field("", description="API简介", example="查看用户列表")
+    method: MethodType = Field(..., description="API方法", example="GET")
+    tags: str = Field(..., description="API标签", example="User")
+    created_at: datetime | None = Field(None, description="创建时间")
+    updated_at: datetime | None = Field(None, description="更新时间")
+    deleted_at: datetime | None = Field(None, description="删除时间")
+
+
+class ApiBaseDTO(BaseModel):
+    """API基础字段"""
+
+    path: str = Field(..., description="API路径", example="/api/v1/user/list")
+    summary: str = Field("", description="API简介", example="查看用户列表")
+    method: MethodType = Field(..., description="API方法", example="GET")
+    tags: str = Field(..., description="API标签", example="User")
+
+
+class ApiCreateDTO(ApiBaseDTO):
+    """创建API请求参数"""
+
+    pass
+
+
+class ApiUpdateDTO(ApiBaseDTO):
+    """更新API请求参数"""
+
+    id: int

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

@@ -0,0 +1,8 @@
+from fastapi import APIRouter
+
+from .controller import router
+
+auditlog_router = APIRouter()
+auditlog_router.include_router(router, tags=["审计日志模块"])
+
+__all__ = ["auditlog_router"]

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

@@ -0,0 +1,54 @@
+from datetime import datetime
+
+from fastapi import APIRouter, Query
+from tortoise.expressions import Q
+
+from common.schemas.response_schema import SuccessPagination
+
+from .model import AuditLog
+from .schema import AuditLogVO
+
+router = APIRouter()
+
+
+@router.get(
+    "/list", summary="查看操作日志", response_model=SuccessPagination[AuditLogVO]
+)
+async def get_audit_log_list(
+    page: int = Query(1, description="页码"),
+    page_size: int = Query(10, description="每页数量"),
+    username: str = Query("", description="操作人名称"),
+    module: str = Query("", description="功能模块"),
+    method: str = Query("", description="请求方法"),
+    summary: str = Query("", description="接口描述"),
+    status: int = Query(None, description="状态码"),
+    start_time: datetime = Query("", description="开始时间"),
+    end_time: datetime = Query("", description="结束时间"),
+):
+    q = Q()
+    if username:
+        q &= Q(username__icontains=username)
+    if module:
+        q &= Q(module__icontains=module)
+    if method:
+        q &= Q(method__icontains=method)
+    if summary:
+        q &= Q(summary__icontains=summary)
+    if status:
+        q &= Q(status=status)
+    if start_time and end_time:
+        q &= Q(created_at__range=[start_time, end_time])
+    elif start_time:
+        q &= Q(created_at__gte=start_time)
+    elif end_time:
+        q &= Q(created_at__lte=end_time)
+
+    audit_log_objs = (
+        await AuditLog.filter(q)
+        .offset((page - 1) * page_size)
+        .limit(page_size)
+        .order_by("-created_at")
+    )
+    total = await AuditLog.filter(q).count()
+    data = [await audit_log.to_dict() for audit_log in audit_log_objs]
+    return SuccessPagination(data=data, total=total, page=page, page_size=page_size)

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

@@ -0,0 +1,31 @@
+from tortoise import fields
+
+from common.models import BaseModel, TimestampModel
+
+
+class AuditLog(BaseModel, TimestampModel):
+    user_id = fields.IntField(description="用户ID", db_index=True)
+    username = fields.CharField(
+        max_length=64, default="", description="用户名称", db_index=True
+    )
+    module = fields.CharField(
+        max_length=64, default="", description="功能模块", db_index=True
+    )
+    summary = fields.CharField(
+        max_length=128, default="", description="请求描述", db_index=True
+    )
+    method = fields.CharField(
+        max_length=10, default="", description="请求方法", db_index=True
+    )
+    path = fields.CharField(
+        max_length=255, default="", description="请求路径", db_index=True
+    )
+    status = fields.IntField(default=-1, description="状态码", db_index=True)
+    response_time = fields.IntField(
+        default=0, description="响应时间(单位ms)", db_index=True
+    )
+    request_args = fields.JSONField(null=True, description="请求参数")
+    response_body = fields.JSONField(null=True, description="返回数据")
+
+    class Meta:
+        table = "audit_log"

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

@@ -0,0 +1,21 @@
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+
+class AuditLogVO(BaseModel):
+    """审计日志响应模型"""
+
+    id: int
+    user_id: int = Field(..., description="用户ID", example=1)
+    username: str = Field(..., description="用户名称", example="admin")
+    module: str = Field(..., description="功能模块", example="用户管理")
+    summary: str = Field(..., description="接口描述", example="查看用户列表")
+    method: str = Field(..., description="请求方法", example="GET")
+    path: str = Field(..., description="请求路径", example="/api/v1/user/list")
+    status: int = Field(..., description="状态码", example=200)
+    response_time: int = Field(..., description="响应时间(单位ms)", example=125)
+    request_args: dict | None = Field(None, description="请求参数")
+    response_body: dict | None = Field(None, description="返回数据")
+    created_at: datetime | None = Field(None, description="创建时间")
+    updated_at: datetime | None = Field(None, description="更新时间")