@stephen-lord/docs 1.0.0 → 1.0.1

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

@@ -0,0 +1,3 @@
+from .request import MethodType
+
+__all__ = ["MethodType"]

package/dist-repo/fastapi-backend/src/common/enums/request.py

@@ -0,0 +1,11 @@
+"""请求相关的枚举值"""
+
+from enum import StrEnum
+
+
+class MethodType(StrEnum):
+    GET = "GET"
+    POST = "POST"
+    PUT = "PUT"
+    DELETE = "DELETE"
+    PATCH = "PATCH"

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

@@ -0,0 +1,5 @@
+from .base_model import BaseModel
+from .soft_delete_model import SoftDeleteModel
+from .timestamp_model import TimestampModel
+
+__all__ = ["BaseModel", "TimestampModel", "SoftDeleteModel"]

package/dist-repo/fastapi-backend/src/common/models/base_model.py

@@ -0,0 +1,53 @@
+import asyncio
+from datetime import datetime
+
+from tortoise import fields, models
+
+from config.settings import settings
+
+
+class BaseModel(models.Model):
+    id = fields.BigIntField(primary_key=True, db_index=True)
+
+    async def to_dict(self, m2m: bool = False, exclude_fields: list[str] | None = None):
+        if exclude_fields is None:
+            exclude_fields = []
+
+        d = {}
+        for field in self._meta.db_fields:
+            if field not in exclude_fields:
+                value = getattr(self, field)
+                if isinstance(value, datetime):
+                    value = value.strftime(settings.DATETIME_FORMAT)
+                d[field] = value
+
+        if m2m:
+            tasks = [
+                self.__fetch_m2m_field(field, exclude_fields)
+                for field in self._meta.m2m_fields
+                if field not in exclude_fields
+            ]
+            results = await asyncio.gather(*tasks)
+            for field, values in results:
+                d[field] = values
+
+        return d
+
+    async def __fetch_m2m_field(self, field, exclude_fields):
+        values = await getattr(self, field).all().values()
+        formatted_values = []
+
+        for value in values:
+            formatted_value = {}
+            for k, v in value.items():
+                if k not in exclude_fields:
+                    if isinstance(v, datetime):
+                        formatted_value[k] = v.strftime(settings.DATETIME_FORMAT)
+                    else:
+                        formatted_value[k] = v
+            formatted_values.append(formatted_value)
+
+        return field, formatted_values
+
+    class Meta:
+        abstract = True

package/dist-repo/fastapi-backend/src/common/models/soft_delete_model.py

@@ -0,0 +1,5 @@
+from tortoise import fields
+
+
+class SoftDeleteModel:
+    deleted_at = fields.DatetimeField(null=True)

package/dist-repo/fastapi-backend/src/common/models/timestamp_model.py

@@ -0,0 +1,6 @@
+from tortoise import fields
+
+
+class TimestampModel:
+    created_at = fields.DatetimeField(auto_now_add=True, db_index=True)
+    updated_at = fields.DatetimeField(auto_now=True, db_index=True)

package/dist-repo/fastapi-backend/src/common/models/uuid_model.py

@@ -0,0 +1,5 @@
+from tortoise import fields
+
+
+class UUIDModel:
+    uuid = fields.UUIDField(unique=True, primary_key=False, db_index=True)

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

@@ -0,0 +1,4 @@
+from .crud_base_repository import CRUDBase
+from .crud_batch_repository import CRUDBatch
+
+__all__ = ["CRUDBase", "CRUDBatch"]

package/dist-repo/fastapi-backend/src/common/repositories/crud_base_repository.py

