refactor: 移除 Python 后端源码，全面迁移至 Rust gateway 架构

- 删除全部 Python 源码 (src/) 及 Alembic 迁移脚本，归档至 _deprecated_py_src/
- 重构 Rust gateway ai_pipeline: 拆分 planner/finalize 模块，新增 contracts/adaptation 层
- 重组 handlers 模块为 admin/public/proxy/internal/shared 子模块结构
- 新增 executor 模块，引入 Rust 原生数据库迁移 (aether-data/migrations)
- 简化 CI/Docker 构建流程，移除 base image 二级构建，统一为单一 app image
- 移除 Python 相关基础设施文件 (entrypoint.sh, gunicorn_conf.py, Dockerfile.base)

_deprecated_py_src/services/candidate/__init__.py

@@ -0,0 +1,28 @@
+"""
+Candidate domain (Phase2)
+
+This package centralizes:
+- candidate resolving (Provider/Endpoint/Key combinations)
+- request_candidates recording & audit
+- failover execution policies
+"""
+
+from src.services.candidate.policy import RetryMode, RetryPolicy, SkipPolicy
+from src.services.candidate.schema import (
+    CANDIDATE_KEY_SCHEMA_VERSION,
+    CandidateKey,
+    CandidateResult,
+)
+from src.services.candidate.service import CandidateService
+
+__all__ = [
+    "CandidateService",
+    # schema
+    "CANDIDATE_KEY_SCHEMA_VERSION",
+    "CandidateKey",
+    "CandidateResult",
+    # policies
+    "RetryMode",
+    "RetryPolicy",
+    "SkipPolicy",
+]

_deprecated_py_src/services/candidate/policy.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class RetryMode(str, Enum):
+    """Retry mode for candidate attempts."""
+
+    PRE_EXPAND = "pre_expand"  # pre-create retry slots (sync)
+    ON_DEMAND = "on_demand"  # create retry record only when retry happens
+    DISABLED = "disabled"  # no retry
+
+
+class FailoverAction(str, Enum):
+    """Failover decision after an attempt error."""
+
+    STOP = "stop"  # stop failover (client error / non-retriable)
+    CONTINUE = "continue"  # continue with next candidate
+    RETRY = "retry"  # retry current candidate
+
+
+@dataclass(frozen=True)
+class RetryPolicy:
+    """Unified retry policy."""
+
+    mode: RetryMode = RetryMode.DISABLED
+    max_retries: int = 1
+    retry_on_cached_only: bool = True
+
+    @classmethod
+    def for_sync_task(cls) -> "RetryPolicy":
+        return cls(mode=RetryMode.PRE_EXPAND, max_retries=2)
+
+    @classmethod
+    def for_async_task(cls) -> "RetryPolicy":
+        return cls(mode=RetryMode.DISABLED, max_retries=1)
+
+    @classmethod
+    def for_async_submit_with_retry(cls) -> "RetryPolicy":
+        return cls(mode=RetryMode.ON_DEMAND, max_retries=2)
+
+
+@dataclass(frozen=True)
+class SkipPolicy:
+    """Rules for skipping unsupported candidates."""
+
+    allow_format_conversion: bool = True
+    supported_auth_types: set[str] | None = None

_deprecated_py_src/services/candidate/recorder.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from sqlalchemy.orm import Session
+
+from src.models.database import RequestCandidate
+
+from .schema import CandidateKey
+
+
+class CandidateRecorder:
+    """Read helpers for RequestCandidate audit data."""
+
+    def __init__(self, db: Session):
+        self.db = db
+
+    def get_candidate_keys(self, request_id: str) -> list[CandidateKey]:
+        rows: list[RequestCandidate] = (
+            self.db.query(RequestCandidate)
+            .filter(RequestCandidate.request_id == request_id)
+            .order_by(RequestCandidate.candidate_index.asc(), RequestCandidate.retry_index.asc())
+            .all()
+        )
+
+        result: list[CandidateKey] = []
+        for row in rows:
+            provider_name = None
+            if getattr(row, "provider", None) is not None:
+                provider_name = getattr(row.provider, "name", None)
+
+            key_name = getattr(row, "api_key_name", None)
+
+            result.append(
+                CandidateKey(
+                    candidate_index=int(row.candidate_index or 0),
+                    retry_index=int(row.retry_index or 0),
+                    provider_id=str(row.provider_id) if row.provider_id else None,
+                    provider_name=str(provider_name) if provider_name else None,
+                    endpoint_id=str(row.endpoint_id) if row.endpoint_id else None,
+                    key_id=str(row.key_id) if row.key_id else None,
+                    key_name=str(key_name) if key_name else None,
+                    is_cached=bool(getattr(row, "is_cached", False)),
+                    status=str(getattr(row, "status", "") or "pending"),
+                    skip_reason=getattr(row, "skip_reason", None),
+                    error_type=getattr(row, "error_type", None),
+                    error_message=getattr(row, "error_message", None),
+                    status_code=getattr(row, "status_code", None),
+                    latency_ms=getattr(row, "latency_ms", None),
+                    extra_data=getattr(row, "extra_data", None),
+                )
+            )
+
+        return result

