ForcePilot/backend/package/yuxi/external_systems/exceptions.py

"""外部系统限界上下文的异常层次。

设计原则（见设计方案 §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 验签/处理失败
"""

from __future__ import annotations

from typing import Any


class ExternalSystemError(Exception):
    """外部系统限界上下文根异常。

    所有本上下文抛出的异常都应继承此类，最外层统一捕获后映射为 HTTP 响应。
    ``status_code`` 作为异常到 HTTP 状态码的映射依据，子类按需覆盖。
    """

    status_code: int = 500

    def __init__(
        self,
        message: str,
        *,
        details: dict[str, Any] | None = None,
    ) -> None:
        super().__init__(message)
        self.message = message
        self.details = details or {}

    def __str__(self) -> str:
        return self.message


# ─── 业务规则异常 ──────────────────────────────────────────────────────────


class DomainValidationError(ExternalSystemError, ValueError):
    """领域校验失败。

    同时继承 ``ValueError`` 以兼容 Pydantic 的 ``field_validator`` 与 ``raise ValueError(...)``
    习惯写法（在 dataclass 薄校验中可直接 ``raise DomainValidationError(...)``）。
    """

    status_code = 400


class InvalidSlugError(DomainValidationError):
    """slug 非法或命中保留字。"""


class EnvironmentDisabledError(DomainValidationError):
    """禁用环境不能设为默认环境。"""


class ImportConflictError(DomainValidationError):
    """导入时发现 slug 冲突。"""


class SsrfViolationError(DomainValidationError):
    """SSRF 安全规则违反。"""

    status_code = 403


class CircuitBreakerStateError(DomainValidationError):
    """熔断器当前状态不允许重置。

    由 ``POST /circuit-breaker/reset`` 端点在熔断器状态为 ``closed`` 时抛出，
    表示熔断器未处于打开或半开状态，无需也无法重置。
    """


class EntityNotFoundError(ExternalSystemError):
    """领域实体不存在。

    统一覆盖原 ``ExternalSystemNotFoundError`` / ``ExternalSystemEnvironmentNotFoundError``
    / ``ExternalToolNotFoundError`` / ``ExternalAssetNotFoundError`` 四个异常。
    具体实体类型由 ``message`` 描述，``details`` 可携带 ``entity_type`` / ``identifier``。
    """

    status_code = 404


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

    def __init__(self, references: dict[str, dict[str, list[str]]]) -> None:
        self.references = references
        super().__init__(
            f"以下外部系统仍被引用，无法删除: {references}",
            details={"references": references},
        )


class ConflictError(ExternalSystemError):
    """资源冲突。

    表示写操作因唯一约束冲突或状态竞争无法完成（如版本号重复、slug 重复等）。
    与 ``ReferencedError`` 的区别：本异常表示新建/更新资源时与既有资源冲突，
    ``ReferencedError`` 表示删除资源时被其他实体引用。
    """

    status_code = 409


# ─── 框架技术异常 ──────────────────────────────────────────────────────────


class FrameworkError(ExternalSystemError):
    """框架层技术异常基类。

    覆盖适配器查找、认证插件查找、执行、密钥解析、认证失败等技术场景。
    与 ``DomainValidationError`` 的区别：本类描述"技术层面无法完成操作"，
    而非"业务规则不允许"。
    """


class AdapterNotFoundError(FrameworkError):
    """找不到对应 ``adapter_type`` 的适配器。

    同时覆盖原 ``IntegrationNotFoundError``（厂商集成找不到的情况合并到此处）。
    """

    status_code = 404


class AuthPluginNotFoundError(FrameworkError):
    """找不到对应 ``auth_type`` 的认证插件。"""

    status_code = 404


class IntegrationOperationNotRegisteredError(FrameworkError):
    """厂商操作未注册。

    由 ``IntegrationOperationRegistry`` 在 ``(operation, source_type)``
    未注册对应 handler 时抛出（PRD FR-08）。

    与 ``AdapterNotFoundError`` 的区别：本异常表示厂商集成已找到，
    但不支持指定的操作（如 salesforce 不支持 ``discover`` 操作的
    ``openapi`` source_type）；``AdapterNotFoundError`` 表示适配器类型本身不存在。
    """

    status_code = 400


class ExecutionError(FrameworkError):
    """执行阶段通用异常。

    覆盖原 ``ExternalSystemExecutionError``，表示适配器执行过程中发生的非业务异常
    （网络错误、协议错误、目标系统返回 5xx 等）。
    """

    status_code = 502


class RateLimitExceededError(ExecutionError):
    """超出限流阈值。

    由 ``RateLimiter`` 在令牌桶耗尽时抛出，对应原 ``ExternalSystemThrottledError``。

    结构化字段（写入 ``details``）：
    - ``retry_after``: 建议客户端等待秒数（令牌恢复时间）。
    - ``limit_type``: 限流类型，``qps`` 或 ``concurrency``。
    - ``system_id`` / ``env_key``: 限流维度。
    """

    status_code = 429

    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,
    ) -> None:
        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)


class CircuitOpenError(ExecutionError):
    """熔断器打开。

    由 ``CircuitBreaker`` 在熔断状态打开时抛出，对应原 ``ExternalSystemCircuitOpenError``。

    结构化字段（写入 ``details``）：
    - ``retry_after``: 剩余冷却秒数（熔断器进入 half_open 的等待时间）。
    - ``system_id`` / ``env_key``: 熔断维度。
    """

    status_code = 503

    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,
    ) -> None:
        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)


class SecretResolutionError(FrameworkError):
    """密钥解析失败。

    由 ``SecretResolver`` 在 ``secret_refs`` 引用的密钥不存在或无权访问时抛出，
    对应原 ``ExternalSystemSecretError``。
    """

    status_code = 400


class AuthError(FrameworkError):
    """认证失败。

    由 ``TokenManager`` / 认证插件在获取/刷新 token 失败时抛出，
    对应原 ``ExternalSystemAuthError``。
    """

    status_code = 403


class QuotaExceededError(ExecutionError):
    """配额耗尽。

    由 ``QuotaManager`` 在调用前预检发现配额已耗尽时抛出。
    与 ``RateLimitExceededError`` 同属执行节流类，但语义不同：
    限流是本地令牌桶节流，配额是远端系统配额耗尽。

    结构化字段（写入 ``details``）：
    - ``quota_key``: 配额键。
    - ``limit_value``: 配额上限。
    - ``used_value``: 已用配额。
    - ``remaining``: 剩余配额（通常为 0）。
    - ``system_id`` / ``env_key``: 配额维度。
    """

    status_code = 429

    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,
    ) -> None:
        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)


class AccessDeniedError(FrameworkError):
    """访问规则拒绝。

    由 ``AccessController`` 在执行前评估访问控制规则时，
    命中 deny 规则时抛出。与 ``AuthError`` 的区别：
    AuthError 是认证失败（token 无效），AccessDeniedError 是认证通过但无权限。
    """

    status_code = 403


class WebhookError(FrameworkError):
    """Webhook 验签或处理失败。

    由 ``WebhookVerifier`` 在验签失败、订阅不存在、密钥解密失败等场景抛出。
    """

    status_code = 400