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

aury/boot/commands/templates/project/aury_docs/06-exception.md.tpl

@@ -0,0 +1,118 @@
+# 异常处理
+
+框架提供了统一的异常处理机制，所有异常都会被全局异常处理中间件捕获并转换为标准的 HTTP 响应。
+
+## 6.1 异常处理流程
+
+```
+请求 → API 路由 → Service → Repository → 抛出异常
+                                              ↓
+                              全局异常处理中间件（Middleware）
+                                              ↓
+                                  转换为 ErrorResponse Schema
+                                              ↓
+                                       JSON 响应返回客户端
+```
+
+**流程说明**：
+1. 业务代码抛出异常（如 `NotFoundError`）
+2. 框架的全局异常处理中间件自动捕获
+3. 根据异常类型转换为对应的 HTTP 状态码和错误响应
+4. 返回统一格式的 JSON 错误响应
+
+**响应格式**：
+```json
+{{
+  "code": "NOT_FOUND",
+  "message": "用户不存在",
+  "data": null
+}}
+```
+
+## 6.2 内置异常
+
+```python
+from aury.boot.application.errors import (
+    BaseError,
+    NotFoundError,       # 404
+    AlreadyExistsError,  # 409
+    ValidationError,     # 422
+    UnauthorizedError,   # 401
+    ForbiddenError,      # 403
+    BusinessError,       # 400
+)
+
+# 使用示例
+raise NotFoundError("用户不存在", resource=user_id)
+raise AlreadyExistsError(f"邮箱 {{email}} 已被注册")
+raise UnauthorizedError("未登录或登录已过期")
+```
+
+## 6.3 自定义异常
+
+**文件**: `{package_name}/exceptions/order.py`
+
+```python
+from enum import Enum
+from fastapi import status
+from aury.boot.application.errors import BaseError
+
+
+# 推荐：定义错误码枚举
+class OrderErrorCode(str, Enum):
+    ORDER_ERROR = "5000"
+    ORDER_NOT_FOUND = "5001"
+    INSUFFICIENT_STOCK = "5002"
+    PAYMENT_FAILED = "5003"
+
+
+class OrderError(BaseError):
+    default_message = "订单错误"
+    default_code = OrderErrorCode.ORDER_ERROR
+    default_status_code = status.HTTP_400_BAD_REQUEST
+
+
+class OrderNotFoundError(OrderError):
+    default_message = "订单不存在"
+    default_code = OrderErrorCode.ORDER_NOT_FOUND
+    default_status_code = status.HTTP_404_NOT_FOUND
+
+
+class InsufficientStockError(OrderError):
+    default_message = "库存不足"
+    default_code = OrderErrorCode.INSUFFICIENT_STOCK
+    default_status_code = status.HTTP_400_BAD_REQUEST
+
+
+# 使用
+raise OrderNotFoundError()  # 使用默认值
+raise OrderError(message="订单ID无效")  # 自定义消息
+raise InsufficientStockError(message=f"商品 {{product_id}} 库存不足")
+```
+
+**Error Code 规范**：
+- **推荐使用枚举**定义错误码，枚举值必须为数字字符串（如 `"5001"`）
+- 框架预留编码范围：1xxx 通用、2xxx 数据库、3xxx 业务、4xxx 外部服务、**5xxx+ 用户自定义**
+
+## 6.4 异常与 Schema 的关系
+
+异常处理中间件会自动将异常转换为 Schema 响应：
+
+```python
+# Service 层抛出异常
+raise NotFoundError("用户不存在")
+
+# 中间件捕获并转换为响应
+# HTTP 状态码：404
+# 响应体：
+# {{
+#   "code": "NOT_FOUND",
+#   "message": "用户不存在",
+#   "data": null
+# }}
+```
+
+**最佳实践**：
+- 在 Service 层抛出业务异常，不要在 API 层手动处理
+- 使用框架内置异常或自定义异常，不要直接抛出 `Exception`
+- 自定义异常继承 `BaseError`，框架会自动处理

aury/boot/commands/templates/project/aury_docs/07-cache.md.tpl

