fix: 蛇形遍历颜色并逐色采价 (#37)

2026-08-08 09:25:40 +08:00
parent e08fd89c91
commit 9562da9aad
7 changed files with 668 additions and 202 deletions
@@ -50,10 +50,16 @@ Client 顶级导航仅包含：
 - 已拼数量及原始显示文字；
 - 评价数量及原始显示文字（当前首页未提供时允许留空，不能为此反复滚动并阻塞规格采集）；
 - 所有规格维度及其可见值；
- 每个规格组合对应的价格、币种和可用状态；
+- 每个颜色对应的价格、币种，以及当前控件树显示的规格可用状态；
 - 采集时间、设备及必要诊断产物引用。

-颜色、尺码和价格不能只保存为互不关联的列表，必须以 SKU 规格组合保存价格关系。对于“1.2 万+”等近似数值，同时保存规范化数值、原始文字和近似标记。
+当前业务按颜色采价：进入规格面板后逐个选中颜色并立即读取稳定价格；尺码只
+收集文字和当前显示的可用状态，不逐个选择、不单独采价。提交时仍以 SKU 规格
+组合保存颜色与尺码关系，同一颜色的组合复用该颜色价格，
+`price_observed_at` 只记录实际选中的颜色，不得虚构已选尺码。以后需要按尺码
+区分价格或组合库存时，必须另行确认并改用 `price_granularity=sku`。
+
+对于“1.2 万+”等近似数值，同时保存规范化数值、原始文字和近似标记。

 ### 4.2 采购任务

@@ -355,8 +355,14 @@ reconcile_purchase(task, run) -> PurchaseResult | ManualReview
 PDD 页面可能出现登录失效、验证码、控件树不完整、A/B 页面、库存变化和价格变化。适配层必须返回结构化错误，不得把这些情况统一返回 `False`。

 采集商品时按“首页就绪 → 读取当前首页摘要 → 点击规格入口 → 确认规格面板
-出现 → 扫描颜色和尺码”的顺序执行。打开规格面板前不得为了寻找评价或店铺
-连续滚动商品详情；这两个可选字段缺失时保存证据，但不阻塞核心 SKU 采集。
+出现 → 颜色列表归左 → 按行蛇形逐色点击并采价 → 向下滚动并只读尺码 →
+组装结果”的顺序执行。颜色点击可能改变列表位置，因此每次点击后必须重新读取
+控件树，不能复用旧坐标；左右边缘以连续两次没有新颜色且视口稳定为准。
+
+当前业务价格粒度固定为颜色。第一行从左到右、下一行从右到左交替遍历，操作
+顺序采用蛇形以减少滑动，输出维度仍恢复为页面每行从左到右的自然顺序。尺码
+只读取文字和当前可用状态，不点击、不参与采价。打开规格面板前不得为了寻找
+评价或店铺连续滚动商品详情；这两个可选字段缺失时保存证据，但不阻塞核心采集。

 ## 10. 关键架构决策

@@ -502,6 +502,7 @@ CREATE TABLE app_settings (
    {
      "options": {"color": "黑色", "size": "L"},
      "price_cent": 3990,
+      "price_observed_at": {"color": "黑色"},
      "currency": "CNY",
      "available": true,
      "raw_price": "¥39.90"
@@ -518,6 +519,12 @@ CREATE TABLE app_settings (
 }
 ```

+当前采集任务使用 `price_granularity=color`。Client 逐个选中颜色读取价格，
+尺码只读取文字；因此同一颜色的多个尺码组合可以共享颜色价格，但
+`price_observed_at` 只能包含实际选中的颜色。它不能填写未点击、未确认的尺码。
+这里的 `available` 来自当前规格节点显示状态，不表示 Client 已逐个验证了每个
+颜色与尺码组合的实时库存。
+
 ### 8.2 采购结果

 采购任务在同一结构中增加：
@@ -283,7 +283,7 @@ Idempotency-Key: task-id:attempt-id:result-v1
      "options": {"color": "黑色", "size": "M"},
      "price_cent": 470,
      "list_price_cent": 1990,
-      "price_observed_at": {"color": "黑色", "size": "M"},
+      "price_observed_at": {"color": "黑色"},
      "available": true,
      "raw_price": "折后¥4.7"
    }]
@@ -309,7 +309,7 @@ Idempotency-Key: task-id:attempt-id:result-v1
 - `[必须]` 相同键但不同内容返回 `409 IDEMPOTENCY_CONFLICT`。
 - `[必须]` Client 只有收到 `accepted: true` 后才能把本地任务标为 `succeeded`。
 - `[必须]` `price_cent` 是实际支付价的整数分；划线价可放在 `list_price_cent`。
- `[必须]` `price_granularity` 只能是 `color` 或 `sku`。按颜色采样时填 `color`，并为每条 SKU 填写读取该价格时实际选中的 `price_observed_at`。
+- `[必须]` `price_granularity` 只能是 `color` 或 `sku`。当前 Client 按颜色采样时填 `color`；同一颜色的尺码组合可以共享颜色价格，但 `price_observed_at` 只填写实际选中的颜色，不得虚构尺码。以后逐个选择完整组合采价时才使用 `sku`。
 - `[必须]` `shop_name` 采不到时允许省略或留空；Admin 不得因此拒绝老版本 Client，也不得用空值覆盖已保存的店铺名。

 ### 6.1 Admin 必须无条件接受