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

aury/boot/commands/templates/project/AGENTS.md.tpl

@@ -0,0 +1,217 @@
+# AGENTS.md
+
+> 这是给 AI 编程助手阅读的项目上下文文件。根据开发任务类型，阅读下方「开发任务文档索引」中对应的文档。
+
+## 项目概述
+
+- **项目名称**: {project_name}
+- **包名**: {package_name}
+- **框架**: [Aury Boot](https://github.com/AuriMyth/aury-boot)（基于 FastAPI + SQLAlchemy 2.0 的微服务框架）
+- **Python 版本**: >= 3.13
+- **包管理**: uv（推荐）或 pip
+
+## 常用命令
+
+```bash
+# 开发服务器（热重载）
+aury server dev
+
+# 数据库迁移
+aury migrate make -m "描述"    # 生成迁移
+aury migrate up                # 执行迁移
+aury migrate down              # 回滚迁移
+aury migrate status            # 查看状态
+aury migrate show              # 查看历史
+
+# 测试
+pytest
+pytest tests/test_xxx.py -v
+
+# 代码检查
+ruff check .
+mypy {package_name}/
+```
+
+> ⚠️ **重要**：数据库迁移文件**必须**使用 `aury migrate make` 命令生成，**禁止**手写迁移文件！
+
+## 项目结构
+
+```
+{project_name}/
+├── {package_name}/           # 主代码包
+│   ├── models/               # SQLAlchemy ORM 模型
+│   ├── repositories/         # 数据访问层（Repository 模式）
+│   ├── services/             # 业务逻辑层
+│   ├── schemas/              # Pydantic 请求/响应模型
+│   ├── api/                  # FastAPI 路由
+│   ├── exceptions/           # 业务异常
+│   ├── tasks/                # 异步任务（Dramatiq）
+│   └── schedules/            # 定时任务
+├── aury_docs/               # 开发文档（由 aury docs dev 生成）
+├── tests/                    # 测试
+├── migrations/               # 数据库迁移
+└── main.py                   # 应用入口
+```
+
+## 重要提醒
+
+> **修改代码前，必须先阅读对应的文档！**
+> 
+> 框架的 API 可能与常见框架不同，不要猜测。请查看 `aury_docs/` 下对应的文档。
+
+## 开发任务文档索引
+
+根据你要开发的功能类型，**必须阅读**对应的文档：
+
+### CRUD / 数据库相关（最常见）
+
+开发 CRUD 功能时，按顺序阅读以下文档：
+
+1. **[aury_docs/01-model.md](./aury_docs/01-model.md)** - Model 定义规范
+   - 基类选择（UUIDAuditableStateModel 等）
+   - 字段类型映射
+   - 约束定义（软删除模型的复合唯一约束）
+
+2. **[aury_docs/02-repository.md](./aury_docs/02-repository.md)** - Repository 使用
+   - BaseRepository API
+   - Filters 语法（__gt, __like 等）
+   - 自动提交机制
+
+3. **[aury_docs/03-service.md](./aury_docs/03-service.md)** - Service 编写与事务
+   - 事务装饰器 @transactional
+   - 跨 Service 调用
+   - 事务传播 / Savepoints / on_commit 回调
+   - SELECT FOR UPDATE
+
+4. **[aury_docs/04-schema.md](./aury_docs/04-schema.md)** - Pydantic Schema
+   - 请求/响应模型
+   - 常用验证
+
+5. **[aury_docs/05-api.md](./aury_docs/05-api.md)** - API 路由
+   - 路由编写示例
+   - 依赖注入模式
+
+6. **[aury_docs/06-exception.md](./aury_docs/06-exception.md)** - 异常处理
+   - 内置异常
+   - 自定义异常
+
+### 异步任务 / 定时任务
+
+- **[aury_docs/08-scheduler.md](./aury_docs/08-scheduler.md)** - 定时任务（APScheduler）
+- **[aury_docs/09-tasks.md](./aury_docs/09-tasks.md)** - 异步任务（Dramatiq）
+
+### 基础设施
+
+- **[aury_docs/07-cache.md](./aury_docs/07-cache.md)** - 缓存
+- **[aury_docs/10-storage.md](./aury_docs/10-storage.md)** - 对象存储（S3/COS/OSS）
+- **[aury_docs/11-logging.md](./aury_docs/11-logging.md)** - 日志
+- **[aury_docs/12-admin.md](./aury_docs/12-admin.md)** - 管理后台（SQLAdmin）
+- **[aury_docs/13-channel.md](./aury_docs/13-channel.md)** - 流式通道（SSE）
+- **[aury_docs/14-mq.md](./aury_docs/14-mq.md)** - 消息队列
+- **[aury_docs/15-events.md](./aury_docs/15-events.md)** - 事件总线
+
+### 配置 / CLI / 环境变量
+
+- **[aury_docs/00-overview.md](./aury_docs/00-overview.md)** - 项目概览与最佳实践
+- **[aury_docs/99-cli.md](./aury_docs/99-cli.md)** - CLI 命令参考
+- **[.env.example](./.env.example)** - 所有可用环境变量
+
+## 代码规范
+
+### Model 规范
+
+- **必须**继承框架预定义基类，**不要**直接继承 `Base`
+- **推荐**使用 `UUIDAuditableStateModel`（UUID 主键 + 时间戳 + 软删除）
+- 软删除模型**必须**使用复合唯一约束（包含 `deleted_at`），不能单独使用 `unique=True`
+- **不建议**使用数据库外键（`ForeignKey`），通过程序控制关系，便于分库分表和微服务拆分
+
+```python
+# ✅ 正确
+from aury.boot.domain.models import UUIDAuditableStateModel
+
+class User(UUIDAuditableStateModel):
+    __tablename__ = "users"
+    email: Mapped[str] = mapped_column(String(255), index=True)
+    __table_args__ = (
+        UniqueConstraint("email", "deleted_at", name="uq_users_email_deleted"),
+    )
+
+# ❌ 错误：直接继承 Base
+from aury.boot.domain.models.base import Base
+class User(Base): ...
+```
+
+### Service 规范
+
+- 写操作**必须**使用 `@transactional` 装饰器
+- 只读操作可以不加事务装饰器
+- 跨 Service 调用通过共享 session 实现事务共享
+
+```python
+from aury.boot.domain.transaction import transactional
+
+class UserService(BaseService):
+    @transactional
+    async def create(self, data: UserCreate) -> User:
+        # 自动事务管理
+        return await self.repo.create(data.model_dump())
+```
+
+### Manager API 规范
+
+所有基础设施 Manager 统一使用 `initialize()` 方法初始化：
+
+```python
+# ✅ 正确
+from aury.boot.infrastructure.cache import CacheManager
+cache = CacheManager.get_instance()
+await cache.initialize(backend="redis", url="redis://localhost:6379")
+
+from aury.boot.infrastructure.storage import StorageManager, StorageConfig
+storage = StorageManager.get_instance()
+await storage.initialize(StorageConfig(...))
+
+from aury.boot.infrastructure.events import EventBusManager
+events = EventBusManager.get_instance()
+await events.initialize(backend="memory")
+
+# ❗ 注意：没有 configure() 方法，配置直接传入 initialize()
+```
+
+### 异常规范
+
+- **必须**继承框架异常类，**不要**直接继承 `Exception`
+- 使用框架内置异常：`NotFoundError`, `AlreadyExistsError`, `UnauthorizedError` 等
+
+```python
+# ✅ 正确
+from aury.boot.application.errors import NotFoundError
+raise NotFoundError("用户不存在", resource=user_id)
+
+# ❌ 错误
+raise Exception("用户不存在")
+```
+
+### 响应规范
+
+- **不要**自定义通用响应 Schema
+- 使用框架内置：`BaseResponse`, `PaginationResponse`
+
+```python
+from aury.boot.application.interfaces.egress import BaseResponse
+return BaseResponse(code=200, message="成功", data=user)
+```
+
+## 禁止操作
+
+- ❌ 不要直接修改 `aury/boot/` 框架代码
+- ❌ 不要在 Model 中直接使用 `unique=True`（软删除模型）
+- ❌ 不要自定义通用响应 Schema
+- ❌ 不要在 Repository 之外直接操作 session
+- ❌ 不要提交 `.env` 文件到版本库
+
+## 需要确认的操作
+
+- ⚠️ 添加新的 pip 依赖前请确认
+- ⚠️ 修改数据库迁移前请确认
+- ⚠️ 删除文件前请确认

aury/boot/commands/templates/project/README.md.tpl

@@ -106,6 +106,6 @@ aury worker
 
 ## 文档
 
-- [DEVELOPMENT.md](./DEVELOPMENT.md) - 开发指南（代码组织与规范）
-- [CLI.md](./CLI.md) - CLI 命令参考
+- [AGENTS.md](./AGENTS.md) - AI 编程助手上下文
+- [aury_docs/](./aury_docs/) - 开发文档（包含 Model/Service/API 等指南）
 - [Aury Boot 文档](https://github.com/AuriMyth/aury-boot)

aury/boot/commands/templates/project/aury_docs/00-overview.md.tpl

@@ -0,0 +1,59 @@
+# {project_name} 开发指南
+
+本文档基于 [Aury Boot](https://github.com/AuriMyth/aury-boot) 框架。
+
+CLI 命令参考请查看 [99-cli.md](./99-cli.md)。
+
+---
+
+## 目录结构
+
+```
+{project_name}/
+├── {package_name}/              # 代码包（默认 app，可通过 aury init <pkg> 自定义）
+│   ├── models/       # SQLAlchemy ORM 模型
+│   ├── repositories/ # 数据访问层
+│   ├── services/     # 业务逻辑层
+│   ├── schemas/      # Pydantic 请求/响应模型
+│   ├── api/          # FastAPI 路由
+│   ├── exceptions/   # 业务异常
+│   ├── tasks/        # 异步任务（Dramatiq）
+│   └── schedules/    # 定时任务（Scheduler）
+├── tests/            # 测试
+├── migrations/       # 数据库迁移
+└── main.py           # 应用入口
+```
+
+---
+
+## 最佳实践
+
+1. **分层架构**：API → Service → Repository → Model
+2. **事务管理**：在 Service 层使用 `@transactional`，只读操作可不加
+3. **错误处理**：使用框架异常类，全局异常处理器统一处理
+4. **配置管理**：使用 `.env` 文件，不提交到版本库
+5. **日志记录**：使用框架 logger，支持结构化日志和链路追踪
+6. **多实例配置**：环境变量格式 `{{PREFIX}}_{{INSTANCE}}_{{FIELD}}`
+
+---
+
+## 文档索引
+
+### CRUD / 数据库
+- [01-model.md](./01-model.md) - Model 定义
+- [02-repository.md](./02-repository.md) - Repository 使用
+- [03-service.md](./03-service.md) - Service 与事务
+- [04-schema.md](./04-schema.md) - Pydantic Schema
+- [05-api.md](./05-api.md) - API 路由
+- [06-exception.md](./06-exception.md) - 异常处理
+
+### 基础设施
+- [07-cache.md](./07-cache.md) - 缓存
+- [08-scheduler.md](./08-scheduler.md) - 定时任务
+- [09-tasks.md](./09-tasks.md) - 异步任务
+- [10-storage.md](./10-storage.md) - 对象存储
+- [11-logging.md](./11-logging.md) - 日志
+- [12-admin.md](./12-admin.md) - 管理后台
+- [13-channel.md](./13-channel.md) - 流式通道（SSE）
+- [14-mq.md](./14-mq.md) - 消息队列
+- [15-events.md](./15-events.md) - 事件总线

aury/boot/commands/templates/project/aury_docs/01-model.md.tpl

@@ -0,0 +1,183 @@
+# Model（数据模型）
+
+## 1.1 模型基类选择
+
+框架提供多种预组合基类，按需选择：
+
+| 基类 | 主键 | 时间戳 | 软删除 | 乐观锁 | 场景 |
+|------|------|--------|--------|--------|------|
+| `Model` | int | ✓ | ✗ | ✗ | 简单实体 |
+| `AuditableStateModel` | int | ✓ | ✓ | ✗ | 需软删除 |
+| `UUIDModel` | UUID | ✓ | ✗ | ✗ | 分布式 |
+| `UUIDAuditableStateModel` | UUID | ✓ | ✓ | ✗ | **推荐** |
+| `VersionedModel` | int | ✗ | ✗ | ✓ | 乐观锁 |
+| `VersionedUUIDModel` | UUID | ✓ | ✗ | ✓ | UUID+乐观锁 |
+| `FullFeaturedUUIDModel` | UUID | ✓ | ✓ | ✓ | 全功能 |
+
+## 1.2 基类自动提供的字段
+
+**IDMixin** (int 主键):
+```python
+id: Mapped[int]  # 自增主键
+```
+
+**UUIDMixin** (UUID 主键):
+```python
+import uuid
+from sqlalchemy.types import Uuid as SQLAlchemyUuid
+from sqlalchemy.orm import Mapped, mapped_column
+
+id: Mapped[uuid.UUID] = mapped_column(
+    SQLAlchemyUuid(as_uuid=True),  # SQLAlchemy 2.0 自动适配 PG(uuid) 和 MySQL(char(36))
+    primary_key=True,
+    default=uuid.uuid4,
+)
+```
+
+> **关于 SQLAlchemyUuid**：
+> - 使用 `sqlalchemy.types.Uuid`（导入为 `SQLAlchemyUuid`）而非直接使用 `uuid.UUID`
+> - `as_uuid=True` 确保 Python 层面使用 UUID 对象而非字符串
+> - 框架会自动适配不同数据库：PostgreSQL 使用原生 UUID 类型，MySQL/SQLite 使用 CHAR(36)
+> - 如需手动定义 UUID 字段，请使用 `SQLAlchemyUuid(as_uuid=True)` 而非 `Uuid(as_uuid=True)`
+
+**TimestampMixin** (时间戳):
+```python
+created_at: Mapped[datetime]  # 创建时间，自动设置
+updated_at: Mapped[datetime]  # 更新时间，自动更新
+```
+
+**AuditableStateMixin** (软删除):
+```python
+deleted_at: Mapped[int]  # 删除时间戳，0=未删除，>0=删除时间
+# 自动提供：is_deleted 属性、mark_deleted() 方法、restore() 方法
+```
+
+> **注意**：使用软删除的模型不要单独使用 `unique=True`，否则删除后再插入相同值会报错。
+> 应使用复合唯一索引：`UniqueConstraint("email", "deleted_at", name="uq_users_email_deleted")`
+
+**VersionMixin** (乐观锁):
+```python
+version: Mapped[int]  # 版本号，自动管理
+```
+
+## 1.3 Model 编写示例
+
+**文件**: `{package_name}/models/user.py`
+
+```python
+"""User 数据模型。"""
+
+from sqlalchemy import String, Boolean, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column
+
+from aury.boot.domain.models import UUIDAuditableStateModel
+
+
+class User(UUIDAuditableStateModel):
+    """User 模型。
+
+    继承 UUIDAuditableStateModel 自动获得：
+    - id: UUID 主键（使用 SQLAlchemyUuid 自动适配数据库）
+    - created_at, updated_at: 时间戳
+    - deleted_at: 软删除支持
+    """
+
+    __tablename__ = "users"
+
+    name: Mapped[str] = mapped_column(String(100), nullable=False, comment="用户名")
+    email: Mapped[str] = mapped_column(String(255), nullable=False, index=True, comment="邮箱")
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True, comment="是否激活")
+
+    # 软删除模型必须使用复合唯一约束（包含 deleted_at），避免删除后无法插入相同值
+    # 注意：复合约束必须使用 __table_args__，这是 SQLAlchemy 的要求
+    __table_args__ = (
+        UniqueConstraint("email", "deleted_at", name="uq_users_email_deleted"),
+    )
+```
+
+## 1.4 字段类型映射
+
+| Python 类型 | SQLAlchemy 类型 | 说明 |
+|-------------|----------------|------|
+| `str` | `String(length)` | 必须指定长度 |
+| `int` | `Integer` | 整数 |
+| `float` | `Float` | 浮点数 |
+| `bool` | `Boolean` | 布尔值 |
+| `datetime` | `DateTime(timezone=True)` | 带时区 |
+| `date` | `Date` | 日期 |
+| `Decimal` | `Numeric(precision, scale)` | 精确小数 |
+| `dict`/`list` | `JSON` | JSON 数据 |
+| `uuid.UUID` | `SQLAlchemyUuid(as_uuid=True)` | UUID（推荐使用 `from sqlalchemy.types import Uuid as SQLAlchemyUuid`） |
+
+## 1.5 常用字段约束
+
+```python
+from sqlalchemy import String, Integer, Index, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column
+import uuid
+
+class Example(UUIDAuditableStateModel):
+    __tablename__ = "examples"
+    
+    # 可选字段
+    description: Mapped[str | None] = mapped_column(String(500), nullable=True)
+    
+    # 带默认值
+    status: Mapped[int] = mapped_column(Integer, default=0, server_default="0", index=True)
+    
+    # 单列索引：直接在 mapped_column 中使用 index=True（推荐）
+    code: Mapped[str] = mapped_column(String(50), index=True, comment="编码")
+    
+    # 单列唯一约束：直接在 mapped_column 中使用 unique=True（仅非软删除模型）
+    # 注意：软删除模型不能单独使用 unique=True，必须使用复合唯一约束
+    
+    # 关联字段（不使用数据库外键，通过程序控制关系）
+    category_id: Mapped[uuid.UUID | None] = mapped_column(index=True)
+    
+    # 复合索引和复合唯一约束：必须使用 __table_args__（SQLAlchemy 要求）
+    # 软删除模型必须使用复合唯一约束（包含 deleted_at），避免删除后无法插入相同值
+    __table_args__ = (
+        Index("ix_examples_status_created", "status", "created_at"),
+        UniqueConstraint("code", "deleted_at", name="uq_examples_code_deleted"),
+    )
+
+
+# 非软删除模型可以直接使用 unique=True 和 index=True
+class Config(UUIDModel):  # UUIDModel 不包含软删除
+    __tablename__ = "configs"
+    
+    # 单列唯一约束：直接在 mapped_column 中使用（推荐）
+    key: Mapped[str] = mapped_column(String(100), unique=True, index=True, comment="配置键")
+    value: Mapped[str] = mapped_column(String(500), comment="配置值")
+    
+    # 单列索引：直接在 mapped_column 中使用（推荐）
+    name: Mapped[str] = mapped_column(String(100), index=True, comment="配置名称")
+```
+
+**约束定义最佳实践**：
+
+1. **单列索引**：使用 `index=True` 在 `mapped_column` 中（推荐）
+   ```python
+   email: Mapped[str] = mapped_column(String(255), index=True)
+   ```
+
+2. **单列唯一约束**：
+   - 非软删除模型：使用 `unique=True` 在 `mapped_column` 中（推荐）
+   - 软删除模型：必须使用复合唯一约束（包含 `deleted_at`）
+
+3. **复合索引/唯一约束**：必须使用 `__table_args__`（SQLAlchemy 要求）
+   ```python
+   __table_args__ = (
+       Index("ix_name", "col1", "col2"),
+       UniqueConstraint("col1", "col2", name="uq_name"),
+   )
+   ```
+
+4. **关联关系**：**不建议使用数据库外键**，通过程序控制关系
+   - 便于分库分表、微服务拆分
+   - 避免级联操作影响性能
+   - 简化数据迁移
+   ```python
+   # 只存储关联 ID，不使用 ForeignKey
+   category_id: Mapped[uuid.UUID | None] = mapped_column(index=True)
+   ```

aury/boot/commands/templates/project/aury_docs/02-repository.md.tpl

@@ -0,0 +1,206 @@
+# Repository（数据访问层）
+
+## 2.1 Repository 编写示例
+
+**文件**: `{package_name}/repositories/user_repository.py`
+
+```python
+"""User 数据访问层。"""
+
+from aury.boot.domain.repository.impl import BaseRepository
+
+from {package_name}.models.user import User
+
+
+class UserRepository(BaseRepository[User]):
+    """User 仓储。
+
+    继承 BaseRepository 自动获得：
+    - get(id): 按 ID 获取
+    - get_by(**filters): 按条件获取单个
+    - list(skip, limit, **filters): 获取列表
+    - paginate(params, **filters): 分页获取
+    - count(**filters): 计数
+    - exists(**filters): 是否存在
+    - create(data): 创建
+    - update(entity, data): 更新
+    - delete(entity, soft=True): 删除（默认软删除）
+    - batch_create(data_list): 批量创建
+    - bulk_insert(data_list): 高性能批量插入
+    """
+
+    async def get_by_email(self, email: str) -> User | None:
+        """按邮箱查询用户。"""
+        return await self.get_by(email=email)
+
+    async def list_active(self, skip: int = 0, limit: int = 100) -> list[User]:
+        """获取激活用户列表。"""
+        return await self.list(skip=skip, limit=limit, is_active=True)
+```
+
+## 2.2 BaseRepository 方法详解
+
+```python
+from sqlalchemy.ext.asyncio import AsyncSession
+
+# 初始化（默认 auto_commit=True）
+repo = UserRepository(session, User)
+
+# === 查询 ===
+user = await repo.get(user_id)                    # 按 ID（支持 int/UUID）
+user = await repo.get_by(email="a@b.com")         # 按条件（简单 AND 过滤）
+users = await repo.list(skip=0, limit=10)         # 列表
+users = await repo.list(is_active=True)           # 带过滤
+count = await repo.count(is_active=True)          # 计数
+exists = await repo.exists(email="a@b.com")       # 是否存在
+
+# === 分页 ===
+from aury.boot.domain.pagination import PaginationParams, SortParams
+
+result = await repo.paginate(
+    pagination_params=PaginationParams(page=1, page_size=20),
+    sort_params=SortParams.from_string("-created_at"),
+    is_active=True,
+)
+
+# PaginationResult 结构：
+# - result.items: list[T]      # 数据列表
+# - result.total: int          # 总记录数
+# - result.page: int           # 当前页码
+# - result.page_size: int      # 每页数量
+# - result.total_pages: int    # 总页数
+# - result.has_next: bool      # 是否有下一页
+# - result.has_prev: bool      # 是否有上一页
+
+# === 创建 ===
+user = await repo.create({{"name": "Alice", "email": "a@b.com"}})
+users = await repo.batch_create([{{"name": "A"}}, {{"name": "B"}}])  # 返回实体
+await repo.bulk_insert([{{"name": "A"}}, {{"name": "B"}}])           # 高性能，无返回
+
+# === 更新 ===
+user = await repo.update(user, {{"name": "Bob"}})
+
+# === 删除 ===
+await repo.delete(user)              # 软删除
+await repo.delete(user, soft=False)  # 硬删除
+await repo.hard_delete(user)         # 硬删除别名
+deleted = await repo.delete_by_id(user_id)  # 按 ID 删除
+```
+
+### 2.2.1 Filters 语法（增强）
+
+BaseRepository 的 `get_by/list/paginate/count/exists` 的 `**filters` 支持下列操作符（与 `QueryBuilder.filter` 对齐）：
+- `__gt`, `__lt`, `__gte`, `__lte`, `__in`, `__like`, `__ilike`, `__isnull`, `__ne`
+
+示例：
+
+```python
+# 模糊匹配 + 范围 + IN + 为空判断（条件之间为 AND 关系）
+users = await repo.list(
+    name__ilike="%foo%",
+    age__gte=18,
+    id__in=[u1, u2, u3],
+    deleted_at__isnull=True,
+)
+
+# 单个实体（不等于）
+user = await repo.get_by(status__ne="archived")
+```
+
+> 注意：filters 条件之间用 AND 组合；如需 AND/OR/NOT 的复杂组合，请使用 `QueryBuilder`（见 2.4）。
+
+### 2.2.2 排序参数（SortParams）
+
+`SortParams.from_string()` 支持两种语法：
+
+```python
+from aury.boot.domain.pagination import SortParams
+
+# 简洁语法："-" 前缀表示降序
+sort_params = SortParams.from_string("-created_at")
+sort_params = SortParams.from_string("-created_at,priority")  # 多字段
+
+# 完整语法：字段:方向
+sort_params = SortParams.from_string("created_at:desc,priority:asc")
+
+# 带字段白名单验证（防止 SQL 注入）
+ALLOWED_FIELDS = {{"id", "created_at", "priority", "status"}}
+sort_params = SortParams.from_string(
+    "-created_at",
+    allowed_fields=ALLOWED_FIELDS
+)
+# 传入非法字段会抛出 ValueError
+```
+
+### 2.2.3 查询全部（limit=None）
+
+`list()` 支持 `limit=None` 返回全部记录（谨慎使用大表）：
+
+```python
+all_users = await repo.list(limit=None)                 # 全量
+active_all = await repo.list(limit=None, is_active=True)
+```
+
+## 2.3 自动提交机制
+
+BaseRepository 支持智能的自动提交机制，优于 Django 的设计：
+
+| 场景 | 行为 |
+|------|------|
+| 非事务中 + `auto_commit=True` | 写操作后自动 commit |
+| 非事务中 + `auto_commit=False` | 只 flush，需手动管理或使用 `.with_commit()` |
+| 在事务中（`@transactional` 等） | **永不自动提交**，由事务统一管理 |
+
+```python
+# 默认行为：非事务中自动提交
+repo = UserRepository(session, User)  # auto_commit=True
+await repo.create({{"name": "test"}})  # 自动 commit
+
+# 禁用自动提交
+repo = UserRepository(session, User, auto_commit=False)
+await repo.create({{"name": "test"}})  # 只 flush，不 commit
+
+# 单次强制提交（auto_commit=False 时）
+await repo.with_commit().create({{"name": "test2"}})  # 强制 commit
+
+# 在事务中：无论 auto_commit 是什么，都不会自动提交
+@transactional
+async def create_with_profile(session: AsyncSession):
+    repo = UserRepository(session, User)  # auto_commit=True 但不生效
+    user = await repo.create({{"name": "a"}})  # 只 flush
+    profile = await profile_repo.create({{"user_id": user.id}})  # 只 flush
+    # 事务结束时统一 commit
+```
+
+**设计优势**（对比 Django）：
+- Django：每个 `save()` 默认独立事务，容易无意识地失去原子性
+- Aury Boot：默认自动提交，但**事务上下文自动接管**，更显式可控
+
+## 2.4 复杂查询示例
+
+```python
+async def search_users(
+    self, 
+    keyword: str | None = None,
+    status: int | None = None,
+) -> list[User]:
+    """复杂搜索。"""
+    query = self.query()  # 自动排除软删除
+    
+    if keyword:
+        # 使用 QueryBuilder 的 or_ 与 filter_by 组合复杂条件
+        query = query.filter_by(
+            query.or_(
+                User.name.ilike(f"%{{keyword}}%"),
+                User.email.ilike(f"%{{keyword}}%"),
+            )
+        )
+    
+    if status is not None:
+        # 简单等值可直接使用 filter（支持 **kwargs）
+        query = query.filter(status=status)
+    
+    query = query.order_by("-created_at").limit(100)
+    result = await self.session.execute(query.build())
+    return list(result.scalars().all())
+```