fix: complete PDD spec panel traversal (#26)

2026-08-15 17:03:52 +08:00
parent 7b96810200
commit 72d614524b
11 changed files with 407 additions and 105 deletions
@@ -32,4 +32,4 @@

 ## 当前阶段

-当前 MVP 的 T01～T07、T09～T22 均已完成实现、验证并由用户验收。T08（只读实时屏幕）已延期且未实施，不属于当前 MVP。T17 已在一加/ColorOS 真机完成指定设备领取、空闲领取、PDD 商品详情页到达和部分结果提交验证，不包含华为兼容。T23 已完成 v2 一加真机实施验证，覆盖浏览器跳转、颜色文字安全点击、逐颜色稳定价格、全部可见尺码读取和颜色 × 尺码 SKU 展开，正在等待用户验收。当前实施范围仍是采集闭环；Agent 架构允许未来增加独立采购规则的创建订单能力，但付款能力禁止进入项目。
+当前 MVP 的 T01～T07、T09～T22 均已完成实现、验证并由用户验收。T08（只读实时屏幕）已延期且未实施，不属于当前 MVP。T17 已在一加/ColorOS 真机完成指定设备领取、空闲领取、PDD 商品详情页到达和部分结果提交验证，不包含华为兼容。T23 已完成 v2 一加真机实施验证，正在等待用户验收。T24 已完成规格面板锚定滚动、逐行蛇形颜色遍历和尺码续页实现，并以商品 `236231603269` 验证 14 色、8 尺码和 112 个 SKU，正在等待用户验收。当前实施范围仍是采集闭环；Agent 架构允许未来增加独立采购规则的创建订单能力，但付款能力禁止进入项目。
@@ -20,6 +20,7 @@
 - 商品详情步骤应声明精确 `activityName`，并与包名和唯一控件共同作为页面证据；进入 PDD 登录 Activity 必须返回 `PDD_LOGIN_REQUIRED`，不能提交采集成功。
 - 唯一文字节点不可点击时，Agent 只可点击其最近的可点击父容器；不得改点兄弟节点或相似文字。
 - v2 规则使用类型化动作和固定阶段钩子。已由 Agent 支持的选择器、别名、超时、滑动方向和有限次数可以只更新规则；新增动作类型或页面算法才需要升级 Agent。
+- 商品规格遍历必须用已识别规格节点锁定横向颜色容器和纵向面板容器；颜色按视觉行蛇形遍历，滑动完成后重新读取节点，尺码只读并允许在标题滚出后沿已锁定容器续页。
 - Agent 可扩展，但规则必须按任务类型授权：采集规则不能创建订单，采购规则未来可以使用独立的创建订单能力，任何规则都不能付款。

 ## 采集任务
@@ -87,9 +87,11 @@ Android 的 `pddProductDetailV1` 采集器执行以下固定流程：

 1. 以规则中的包名、精确 Activity 和节点选择器验证商品详情页，并持续识别登录、验证码、风控和失效商品页面。
 2. 在商品页有限次纵向查找安全规格入口；规格面板必须同时具备规格维度和确认摘要或可滚动区域等强证据。
-3. 颜色列表先向起点归边，再按可见行蛇形去重遍历；每次点击都在最新无障碍树中重新定位唯一控件，确认选中后连续读取相同价格。
-4. 尺码仅通过有限次纵向滑动读取，不点击尺码；颜色价格展开到该颜色下的可用尺码 SKU。
-5. 缺失颜色价格、尺码、第三规格维度或超过 SKU 上限时提交有界的 `completed_partial`；不猜测缺失值。采集期间离开商品页或出现验证码、登录、风控时明确失败。
+3. 规格面板以有界稳定读取恢复到顶部；横向颜色容器和纵向面板容器必须由已识别规格节点的祖先关系锁定，不能只按屏幕中最大滚动区域猜测。
+4. 颜色先归左，再按视觉行执行左到右、右到左交替的蛇形遍历；每次点击都在最新无障碍树中重新定位唯一文字控件，确认选中后连续读取相同价格。
+5. 滚动优先调用目标容器的无障碍前进/后退动作；回退坐标手势时必须等待系统完成回调。视口签名包含规格文字和 bounds，连续稳定后才确认到边。
+6. 尺码仅通过有限次纵向滑动读取，不点击尺码；首次定位后保存容器和选项结构，标题滚出屏幕后仍可续页。颜色价格展开到该颜色下的可用尺码 SKU。
+7. 缺失颜色价格、尺码、第三规格维度或超过 SKU 上限时提交有界的 `completed_partial`；不猜测缺失值。采集期间离开商品页或出现验证码、登录、风控时明确失败。

 无障碍节点只投影为 Agent 进程内的瞬时不可变模型，不序列化、不上传、不写入文件。完整状态机接入后 Agent 才上报 `collector.pdd.product-detail.v1`。

@@ -31,6 +31,7 @@
 | T21 | [#23](https://git.ilapage.cn/OPC/goauto/issues/23) | Android PDD 商品详情采集器 | T20 |
 | T22 | [#24](https://git.ilapage.cn/OPC/goauto/issues/24) | 内置规则模板与管理端校验 | T20、T21 |
 | T23 | [#25](https://git.ilapage.cn/OPC/goauto/issues/25) | v2 一加真机验收 | T20～T22 |
+| T24 | [#26](https://git.ilapage.cn/OPC/goauto/issues/26) | 修复 PDD 规格面板蛇形遍历与尺码续页 | T20～T23 |

 ## 延期

@@ -60,6 +60,16 @@ T17 只验证 PDD 商品采集最小闭环：Agent 注册与心跳、任务串
 - 标题和“已拼1件”已提交；页面未暴露店铺名和评价数量，因此按约定保存 `completed_partial` 和 `missing=[shopName, reviewCount]`，没有猜测字段。
 - T23 所需的浏览器跳转、颜色文字点击、逐颜色价格、全部可见尺码和颜色 × 尺码展开均已有真机证据，实施验证完成，等待用户验收。

+## 2026-08-15 T24 长规格列表复核
+
+- 商品 `236231603269` 的任务 23 初次结果只有颜色并标记 `missing:size`；真机面板实际存在尺码，确认属于 Agent 遍历提前结束，而非商品无尺码。
+- 修正后颜色容器与纵向规格面板通过当前规格节点的祖先关系分别锁定；规格面板先稳定归顶，颜色按视觉行交替方向蛇形遍历。
+- 已确认 Android 坐标手势原来在 450ms 完成前被读取，导致旧视口连续两次被误判为列表边缘。现在优先调用目标容器的无障碍滚动动作；坐标手势回退等待完成回调。
+- 最终重置复采状态为 `completed`、缺失清单为空：14 个颜色、14 个颜色价格、8 个尺码和 112 个完整可用 SKU；同一颜色价格按业务规则复制到各尺码。
+- 尺码包含 `S` 至 `4XL` 和页面实际提供的定制选项；Agent 全程只读尺码，没有点击尺码、订单或支付控件。
+- 标题候选改为与销量节点存在空间关联的文本，不再把页面任意最长文本当作商品标题；旧结果已由重置事务清除。
+- 全程只持久化结构化结果，未保存或上传原始控件树和截图。T24 实施与真机验证完成，等待用户验收。
+
 ## 支持范围

 当前 MVP 只维护一加/ColorOS 真机兼容，不包含华为 ROM。实机过程中发现的精确 Activity 页面证据和最近可点击父容器规则属于通用安全能力，继续保留。
@@ -118,4 +118,4 @@ Agent 不限制为“只能采集”，而是注册带版本的类型化能力

 ## 当前状态

-T19～T22 已验收：v2 契约、能力协商、Android 商品详情采集器、服务端内置模板和管理端安全编辑表单已经接入。T23 已在一加真机跑通浏览器跳转、规格面板强识别、颜色文字安全点击、逐颜色稳定价格、全部可见尺码读取和颜色 × 尺码 SKU 展开。任务 22 使用商品 `972800403573` 得到 2 个颜色、2 个尺码、2 个颜色价格和 4 个完整可用 SKU；同时通过真机问题修正排除了 `#一次选多款#` 这类功能入口。T23 实施验证完成，等待用户验收。
+T19～T22 已验收：v2 契约、能力协商、Android 商品详情采集器、服务端内置模板和管理端安全编辑表单已经接入。T23 已在一加真机跑通浏览器跳转、规格面板强识别、颜色文字安全点击、逐颜色稳定价格、全部可见尺码读取和颜色 × 尺码 SKU 展开。T24 进一步迁移并强化了源项目的逐行蛇形算法：用规格节点祖先锁定横纵容器、以文字和 bounds 判断视口、等待手势完成、尺码标题滚出后按容器结构续页。任务 23 使用商品 `236231603269` 得到 14 个颜色、8 个尺码、14 个颜色价格和 112 个完整可用 SKU，状态为 `completed`。T23、T24 实施验证完成，等待用户验收。