@@ -0,0 +1,122 @@
+# 缓存
+
+框架的 `CacheManager` 支持**命名多实例**，可以为不同用途配置不同的缓存后端。
+
+## 7.1 基本用法
+
+```python
+from aury.boot.infrastructure.cache import CacheManager
+
+# 默认实例
+cache = CacheManager.get_instance()
+await cache.set("key", value, expire=300)  # 5 分钟
+value = await cache.get("key")
+await cache.delete("key")
+```
+
+## 7.2 多实例使用
+
+```python
+# 获取不同用途的缓存实例
+session_cache = CacheManager.get_instance("session")
+rate_limit_cache = CacheManager.get_instance("rate_limit")
+
+# 分别初始化（可以使用不同的后端或配置）
+await session_cache.initialize(
+    backend="redis",
+    url="redis://localhost:6379/1",  # 使用不同的 Redis DB
+)
+await rate_limit_cache.initialize(
+    backend="memory",
+    max_size=10000,
+)
+```
+
+## 7.3 缓存装饰器
+
+```python
+cache = CacheManager.get_instance()
+
+@cache.cached(expire=300, key_prefix="user")
+async def get_user(user_id: int):
+    # 缓存键自动生成：user:<func_name>:<args_hash>
+    return await repo.get(user_id)
+```
+
+## 7.4 支持的后端
+
+- `redis` - Redis（推荐生产用）
+- `memory` - 内存缓存（开发/测试用）
+- `memcached` - Memcached
+
+## 7.5 API 响应缓存装饰器
+
+使用 `@cache.cache_response()` 装饰器自动缓存 API 响应：
+
+```python
+cache = CacheManager.get_instance()
+
+# 基本用法：自动生成缓存键
+@router.get("/{{id}}")
+@cache.cache_response(expire=300)
+async def get_todo(id: UUID, service: TodoService = Depends(get_service)):
+    entity = await service.get(id)
+    return BaseResponse(code=200, message="获取成功", data=TodoResponse.model_validate(entity))
+
+# 自定义缓存键
+@router.get("/{{id}}")
+@cache.cache_response(
+    expire=300,
+    key_builder=lambda id, **kwargs: f"todo:{{id}}"
+)
+async def get_todo(id: UUID, service: TodoService = Depends(get_service)):
+    entity = await service.get(id)
+    return BaseResponse(code=200, message="获取成功", data=TodoResponse.model_validate(entity))
+```
+
+## 7.6 模式删除（delete_pattern）
+
+使用通配符批量删除缓存：
+
+```python
+# 删除所有 todo 相关缓存
+await cache.delete_pattern("api:todo:*")
+
+# 删除所有列表缓存
+await cache.delete_pattern("api:todo:list:*")
+```
+
+## 7.7 缓存清理策略
+
+数据变更时应及时清理相关缓存：
+
+```python
+# 更新时清理缓存
+@router.put("/{{id}}")
+async def update_todo(id: UUID, data: TodoUpdate, service: TodoService = Depends(get_service)):
+    entity = await service.update(id, data)
+    
+    # 清理单个 + 模式删除
+    await cache.delete(f"api:todo:{{id}}")
+    await cache.delete_pattern("api:todo:list:*")  # 清理所有列表缓存
+    
+    return BaseResponse(code=200, message="更新成功", data=TodoResponse.model_validate(entity))
+
+# 删除时清理缓存
+@router.delete("/{{id}}")
+async def delete_todo(id: UUID, service: TodoService = Depends(get_service)):
+    await service.delete(id)
+    await cache.delete(f"api:todo:{{id}}")
+    await cache.delete_pattern("api:todo:*")  # 清理所有相关缓存
+    return BaseResponse(code=200, message="删除成功", data=None)
+```
+
+### 7.7.1 缓存键命名规范
+
+```python
+# 推荐格式：{{layer}}:{{resource}}:{{identifier}}
+f"api:todo:{{id}}"           # 单个资源
+f"api:todo:list:{{page}}"    # 列表
+f"api:todo:statistics"       # 统计
+f"service:user:{{user_id}}"  # Service 层缓存
+```

aury/boot/commands/templates/project/aury_docs/08-scheduler.md.tpl