@@ -0,0 +1,288 @@
+from typing import Any, NewType, TypeVar
+
+from pydantic import BaseModel
+from tortoise.expressions import Q
+from tortoise.models import Model
+
+Total = NewType("Total", int)
+ModelType = TypeVar("ModelType", bound=Model)
+CreateSchemaType = TypeVar("CreateSchemaType", bound=BaseModel)
+UpdateSchemaType = TypeVar("UpdateSchemaType", bound=BaseModel)
+
+
+class CRUDBase[
+    ModelType: Model,
+    CreateSchemaType: BaseModel,
+    UpdateSchemaType: BaseModel,
+]:
+    def __init__(self, model: type[ModelType]):
+        self.model = model
+
+    async def get_by_id(self, id: int) -> ModelType:
+        """
+        根据ID获取单个对象
+
+        Args:
+            id: 对象的主键ID
+
+        Returns:
+            ModelType: 查询到的模型对象
+
+        Raises:
+            DoesNotExist: 当指定ID的对象不存在时抛出异常
+
+        Example:
+            user = await user_crud.get_by_id(1)
+        """
+        return await self.model.get(id=id)
+
+    async def get(self, **filters: Any) -> ModelType:
+        """
+        通用获取方法：支持通过任意字段过滤获取单个对象
+
+        Args:
+            **filters: 过滤条件，支持任意字段名和值的组合
+
+        Returns:
+            ModelType: 查询到的模型对象
+
+        Raises:
+            DoesNotExist: 当没有匹配的对象时抛出异常
+            MultipleObjectsReturned: 当匹配到多个对象时抛出异常
+
+        Examples:
+            user = await user_crud.get(id=1)
+            user = await user_crud.get(username="alice")
+            user = await user_crud.get(email="alice@example.com", is_active=True)
+        """
+        return await self.model.get(**filters)
+
+    async def list(
+        self, page: int, page_size: int, search: Q = Q(), order: list | None = None
+    ) -> tuple[Total, list[ModelType]]:
+        """
+        分页查询列表数据
+
+        Args:
+            page: 页码，从1开始
+            page_size: 每页数据量
+            search: Tortoise Q对象，用于复杂查询条件，默认为空查询
+            order: 排序字段列表，默认为空列表（不排序）
+
+        Returns:
+            tuple[Total, list[ModelType]]: 返回元组，包含总数和当前页数据列表
+
+        Examples:
+            # 基础分页
+            total, users = await user_crud.list(page=1, page_size=10)
+
+            # 带搜索条件的分页
+            search_q = Q(username__icontains="alice") | Q(email__icontains="alice")
+            total, users = await user_crud.list(page=1, page_size=10, search=search_q)
+
+            # 带排序的分页
+            total, users = await user_crud.list(page=1, page_size=10, order=["-created_at", "username"])
+        """
+        query = self.model.filter(search)
+        if order is None:
+            order = []
+        return await query.count(), await query.offset((page - 1) * page_size).limit(
+            page_size
+        ).order_by(*order)
+
+    async def create(self, obj_in: CreateSchemaType) -> ModelType:
+        """
+        创建新对象
+
+        Args:
+            obj_in: 创建数据，可以是Pydantic模型实例或字典
+
+        Returns:
+            ModelType: 创建成功的模型对象
+
+        Examples:
+            # 使用Pydantic模型创建
+            user_data = UserCreateSchema(username="alice", email="alice@example.com")
+            user = await user_crud.create(user_data)
+
+            # 使用字典创建
+            user_dict = {"username": "bob", "email": "bob@example.com"}
+            user = await user_crud.create(user_dict)
+        """
+        if isinstance(obj_in, dict):
+            obj_dict = obj_in
+        else:
+            obj_dict = obj_in.model_dump()
+        obj = self.model(**obj_dict)
+        await obj.save()
+        return obj
+
+    async def update_by_id(
+        self, id: int, obj_in: UpdateSchemaType | dict[str, Any]
+    ) -> ModelType:
+        """
+        根据ID更新对象
+
+        Args:
+            id: 要更新对象的主键ID
+            obj_in: 更新数据，可以是Pydantic模型实例或字典
+
+        Returns:
+            ModelType: 更新后的模型对象
+
+        Raises:
+            DoesNotExist: 当指定ID的对象不存在时抛出异常
+
+        Examples:
+            # 使用Pydantic模型更新
+            update_data = UserUpdateSchema(username="alice_new")
+            user = await user_crud.update_by_id(1, update_data)
+
+            # 使用字典更新
+            update_dict = {"username": "alice_updated", "is_active": False}
+            user = await user_crud.update_by_id(1, update_dict)
+        """
+        if isinstance(obj_in, dict):
+            obj_dict = obj_in
+        else:
+            obj_dict = obj_in.model_dump(exclude_unset=True, exclude={"id"})
+        obj = await self.get_by_id(id=id)
+        obj = obj.update_from_dict(obj_dict)
+        await obj.save()
+        return obj
+
+    async def update(
+        self, filters: dict[str, Any], obj_in: UpdateSchemaType | dict[str, Any]
+    ) -> ModelType:
+        """
+        通用更新方法：支持通过任意字段过滤并更新单个对象
+
+        Args:
+            filters: 过滤条件字典，用于定位要更新的对象
+            obj_in: 更新数据，可以是Pydantic模型实例或字典
+
+        Returns:
+            ModelType: 更新后的模型对象
+
+        Raises:
+            DoesNotExist: 当没有匹配的对象时抛出异常
+            MultipleObjectsReturned: 当匹配到多个对象时抛出异常
+
+        Examples:
+            # 根据用户名更新
+            update_data = {"email": "newemail@example.com"}
+            user = await user_crud.update({"username": "alice"}, update_data)
+
+            # 根据多个条件更新
+            filters = {"username": "alice", "is_active": True}
+            update_data = UserUpdateSchema(last_login=datetime.now())
+            user = await user_crud.update(filters, update_data)
+        """
+        if isinstance(obj_in, dict):
+            obj_dict = obj_in
+        else:
+            obj_dict = obj_in.model_dump(exclude_unset=True)
+        obj = await self.get(**filters)
+        obj = obj.update_from_dict(obj_dict)
+        await obj.save()
+        return obj
+
+    async def delete_by_id(self, id: int) -> None:
+        """
+        根据ID删除对象
+
+        Args:
+            id: 要删除对象的主键ID
+
+        Returns:
+            None
+
+        Raises:
+            DoesNotExist: 当指定ID的对象不存在时抛出异常
+
+        Example:
+            await user_crud.delete_by_id(1)
+        """
+        obj = await self.get_by_id(id=id)
+        await obj.delete()
+
+    async def delete(self, **filters: Any) -> int:
+        """
+        通用删除方法：支持通过任意字段删除，返回删除的行数
+
+        Args:
+            **filters: 过滤条件，支持任意字段名和值的组合
+
+        Returns:
+            int: 删除的行数
+
+        Examples:
+            # 根据ID删除
+            deleted_count = await user_crud.delete(id=1)
+
+            # 根据状态批量删除
+            deleted_count = await user_crud.delete(status="inactive")
+
+            # 根据多个条件删除
+            deleted_count = await user_crud.delete(is_active=False, created_at__lt=some_date)
+        """
+        return await self.model.filter(**filters).delete()
+
+    # async def upsert(
+    #     self,
+    #     obj_in: CreateSchemaType | dict[str, Any],
+    #     conflict_fields: list[str],
+    #     update_fields: list[str] | None = None
+    # ) -> ModelType:
+    #     """
+    #     插入或更新对象（如果存在冲突则更新）
+
+    #     Args:
+    #         obj_in: 要插入或更新的对象数据，可以是Pydantic模型实例或字典
+    #         conflict_fields: 冲突字段列表，用于判断是否需要更新
+    #         update_fields: 需要更新的字段列表，如果为None则更新所有字段（除了冲突字段）
+
+    #     Returns:
+    #         ModelType: 插入或更新后的模型对象
+
+    #     Examples:
+    #         # 基础upsert操作
+    #         user_data = {"email": "user@example.com", "name": "User", "age": 25}
+    #         user = await user_crud.upsert(user_data, conflict_fields=["email"])
+
+    #         # 指定更新字段的upsert操作
+    #         user_data = UserCreateSchema(email="user@example.com", name="Updated User", age=30)
+    #         user = await user_crud.upsert(
+    #             user_data,
+    #             conflict_fields=["email"],
+    #             update_fields=["name", "age"]
+    #         )
+
+    #         # 多字段冲突检测
+    #         user = await user_crud.upsert(
+    #             {"username": "alice", "email": "alice@example.com", "department": "IT"},
+    #             conflict_fields=["username", "email"]
+    #         )
+    #     """
+    #     if isinstance(obj_in, dict):
+    #         obj_dict = obj_in
+    #     else:
+    #         obj_dict = obj_in.model_dump()
+
+    #     # 如果没有指定update_fields，则更新除冲突字段外的所有字段
+    #     if update_fields is None:
+    #         update_fields = [field for field in obj_dict.keys() if field not in conflict_fields]
+
+    #     obj = self.model(**obj_dict)
+
+    #     # 使用bulk_create的on_conflict参数实现upsert
+    #     await self.model.bulk_create(
+    #         [obj],
+    #         on_conflict=conflict_fields,
+    #         update_fields=update_fields
+    #     )
+
+    #     # 返回插入或更新后的对象
+    #     # 根据冲突字段构建查询条件
+    #     filter_conditions = {field: obj_dict[field] for field in conflict_fields if field in obj_dict}
+    #     return await self.get(**filter_conditions)

