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

aury/boot/contrib/__init__.py

@@ -0,0 +1,10 @@
+"""可选扩展（Contrib）。
+
+该目录用于放置与核心框架解耦的可选集成能力（例如管理后台、监控面板等）。
+"""
+
+from __future__ import annotations
+
+__all__ = []
+
+

aury/boot/contrib/admin_console/__init__.py

@@ -0,0 +1,18 @@
+"""SQLAdmin 管理后台（Admin Console）集成。
+
+设计目标：
+- 默认路径 `/api/admin-console`，避免与业务 URL 冲突
+- 默认只内置 basic / bearer 两种可用认证模式
+- 允许通过 settings 或项目模块显式覆盖认证/视图注册
+- 不依赖 CLI command，适合生产快速集成
+"""
+
+from __future__ import annotations
+
+from .install import install_admin_console
+
+__all__ = [
+    "install_admin_console",
+]
+
+

aury/boot/contrib/admin_console/auth.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from starlette.requests import Request
+
+
+try:  # pragma: no cover
+    from sqladmin.authentication import AuthenticationBackend as _SQLAdminAuthenticationBackend
+except Exception:  # pragma: no cover
+    _SQLAdminAuthenticationBackend = None
+
+
+def _require_sqladmin():
+    try:
+        from sqladmin.authentication import AuthenticationBackend  # noqa: F401
+    except Exception as exc:  # pragma: no cover
+        raise ImportError(
+            "未安装 sqladmin。请先安装: uv add \"aury-boot[admin]\" 或 uv add sqladmin"
+        ) from exc
+
+
+def _get_bearer_token(request: Request) -> str | None:
+    auth = request.headers.get("authorization", "")
+    if not auth:
+        return None
+    parts = auth.split(None, 1)
+    if len(parts) != 2:
+        return None
+    scheme, token = parts
+    if scheme.lower() != "bearer":
+        return None
+    token = token.strip()
+    return token or None
+
+
+class BasicAdminAuthBackend(_SQLAdminAuthenticationBackend or object):
+    """SQLAdmin 登录页 + session 的最简用户名/密码认证（推荐默认）。"""
+
+    def __init__(self, *, username: str, password: str, secret_key: str, session_key: str = "aury_admin") -> None:
+        _require_sqladmin()
+        # 若 sqladmin 不存在，此类的 base 会是 object，这里会提前抛错，避免静默不兼容
+        super().__init__(secret_key=secret_key)  # type: ignore[misc]
+        self._username = username
+        self._password = password
+        self._session_key = session_key
+
+    async def login(self, request: Request) -> bool:
+        form = await request.form()
+        username = str(form.get("username", "")).strip()
+        password = str(form.get("password", "")).strip()
+        if username == self._username and password == self._password:
+            request.session.update({self._session_key: True})
+            return True
+        return False
+
+    async def logout(self, request: Request) -> bool:
+        request.session.clear()
+        return True
+
+    async def authenticate(self, request: Request) -> bool:
+        return bool(request.session.get(self._session_key))
+
+
+class BearerWhitelistAdminAuthBackend(_SQLAdminAuthenticationBackend or object):
+    """Bearer 白名单认证。
+
+    支持两种方式：
+    - Authorization: Bearer <token>（适合反向代理注入/自动化）
+    - 登录页输入 token（用户名任意，password/token 字段均可）
+    """
+
+    def __init__(
+        self,
+        *,
+        tokens: list[str],
+        secret_key: str,
+        session_key: str = "aury_admin_token",
+    ) -> None:
+        _require_sqladmin()
+        super().__init__(secret_key=secret_key)  # type: ignore[misc]
+        self._tokens = {t.strip() for t in tokens if t and t.strip()}
+        self._session_key = session_key
+
+    async def login(self, request: Request) -> bool:
+        form = await request.form()
+        # 兼容不同表单字段：优先 token，其次 password
+        token = str(form.get("token") or form.get("password") or "").strip()
+        if token and token in self._tokens:
+            request.session.update({self._session_key: token})
+            return True
+        return False
+
+    async def logout(self, request: Request) -> bool:
+        request.session.clear()
+        return True
+
+    async def authenticate(self, request: Request) -> bool:
+        header_token = _get_bearer_token(request)
+        if header_token and header_token in self._tokens:
+            return True
+        session_token = request.session.get(self._session_key)
+        return bool(session_token and session_token in self._tokens)
+
+
+def wrap_authenticate(
+    *,
+    secret_key: str,
+    authenticate: Callable[[Request], Any],
+    session_key: str = "aury_admin",
+):
+    """将一个 authenticate(request) 可调用对象包装为 SQLAdmin AuthenticationBackend。
+
+    用于让用户以最小成本自定义（不必继承 SQLAdmin 类）。
+    """
+    _require_sqladmin()
+    from sqladmin.authentication import AuthenticationBackend
+
+    class _Wrapped(AuthenticationBackend):
+        async def login(self, request: Request) -> bool:  # noqa: D401
+            # 默认不提供登录页逻辑；用户可自己实现更复杂版本
+            return False
+
+        async def logout(self, request: Request) -> bool:
+            request.session.pop(session_key, None)
+            return True
+
+        async def authenticate(self, request: Request) -> bool:
+            result = authenticate(request)
+            if hasattr(result, "__await__"):
+                result = await result
+            return bool(result)
+
+    return _Wrapped(secret_key=secret_key)
+
+

