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

aury/boot/application/constants/components.py

@@ -35,6 +35,12 @@ class ComponentName(str, Enum):
     # 存储组件
     STORAGE = "storage"
 
+    # 消息队列组件
+    MESSAGE_QUEUE = "message_queue"
+
+    # 事件总线组件
+    EVENT_BUS = "event_bus"
+
     # 迁移组件
     MIGRATIONS = "migrations"
 

aury/boot/application/errors/handlers.py

@@ -9,6 +9,7 @@ from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING
 
 from fastapi import HTTPException, Request, status
+from fastapi.exceptions import RequestValidationError
 from fastapi.responses import JSONResponse
 from pydantic import ValidationError
 from sqlalchemy.exc import IntegrityError, SQLAlchemyError
@@ -121,9 +122,19 @@ class BaseErrorHandler(ErrorHandler):
         
         errors = [detail.model_dump() for detail in exception.details] if exception.details else None
         
+        # 兼容 ErrorCode 枚举和字符串
+        code_value = exception.code.value if hasattr(exception.code, "value") else exception.code
+        
+        # 尝试转换为 int，如果失败则使用 status_code
+        try:
+            code_int = int(code_value)
+        except (ValueError, TypeError):
+            # 非数字字符串（如 "TODO_ATTACHMENT_ERROR"），使用 HTTP 状态码作为 code
+            code_int = exception.status_code
+        
         response = ResponseBuilder.fail(
             message=exception.message,
-            code=int(exception.code.value),
+            code=code_int,
             errors=errors,
         )
         
@@ -160,11 +171,14 @@ class HTTPExceptionHandler(ErrorHandler):
 
 
 class ValidationErrorHandler(ErrorHandler):
-    """Pydantic验证异常处理器。"""
+    """验证异常处理器。
+    
+    处理 Pydantic ValidationError 和 FastAPI RequestValidationError。
+    """
     
     def can_handle(self, exception: Exception) -> bool:
         """判断是否为验证异常。"""
-        return isinstance(exception, ValidationError)
+        return isinstance(exception, ValidationError | RequestValidationError)
     
     async def handle(self, exception: Exception, request: Request) -> JSONResponse:
         """处理验证异常。"""

aury/boot/application/middleware/logging.py

@@ -16,7 +16,8 @@ from starlette.middleware.base import BaseHTTPMiddleware
 from starlette.requests import Request
 from starlette.responses import Response
 
-from aury.boot.common.logging import get_trace_id, logger, set_trace_id
+from aury.boot.application.errors import global_exception_handler
+from aury.boot.common.logging import get_request_contexts, logger, set_trace_id
 
 
 def log_request[T](func: Callable[..., T]) -> Callable[..., T]:
@@ -107,10 +108,7 @@ def _should_log_body(content_type: str | None) -> bool:
     if not content_type:
         return True
     content_type = content_type.lower()
-    for skip_type in SKIP_BODY_CONTENT_TYPES:
-        if skip_type in content_type:
-            return False
-    return True
+    return all(skip_type not in content_type for skip_type in SKIP_BODY_CONTENT_TYPES)
 
 
 class RequestLoggingMiddleware(BaseHTTPMiddleware):
@@ -189,6 +187,12 @@ class RequestLoggingMiddleware(BaseHTTPMiddleware):
             )
             logger.log(log_level.upper(), response_log)
             
+            # 记录请求上下文（user_id, tenant_id 等用户注册的字段）
+            request_contexts = get_request_contexts()
+            if request_contexts:
+                ctx_str = " | ".join(f"{k}: {v}" for k, v in request_contexts.items())
+                logger.info(f"[REQUEST_CONTEXT] Trace-ID: {trace_id} | {ctx_str}")
+            
             # 写入 access 日志（简洁格式）
             logger.bind(access=True).info(
                 f"{request.method} {request.url.path} {status_code} {duration:.3f}s"
@@ -211,7 +215,18 @@ class RequestLoggingMiddleware(BaseHTTPMiddleware):
                 f"请求处理失败: {request.method} {request.url.path} | "
                 f"耗时: {duration:.3f}s | Trace-ID: {trace_id}"
             )