@@ -0,0 +1,32 @@
+# 定时任务（Scheduler）
+
+**文件**: `{package_name}/schedules/__init__.py`
+
+```python
+"""定时任务模块。"""
+
+from aury.boot.common.logging import logger
+from aury.boot.infrastructure.scheduler import SchedulerManager
+
+scheduler = SchedulerManager.get_instance()
+
+
+@scheduler.scheduled_job("interval", seconds=60)
+async def every_minute():
+    """每 60 秒执行。"""
+    logger.info("定时任务执行中...")
+
+
+@scheduler.scheduled_job("cron", hour=0, minute=0)
+async def daily_task():
+    """每天凌晨执行。"""
+    logger.info("每日任务执行中...")
+
+
+@scheduler.scheduled_job("cron", day_of_week="mon", hour=9)
+async def weekly_report():
+    """每周一 9 点执行。"""
+    logger.info("周报任务执行中...")
+```
+
+启用方式：配置 `SCHEDULER_ENABLED=true`，框架自动加载 `{package_name}/schedules/` 模块。

aury/boot/commands/templates/project/aury_docs/09-tasks.md.tpl

@@ -0,0 +1,38 @@
+# 异步任务（Dramatiq）
+
+**文件**: `{package_name}/tasks/__init__.py`
+
+```python
+"""异步任务模块。"""
+
+from aury.boot.common.logging import logger
+from aury.boot.infrastructure.tasks import conditional_task
+
+
+@conditional_task()
+def send_email(to: str, subject: str, body: str):
+    """异步发送邮件。"""
+    logger.info(f"发送邮件到 {{to}}: {{subject}}")
+    # 实际发送逻辑...
+    return {{"status": "sent"}}
+
+
+@conditional_task()
+def process_order(order_id: str):
+    """异步处理订单。"""
+    logger.info(f"处理订单: {{order_id}}")
+```
+
+调用方式：
+
+```python
+# 异步执行（发送到队列）
+send_email.send("user@example.com", "Hello", "World")
+
+# 延迟执行
+send_email.send_with_options(args=("user@example.com", "Hello", "World"), delay=60000)  # 60秒后
+```
+
+启用方式：
+1. 配置 `TASK_BROKER_URL`（如 `redis://localhost:6379/0`）
+2. 运行 Worker：`aury worker`

aury/boot/commands/templates/project/aury_docs/10-storage.md.tpl

@@ -0,0 +1,115 @@
+# 对象存储（基于 aury-sdk-storage）
+
+## 10.1 安装
+
+```bash
+# 完整安装（S3/COS/OSS + STS 支持）
+uv add "aury-sdk-storage[aws]"
+# 或
+pip install "aury-sdk-storage[aws]"
+```
+
+## 10.2 基本用法（StorageManager）
+
+`StorageManager` 支持**命名多实例**，可以同时管理多个存储后端。
+
+```python
+from aury.boot.infrastructure.storage import (
+    StorageManager, StorageConfig, StorageBackend, StorageFile,
+)
+
+# 默认实例
+storage = StorageManager.get_instance()
+await storage.initialize(StorageConfig(
+    backend=StorageBackend.COS,
+    bucket_name="my-bucket-1250000000",
+    region="ap-guangzhou",
+    endpoint="https://cos.ap-guangzhou.myqcloud.com",
+    access_key_id="AKIDxxxxx",
+    access_key_secret="xxxxx",
+))
+
+# 多实例示例：源存储和目标存储
+source = StorageManager.get_instance("source")
+target = StorageManager.get_instance("target")
+await source.initialize(StorageConfig(backend=StorageBackend.COS, ...))
+await target.initialize(StorageConfig(backend=StorageBackend.S3, ...))
+
+# 上传文件（返回 URL）
+# data 支持: bytes / BytesIO / BinaryIO
+url = await storage.upload_file(
+    StorageFile(
+        object_name="user/123/avatar.png",
+        data=image_bytes,
+        content_type="image/png",
+    )
+)
+
+# 下载文件
+content = await storage.download_file("user/123/avatar.png")
+
+# 获取预签名 URL
+url = await storage.get_file_url("user/123/avatar.png", expires_in=3600)
+
+# 检查文件是否存在
+exists = await storage.file_exists("user/123/avatar.png")
+
+# 删除文件
+await storage.delete_file("user/123/avatar.png")
+```
+
+## 10.3 STS 临时凭证（前端直传）
+
+```python
+from aury.sdk.storage.sts import (
+    STSProviderFactory, ProviderType, STSRequest, ActionType,
+)
+
+# 创建腾讯云 STS Provider
+provider = STSProviderFactory.create(
+    ProviderType.TENCENT,
+    secret_id="AKIDxxxxx",
+    secret_key="xxxxx",
+)
+
+# 签发临时上传凭证
+credentials = await provider.get_credentials(
+    STSRequest(
+        bucket="my-bucket-1250000000",
+        region="ap-guangzhou",
+        allow_path="user/123/",
+        action_type=ActionType.WRITE,
+        duration_seconds=900,
+    )
+)
+
+# 返回给前端
+return {{
+    "accessKeyId": credentials.access_key_id,
+    "secretAccessKey": credentials.secret_access_key,
+    "sessionToken": credentials.session_token,
+    "expiration": credentials.expiration.isoformat(),
+    "bucket": credentials.bucket,
+    "region": credentials.region,
+    "endpoint": credentials.endpoint,
+}}
+```
+
+## 10.4 本地存储（开发测试）
+
+```python
+from aury.boot.infrastructure.storage import (
+    StorageManager, StorageConfig, StorageBackend, StorageFile,
+)
+
+storage = StorageManager.get_instance()
+await storage.initialize(StorageConfig(
+    backend=StorageBackend.LOCAL,
+    base_path="./dev_storage",
+))
+
+url = await storage.upload_file(
+    StorageFile(object_name="test.txt", data=b"hello")
+)
+# url: file:///path/to/dev_storage/default/test.txt
+```