aury/boot/contrib/admin_console/discovery.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+from aury.boot.common.logging import logger
+
+
+def _candidate_modules(app: Any, config: Any) -> list[str]:
+    """生成项目侧 admin-console 模块候选列表（多策略自动发现）。
+
+    参考 SchedulerComponent._autodiscover_schedules 的风格：
+    - settings 显式指定优先
+    - 读取 [tool.aury].package
+    - service.name / 调用者模块推断
+    - 最后尝试根模块 admin_console/admin
+    """
+    modules: list[str] = []
+
+    # 策略 0：显式指定
+    views_module = getattr(getattr(config, "admin", None), "views_module", None)
+    if views_module:
+        modules.append(str(views_module).strip())
+
+    # 策略 1：读取 pyproject.toml 的 [tool.aury].package
+    try:
+        from aury.boot.commands.config import get_project_config
+
+        cfg = get_project_config()
+        if getattr(cfg, "has_package", False):
+            pkg = cfg.package
+            modules.extend([f"{pkg}.admin_console", f"{pkg}.admin"])
+    except Exception:
+        pass
+
+    # 策略 2：service.name 推断
+    service_name = (getattr(getattr(config, "service", None), "name", None) or "").strip()
+    if service_name and service_name not in {"app", "main"}:
+        modules.extend([f"{service_name}.admin_console", f"{service_name}.admin"])
+
+    # 策略 3：从调用者模块推断
+    caller = getattr(app, "_caller_module", "__main__")
+    if caller in ("__main__", "main"):
+        modules.extend(["admin_console", "admin"])
+    elif "." in str(caller):
+        package = str(caller).rsplit(".", 1)[0]
+        modules.extend([f"{package}.admin_console", f"{package}.admin", "admin_console", "admin"])
+    else:
+        modules.extend([f"{caller}.admin_console", f"{caller}.admin", "admin_console", "admin"])
+
+    # 去重，保持顺序
+    seen: set[str] = set()
+    return [m for m in modules if m and not (m in seen or seen.add(m))]
+
+
+def load_project_admin_module(app: Any, config: Any):
+    """尝试导入项目侧 admin-console 模块，成功则返回 module，否则返回 None。"""
+    for module_name in _candidate_modules(app, config):
+        try:
+            module = importlib.import_module(module_name)
+            logger.info(f"已加载管理后台模块: {module_name}")
+            return module
+        except ImportError:
+            logger.debug(f"管理后台模块不存在: {module_name}")
+        except Exception as exc:
+            logger.warning(f"加载管理后台模块失败 ({module_name}): {exc}")
+    return None
+
+