-            raise
+            
+            # 记录请求上下文（即使异常也要记录，便于追踪问题）
+            request_contexts = get_request_contexts()
+            if request_contexts:
+                ctx_str = " | ".join(f"{k}: {v}" for k, v in request_contexts.items())
+                logger.info(f"[REQUEST_CONTEXT] Trace-ID: {trace_id} | {ctx_str}")
+            
+            # 使用全局异常处理器生成响应，而不是直接抛出异常
+            # BaseHTTPMiddleware 中直接 raise 会绕过 FastAPI 的异常处理器
+            response = await global_exception_handler(request, exc)
+            response.headers["x-trace-id"] = trace_id
+            return response
 
 
 class WebSocketLoggingMiddleware:
@@ -328,120 +343,6 @@ class WebSocketLoggingMiddleware:
             raise
 
 
-class WebSocketLoggingMiddleware:
-    """WebSocket 日志中间件。
-    
-    记录 WebSocket 连接生命周期和消息收发（可选）。
-    
-    使用示例:
-        from aury.boot.application.middleware.logging import WebSocketLoggingMiddleware
-        
-        app.add_middleware(WebSocketLoggingMiddleware, log_messages=True)
-    """
-    
-    def __init__(
-        self,
-        app,
-        *,
-        log_messages: bool = False,
-        max_message_length: int = 500,
-    ) -> None:
-        """初始化 WebSocket 日志中间件。
-        
-        Args:
-            app: ASGI 应用
-            log_messages: 是否记录消息内容（默认 False，注意性能和敏感数据）
-            max_message_length: 消息内容最大记录长度
-        """
-        self.app = app
-        self.log_messages = log_messages
-        self.max_message_length = max_message_length
-    
-    async def __call__(self, scope, receive, send) -> None:
-        if scope["type"] != "websocket":
-            await self.app(scope, receive, send)
-            return
-        
-        # 获取或生成 trace_id
-        headers = dict(scope.get("headers", []))
-        trace_id = (
-            headers.get(b"x-trace-id", b"").decode() or
-            headers.get(b"x-request-id", b"").decode() or
-            str(uuid.uuid4())
-        )
-        set_trace_id(trace_id)
-        
-        path = scope.get("path", "/")
-        client = scope.get("client")
-        client_host = f"{client[0]}:{client[1]}" if client else "unknown"
-        
-        start_time = time.time()
-        message_count = {"sent": 0, "received": 0}
-        
-        async def logging_receive():
-            message = await receive()
-            msg_type = message.get("type", "")
-            
-            if msg_type == "websocket.connect":
-                logger.info(
-                    f"WS → 连接: {path} | "
-                    f"客户端: {client_host} | Trace-ID: {trace_id}"
-                )
-            elif msg_type == "websocket.disconnect":
-                duration = time.time() - start_time
-                logger.info(
-                    f"WS ← 断开: {path} | "
-                    f"时长: {duration:.1f}s | "
-                    f"收/发: {message_count['received']}/{message_count['sent']} | "
-                    f"Trace-ID: {trace_id}"
-                )
-            elif msg_type == "websocket.receive":
-                message_count["received"] += 1
-                if self.log_messages:
-                    text = message.get("text") or message.get("bytes", b"").decode("utf-8", errors="replace")
-                    if len(text) > self.max_message_length:
-                        text = text[:self.max_message_length] + "..."
-                    logger.debug(f"WS → 收: {path} | {text}")
-            
-            return message
-        
-        async def logging_send(message):
-            msg_type = message.get("type", "")
-            
-            if msg_type == "websocket.send":
-                message_count["sent"] += 1
-                if self.log_messages:
-                    text = message.get("text") or message.get("bytes", b"").decode("utf-8", errors="replace")
-                    if len(text) > self.max_message_length:
-                        text = text[:self.max_message_length] + "..."
-                    logger.debug(f"WS ← 发: {path} | {text}")
-            elif msg_type == "websocket.close":
-                code = message.get("code", 1000)
-                reason = message.get("reason", "")
-                duration = time.time() - start_time
-                log_level = "warning" if code != 1000 else "info"
-                logger.log(
-                    log_level.upper(),
-                    f"WS × 关闭: {path} | "
-                    f"Code: {code}{' | 原因: ' + reason if reason else ''} | "
-                    f"时长: {duration:.1f}s | Trace-ID: {trace_id}"
-                )
-            
-            await send(message)
-        
-        try:
-            await self.app(scope, logging_receive, logging_send)
-        except Exception as exc:
-            duration = time.time() - start_time
-            logger.exception(
-                f"WS ✖ 异常: {path} | "
-                f"时长: {duration:.1f}s | "
-                f"收/发: {message_count['received']}/{message_count['sent']} | "
-                f"Trace-ID: {trace_id}"
-            )
-            raise
-
-
 __all__ = [
     "RequestLoggingMiddleware",
     "WebSocketLoggingMiddleware",

aury/boot/application/rpc/__init__.py

@@ -51,13 +51,13 @@ __all__ = [
     "BaseRPCClient",
     "CompositeServiceDiscovery",
     "ConfigServiceDiscovery",
-    "create_rpc_client",
     "DNSServiceDiscovery",
-    "get_service_discovery",
     "RPCClient",
     "RPCError",
     "RPCResponse",
     "ServiceDiscovery",
+    "create_rpc_client",
+    "get_service_discovery",
     "set_service_discovery",
 ]
 

aury/boot/commands/__init__.py

@@ -1,6 +1,21 @@
 """命令行工具模块。
 
-统一入口: aum
+统一入口: aury
+
+CLI 继承接口：
+    子框架（如 aury-django、aury-cloud）可以通过以下接口继承基础命令：
+    
+    - register_commands(app): 将所有命令注册到目标 app
+    - get_command_modules(): 获取所有命令模块，供进一步定制
+    
+    示例:
+        ```python
+        from typer import Typer
+        from aury.boot.commands import register_commands
+        
+        app = Typer(name="aury-django")
+        register_commands(app)  # 继承所有命令
+        ```
 """
 
 from __future__ import annotations
@@ -9,22 +24,27 @@ from __future__ import annotations
 from .config import ProjectConfig, get_project_config, save_project_config
 
 
-# 延迟导入 app 和 main，避免加载重型依赖
+# 延迟导入 app、main、register_commands、get_command_modules，避免加载重型依赖
 def __getattr__(name: str):
-    if name in ("app", "main"):
-        from .app import main as _main
+    if name in ("app", "main", "register_commands", "get_command_modules"):
+        from .app import _get_app, get_command_modules, main, register_commands
         if name == "main":
-            return _main
-        # app 通过 app 模块的 __getattr__ 获取
-        from . import app as app_module
-        return app_module.app
+            return main
+        if name == "app":
+            return _get_app()
+        if name == "register_commands":
+            return register_commands
+        if name == "get_command_modules":
+            return get_command_modules
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 
 __all__ = [
-    "app",
-    "main",
     "ProjectConfig",
+    "app",
+    "get_command_modules",
     "get_project_config",
+    "main",
+    "register_commands",
     "save_project_config",
 ]

aury/boot/commands/app.py

@@ -18,6 +18,22 @@
     aury worker                    # 运行 Worker
     aury migrate up                # 执行数据库迁移
     aury docs all --force          # 更新所有文档
+
+CLI 继承：
+    子框架（如 aury-django、aury-cloud）可以通过 `register_commands` 继承所有基础命令：
+    
+    ```python
+    from typer import Typer
+    from aury.boot.commands import register_commands
+    
+    app = Typer(name="aury-django")
+    register_commands(app)  # 继承所有 aury-boot 命令
+    
+    # 添加 django 特有命令
+    @app.command()
+    def startapp(name: str):
+        ...
+    ```
 """
 
 from __future__ import annotations
@@ -92,7 +108,119 @@ def main() -> None:
     _get_app()()
 
 
-# 为了向后兼容，允许 `from .app import app`
+def register_commands(
+    target_app: typer.Typer,
+    *,
+    include_init: bool = True,
+    include_add: bool = True,
+    include_generate: bool = True,
+    include_server: bool = True,
+    include_scheduler: bool = True,
+    include_worker: bool = True,
+    include_migrate: bool = True,
+    include_docker: bool = True,
+    include_docs: bool = True,
+) -> None:
+    """将 aury-boot 的所有命令注册到目标 Typer app。
+    
+    用于子框架（如 aury-django、aury-cloud）继承基础命令。
+    
+    Args:
+        target_app: 目标 Typer 应用
+        include_*: 是否包含对应的命令组
+    
+    使用示例:
+        ```python
+        from typer import Typer
+        from aury.boot.commands import register_commands
+        
+        app = Typer(name="aury-django")
+        
+        # 继承所有 aury-boot 命令
+        register_commands(app)
+        
+        # 或选择性继承
+        register_commands(app, include_docker=False)
+        
+        # 添加 django 特有命令
+        django_app = Typer(name="django")
+        
+        @django_app.command()
+        def startapp(name: str):
+            '''Django startapp'''
+            ...
+        
+        app.add_typer(django_app, name="django")
+        ```
+    """
+    # 延迟导入子命令
+    if include_init:
+        from .init import init
+        target_app.command(name="init", help="🎯 初始化项目脚手架")(init)
+    
+    if include_add:
+        from .add import app as add_app
+        target_app.add_typer(add_app, name="add", help="➕ 添加可选模块")
+    
+    if include_generate:
+        from .generate import app as generate_app
+        target_app.add_typer(generate_app, name="generate", help="⚡ 代码生成器")
+    
+    if include_server:
+        from .server import app as server_app
+        target_app.add_typer(server_app, name="server", help="🖥️  服务器管理")
+    
+    if include_scheduler:
+        from .scheduler import app as scheduler_app
+        target_app.add_typer(scheduler_app, name="scheduler", help="🕐 独立运行调度器")
+    
+    if include_worker:
+        from .worker import app as worker_app
+        target_app.add_typer(worker_app, name="worker", help="⚙️  运行任务队列 Worker")
+    
+    if include_migrate:
+        from .migrate import app as migrate_app
+        target_app.add_typer(migrate_app, name="migrate", help="🗃️  数据库迁移")
+    
+    if include_docker:
+        from .docker import app as docker_app
+        target_app.add_typer(docker_app, name="docker", help="🐳 Docker 配置")
+    
+    if include_docs:
+        from .docs import app as docs_app
+        target_app.add_typer(docs_app, name="docs", help="📚 生成/更新项目文档")
+
+
+def get_command_modules() -> dict[str, type]:
+    """获取所有命令模块，供子框架进一步定制。
+    
+    Returns:
+        dict: 命令名 -> 模块对象
+    
+    使用示例:
+        ```python
+        from aury.boot.commands import get_command_modules
+        
+        modules = get_command_modules()
+        # {'init': <module>, 'add': <module>, 'server': <module>, ...}
+        ```
+    """
+    from . import add, docker, docs, generate, init, migrate, scheduler, server, worker
+    
+    return {
+        "init": init,
+        "add": add,
+        "generate": generate,
+        "server": server,
+        "scheduler": scheduler,
+        "worker": worker,
+        "migrate": migrate,
+        "docker": docker,
+        "docs": docs,
+    }
+
+
+# 允许 `from .app import app`
 def __getattr__(name: str):
     if name == "app":
         return _get_app()
@@ -101,5 +229,7 @@ def __getattr__(name: str):
 
 __all__ = [
     "app",
+    "get_command_modules",
     "main",
+    "register_commands",
 ]

aury/boot/commands/docs.py

@@ -1,13 +1,15 @@
 """文档生成命令。
 
 提供命令行工具用于在现有项目中生成/更新文档：
-- aury docs dev         生成/更新 DEVELOPMENT.md
+- aury docs agents      生成/更新 AGENTS.md（AI 编程助手上下文）
+- aury docs dev         生成/更新 docs/ 目录（开发文档包）
 - aury docs cli         生成/更新 CLI.md
 - aury docs env         生成/更新 .env.example
 - aury docs all         生成/更新所有文档
 
 使用示例：
-    aury docs dev                    # 生成开发文档
+    aury docs agents                 # 生成 AI 编程助手上下文文档
+    aury docs dev                    # 生成 docs/ 开发文档包
     aury docs cli                    # 生成 CLI 文档
     aury docs env                    # 生成环境变量示例
     aury docs all                    # 生成所有文档
@@ -79,10 +81,17 @@ def _detect_project_info(project_dir: Path) -> dict[str, str]:
 
 
 def _render_template(template_name: str, context: dict[str, str]) -> str:
-    """渲染模板。"""
+    """渲染模板。
+    
+    支持根目录模板和 aury_docs/ 子目录模板。
+    """
+    # 先在根目录找
     template_path = TEMPLATES_DIR / template_name
     if not template_path.exists():
-        raise FileNotFoundError(f"模板文件不存在: {template_path}")
+        # 再在 aury_docs/ 子目录找
+        template_path = AURY_DOCS_TPL_DIR / template_name
+    if not template_path.exists():
+        raise FileNotFoundError(f"模板文件不存在: {template_name}")
     
     content = template_path.read_text(encoding="utf-8")
     return content.format(**context)
@@ -116,8 +125,8 @@ def _write_file(
     return True
 
 
-@app.command(name="dev")
-def generate_dev_doc(
+@app.command(name="agents")
+def generate_agents_doc(
     project_dir: Path = typer.Argument(
         Path("."),
         help="项目目录路径",
@@ -139,20 +148,84 @@ def generate_dev_doc(
         help="预览模式，不实际写入文件",
     ),
 ) -> None:
-    """生成/更新 DEVELOPMENT.md 开发文档。"""
+    """生成/更新 AGENTS.md（AI 编程助手上下文文档）。"""
     context = _detect_project_info(project_dir)
     
     console.print(f"[cyan]📚 检测到项目: {context['project_name']}[/cyan]")
     
     try:
-        content = _render_template("DEVELOPMENT.md.tpl", context)
-        output_path = project_dir / "DEVELOPMENT.md"
+        content = _render_template("AGENTS.md.tpl", context)
+        output_path = project_dir / "AGENTS.md"
         _write_file(output_path, content, force=force, dry_run=dry_run)
     except Exception as e:
         console.print(f"[red]❌ 生成失败: {e}[/red]")
         raise typer.Exit(1)
 
 
+# aury_docs/ 模板目录
+AURY_DOCS_TPL_DIR = TEMPLATES_DIR / "aury_docs"
+
+
+def _get_aury_docs_templates() -> list[Path]:
+    """动态扫描 aury_docs/ 模板目录。"""
+    if not AURY_DOCS_TPL_DIR.exists():
+        return []
+    return sorted(AURY_DOCS_TPL_DIR.glob("*.md.tpl"))
+
+
+@app.command(name="dev")
+def generate_dev_doc(
+    project_dir: Path = typer.Argument(
+        Path("."),
+        help="项目目录路径",
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        resolve_path=True,
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        "-f",
+        help="强制覆盖已存在的文件",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        "-n",
+        help="预览模式，不实际写入文件",
+    ),
+) -> None:
+    """生成/更新 aury_docs/ 开发文档包。"""
+    context = _detect_project_info(project_dir)
+    
+    console.print(f"[cyan]📚 检测到项目: {context['project_name']}[/cyan]")
+    console.print()
+    
+    # 确保输出目录存在
+    aury_docs_dir = project_dir / "aury_docs"
+    if not dry_run:
+        aury_docs_dir.mkdir(parents=True, exist_ok=True)
+    
+    success_count = 0
+    for tpl_path in _get_aury_docs_templates():
+        try:
+            output_name = tpl_path.stem  # 去掉 .tpl 后缀，保留 .md
+            output_path = aury_docs_dir / output_name
+            content = tpl_path.read_text(encoding="utf-8")
+            content = content.format(**context)
+            if _write_file(output_path, content, force=force, dry_run=dry_run):
+                success_count += 1
+        except Exception as e:
+            console.print(f"[red]❌ 生成 {tpl_path.name} 失败: {e}[/red]")
+    
+    console.print()
+    if dry_run:
+        console.print(f"[dim]🔍 预览模式完成，将生成 {success_count} 个文档到 aury_docs/ 目录[/dim]")
+    else:
+        console.print(f"[green]✨ 完成！成功生成 {success_count} 个文档到 aury_docs/ 目录[/green]")
+
+
 @app.command(name="cli")
 def generate_cli_doc(
     project_dir: Path = typer.Argument(
@@ -176,14 +249,18 @@ def generate_cli_doc(
         help="预览模式，不实际写入文件",
     ),
 ) -> None:
-    """生成/更新 CLI.md 命令行文档。"""
+    """生成/更新 aury_docs/99-cli.md 命令行文档。"""
     context = _detect_project_info(project_dir)
     
     console.print(f"[cyan]📚 检测到项目: {context['project_name']}[/cyan]")
     
     try:
-        content = _render_template("CLI.md.tpl", context)
-        output_path = project_dir / "CLI.md"
+        tpl_path = AURY_DOCS_TPL_DIR / "99-cli.md.tpl"
+        content = tpl_path.read_text(encoding="utf-8")
+        content = content.format(**context)
+        output_path = project_dir / "aury_docs" / "99-cli.md"
+        if not dry_run:
+            output_path.parent.mkdir(parents=True, exist_ok=True)
         _write_file(output_path, content, force=force, dry_run=dry_run)
     except Exception as e:
         console.print(f"[red]❌ 生成失败: {e}[/red]")
@@ -250,20 +327,30 @@ def generate_all_docs(
         help="预览模式，不实际写入文件",
     ),
 ) -> None:
-    """生成/更新所有文档（DEVELOPMENT.md, CLI.md, .env.example）。"""
+    """生成/更新所有文档（AGENTS.md, docs/, CLI.md, .env.example）。"""
     context = _detect_project_info(project_dir)
     
     console.print(f"[cyan]📚 检测到项目: {context['project_name']}[/cyan]")
     console.print()
     
-    docs_to_generate = [
-        ("DEVELOPMENT.md.tpl", "DEVELOPMENT.md", "开发文档"),
-        ("CLI.md.tpl", "CLI.md", "CLI 文档"),
+    # 根目录文档
+    root_docs: list[tuple[str, str, str]] = [
+        ("AGENTS.md.tpl", "AGENTS.md", "AI 编程助手上下文"),
         ("env.example.tpl", ".env.example", "环境变量示例"),
     ]
     
+    # aury_docs/ 开发文档
+    aury_docs_templates = _get_aury_docs_templates()
+    dev_docs = [
+        (tpl.name, f"aury_docs/{tpl.stem}", f"开发文档: {tpl.stem}")
+        for tpl in aury_docs_templates
+    ]
+    
+    # 合并所有文档
+    all_docs = root_docs + dev_docs
+    
     success_count = 0
-    for template_name, output_name, description in docs_to_generate:
+    for template_name, output_name, description in all_docs:
         try:
             content = _render_template(template_name, context)
             output_path = project_dir / output_name