aury-boot 0.0.2__py3-none-any.whl → 0.0.4__py3-none-any.whl

aury/boot/domain/models/__init__.py

@@ -0,0 +1,51 @@
+"""领域模型模块。
+
+提供 ORM 模型基类、Mixin 和常用组合模型。
+"""
+
+from .base import GUID, Base
+from .mixins import (
+    AuditableStateMixin,
+    IDMixin,
+    TimestampMixin,
+    UUIDMixin,
+    VersionMixin,
+)
+from .models import (
+    AuditableStateModel,
+    FullFeaturedModel,
+    FullFeaturedUUIDModel,
+    IDOnlyModel,
+    Model,
+    UUIDAuditableStateModel,
+    UUIDModel,
+    UUIDOnlyModel,
+    VersionedModel,
+    VersionedTimestampedModel,
+    VersionedUUIDModel,
+)
+
+__all__ = [
+    "GUID",
+    "AuditableStateMixin",
+    "AuditableStateModel",
+    # 基类和类型装饰器
+    "Base",
+    "FullFeaturedModel",
+    "FullFeaturedUUIDModel",
+    # Mixins
+    "IDMixin",
+    "IDOnlyModel",
+    # 组合模型
+    "Model",
+    "TimestampMixin",
+    "UUIDAuditableStateModel",
+    "UUIDMixin",
+    "UUIDModel",
+    "UUIDOnlyModel",
+    "VersionMixin",
+    "VersionedModel",
+    "VersionedTimestampedModel",
+    "VersionedUUIDModel",
+]
+

aury/boot/domain/models/base.py