aury/boot/commands/templates/project/aury_docs/11-logging.md.tpl

@@ -0,0 +1,131 @@
+# 日志
+
+基于 loguru 的日志系统，trace_id 自动注入每条日志，无需手动记录。
+
+## 11.1 基本用法
+
+```python
+from aury.boot.common.logging import logger
+
+# trace_id 自动包含在日志格式中，无需手动记录
+logger.info("操作成功")
+logger.warning("警告信息")
+logger.error("错误信息")
+logger.exception("异常信息")  # 自动记录堆栈
+```
+
+输出示例：
+```
+2024-01-15 12:00:00 | INFO | app.service:create:42 | abc123 - 操作成功
+```
+
+## 11.2 注入用户信息
+
+框架不内置用户系统，但支持注入自定义请求上下文：
+
+```python
+# app/auth/context.py
+from contextvars import ContextVar
+from aury.boot.common.logging import register_request_context
+
+_user_id: ContextVar[str] = ContextVar("user_id", default="")
+
+def set_user_id(uid: str) -> None:
+    _user_id.set(uid)
+
+# 启动时注册（只需一次）
+register_request_context("user_id", _user_id.get)
+```
+
+在认证中间件中设置（order < 100 以在日志中间件前执行）：
+
+```python
+class AuthMiddleware(Middleware):
+    order = 50  # 在日志中间件(order=100)之前执行
+    
+    async def dispatch(self, request, call_next):
+        user = await verify_token(request)
+        if user:
+            set_user_id(str(user.id))
+        return await call_next(request)
+```
+
+结果：
+```
+← GET /api/users | 状态: 200 | 耗时: 0.05s | Trace-ID: abc123
+[REQUEST_CONTEXT] Trace-ID: abc123 | user_id: 123
+```
+
+## 11.3 性能监控装饰器
+
+```python
+from aury.boot.common.logging import log_performance, log_exceptions
+
+@log_performance(threshold=0.5)  # 超过 0.5 秒记录警告
+async def slow_operation():
+    ...
+
+@log_exceptions  # 自动记录异常
+async def risky_operation():
+    ...
+```
+
+## 11.4 HTTP 请求日志
+
+框架内置 `RequestLoggingMiddleware` 自动记录：
+
+```
+# 请求日志（包含查询参数和请求体）
+→ POST /api/users | 参数: {{'page': '1'}} | Body: {{"name": "test"}} | Trace-ID: abc123
+
+# 响应日志（包含状态码和耗时）
+← POST /api/users | 状态: 201 | 耗时: 0.123s | Trace-ID: abc123
+
+# 慢请求警告（超过 1 秒）
+慢请求: GET /api/reports | 耗时: 2.345s (超过1秒) | Trace-ID: abc123
+```
+
+## 11.5 自定义日志文件
+
+为特定业务创建独立的日志文件：
+
+```python
+from aury.boot.common.logging import register_log_sink, logger
+
+# 启动时注册（生成 payment_2024-01-15.log）
+register_log_sink("payment", filter_key="payment")
+
+# 业务代码中使用
+logger.bind(payment=True).info(f"支付成功 | 订单: {{order_id}}")
+```
+
+## 11.6 异步任务链路追踪
+
+跨进程任务需要手动传递 trace_id：
+
+```python
+from aury.boot.common.logging import get_trace_id, set_trace_id
+
+# 发送任务时传递
+process_order.send(order_id="123", trace_id=get_trace_id())
+
+# 任务执行时恢复
+@tm.conditional_task()
+async def process_order(order_id: str, trace_id: str | None = None):
+    if trace_id:
+        set_trace_id(trace_id)
+    logger.info(f"处理订单: {{order_id}}")  # 自动包含 trace_id
+```
+
+## 11.7 服务上下文隔离
+
+日志自动按服务类型分离：
+
+```
+logs/
+├── api_info_2024-01-15.log      # API 服务日志
+├── api_error_2024-01-15.log
+├── scheduler_info_2024-01-15.log # 调度器日志
+├── worker_info_2024-01-15.log    # Worker 日志
+└── access_2024-01-15.log         # HTTP 访问日志
+```