_deprecated_py_src/services/candidate/resolver.py

@@ -0,0 +1,10 @@
+"""
+CandidateResolver facade import.
+
+Phase2 keeps the implementation in `services/orchestration/` for compatibility,
+and gradually migrates it into this package.
+"""
+
+from src.services.orchestration.candidate_resolver import CandidateResolver
+
+__all__ = ["CandidateResolver"]

_deprecated_py_src/services/candidate/schema.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from src.services.scheduling.aware_scheduler import ProviderCandidate
+
+CANDIDATE_KEY_SCHEMA_VERSION = "1.0"
+
+
+@dataclass(frozen=True)
+class CandidateKey:
+    """Stable candidate key snapshot for audit."""
+
+    schema_version: str = CANDIDATE_KEY_SCHEMA_VERSION
+
+    candidate_index: int = 0
+    retry_index: int = 0
+
+    provider_id: str | None = None
+    provider_name: str | None = None
+    endpoint_id: str | None = None
+    key_id: str | None = None
+    key_name: str | None = None
+    auth_type: str | None = None
+    priority: int | None = None
+    is_cached: bool = False
+
+    status: str = "pending"  # pending/success/failed/skipped/available/...
+    skip_reason: str | None = None
+    error_type: str | None = None
+    error_message: str | None = None
+    status_code: int | None = None
+    latency_ms: int | None = None
+    extra_data: dict[str, Any] | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        data: dict[str, Any] = {
+            "schema_version": self.schema_version,
+            "candidate_index": self.candidate_index,
+            "retry_index": self.retry_index,
+            "provider_id": self.provider_id,
+            "provider_name": self.provider_name,
+            "endpoint_id": self.endpoint_id,
+            "key_id": self.key_id,
+            "key_name": self.key_name,
+            "auth_type": self.auth_type,
+            "priority": self.priority,
+            "is_cached": self.is_cached,
+            "status": self.status,
+            "skip_reason": self.skip_reason,
+            "error_type": self.error_type,
+            "error_message": self.error_message,
+            "status_code": self.status_code,
+            "latency_ms": self.latency_ms,
+            "extra_data": self.extra_data,
+        }
+        # drop Nones for compact audit payload
+        return {k: v for k, v in data.items() if v is not None}
+
+
+@dataclass(slots=True)
+class CandidateResult:
+    """Failover execution result."""
+
+    success: bool
+    selected: ProviderCandidate | None
+    selected_index: int | None
+    candidate_keys: list[CandidateKey]
+
+    external_task_id: str | None = None
+    error: Exception | None = None
+    last_status_code: int | None = None