aury/boot/contrib/admin_console/install.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy import create_engine
+from sqlalchemy.ext.asyncio import create_async_engine
+
+from aury.boot.common.logging import logger
+
+from .auth import BasicAdminAuthBackend, BearerWhitelistAdminAuthBackend
+from .discovery import load_project_admin_module
+from .utils import import_from_string
+
+
+def _require_sqladmin():
+    try:
+        from sqladmin import Admin  # noqa: F401
+    except Exception as exc:  # pragma: no cover
+        raise ImportError(
+            "未安装 sqladmin。请先安装: uv add \"aury-boot[admin]\" 或 uv add sqladmin"
+        ) from exc
+
+
+def _resolve_auth_backend(app: Any, config: Any, module: Any | None):
+    """解析 SQLAdmin authentication_backend。
+
+    优先级（与项目现有 autodiscover 风格一致）：
+    1) settings: ADMIN_AUTH_BACKEND="module:attr"（完全覆盖）
+    2) 项目模块: register_admin_auth(config) -> backend（覆盖内置）
+    3) 内置 basic/bearer/none
+    """
+    admin_cfg = getattr(config, "admin", None)
+    auth_cfg = getattr(admin_cfg, "auth", None)
+
+    mode = getattr(auth_cfg, "mode", "basic")
+    backend_path = getattr(auth_cfg, "backend", None)
+    secret_key = getattr(auth_cfg, "secret_key", None)
+
+    # 生产环境安全约束
+    if getattr(config, "is_production", False):
+        if mode == "none":
+            raise ValueError("生产环境不允许 ADMIN_AUTH_MODE=none，请使用 basic/bearer 或自定义 backend")
+        if not secret_key or str(secret_key).strip() in {"CHANGE_ME", "changeme"}:
+            raise ValueError("生产环境启用管理后台时必须设置 ADMIN_AUTH_SECRET_KEY（且不能为 CHANGE_ME）")
+
+    # 1) 显式 backend 覆盖
+    if backend_path:
+        obj = import_from_string(str(backend_path).strip())
+        backend = obj(config) if callable(obj) else obj
+        if backend is None:
+            raise ValueError(f"ADMIN_AUTH_BACKEND={backend_path!r} 返回 None")
+        logger.info("管理后台认证：使用 settings 指定的自定义 backend")
+        return backend
+
+    # 2) 项目模块覆盖
+    if module is not None and hasattr(module, "register_admin_auth"):
+        backend = module.register_admin_auth(config)  # type: ignore[attr-defined]
+        if backend is None:
+            raise ValueError("register_admin_auth(config) 返回 None")
+        logger.info("管理后台认证：使用项目模块 register_admin_auth 提供的 backend")
+        return backend
+
+    # 3) 内置兜底
+    if mode in {"custom", "jwt"}:
+        raise ValueError(
+            f"ADMIN_AUTH_MODE={mode!r} 需要提供 ADMIN_AUTH_BACKEND 或在项目模块实现 register_admin_auth(config)"
+        )
+
+    if mode == "none":
+        logger.warning("管理后台认证：已关闭认证（ADMIN_AUTH_MODE=none）")
+        return None
+
+    if not secret_key:
+        raise ValueError("启用管理后台认证需要设置 ADMIN_AUTH_SECRET_KEY")
+
+    if mode == "basic":
+        username = getattr(auth_cfg, "basic_username", None)
+        password = getattr(auth_cfg, "basic_password", None)
+        if not username or not password:
+            raise ValueError("ADMIN_AUTH_MODE=basic 需要设置 ADMIN_AUTH_BASIC_USERNAME/ADMIN_AUTH_BASIC_PASSWORD")
+        return BasicAdminAuthBackend(username=username, password=password, secret_key=secret_key)
+
+    if mode == "bearer":
+        tokens = list(getattr(auth_cfg, "bearer_tokens", []) or [])
+        if not tokens:
+            raise ValueError("ADMIN_AUTH_MODE=bearer 需要设置 ADMIN_AUTH_BEARER_TOKENS（token 白名单）")
+        return BearerWhitelistAdminAuthBackend(tokens=tokens, secret_key=secret_key)
+
+    raise ValueError(f"未知的 ADMIN_AUTH_MODE: {mode!r}")
+
+
+def _register_views(admin: Any, module: Any | None) -> None:
+    """注册项目侧 views。"""
+    if module is None:
+        logger.info("管理后台：未发现项目 admin-console 模块，跳过 views 注册")
+        return
+
+    if hasattr(module, "register_admin"):
+        module.register_admin(admin)  # type: ignore[attr-defined]
+        logger.info("管理后台：已通过 register_admin(admin) 注册 views")
+        return
+
+    views = getattr(module, "ADMIN_VIEWS", None)
+    if views:
+        for view_cls in list(views):
+            admin.add_view(view_cls)
+        logger.info("管理后台：已通过 ADMIN_VIEWS 注册 views")
+        return
+
+    logger.info("管理后台：项目模块已加载，但未提供 register_admin/ADMIN_VIEWS，跳过 views 注册")
+
+
+def install_admin_console(app: Any, config: Any | None = None):
+    """安装 SQLAdmin 管理后台到 FastAPI/FoundationApp。
+
+    - 默认路径：/api/admin-console（可通过 ADMIN_PATH 覆盖）
+    - 认证：默认 basic/bearer（可通过 ADMIN_AUTH_* 配置，或自定义 backend 覆盖）
+    - 视图：可通过项目模块 register_admin(admin) 或 ADMIN_VIEWS 提供
+    - 引擎：支持同步或异步 SQLAlchemy Engine（AsyncEngine）
+
+    返回：
+        sqladmin.Admin 实例；若未启用（ADMIN_ENABLED=false）返回 None
+    """
+    _require_sqladmin()
+    from sqladmin import Admin
+
+    if config is None:
+        from aury.boot.application.config import BaseConfig
+
+        config = BaseConfig()
+
+    admin_cfg = getattr(config, "admin", None)
+    if not getattr(admin_cfg, "enabled", False):
+        logger.debug("管理后台未启用（ADMIN_ENABLED=false），跳过安装")
+        return None
+
+    # 1) 自动发现项目模块（用于 auth/views）
+    module = load_project_admin_module(app, config)
+
+    # 2) 解析认证后端（可能为 None）
+    auth_backend = _resolve_auth_backend(app, config, module)
+
+    # 3) 构建 Engine（支持同步/异步）
+    db_url = getattr(admin_cfg, "database_url", None) or getattr(config.database, "url", "")
+    if not db_url:
+        raise ValueError("无法确定管理后台数据库 URL：请设置 ADMIN_DATABASE_URL 或 DATABASE_URL")
+
+    def _is_async_url(url: str) -> bool:
+        return any(s in url for s in ["+asyncpg", "+aiosqlite", "+aiomysql", "+asyncmy"])
+
+    try:
+        if _is_async_url(str(db_url)):
+            engine = create_async_engine(str(db_url), future=True)
+        else:
+            engine = create_engine(str(db_url), future=True)
+    except Exception as exc:
+        raise RuntimeError(
+            "创建管理后台数据库 Engine 失败。请检查 ADMIN_DATABASE_URL/DATABASE_URL 与对应驱动是否可用。"
+        ) from exc
+
+    base_url = getattr(admin_cfg, "path", "/api/admin-console")
+
+    # 4) 安装 admin（engine 可为同步或异步）
+    admin = Admin(app=app, engine=engine, base_url=base_url, authentication_backend=auth_backend)
+
+    # 5) 注册 views
+    _register_views(admin, module)
+
+    logger.info(f"✅ 管理后台已启用：{base_url}")
+    return admin
+
+