@@ -0,0 +1,69 @@
+"""模型基类和类型装饰器。
+
+提供 SQLAlchemy 2.0 声明式基类和跨数据库类型装饰器。
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+from sqlalchemy import String
+from sqlalchemy.orm import DeclarativeBase
+from sqlalchemy.types import TypeDecorator
+
+from aury.boot.common.logging import logger
+
+if TYPE_CHECKING:
+    pass
+
+
+class GUID(TypeDecorator):
+    """跨数据库 UUID 类型装饰器。
+
+    自动适配不同数据库：
+    - PostgreSQL: 使用原生 UUID 类型（需要安装 [pg] 可选依赖）
+    - 其他数据库: 使用 CHAR(36) 存储字符串格式的 UUID
+    """
+
+    impl = String(36)
+    cache_ok = True
+
+    def load_dialect_impl(self, dialect):
+        if dialect.name == "postgresql":
+            # PostgreSQL: 使用原生 UUID 类型
+            try:
+                from sqlalchemy.dialects.postgresql import UUID as PGUUID
+                return dialect.type_descriptor(PGUUID(as_uuid=True))
+            except ImportError:
+                # 如果未安装 PostgreSQL 支持，回退到字符串
+                logger.warning(
+                    "PostgreSQL UUID 支持需要安装 [pg] 可选依赖："
+                    "pip install aury-boot[pg]"
+                )
+                return dialect.type_descriptor(String(36))
+        else:
+            # 其他数据库: 使用字符串
+            return dialect.type_descriptor(String(36))
+
+    def process_bind_param(self, value, dialect):
+        if value is None:
+            return value
+        if not isinstance(value, UUID):
+            raise TypeError(f"Expected UUID, got {type(value)}")
+        return str(value)
+
+    def process_result_value(self, value, dialect):
+        if value is None:
+            return value
+        if isinstance(value, UUID):
+            return value
+        return UUID(value)
+
+
+class Base(DeclarativeBase):
+    """SQLAlchemy 2.0 声明式基类"""
+
+    # 自动生成表名逻辑（可选，例如将 UserProfile 转为 user_profile）
+    # pass
+

aury/boot/domain/models/mixins.py

@@ -0,0 +1,135 @@
+"""模型功能 Mixins。
+
+提供可组合的功能 Mixin，包括主键、时间戳、软删除、乐观锁等。
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+import time
+from typing import TYPE_CHECKING
+import uuid
+
+from sqlalchemy import BigInteger, DateTime, Integer, func, text
+from sqlalchemy.orm import Mapped, mapped_column
+from sqlalchemy.types import Uuid as SQLAlchemyUuid
+
+if TYPE_CHECKING:
+    from sqlalchemy.sql import Select
+
+
+class IDMixin:
+    """标准自增主键 Mixin"""
+
+    id: Mapped[int] = mapped_column(
+        Integer,
+        primary_key=True,
+        autoincrement=True,
+        sort_order=-1,  # 确保 ID 在 DDL 中排在前面
+        comment="主键ID",
+    )
+
+
+class UUIDMixin:
+    """UUID 主键 Mixin"""
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        SQLAlchemyUuid(as_uuid=True),  # 2.0 会自动适配 PG(uuid) 和 MySQL(char(36))
+        primary_key=True,
+        default=uuid.uuid4,
+        sort_order=-1,
+        comment="UUID主键",
+    )
+
+
+class TimestampMixin:
+    """创建/更新时间 Mixin"""
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        sort_order=99,
+        comment="创建时间",
+    )
+
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        onupdate=func.now(),  # 使用数据库层面的更新，比 Python lambda 更准确
+        sort_order=99,
+        comment="更新时间",
+    )
+
+
+class AuditableStateMixin:
+    """可审计状态 Mixin (软删除核心优化版)
+
+    采用 '默认 0' 策略：
+    - deleted_at = 0: 未删除
+    - deleted_at > 0: 已删除 (Unix 时间戳)
+
+    优势：
+    1. 完美支持 MySQL 唯一索引 UNIQUE(email, deleted_at)。
+    2. 整数索引查询极快。
+    3. 可以记录删除时间（审计支持）。
+    """
+
+    deleted_at: Mapped[int] = mapped_column(
+        BigInteger,
+        default=0,
+        server_default=text("0"),  # 确保数据库层面默认值也是 0
+        index=True,
+        comment="删除时间戳(0=未删)",
+    )
+
+    @property
+    def is_deleted(self) -> bool:
+        """判断是否已删除。"""
+        return self.deleted_at > 0
+
+    def mark_deleted(self) -> None:
+        """标记为已删除。"""
+        self.deleted_at = int(time.time())
+
+    def restore(self) -> None:
+        """恢复数据。"""
+        self.deleted_at = 0
+
+    @classmethod
+    def not_deleted(cls) -> Select:
+        """返回未删除记录的查询条件（用于 SQLAlchemy 查询）。
+        
+        注意：这是简单的工具方法，仅构建查询对象，不执行查询。
+        实际查询应在 Repository 层执行。
+        """
+        from sqlalchemy import select  # 延迟导入避免循环依赖
+
+        return select(cls).where(cls.deleted_at == 0)
+
+    @classmethod
+    def with_deleted(cls) -> Select:
+        """返回包含已删除记录的查询（用于审计）。
+        
+        注意：这是简单的工具方法，仅构建查询对象，不执行查询。
+        实际查询应在 Repository 层执行。
+        """
+        from sqlalchemy import select  # 延迟导入避免循环依赖
+
+        return select(cls)
+
+
+class VersionMixin:
+    """乐观锁版本控制 Mixin"""
+
+    version: Mapped[int] = mapped_column(
+        Integer,
+        default=1,
+        server_default=text("1"),
+        nullable=False,
+        comment="乐观锁版本号",
+    )
+
+    __mapper_args__ = {
+        "version_id_col": "version"  # SQLAlchemy 自动处理乐观锁逻辑
+    }
+

aury/boot/domain/models/models.py