_deprecated_py_src/services/candidate/service.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy.orm import Session
+
+from src.models.database import ApiKey
+from src.services.orchestration.error_classifier import ErrorClassifier
+from src.services.scheduling.aware_scheduler import ProviderCandidate, get_cache_aware_scheduler
+from src.services.system.config import SystemConfigService
+
+from .recorder import CandidateRecorder
+from .resolver import CandidateResolver
+from .schema import CandidateKey
+
+
+class CandidateService:
+    """
+    CandidateService (Facade).
+
+    Phase2 note: this is introduced as a new domain entrypoint. Legacy orchestrators
+    still exist and will be migrated gradually to use this service.
+    """
+
+    def __init__(self, db: Session, redis_client: Any | None = None) -> None:
+        self.db = db
+        self.redis = redis_client
+        self._cache_scheduler = None
+        self._resolver: CandidateResolver | None = None
+        self._error_classifier: ErrorClassifier | None = None
+        self._recorder = CandidateRecorder(db)
+
+    async def _ensure_initialized(self) -> None:
+        if self._cache_scheduler is not None:
+            return
+
+        priority_mode = SystemConfigService.get_config(
+            self.db,
+            "provider_priority_mode",
+            "provider",
+        )
+        scheduling_mode = SystemConfigService.get_config(
+            self.db,
+            "scheduling_mode",
+            "cache_affinity",
+        )
+        self._cache_scheduler = await get_cache_aware_scheduler(
+            self.redis,
+            priority_mode=priority_mode,
+            scheduling_mode=scheduling_mode,
+        )
+        self._resolver = CandidateResolver(db=self.db, cache_scheduler=self._cache_scheduler)
+        self._error_classifier = ErrorClassifier(db=self.db, cache_scheduler=self._cache_scheduler)
+
+    async def resolve(
+        self,
+        *,
+        api_format: str,
+        model_name: str,
+        affinity_key: str,
+        user_api_key: ApiKey | None = None,
+        request_id: str | None = None,
+        is_stream: bool = False,
+        capability_requirements: dict[str, bool] | None = None,
+        preferred_key_ids: list[str] | None = None,
+    ) -> tuple[list[ProviderCandidate], str]:
+        await self._ensure_initialized()
+        assert self._resolver is not None
+        return await self._resolver.fetch_candidates(
+            api_format=api_format,
+            model_name=model_name,
+            affinity_key=affinity_key,
+            user_api_key=user_api_key,
+            request_id=request_id,
+            is_stream=is_stream,
+            capability_requirements=capability_requirements,
+            preferred_key_ids=preferred_key_ids,
+        )
+
+    def create_candidate_records(
+        self,
+        *,
+        candidates: list[ProviderCandidate],
+        request_id: str,
+        user_api_key: ApiKey,
+        required_capabilities: dict[str, bool] | None = None,
+        expand_retries: bool = True,
+    ) -> dict[tuple[int, int], str]:
+        # CandidateResolver.create_candidate_records is currently the canonical implementation
+        assert self._resolver is not None, "Call resolve() once before create_candidate_records()"
+        return self._resolver.create_candidate_records(
+            all_candidates=candidates,
+            request_id=request_id,
+            user_id=str(user_api_key.user_id),
+            user_api_key=user_api_key,
+            required_capabilities=required_capabilities,
+            expand_retries=expand_retries,
+        )
+
+    def get_candidate_keys(self, request_id: str) -> list["CandidateKey"]:
+        return self._recorder.get_candidate_keys(request_id)

_deprecated_py_src/services/candidate/submit.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+import httpx
+
+from src.services.billing.rule_service import BillingRuleLookupResult
+from src.services.scheduling.aware_scheduler import ProviderCandidate
+
+
+@runtime_checkable
+class SubmitFunc(Protocol):
+    async def __call__(self, candidate: ProviderCandidate) -> httpx.Response: ...
+
+
+@runtime_checkable
+class ExtractExternalTaskIdFunc(Protocol):
+    def __call__(self, payload: dict[str, Any]) -> str | None: ...
+
+
+class UpstreamClientRequestError(RuntimeError):
+    """命中上游终止规则（不应继续 failover）的错误。"""
+
+    def __init__(
+        self,
+        *,
+        response: httpx.Response,
+        candidate_keys: list[dict[str, Any]],
+    ) -> None:
+        self.response = response
+        self.candidate_keys = candidate_keys
+        super().__init__(f"Upstream stop rule matched: HTTP {response.status_code}")
+
+
+class AllCandidatesFailedError(RuntimeError):
+    def __init__(
+        self,
+        *,
+        reason: str,
+        candidate_keys: list[dict[str, Any]],
+        last_status_code: int | None = None,
+    ) -> None:
+        self.reason = reason
+        self.candidate_keys = candidate_keys
+        self.last_status_code = last_status_code
+        super().__init__(f"All candidates failed: {reason}")
+
+
+class CandidateUnsupportedError(RuntimeError):
+    """候选不被当前任务支持（如 auth_type/格式转换需求不支持）。"""
+
+
+class CandidateSubmissionError(RuntimeError):
+    """候选提交异常（网络/解密/解析等）。"""
+
+
+@dataclass(slots=True)
+class SubmitOutcome:
+    candidate: ProviderCandidate
+    candidate_keys: list[dict[str, Any]]
+    external_task_id: str
+    rule_lookup: BillingRuleLookupResult | None
+    upstream_payload: dict[str, Any] | None = None
+    upstream_headers: dict[str, str] | None = None
+    upstream_status_code: int | None = None