aury/boot/contrib/admin_console/utils.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import importlib
+
+
+def import_from_string(path: str):
+    """从 'module:attr' 动态导入对象。
+
+    与 commands/server 的 app 导入风格保持一致。
+    """
+    if ":" not in path:
+        raise ValueError(f"无效导入路径: {path!r}（应为 'module:attr'）")
+    module_path, attr = path.rsplit(":", 1)
+    module = importlib.import_module(module_path)
+    try:
+        return getattr(module, attr)
+    except AttributeError as exc:
+        raise AttributeError(f"模块 {module_path!r} 中不存在 {attr!r}") from exc
+
+
+def derive_sync_database_url(database_url: str) -> str:
+    """从异步 URL 推导同步 URL（用于 SQLAdmin）。
+
+    说明：
+    - sqladmin 通常要求同步 SQLAlchemy Engine（create_engine）
+    - 本函数只做最常见的 driver 映射；如需完全自定义请用 ADMIN_DATABASE_URL 覆盖
+    """
+    # SQLite
+    if database_url.startswith("sqlite+aiosqlite://"):
+        return database_url.replace("sqlite+aiosqlite://", "sqlite://", 1)
+
+    # PostgreSQL
+    if database_url.startswith("postgresql+asyncpg://"):
+        # 推荐 psycopg（psycopg3）
+        return database_url.replace("postgresql+asyncpg://", "postgresql+psycopg://", 1)
+
+    # MySQL
+    if database_url.startswith("mysql+aiomysql://"):
+        return database_url.replace("mysql+aiomysql://", "mysql+pymysql://", 1)
+
+    # 其他情况：认为已经是同步 URL
+    return database_url
+
+

aury/boot/domain/__init__.py