@@ -0,0 +1,96 @@
+"""常用组合模型。
+
+提供预定义的模型组合，方便直接使用。
+
+**重要提示**：不要直接继承 Base 类用于 Repository，必须使用下列预定义模型或自己组合 Mixin。
+直接使用 Base 会导致缺少 id 等必要字段，Repository 会报错。
+
+可用模型：
+- Model: 标准模型（int主键 + 时间戳）
+- AuditableStateModel: 标准模型 + 软删除
+- UUIDModel: UUID 主键模型（UUID 主键 + 时间戳）
+- UUIDAuditableStateModel: UUID 主键模型 + 软删除
+- VersionedModel: 乐观锁模型（int主键 + 乐观锁）
+- VersionedTimestampedModel: 乐观锁 + 时间戳
+- VersionedUUIDModel: UUID 主键 + 乐观锁 + 时间戳
+- FullFeaturedModel: 完整功能（int主键 + 时间戳 + 软删除 + 乐观锁）
+- FullFeaturedUUIDModel: 完整功能 UUID 版本
+"""
+
+from __future__ import annotations
+
+from .base import Base
+from .mixins import (
+    AuditableStateMixin,
+    IDMixin,
+    TimestampMixin,
+    UUIDMixin,
+    VersionMixin,
+)
+
+
+class IDOnlyModel(IDMixin, Base):
+    """纯 int 主键模型（无时间戳，适合关系表）"""
+
+    __abstract__ = True
+
+
+class UUIDOnlyModel(UUIDMixin, Base):
+    """纯 UUID 主键模型（无时间戳，适合关系表）"""
+
+    __abstract__ = True
+
+
+class Model(IDMixin, TimestampMixin, Base):
+    """【常用】标准整数主键模型"""
+
+    __abstract__ = True
+
+
+class AuditableStateModel(IDMixin, TimestampMixin, AuditableStateMixin, Base):
+    """【常用】带可审计状态的标准模型（整数主键 + 时间戳 + 软删除）"""
+
+    __abstract__ = True
+
+
+class UUIDModel(UUIDMixin, TimestampMixin, Base):
+    """【常用】UUID 主键模型"""
+
+    __abstract__ = True
+
+
+class UUIDAuditableStateModel(UUIDMixin, TimestampMixin, AuditableStateMixin, Base):
+    """【常用】带可审计状态的 UUID 主键模型（UUID 主键 + 时间戳 + 软删除）"""
+
+    __abstract__ = True
+
+
+class VersionedModel(IDMixin, VersionMixin, Base):
+    """整数主键 + 乐观锁"""
+
+    __abstract__ = True
+
+
+class VersionedTimestampedModel(IDMixin, TimestampMixin, VersionMixin, Base):
+    """整数主键 + 时间戳 + 乐观锁"""
+
+    __abstract__ = True
+
+
+class VersionedUUIDModel(UUIDMixin, TimestampMixin, VersionMixin, Base):
+    """UUID 主键 + 时间戳 + 乐观锁"""
+
+    __abstract__ = True
+
+
+class FullFeaturedModel(IDMixin, TimestampMixin, AuditableStateMixin, VersionMixin, Base):
+    """完整功能：整数主键 + 时间戳 + 可审计状态 + 乐观锁"""
+
+    __abstract__ = True
+
+
+class FullFeaturedUUIDModel(UUIDMixin, TimestampMixin, AuditableStateMixin, VersionMixin, Base):
+    """完整功能：UUID 主键 + 时间戳 + 可审计状态 + 乐观锁"""
+
+    __abstract__ = True
+

aury/boot/domain/pagination/__init__.py

