"""外部系统限界上下文的异常层次。 设计原则（见设计方案 §8.1）： - **根异常 + 分层异常，一个文件**：保留 ``ExternalSystemError`` 根异常，按层内聚子异常。 - **统一兜底**：所有异常继承 ``ExternalSystemError``，最外层（Router / 全局异常处理器）统一捕获。 - **保留 ``ReferencedError`` 自定义 ``__init__``**：接收 ``references: dict[str, dict[str, list[str]]]`` 参数。 本文件位于包根目录（非 ``core/`` 下），因为异常被所有层共享（core / use_cases / framework / adapters），放在根目录便于统一导入路径。 异常层次： :: ExternalSystemError (500) # 根异常 ├── DomainValidationError (400, ValueError) # 业务规则异常 │ ├── InvalidSlugError # slug 非法或命中保留字 │ ├── EnvironmentDisabledError # 禁用环境不能设为默认 │ ├── ImportConflictError # 导入 slug 冲突 │ ├── SsrfViolationError (403) # SSRF 安全规则违反 │ └── CircuitBreakerStateError # 熔断器状态不允许重置 ├── EntityNotFoundError (404) # 领域实体不存在 ├── ReferencedError (409) # 被引用无法删除 ├── ConflictError (409) # 资源冲突（唯一约束/状态竞争） └── FrameworkError # 框架层技术异常 ├── AdapterNotFoundError (404) # 找不到适配器 ├── AuthPluginNotFoundError (404) # 找不到认证插件 ├── ExecutionError (502) # 执行阶段通用异常 │ ├── RateLimitExceededError (429) # 超出限流阈值 │ ├── CircuitOpenError (503) # 熔断器打开 │ └── QuotaExceededError (429) # 配额耗尽 ├── SecretResolutionError (400) # 密钥解析失败 ├── AuthError (403) # 认证失败 ├── AccessDeniedError (403) # 访问规则拒绝 ├── WebhookError (400) # Webhook 验签/处理失败 └── CapabilityNotSupportedError (501) # 适配器未实现可选能力 """ from __future__ import annotations from typing import Any class ExternalSystemError(Exception): """外部系统限界上下文根异常。 所有本上下文抛出的异常都应继承此类，最外层统一捕获后映射为 HTTP 响应。 ``status_code`` 作为异常到 HTTP 状态码的映射依据，子类按需覆盖。 ``error_code`` 作为稳定错误码，子类以类变量覆盖，用于驱动协议响应与日志关联。 ``trace_id`` 用于跨链路追踪关联。 """ status_code: int = 500 error_code: str = "EXTERNAL_SYSTEM_ERROR" def __init__( self, message: str, *, details: dict[str, Any] | None = None, trace_id: str | None = None, ) -> None: """初始化异常实例。 参数： message: 人类可读错误信息。 details: 业务字段字典，默认空字典。 trace_id: 调用链路追踪 ID，用于跨链路关联。 """ super().__init__(message) self.message = message self.details = details or {} self.trace_id = trace_id def to_dict(self) -> dict[str, Any]: """序列化为字典，便于跨层传递、日志记录与 API 响应。 返回 ``error_code`` / ``message`` / ``trace_id`` 三个基础字段， 并展开 ``details`` 中的业务字段。 """ return { "error_code": self.error_code, "message": self.message, "trace_id": self.trace_id, **self.details, } def __str__(self) -> str: """返回 ``[error_code] message`` 格式的字符串表示。""" return f"[{self.error_code}] {self.message}" # ─── 业务规则异常 ────────────────────────────────────────────────────────── class DomainValidationError(ExternalSystemError, ValueError): """领域校验失败。 同时继承 ``ValueError`` 以兼容 Pydantic 的 ``field_validator`` 与 ``raise ValueError(...)`` 习惯写法（在 dataclass 薄校验中可直接 ``raise DomainValidationError(...)``）。 """ status_code = 400 error_code = "VALIDATION_ERROR" class InvalidSlugError(DomainValidationError): """slug 非法或命中保留字。""" error_code = "INVALID_SLUG" class EnvironmentDisabledError(DomainValidationError): """禁用环境不能设为默认环境。""" error_code = "ENVIRONMENT_DISABLED" class ImportConflictError(DomainValidationError): """导入时发现 slug 冲突。""" error_code = "IMPORT_CONFLICT" class SsrfViolationError(DomainValidationError): """SSRF 安全规则违反。""" status_code = 403 error_code = "SSRF_VIOLATION" class CircuitBreakerStateError(DomainValidationError): """熔断器当前状态不允许重置。 由 ``POST /circuit-breaker/reset`` 端点在熔断器状态为 ``closed`` 时抛出， 表示熔断器未处于打开或半开状态，无需也无法重置。 """ error_code = "CIRCUIT_BREAKER_STATE_INVALID" class EntityNotFoundError(ExternalSystemError): """领域实体不存在。 统一覆盖原 ``ExternalSystemNotFoundError`` / ``ExternalSystemEnvironmentNotFoundError`` / ``ExternalToolNotFoundError`` / ``ExternalAssetNotFoundError`` 四个异常。 具体实体类型由 ``message`` 描述，``details`` 可携带 ``entity_type`` / ``identifier``。 """ status_code = 404 error_code = "NOT_FOUND" class ReferencedError(ExternalSystemError): """被引用无法删除。 保留自定义 ``__init__``，接收 ``references: dict[str, dict[str, list[str]]]`` 参数。 ``references`` 结构示例:: { "tools": {"by_slug": ["tool-a", "tool-b"]}, "environments": {"by_id": [1, 2]}, } """ status_code = 409 error_code = "REFERENCED" def __init__( self, references: dict[str, dict[str, list[str]]], *, trace_id: str | None = None, ) -> None: """初始化被引用无法删除异常。 参数： references: 被引用关系字典，结构示例见类 docstring。 trace_id: 调用链路追踪 ID，用于跨链路关联。 """ self.references = references super().__init__( f"以下外部系统仍被引用，无法删除: {references}", details={"references": references}, trace_id=trace_id, ) class ConflictError(ExternalSystemError): """资源冲突。 表示写操作因唯一约束冲突或状态竞争无法完成（如版本号重复、slug 重复等）。 与 ``ReferencedError`` 的区别：本异常表示新建/更新资源时与既有资源冲突， ``ReferencedError`` 表示删除资源时被其他实体引用。 """ status_code = 409 error_code = "CONFLICT" # ─── 框架技术异常 ────────────────────────────────────────────────────────── class FrameworkError(ExternalSystemError): """框架层技术异常基类。 覆盖适配器查找、认证插件查找、执行、密钥解析、认证失败等技术场景。 与 ``DomainValidationError`` 的区别：本类描述"技术层面无法完成操作"， 而非"业务规则不允许"。 """ error_code = "FRAMEWORK_ERROR" class AdapterNotFoundError(FrameworkError): """找不到对应 ``adapter_type`` 的适配器。 同时覆盖原 ``IntegrationNotFoundError``（厂商集成找不到的情况合并到此处）。 """ status_code = 404 error_code = "ADAPTER_NOT_FOUND" class AuthPluginNotFoundError(FrameworkError): """找不到对应 ``auth_type`` 的认证插件。""" status_code = 404 error_code = "AUTH_PLUGIN_NOT_FOUND" class IntegrationOperationNotRegisteredError(FrameworkError): """厂商操作未注册。 由 ``IntegrationOperationRegistry`` 在 ``(operation, source_type)`` 未注册对应 handler 时抛出（PRD FR-08）。 与 ``AdapterNotFoundError`` 的区别：本异常表示厂商集成已找到， 但不支持指定的操作（如 salesforce 不支持 ``discover`` 操作的 ``openapi`` source_type）；``AdapterNotFoundError`` 表示适配器类型本身不存在。 """ status_code = 400 error_code = "OPERATION_NOT_REGISTERED" class ExecutionError(FrameworkError): """执行阶段通用异常。 覆盖原 ``ExternalSystemExecutionError``，表示适配器执行过程中发生的非业务异常 （网络错误、协议错误、目标系统返回 5xx 等）。 """ status_code = 502 error_code = "EXECUTION_ERROR" class RateLimitExceededError(ExecutionError): """超出限流阈值。 由 ``RateLimiter`` 在令牌桶耗尽时抛出，对应原 ``ExternalSystemThrottledError``。 结构化字段（写入 ``details``）： - ``retry_after``: 建议客户端等待秒数（令牌恢复时间）。 - ``limit_type``: 限流类型，``qps`` 或 ``concurrency``。 - ``system_id`` / ``env_key``: 限流维度。 """ status_code = 429 error_code = "RATE_LIMIT_EXCEEDED" def __init__( self, message: str, *, retry_after: int | None = None, limit_type: str | None = None, system_id: int | str | None = None, env_key: str | None = None, details: dict[str, Any] | None = None, trace_id: str | None = None, ) -> None: """初始化限流超限异常。 参数： message: 人类可读错误信息。 retry_after: 建议客户端等待秒数（令牌恢复时间）。 limit_type: 限流类型，``qps`` 或 ``concurrency``。 system_id: 限流维度系统 ID。 env_key: 限流维度环境键。 details: 业务字段字典，与上述参数合并。 trace_id: 调用链路追踪 ID，用于跨链路关联。 """ merged: dict[str, Any] = dict(details or {}) if retry_after is not None: merged["retry_after"] = retry_after if limit_type is not None: merged["limit_type"] = limit_type if system_id is not None: merged["system_id"] = system_id if env_key is not None: merged["env_key"] = env_key super().__init__(message, details=merged, trace_id=trace_id) class CircuitOpenError(ExecutionError): """熔断器打开。 由 ``CircuitBreaker`` 在熔断状态打开时抛出，对应原 ``ExternalSystemCircuitOpenError``。 结构化字段（写入 ``details``）： - ``retry_after``: 剩余冷却秒数（熔断器进入 half_open 的等待时间）。 - ``system_id`` / ``env_key``: 熔断维度。 """ status_code = 503 error_code = "CIRCUIT_OPEN" def __init__( self, message: str, *, retry_after: int | None = None, system_id: int | str | None = None, env_key: str | None = None, details: dict[str, Any] | None = None, trace_id: str | None = None, ) -> None: """初始化熔断器打开异常。 参数： message: 人类可读错误信息。 retry_after: 剩余冷却秒数（熔断器进入 half_open 的等待时间）。 system_id: 熔断维度系统 ID。 env_key: 熔断维度环境键。 details: 业务字段字典，与上述参数合并。 trace_id: 调用链路追踪 ID，用于跨链路关联。 """ merged: dict[str, Any] = dict(details or {}) if retry_after is not None: merged["retry_after"] = retry_after if system_id is not None: merged["system_id"] = system_id if env_key is not None: merged["env_key"] = env_key super().__init__(message, details=merged, trace_id=trace_id) class SecretResolutionError(FrameworkError): """密钥解析失败。 由 ``SecretResolver`` 在 ``secret_refs`` 引用的密钥不存在或无权访问时抛出， 对应原 ``ExternalSystemSecretError``。 """ status_code = 400 error_code = "SECRET_RESOLUTION_FAILED" class AuthError(FrameworkError): """认证失败。 由 ``TokenManager`` / 认证插件在获取/刷新 token 失败时抛出， 对应原 ``ExternalSystemAuthError``。 """ status_code = 403 error_code = "AUTH_ERROR" class QuotaExceededError(ExecutionError): """配额耗尽。 由 ``QuotaManager`` 在调用前预检发现配额已耗尽时抛出。 与 ``RateLimitExceededError`` 同属执行节流类，但语义不同： 限流是本地令牌桶节流，配额是远端系统配额耗尽。 结构化字段（写入 ``details``）： - ``quota_key``: 配额键。 - ``limit_value``: 配额上限。 - ``used_value``: 已用配额。 - ``remaining``: 剩余配额（通常为 0）。 - ``system_id`` / ``env_key``: 配额维度。 """ status_code = 429 error_code = "QUOTA_EXCEEDED" def __init__( self, message: str, *, quota_key: str | None = None, limit_value: int | None = None, used_value: int | None = None, remaining: int | None = None, system_id: int | str | None = None, env_key: str | None = None, details: dict[str, Any] | None = None, trace_id: str | None = None, ) -> None: """初始化配额耗尽异常。 参数： message: 人类可读错误信息。 quota_key: 配额键。 limit_value: 配额上限。 used_value: 已用配额。 remaining: 剩余配额（通常为 0）。 system_id: 配额维度系统 ID。 env_key: 配额维度环境键。 details: 业务字段字典，与上述参数合并。 trace_id: 调用链路追踪 ID，用于跨链路关联。 """ merged: dict[str, Any] = dict(details or {}) if quota_key is not None: merged["quota_key"] = quota_key if limit_value is not None: merged["limit_value"] = limit_value if used_value is not None: merged["used_value"] = used_value if remaining is not None: merged["remaining"] = remaining if system_id is not None: merged["system_id"] = system_id if env_key is not None: merged["env_key"] = env_key super().__init__(message, details=merged, trace_id=trace_id) class AccessDeniedError(FrameworkError): """访问规则拒绝。 由 ``AccessController`` 在执行前评估访问控制规则时， 命中 deny 规则时抛出。与 ``AuthError`` 的区别： AuthError 是认证失败（token 无效），AccessDeniedError 是认证通过但无权限。 """ status_code = 403 error_code = "ACCESS_DENIED" class WebhookError(FrameworkError): """Webhook 验签或处理失败。 由 ``WebhookVerifier`` 在验签失败、订阅不存在、密钥解密失败等场景抛出。 """ status_code = 400 error_code = "WEBHOOK_ERROR" class CapabilityNotSupportedError(FrameworkError): """适配器未实现某项可选能力。 当适配器存在但不实现某项可选能力（如 ``validate_config``）时抛出， 由 Router 捕获 Python 内置 ``NotImplementedError`` 后翻译为本异常， 交由 ``unified_error_handler`` 统一映射为 HTTP 501，避免原生异常 被 ``unhandled_exception_handler`` 兜底为 500。 与 ``IntegrationOperationNotRegisteredError`` 的区别：本异常表示 适配器实例不支持该能力方法；后者表示厂商集成的操作未注册。 """ status_code = 501 error_code = "CAPABILITY_NOT_SUPPORTED" def __init__( self, capability: str, *, adapter_type: str | None = None, details: dict[str, Any] | None = None, trace_id: str | None = None, ) -> None: """初始化能力未支持异常。 参数： capability: 未实现的能力名称（如 ``validate_config``）。 adapter_type: 适配器类型，写入 ``details`` 供客户端参考。 details: 业务字段字典，与上述参数合并。 trace_id: 调用链路追踪 ID，用于跨链路关联。 """ merged: dict[str, Any] = dict(details or {}) if adapter_type is not None: merged["adapter_type"] = adapter_type merged["capability"] = capability adapter_desc = f" {adapter_type}" if adapter_type else "" super().__init__( f"适配器{adapter_desc}未实现能力: {capability}", details=merged, trace_id=trace_id, )