package/dist-repo/fastapi-backend/src/common/repositories/crud_batch_repository.py

@@ -0,0 +1,127 @@
+from typing import Any, TypeVar
+
+from pydantic import BaseModel
+from tortoise.models import Model
+
+ModelType = TypeVar("ModelType", bound=Model)
+CreateSchemaType = TypeVar("CreateSchemaType", bound=BaseModel)
+UpdateSchemaType = TypeVar("UpdateSchemaType", bound=BaseModel)
+
+
+class CRUDBatch[
+    ModelType: Model,
+    CreateSchemaType: BaseModel,
+    UpdateSchemaType: BaseModel,
+]:
+    def __init__(self, model: type[ModelType]):
+        self.model = model
+
+    async def batch_create(
+        self, objs_in: list[CreateSchemaType | dict[str, Any]], batch_size: int = 100
+    ) -> list[ModelType]:
+        """
+        批量创建对象
+
+        Args:
+            objs_in: 要创建的对象列表，可以是Pydantic模型或字典
+            batch_size: 每批次处理的对象数量，默认100
+
+        Returns:
+            创建的对象列表
+
+        Example:
+            await crud_batch.batch_create([
+                {"name": "user1", "email": "user1@example.com"},
+                {"name": "user2", "email": "user2@example.com"}
+            ])
+        """
+        obj_dicts = []
+        for obj_in in objs_in:
+            if isinstance(obj_in, dict):
+                obj_dicts.append(obj_in)
+            else:
+                obj_dicts.append(obj_in.model_dump())
+
+        objs = [self.model(**obj_dict) for obj_dict in obj_dicts]
+        await self.model.bulk_create(objs, batch_size=batch_size)
+        return objs
+
+    async def batch_update(
+        self, filters: dict[str, Any], obj_in: UpdateSchemaType | dict[str, Any]
+    ) -> int:
+        """
+        批量更新对象
+
+        Args:
+            filters: 过滤条件，用于确定要更新的对象
+            obj_in: 更新数据，可以是Pydantic模型或字典
+
+        Returns:
+            更新的对象数量
+
+        Example:
+            await crud_batch.batch_update(
+                {"status": "active"},
+                {"last_login": datetime.now()}
+            )
+        """
+        if isinstance(obj_in, dict):
+            obj_dict = obj_in
+        else:
+            obj_dict = obj_in.model_dump(exclude_unset=True)
+
+        return await self.model.filter(**filters).update(**obj_dict)
+
+    async def batch_delete(self, filters: dict[str, Any]) -> int:
+        """
+        批量删除对象
+
+        Args:
+            filters: 过滤条件，用于确定要删除的对象
+
+        Returns:
+            删除的对象数量
+
+        Example:
+            await crud_batch.batch_delete({"status": "inactive"})
+        """
+        return await self.model.filter(**filters).delete()
+
+    async def batch_upsert(
+        self,
+        objs_in: list[CreateSchemaType | dict[str, Any]],
+        conflict_fields: list[str],
+        batch_size: int = 100,
+    ) -> list[ModelType]:
+        """
+        批量插入或更新对象（如果存在冲突则更新）
+
+        Args:
+            objs_in: 要插入或更新的对象列表
+            conflict_fields: 冲突字段列表，用于判断是否需要更新
+            batch_size: 每批次处理的对象数量，默认100
+
+        Returns:
+            处理后的对象列表
+
+        Example:
+            await crud_batch.batch_upsert(
+                [{"email": "user@example.com", "name": "User"}],
+                conflict_fields=["email"]
+            )
+        """
+        obj_dicts = []
+        for obj_in in objs_in:
+            if isinstance(obj_in, dict):
+                obj_dicts.append(obj_in)
+            else:
+                obj_dicts.append(obj_in.model_dump())
+
+        objs = [self.model(**obj_dict) for obj_dict in obj_dicts]
+        await self.model.bulk_create(
+            objs,
+            on_conflict=conflict_fields,
+            update_fields=list(obj_dicts[0].keys()) if obj_dicts else [],
+            batch_size=batch_size,
+        )
+        return objs

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