aury/boot/commands/templates/project/aury_docs/12-admin.md.tpl

@@ -0,0 +1,56 @@
+# 管理后台（Admin Console，基于 SQLAdmin）
+
+默认提供可选的 SQLAdmin 后台（组件自动装配）。启用后路径默认为 `/api/admin-console`。
+
+- 组件开关与配置由环境变量控制；启用后框架会在启动时自动挂载后台路由。
+- SQLAdmin 通常需要同步 SQLAlchemy Engine；如果你使用的是异步 `DATABASE__URL`，建议单独设置同步的 `ADMIN__DATABASE_URL`（框架也会尝试自动推导常见驱动映射）。
+
+## 快速启用（.env）
+
+```bash
+# 启用与基本路径
+ADMIN__ENABLED=true
+ADMIN__PATH=/api/admin-console
+
+# 认证（二选一，推荐 basic 或 bearer）
+ADMIN__AUTH_MODE=basic
+ADMIN__AUTH_SECRET_KEY=CHANGE_ME_TO_A_RANDOM_SECRET
+ADMIN__AUTH_BASIC_USERNAME=admin
+ADMIN__AUTH_BASIC_PASSWORD=change_me
+
+# 如果使用 bearer
+# ADMIN__AUTH_MODE=bearer
+# ADMIN__AUTH_SECRET_KEY=CHANGE_ME
+# ADMIN__AUTH_BEARER_TOKENS=["token1","token2"]
+
+# 如需显式提供同步数据库 URL（可选）
+# ADMIN__DATABASE_URL=postgresql+psycopg://user:pass@localhost:5432/{project_name}
+```
+
+## 注册后台视图
+
+**文件**: `admin_console.py`
+
+```python
+from sqladmin import ModelView
+from {package_name}.models.user import User
+
+class UserAdmin(ModelView, model=User):
+    column_list = [User.id, User.username, User.email]
+
+# 方式一：声明式（简单）
+ADMIN_VIEWS = [UserAdmin]
+
+# 方式二：函数注册（更灵活）
+# def register_admin(admin):
+#     admin.add_view(UserAdmin)
+```
+
+## 自定义认证（可选，高阶）
+
+- 通过 `ADMIN__AUTH_BACKEND=module:attr` 指定自定义 backend；或在 `admin_console.py` 实现 `register_admin_auth(config)` 返回 SQLAdmin 的 `AuthenticationBackend`。
+- 生产环境下必须设置 `ADMIN__AUTH_SECRET_KEY`，不允许 `none` 模式。
+
+## 访问
+
+启动服务后访问：`http://localhost:8000/api/admin-console`（或你配置的 `ADMIN__PATH`）。