feat: 完整采集采购尺码候选 (#256)

client/src/pdd_purchase_adapter.py

@@ -6,9 +6,128 @@
 
 from __future__ import annotations
 
+import hashlib
 from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
-from typing import Mapping
+from typing import Mapping, Sequence
+
+
+def _hash_frame(value: str) -> str:
+    """按接口契约生成带 UTF-8 字节长度的哈希片段。"""
+
+    return f"{len(value.encode('utf-8'))}:{value}"
+
+
+@dataclass(frozen=True)
+class PurchaseSizeObservation:
+    """完整遍历时看到的一条第二规格，包含不可购买项。"""
+
+    raw_text: str
+    available: bool
+
+
+@dataclass(frozen=True)
+class PurchaseSpecCandidate:
+    """可以交给 Admin 解析的一条可购买尺码候选。"""
+
+    candidate_id: str
+    raw_text: str
+    options: Mapping[str, str]
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "candidate_id": self.candidate_id,
+            "raw_text": self.raw_text,
+            "options": dict(self.options),
+        }
+
+
+@dataclass(frozen=True)
+class PurchaseSpecCandidateSnapshot:
+    """当前商品、已选颜色下，一次完整且稳定的尺码候选观察。"""
+
+    goods_id: str
+    selected_color: str
+    target_size: str
+    dimension_name: str
+    observations: tuple[PurchaseSizeObservation, ...]
+    candidates: tuple[PurchaseSpecCandidate, ...]
+    candidate_snapshot_hash: str
+    observed_at: str
+
+    @classmethod
+    def build(
+        cls,
+        *,
+        goods_id: str,
+        selected_color: str,
+        target_size: str,
+        dimension_name: str,
+        observations: Sequence[PurchaseSizeObservation],
+        observed_at: str,
+    ) -> "PurchaseSpecCandidateSnapshot":
+        """按页面顺序生成候选短编号和 spec-resolution-v1 哈希。"""
+
+        checked_observations = tuple(observations)
+        candidates = tuple(
+            PurchaseSpecCandidate(
+                candidate_id=f"c{index}",
+                raw_text=item.raw_text,
+                options={"color": selected_color, "size": item.raw_text},
+            )
+            for index, item in enumerate(
+                (item for item in checked_observations if item.available),
+                start=1,
+            )
+        )
+        material = "".join(
+            (
+                _hash_frame("spec-resolution-v1"),
+                _hash_frame(goods_id),
+                _hash_frame(selected_color),
+                _hash_frame(str(len(candidates))),
+                *(
+                    "".join(
+                        (
+                            _hash_frame(item.candidate_id),
+                            _hash_frame(item.raw_text),
+                            _hash_frame(str(item.options["color"])),
+                            _hash_frame(str(item.options["size"])),
+                        )
+                    )
+                    for item in candidates
+                ),
+            )
+        )
+        return cls(
+            goods_id=goods_id,
+            selected_color=selected_color,
+            target_size=target_size,
+            dimension_name=dimension_name,
+            observations=checked_observations,
+            candidates=candidates,
+            candidate_snapshot_hash=hashlib.sha256(
+                material.encode("utf-8")
+            ).hexdigest(),
+            observed_at=observed_at,
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        """返回确定顺序的内存结构；调用方不得把它直接写入日志。"""
+
+        return {
+            "goods_id": self.goods_id,
+            "selected_color": self.selected_color,
+            "target_size": self.target_size,
+            "dimension_name": self.dimension_name,
+            "observations": [
+                {"raw_text": item.raw_text, "available": item.available}
+                for item in self.observations
+            ],
+            "candidates": [item.to_dict() for item in self.candidates],
+            "candidate_snapshot_hash": self.candidate_snapshot_hash,
+            "observed_at": self.observed_at,
+        }
 
 
 @dataclass(frozen=True)
@@ -46,6 +165,24 @@ class PddPurchaseError(RuntimeError):
         self.diagnostics = dict(diagnostics or {})
 
 
+class PddPurchaseSpecResolutionRequired(PddPurchaseError):
+    """本地无法精确匹配，但已得到完整可购买候选快照。"""
+
+    def __init__(self, snapshot: PurchaseSpecCandidateSnapshot) -> None:
+        super().__init__(
+            "PURCHASE_SPEC_RESOLUTION_REQUIRED",
+            f"目标尺码无法精确匹配，需要解析候选：{snapshot.target_size}",
+            step="purchase_select_options",
+            diagnostics={
+                "selection_failure": "target_not_visible",
+                "candidate_count": len(snapshot.candidates),
+                "candidate_snapshot_hash": snapshot.candidate_snapshot_hash,
+                "dimension_name": snapshot.dimension_name,
+            },
+        )
+        self.snapshot = snapshot
+
+
 class PddPurchaseAdapter(ABC):
     """一台设备的一次采购演练会话；只能由创建它的工作线程使用。"""