@@ -0,0 +1,19 @@
+from .auth_schema import (
+    CredentialsSchema,
+    JWTOut,
+    JWTPayload,
+    RefreshTokenRequest,
+    TokenRefreshOut,
+)
+from .response_schema import Fail, Success, SuccessPagination
+
+__all__ = [
+    "CredentialsSchema",
+    "JWTOut",
+    "JWTPayload",
+    "RefreshTokenRequest",
+    "TokenRefreshOut",
+    "Fail",
+    "Success",
+    "SuccessPagination",
+]

package/dist-repo/fastapi-backend/src/common/schemas/auth_schema.py

@@ -0,0 +1,33 @@
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+
+class CredentialsSchema(BaseModel):
+    username: str = Field(..., description="用户名称", example="admin")
+    password: str = Field(..., description="密码", example="请输入正确的测试密码")
+
+
+class JWTOut(BaseModel):
+    access_token: str
+    refresh_token: str
+    username: str
+    token_type: str = "bearer"
+    expires_in: int  # 过期时间（秒）
+
+
+class JWTPayload(BaseModel):
+    user_id: int
+    exp: datetime
+    token_type: str = "access"  # access 或 refresh
+
+
+class RefreshTokenRequest(BaseModel):
+    refresh_token: str = Field(..., description="刷新令牌")
+
+
+class TokenRefreshOut(BaseModel):
+    access_token: str
+    refresh_token: str
+    token_type: str = "bearer"
+    expires_in: int  # 新access_token过期时间（秒）

package/dist-repo/fastapi-backend/src/common/schemas/response_schema.py

@@ -0,0 +1,38 @@
+from typing import TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field
+
+T = TypeVar("T")
+
+
+class Success[T](BaseModel):
+    """成功响应 - 固定 code=200"""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    code: int = Field(default=200, description="状态码")
+    msg: str | None = Field(default="OK", description="消息")
+    data: T | None = Field(default=None, description="数据")
+
+
+class Fail[T](BaseModel):
+    """失败响应 - 默认 code=400"""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    code: int = Field(default=400, description="状态码")
+    msg: str | None = Field(default=None, description="消息")
+    data: T | None = Field(default=None, description="数据")
+
+
+class SuccessPagination[T](BaseModel):
+    """分页成功响应 - 固定 code=200"""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    code: int = Field(default=200, description="状态码")
+    msg: str | None = Field(default="OK", description="消息")
+    data: T | None = Field(default=None, description="数据")
+    total: int = Field(default=0, description="总数")
+    page: int = Field(default=1, description="当前页")
+    page_size: int = Field(default=20, description="每页数量")

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

@@ -0,0 +1,3 @@
+from .settings import settings as settings
+
+TORTOISE_ORM = settings.TORTOISE_ORM