@@ -0,0 +1,279 @@
+"""分页和排序标准化模块。
+
+提供统一的分页和排序参数定义，以及分页结果封装。
+使用 Pydantic 2.5 进行数据验证和序列化。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class PaginationParams(BaseModel):
+    """分页参数。
+    
+    定义分页查询的参数，包括页码和每页记录数。
+    """
+    
+    page: int = Field(default=1, ge=1, description="页码，从1开始")
+    page_size: int = Field(default=20, ge=1, le=100, description="每页记录数，最大100")
+    
+    @property
+    def offset(self) -> int:
+        """计算偏移量。
+        
+        Returns:
+            int: 偏移量
+        """
+        return (self.page - 1) * self.page_size
+    
+    @property
+    def limit(self) -> int:
+        """获取限制数量。
+        
+        Returns:
+            int: 限制数量
+        """
+        return self.page_size
+    
+    @field_validator("page")
+    @classmethod
+    def validate_page(cls, v: int) -> int:
+        """验证页码。
+        
+        Args:
+            v: 页码值
+            
+        Returns:
+            int: 验证后的页码
+        """
+        if v < 1:
+            raise ValueError("页码必须大于0")
+        return v
+    
+    @field_validator("page_size")
+    @classmethod
+    def validate_page_size(cls, v: int) -> int:
+        """验证每页记录数。
+        
+        Args:
+            v: 每页记录数
+            
+        Returns:
+            int: 验证后的每页记录数
+        """
+        if v < 1:
+            raise ValueError("每页记录数必须大于0")
+        if v > 100:
+            raise ValueError("每页记录数不能超过100")
+        return v
+
+
+class SortParams(BaseModel):
+    """排序参数。
+    
+    定义排序的字段和方向。
+    """
+    
+    sorts: list[tuple[str, str]] = Field(default_factory=list, description="排序字段列表")
+    
+    def add_sort(self, field: str, direction: str = "asc") -> None:
+        """添加排序字段。
+        
+        Args:
+            field: 字段名
+            direction: 排序方向，asc 或 desc
+        """
+        if direction.lower() not in ("asc", "desc"):
+            raise ValueError("排序方向必须是 'asc' 或 'desc'")
+        self.sorts.append((field, direction.lower()))
+    
+    def add_sorts(self, *sorts: tuple[str, str]) -> None:
+        """添加多个排序字段。
+        
+        Args:
+            *sorts: 排序字段元组列表
+        """
+        for field, direction in sorts:
+            self.add_sort(field, direction)
+    
+    @field_validator("sorts", mode="before")
+    @classmethod
+    def validate_sorts(cls, v: Any) -> list[tuple[str, str]]:
+        """验证排序字段列表。
+        
+        Args:
+            v: 排序字段列表
+            
+        Returns:
+            list[tuple[str, str]]: 验证后的排序字段列表
+        """
+        if not v:
+            return []
+        
+        result = []
+        for item in v:
+            if isinstance(item, str):
+                # 如果是字符串，解析为字段和方向
+                if item.startswith("-"):
+                    field = item[1:]
+                    direction = "desc"
+                else:
+                    field = item
+                    direction = "asc"
+                result.append((field, direction))
+            elif isinstance(item, list | tuple) and len(item) == 2:
+                field, direction = item
+                if direction.lower() not in ("asc", "desc"):
+                    raise ValueError(f"排序方向必须是 'asc' 或 'desc'，得到: {direction}")
+                result.append((field, direction.lower()))
+            else:
+                raise ValueError(f"无效的排序参数: {item}")
+        
+        return result
+
+
+class PaginationResult[ModelType](BaseModel):
+    """分页结果。
+    
+    封装分页查询的结果，包括数据列表和分页信息。
+    """
+    
+    items: list[ModelType] = Field(description="数据列表")
+    total: int = Field(ge=0, description="总记录数")
+    page: int = Field(ge=1, description="当前页码")
+    page_size: int = Field(ge=1, description="每页记录数")
+    total_pages: int = Field(ge=0, description="总页数")
+    has_next: bool = Field(description="是否有下一页")
+    has_prev: bool = Field(description="是否有上一页")
+    
+    @classmethod
+    def create(
+        cls,
+        items: list[ModelType],
+        total: int,
+        pagination_params: PaginationParams
+    ) -> PaginationResult[ModelType]:
+        """创建分页结果。
+        
+        Args:
+            items: 数据列表
+            total: 总记录数
+            pagination_params: 分页参数
+            
+        Returns:
+            PaginationResult[ModelType]: 分页结果
+        """
+        total_pages = (total + pagination_params.page_size - 1) // pagination_params.page_size
+        has_next = pagination_params.page < total_pages
+        has_prev = pagination_params.page > 1
+        
+        return cls(
+            items=items,
+            total=total,
+            page=pagination_params.page,
+            page_size=pagination_params.page_size,
+            total_pages=total_pages,
+            has_next=has_next,
+            has_prev=has_prev,
+        )
+    
+    def get_next_params(self) -> PaginationParams | None:
+        """获取下一页的分页参数。
+        
+        Returns:
+            PaginationParams | None: 下一页的分页参数，如果没有下一页则返回None
+        """
+        if not self.has_next:
+            return None
+        return PaginationParams(page=self.page + 1, page_size=self.page_size)
+    
+    def get_prev_params(self) -> PaginationParams | None:
+        """获取上一页的分页参数。
+        
+        Returns:
+            PaginationParams | None: 上一页的分页参数，如果没有上一页则返回None
+        """
+        if not self.has_prev:
+            return None
+        return PaginationParams(page=self.page - 1, page_size=self.page_size)
+
+
+class CursorPaginationParams(BaseModel):
+    """游标分页参数。
+    
+    基于游标的分页，适用于大数据集和高性能场景。
+    """
+    
+    cursor: str | None = Field(default=None, description="游标，用于定位数据位置")
+    limit: int = Field(default=20, ge=1, le=100, description="每页记录数，最大100")
+    direction: str = Field(default="next", description="分页方向：next 或 prev")
+    
+    @field_validator("direction")
+    @classmethod
+    def validate_direction(cls, v: str) -> str:
+        """验证分页方向。
+        
+        Args:
+            v: 分页方向
+            
+        Returns:
+            str: 验证后的分页方向
+        """
+        if v.lower() not in ("next", "prev"):
+            raise ValueError("分页方向必须是 'next' 或 'prev'")
+        return v.lower()
+
+
+class CursorPaginationResult[ModelType](BaseModel):
+    """游标分页结果。
+    
+    封装游标分页查询的结果。
+    """
+    
+    items: list[ModelType] = Field(description="数据列表")
+    next_cursor: str | None = Field(description="下一页游标")
+    prev_cursor: str | None = Field(description="上一页游标")
+    has_next: bool = Field(description="是否有下一页")
+    has_prev: bool = Field(description="是否有上一页")
+    
+    @classmethod
+    def create(
+        cls,
+        items: list[ModelType],
+        next_cursor: str | None = None,
+        prev_cursor: str | None = None,
+        limit: int = 20
+    ) -> CursorPaginationResult[ModelType]:
+        """创建游标分页结果。
+        
+        Args:
+            items: 数据列表
+            next_cursor: 下一页游标
+            prev_cursor: 上一页游标
+            limit: 每页记录数
+            
+        Returns:
+            CursorPaginationResult[ModelType]: 游标分页结果
+        """
+        has_next = next_cursor is not None
+        has_prev = prev_cursor is not None
+        
+        return cls(
+            items=items,
+            next_cursor=next_cursor,
+            prev_cursor=prev_cursor,
+            has_next=has_next,
+            has_prev=has_prev,
+        )
+
+
+__all__ = [
+    "CursorPaginationParams",
+    "CursorPaginationResult",
+    "PaginationParams",
+    "PaginationResult",
+    "SortParams",
+]

aury/boot/domain/repository/__init__.py

@@ -0,0 +1,23 @@
+"""仓储模块 - 接口、实现和工具。
+
+提供：
+- IRepository: 仓储接口
+- BaseRepository: 通用 CRUD 实现
+- QueryBuilder: 查询构建器
+- QueryInterceptor: 查询拦截器
+"""
+
+from .impl import BaseRepository, SimpleRepository
+from .interceptors import QueryInterceptor
+from .interface import IRepository
+from .query_builder import QueryBuilder
+
+__all__ = [
+    "BaseRepository",
+    "IRepository",
+    "QueryBuilder",
+    "QueryInterceptor",
+    "SimpleRepository",
+]
+
+