@@ -0,0 +1,79 @@
+"""领域层模块。
+
+提供领域模型和业务逻辑的基础类，包括：
+- ORM 模型基类
+- Repository 接口
+- Service 模式
+- 异常定义
+- 事务管理
+
+注意：Event 基类定义在 infrastructure.events 层，不在 domain 层。
+使用事件时请直接从 infrastructure 导入。
+"""
+
+from .exceptions import CoreException, ModelError, VersionConflictError
+from .models import (
+    GUID,
+    AuditableStateMixin,
+    AuditableStateModel,
+    Base,
+    FullFeaturedModel,
+    FullFeaturedUUIDModel,
+    IDMixin,
+    Model,
+    TimestampMixin,
+    UUIDAuditableStateModel,
+    UUIDMixin,
+    UUIDModel,
+    VersionedModel,
+    VersionedTimestampedModel,
+    VersionedUUIDModel,
+    VersionMixin,
+)
+from .repository import (
+    IRepository,
+    QueryInterceptor,
+)
+from .service import BaseService
+from .transaction import (
+    TransactionManager,
+    TransactionRequiredError,
+    ensure_transaction,
+    transactional,
+    transactional_context,
+)
+
+__all__ = [
+    "GUID",
+    "AuditableStateMixin",
+    "AuditableStateModel",
+    # 模型基类
+    "Base",
+    # Service
+    "BaseService",
+    # 异常
+    "CoreException",
+    "FullFeaturedModel",
+    "FullFeaturedUUIDModel",
+    "IDMixin",
+    # Repository (接口)
+    "IRepository",
+    "Model",
+    "ModelError",
+    "QueryInterceptor",
+    "TimestampMixin",
+    "TransactionManager",
+    "TransactionRequiredError",
+    "UUIDAuditableStateModel",
+    "UUIDMixin",
+    "UUIDModel",
+    "VersionConflictError",
+    "VersionMixin",
+    "VersionedModel",
+    "VersionedTimestampedModel",
+    "VersionedUUIDModel",
+    "ensure_transaction",
+    # Transaction
+    "transactional",
+    "transactional_context",
+]

aury/boot/domain/exceptions/__init__.py

@@ -0,0 +1,132 @@
+"""Domain 层异常定义。
+
+Domain 层异常，继承自 FoundationError。
+"""
+
+from __future__ import annotations
+
+from aury.boot.common.exceptions import FoundationError
+
+
+class CoreException(FoundationError):  # noqa: N818
+    """Domain 层异常基类。
+    
+    所有 Domain 层的异常都应该继承此类。
+    
+    注意：虽然命名为 CoreException，但它是 Domain 层的异常基类。
+    保持 Exception 后缀以与 FoundationError 区分。
+    """
+    
+    pass
+
+
+class ModelError(CoreException):
+    """模型相关错误基类。
+    
+    所有模型相关的异常都应该继承此类。
+    包括：版本冲突、约束违反、验证错误等。
+    """
+    
+    pass
+
+
+class VersionConflictError(ModelError):
+    """版本冲突异常（乐观锁）。
+    
+    当使用 VersionedModel 时，如果更新时版本号不匹配，抛出此异常。
+    
+    Attributes:
+        current_version: 当前数据库中的版本号
+        expected_version: 期望的版本号
+    """
+    
+    def __init__(
+        self,
+        message: str = "数据已被其他操作修改，请刷新后重试",
+        current_version: int | None = None,
+        expected_version: int | None = None,
+        *args: object,
+    ) -> None:
+        """初始化版本冲突异常。
+        
+        Args:
+            message: 错误消息
+            current_version: 当前数据库中的版本号
+            expected_version: 期望的版本号
+            *args: 其他参数
+        """
+        super().__init__(message, *args)
+        self.current_version = current_version
+        self.expected_version = expected_version
+    
+    def __str__(self) -> str:
+        """返回异常字符串表示。"""
+        if self.current_version is not None and self.expected_version is not None:
+            return (
+                f"{self.message} "
+                f"(当前版本: {self.current_version}, 期望版本: {self.expected_version})"
+            )
+        return self.message
+
+
+class TransactionRequiredError(CoreException):
+    """事务必需异常。
+    
+    当方法需要在事务中执行，但当前不在事务中时，抛出此异常。
+    """
+    
+    def __init__(
+        self,
+        message: str = "此操作需要在事务中执行",
+        *args: object,
+    ) -> None:
+        """初始化事务必需异常。
+        
+        Args:
+            message: 错误消息
+            *args: 其他参数
+        """
+        super().__init__(message, *args)
+
+
+class ServiceException(CoreException):
+    """服务层异常基类。
+    
+    所有服务层的业务异常都应该继承此类。
+    用于标识业务逻辑错误，区别于系统错误。
+    
+    Attributes:
+        message: 错误消息
+        code: 业务错误代码（可选，用于错误分类）
+        metadata: 额外的元数据（可选）
+    """
+    
+    def __init__(
+        self,
+        message: str,
+        code: str | None = None,
+        metadata: dict[str, object] | None = None,
+        *args: object,
+    ) -> None:
+        """初始化服务异常。
+        
+        Args:
+            message: 错误消息
+            code: 业务错误代码（可选）
+            metadata: 额外的元数据（可选）
+            *args: 其他参数
+        """
+        super().__init__(message, *args)
+        self.code = code
+        self.metadata = metadata or {}
+
+
+__all__ = [
+    "CoreException",
+    "ModelError",
+    "ServiceException",
+    "TransactionRequiredError",
+    "VersionConflictError",
+]
+
+