feat(client): add Admin Gateway mock contract (#10)

2026-08-06 16:38:28 +08:00
parent 799ee33045
commit c412e8afe2
3 changed files with 647 additions and 0 deletions
@@ -0,0 +1,142 @@
+"""Client 访问 Admin 的稳定边界和简单数据对象。
+
+AdminGateway 只有领取任务、提交成功结果、提交失败结果三个业务方法。
+业务层不应直接依赖 HTTP 请求或 Mock 的内部实现。
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Mapping, Optional, Tuple
+
+from .task_models import TaskType
+
+
+@dataclass(frozen=True)
+class ClientInfo:
+    """发起领取请求的 Client 身份，不保存访问令牌。"""
+
+    client_id: str
+
+    def __post_init__(self) -> None:
+        if not self.client_id.strip():
+            raise ValueError("client_id 不能为空")
+
+
+@dataclass(frozen=True)
+class AndroidDeviceInfo:
+    """领取任务时上报的 Android 设备信息。"""
+
+    address: str
+    platform: str = "android"
+    pdd_package: str = "com.xunmeng.pinduoduo"
+
+    def __post_init__(self) -> None:
+        if not self.address.strip():
+            raise ValueError("设备地址不能为空")
+        if self.platform != "android":
+            raise ValueError("当前只支持 android 平台")
+        if not self.pdd_package.strip():
+            raise ValueError("PDD 包名不能为空")
+
+
+@dataclass(frozen=True)
+class ClaimCapabilities:
+    """Client 领取任务时声明的设备与执行能力。"""
+
+    device: AndroidDeviceInfo
+    supported_types: Tuple[TaskType, ...] = (
+        TaskType.COLLECT,
+        TaskType.PURCHASE,
+    )
+    purchase_mode: str = "dry_run"
+    schema_versions: Tuple[int, ...] = (1,)
+
+    def __post_init__(self) -> None:
+        if not self.supported_types:
+            raise ValueError("supported_types 不能为空")
+        if any(not isinstance(value, TaskType) for value in self.supported_types):
+            raise ValueError("supported_types 必须使用 TaskType")
+        if self.purchase_mode not in {"dry_run", "live"}:
+            raise ValueError("purchase_mode 只能是 dry_run 或 live")
+        if not self.schema_versions or any(
+            version <= 0 for version in self.schema_versions
+        ):
+            raise ValueError("schema_versions 必须是正整数")
+
+
+@dataclass(frozen=True)
+class AdminTask:
+    """Admin 派发给 Client 的一个任务。"""
+
+    task_id: str
+    task_type: TaskType
+    version: int
+    priority: int
+    payload: Mapping[str, Any] = field(default_factory=dict)
+    created_at: str = ""
+    updated_at: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.task_id.strip():
+            raise ValueError("task_id 不能为空")
+        if not isinstance(self.task_type, TaskType):
+            raise ValueError("task_type 必须使用 TaskType")
+        if self.version <= 0:
+            raise ValueError("version 必须大于 0")
+        if not isinstance(self.payload, Mapping):
+            raise ValueError("payload 必须是对象")
+
+
+@dataclass(frozen=True)
+class SubmissionReceipt:
+    """Admin 已接收并保存一次提交的确认。"""
+
+    accepted: bool
+    result_id: str
+    accepted_at: str
+
+
+class AdminGatewayError(RuntimeError):
+    """带稳定错误代码和可重试标志的 Admin 边界错误。"""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        retryable: bool,
+        request_id: str = "",
+        details: Optional[Mapping[str, Any]] = None,
+    ):
+        super().__init__(message)
+        self.code = code
+        self.retryable = retryable
+        self.request_id = request_id
+        self.details = dict(details or {})
+
+
+class AdminGateway(ABC):
+    """Admin 边界；不得增加状态查询、心跳或租约方法。"""
+
+    @abstractmethod
+    def claim_next(
+        self, client: ClientInfo, capabilities: ClaimCapabilities
+    ) -> Optional[AdminTask]:
+        """领取至多一个分配给当前 Client 的任务。"""
+
+    @abstractmethod
+    def submit_result(
+        self,
+        task_id: str,
+        idempotency_key: str,
+        result: Mapping[str, Any],
+    ) -> SubmissionReceipt:
+        """幂等提交采集或采购成功结果。"""
+
+    @abstractmethod
+    def submit_failure(
+        self,
+        task_id: str,
+        idempotency_key: str,
+        failure: Mapping[str, Any],
+    ) -> SubmissionReceipt:
+        """幂等提交失败、取消或人工处理结果。"""