generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Android-Agent-API-Contract wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Android-Agent-API-Contract.- wiki_revision: 03ea269058b50fea2be7842b9c284018987c82d9 synchronized_at: 2026-09-21T08:15:05Z generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Android-Agent-API-Contract wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Android-Agent-API-Contract.- wiki_revision: ba259178cf6514d5b48ea425005dfd366ba803a3 synchronized_at: 2026-09-12T03:09:46Z # MVP 共享 API 契约 本文件是服务端、Web 和 Android 的共享契约事实来源。字段可以在实施工单中补充，但语义变化必须同步更新本文档。 ## 通用约定 - 正式环境默认只允许 HTTPS；管理员显式设置 `GOAUTO_ALLOW_INSECURE_AGENT_HTTP=true` 时，全部 `/api/agent/v1/**` 也接受 HTTP。Android Debug/Release 均可配置 HTTP 或 HTTPS Origin。 - 每台设备使用独立 Bearer Token。 - 时间使用 RFC 3339 UTC，金额使用整数分。 - 所有写接口携带 `requestId` 并保证幂等。 - 错误响应包含稳定的 `code`、可读的 `message` 和 `retryable`。 ## 管理端：PDD 商品 ```http POST /api/admin/v1/pdd-products PATCH /api/admin/v1/pdd-products/{productId} GET /api/admin/v1/pdd-products GET /api/admin/v1/pdd-products/{productId} ``` 新增请求只提交 `requestId` 和 `url`。服务端规范化 URL、提取 `goods_id`；无法提取时返回 `PDD_GOODS_ID_INVALID`，已存在时返回 `PDD_PRODUCT_EXISTS` 和现有商品 ID。编辑请求完整提交 URL、标题、店铺、数字销量/评价、状态和 `specs`；人工保存覆盖当前值，但不改变已有任务快照。 `specs` 是维度数组。维度包含非空 `name`、`role`（`color` / `size` / `other`）和非空 `values`；规格值包含 `name`、`selectable`，只有颜色值允许包含非负整数分 `priceCent`。列表支持 `keyword` 搜索 goods_id、标题或店铺，并支持 `status` 筛选。商品状态为 `pending`、`active`、`disabled`。列表项另返回 `collectionSelectable`、可选的 `collectionDisabledReason` 和 `activeCollectionTaskId`，供当前页批量选择；服务端提交时仍必须重新校验。 Android 提交结果的契约不增加字段：服务端在保存任务结果的同一事务更新 PDD 商品最新档案。`completed` 全量覆盖，`completed_partial` 合并明确获得的数据，`failed` 不更新；人工 `disabled` 状态不会被采集自动改回 `active`。 ## 管理端：虾皮商品 ```http GET /api/admin/v1/shopee-products POST /api/admin/v1/shopee-products GET /api/admin/v1/shopee-products/{productId} PATCH /api/admin/v1/shopee-products/{productId} POST /api/admin/v1/shopee-products/{productId}/link-pdd POST /api/admin/v1/shopee-products/{productId}/restore POST /api/admin/v1/shopee-products/{productId}/specs/values DELETE /api/admin/v1/shopee-products/{productId}/specs/values PUT /api/admin/v1/shopee-products/{productId}/specs/mapping DELETE /api/admin/v1/shopee-products/{productId}/specs/mapping POST /api/admin/v1/shopee-products/{productId}/specs/mapping/confirm POST /api/admin/v1/shopee-products/{productId}/specs/mapping/confirm-exact-matches POST /api/admin/v1/shopee-products/{productId}/specs/mapping/preview-auto-size POST /api/admin/v1/shopee-products/batch-delete ``` 创建与关联/映射相关写操作均提交 `requestId` 做幂等重放；重放请求返回相同结果并标记 `replayed`。创建请求提交 `shopeeItemId`、`title`、`shopName`，可选 `pddProductId` 和 `specs`；`shopeeItemId` 重复时返回 `SHOPEE_ITEM_ID_EXISTS` 和已存在商品 ID。`link-pdd` 校验 PDD 商品存在且非 `disabled`，否则分别返回 `PDD_PRODUCT_NOT_FOUND` 或 `PDD_PRODUCT_DISABLED`；关联成功后返回值包含 `sharedByPddCount`，表示当前共用同一 PDD 商品的虾皮商品数。 `specs` 结构同 PDD 商品的维度/规格值形状，但规格值额外携带 `source`（`import` / `manual`）与可选的 `mapping`（`pddValue`、`source`、`status`、`confidence`、`reason`）。新增规格值固定为 `manual` 来源；删除规格值仅允许 `manual` 来源，`import` 来源返回 `SPEC_VALUE_NOT_MANUAL`。设置映射时，`exact_match` 与 `ai_match` 来源一律写入 `pending` 状态，与请求体中的 `status` 无关；只有 `manual` 来源可以直接写入 `confirmed`。`confirm-exact-matches` 仅确认 `source=exact_match` 且状态为 `pending` 的映射，不影响 `ai_match`。该通用入口不因 #188 改变；#188 仅通过下述采购批量规格匹配接口的独立写入路径，将唯一确定性 `exact_match` 或通过高置信度门槛的 `ai_match` 写入 `confirmed`。 `preview-auto-size` 是只读计算接口（使用 `POST` 触发计算，不写数据库），无需 `requestId`。它读取当前蝦皮尺码与关联 PDD 的可选尺码，只返回格式统一后唯一确定的匹配；响应含 `items[]`（`valueName`、可选 `pddValue`、`status=preserved|matched|pending`、`reason`）、`pddValues`、`matchedCount` 和 `pendingCount`。已确认且目标仍存在的映射标为 `preserved`；无唯一结果标为 `pending`。Admin 的显式“保存修改”仍通过既有设置/确认接口落库。 设置映射时，`pddValue` 必须是关联 PDD 商品同角色下当前可选的原始规格标签，否则返回 `INVALID_REQUEST`。PDD 重新采集后旧目标消失时，Admin 标记失效；采购预检与任务创建返回 `PURCHASE_SPEC_MAPPING_REQUIRED` 和“规格匹配已失效，请重新选择 PDD 规格”，不得把旧标签下发给 Agent。 `batch-delete` 提交 `requestId` 和 `ids`（1～500 个），逐条校验引用后返回每条的 `status`（`deleted` / `skipped`）与 `reason`；引用检查覆盖 SYB 明细（#41）与采购任务（#33/#34），两张表落地前恒不阻塞删除。`restore` 恢复一条已软删除商品，恢复后原有 PDD 关联与规格映射保持不变。列表接口 `status=deleted` 筛选已删除商品，默认只返回存活商品。 ## 管理端：SYB 商品明细 ```http GET /api/admin/v1/syb-products GET /api/admin/v1/syb-products/{productId} POST /api/admin/v1/syb-products/import GET /api/admin/v1/syb-products/sync-runs GET /api/admin/v1/syb-products/sync-runs/{runId} POST /api/admin/v1/syb-products/{productId}/reparse POST /api/admin/v1/syb-products/reparse-batch PATCH /api/admin/v1/syb-products/{productId}/correction ``` `import` 允许已认证的管理员（admin）和采购员（purchaser）调用（#236），仍须通过 Casbin 权限校验；其他角色返回 403。采购员的 POST 权限由既有启动权限对账写入，不需要新增数据库迁移。操作人取已认证 claims，不接受客户端冒名。请求体提交 `dateFrom`、`dateTo` 后创建持久化后台任务并立即以 `202` 返回 `runId` 和 `status=running`；关闭弹窗、刷新或离开页面不影响任务。没有启用店铺时必须在读取凭据、登录、验证码 OCR 和任意 SYB 网络请求之前返回 `422`。任意时刻只能有一条 `running` 记录，内存锁与数据库唯一执行槽共同阻止单进程和跨进程重复导入；冲突时返回正在执行任务的日期范围。 `sync-runs` 列表支持 `page`、`pageSize`、`status`、`dateFrom`、`dateTo`，详情返回日期范围、状态（`running` / `succeeded` / `partial_success` / `failed` / `interrupted`）、处理天数、货运单/明细/新增/覆盖数量、店铺准入与跳过数量、店铺筛选快照哈希、按店铺的 `accepted` / `skipped` 统计、操作人和起止时间。列表和详情对已登录角色只读开放。服务启动时遗留的 `running` 任务改为 `interrupted`；中途失败或中断已经写入的数据保留，重新导入仍按唯一键覆盖。 列表返回结构化字段（`orderCode`、`shopeeItemId`、`productTitle`、`targetColor`、`targetSize`、`quantity`、`unitPriceCent`、`imageUrl`、`parseStatus`、`parseNote`、`manuallyConfirmed`），不含原始 JSON；`keyword` 匹配订单号、虾皮商品ID 或商品标题，`parseStatus` 筛选 `success`/`uncertain`/`failed`。详情额外返回 `rawJson`（原始 `details[]` 元素，未做任何改写）。 `reparse` 与 `reparse-batch` 只读取已保存的 `rawJson` 重新执行解析规则，不请求 SYB 接口；请求体 `force` 为 `true` 时才覆盖 `manuallyConfirmed` 的行，默认跳过并在批量结果中标记 `skipped_manual`。批量结果逐条返回 `outcome`（`reparsed` / `skipped_manual` / `unchanged`）与解析状态变化，`ids` 中任何一个不存在都会使整个请求返回错误（与虾皮商品批量删除的"部分成功"语义不同：ID 不存在通常是操作员选错了页面）。 `correction` 提交 `targetColor`、`targetSize`，覆盖解析结果并标记 `manuallyConfirmed=true`；非空的人工修正与解析成功同等可信，会合并进已关联的虾皮商品档案。 ## 管理端：SYB 店铺 ```http GET /api/admin/v1/syb-shops POST /api/admin/v1/syb-shops PATCH /api/admin/v1/syb-shops/{shopId}/name PATCH /api/admin/v1/syb-shops/{shopId}/enabled DELETE /api/admin/v1/syb-shops/{shopId} POST /api/admin/v1/syb-shops/discover ``` 列表支持 `keyword`、`enabledOnly`、`page` 和 `pageSize`，返回店铺原名、规范化名称、启用状态及分页汇总。写操作由 go-admin/Casbin 仅授权管理员；其他角色只读。删除为软删除，不清理已经导入的数据。 `discover` 提交日期范围，从 SYB 真实货运单列表发现店铺，返回 `shopName` 和 `status`（`new` / `exists`）；发现只读，不自动新增。店铺比较固定执行首尾去空白、全角/半角统一和忽略大小写。同步先完成原始列表完整性校验，再按一次性启用店铺快照过滤；明细响应中的店铺名为空或不在快照内时不得写入。 ## 管理端：SYB 商品过滤（#269） ```http GET /api/admin/v1/syb-product-filters POST /api/admin/v1/syb-product-filters PATCH /api/admin/v1/syb-product-filters/{id}/enabled DELETE /api/admin/v1/syb-product-filters/{id} ``` 同步时按 `variationSku` 决定明细是否入库。规则分两类，由 `kind` 区分：`char` 是结构判据 （`-`、`#`），`keyword` 是关键词清单。列表支持 `kind`、`keyword` 和分页，返回 `keyword`、 `normalizedKeyword`、`enabled`、`lastHitCount`、`lastHitAt`、`note`，`char` 另有 `lastChangedBy`、`lastChangedAt`。 `[必须]` 服务端必须拒绝对 `kind=char` 行的 `POST` 新增与 `DELETE` 删除，分别返回 `FORBIDDEN`（`结构过滤不可新增` / `结构过滤不可删除`），不得只依赖前端隐藏按钮。 `kind=char` 的 `PATCH enabled` 允许，并记录操作人与时间。 `[必须]` `lastHitCount` 是每条规则各自的命中数，由同步结束时回写；未命中的规则写 0， 从未同步过为 `null`。停用 `kind=char` 的二次确认提示条数必须取该行实时的 `lastHitCount`， 不得写死——写死的数字在数据变化后会给出错误警告。 关键词归一化与店铺一致：去首尾空白、全角/半角统一、忽略大小写；**不做简繁转换**，SYB 数据 为繁体。唯一性按 (`kind`, `normalizedKeyword`) 判定，重复添加返回 `SYB_PRODUCT_FILTER_DUPLICATE`。写操作由 go-admin/Casbin 仅授权管理员，其他角色只读。 删除为软删除，不清理已经入库的商品明细。 ## 管理端：采集规则 ```http POST /api/admin/v1/collection-rules PATCH /api/admin/v1/collection-rules/{ruleId} DELETE /api/admin/v1/collection-rules/{ruleId} GET /api/admin/v1/collection-rules GET /api/admin/v1/collection-rules/templates/pdd-product-detail-v1 ``` 规则只有 `name` 和 `content` 等当前值，创建成功后立即可用。删除为软删除；已删除规则不能创建新任务，已有任务继续使用任务内快照。 模板接口返回服务端内置的完整 v2 `content`，以及浏览器包名、别名数量/长度、超时、遍历上限和规格面板滑动动作的可编辑范围。管理端以安全表单修改这些参数，并显示只读 JSON 预览；模板中的采集器 ID、价格解析器、页面根证据、动作类型和语义目标不可在界面中改写。最终创建或更新请求仍由服务端按完整 v2 契约重新校验，不能依赖前端校验。 `content` 支持原有 `schemaVersion: 1` 线性步骤和 `schemaVersion: 2` 类型化采集器契约。v1 契约如下： ```json { "schemaVersion": 1, "packageName": "com.xunmeng.pinduoduo", "steps": [ { "id": "extract-title", "page": "product-detail", "activityName": "com.xunmeng.pinduoduo.activity.NewPageActivity", "action": "extract", "selector": {"resourceId": "com.xunmeng.pinduoduo:id/title"}, "field": "title", "timeoutMs": 5000 } ] } ``` - `action` 只允许 `wait`、`click`、`input`、`back`、`extract`；除 `back` 外都必须有非空 `selector`。 - `selector` 可组合 `resourceId`、`text`、`contentDescription`、`className`、`clickable`，执行操作前必须唯一命中；不唯一时以 `RULE_AMBIGUOUS` 失败，不猜测目标。 - 点击步骤仍以唯一命中的节点作为语义证据；若文字节点本身不可点击，只允许沿其父链点击最近的 `clickable` 容器，不搜索兄弟节点或相近候选。父链不存在可点击容器时以 `RULE_ACTION_FAILED` 失败。 - 每一步可以用 `packageName` 覆盖根级默认值；只允许拼多多、受支持浏览器和 Android 系统选择器包。 - `activityName` 可声明该步骤允许执行的精确 Activity；商品详情页规则应同时校验 PDD 包名、目标 Activity 和唯一控件，避免登录页等同包页面误判为商品页。 - `input` 必须有 `value`，`extract` 必须有 `field`；单步 `timeoutMs` 范围为 100～30000 毫秒。 - `optional: true` 仅表示单步超时后继续，适合不同 ROM 可能不存在的浏览器/系统“打开”确认层；多匹配和动作执行失败仍立即失败。 - 规则解析阶段按用途校验文字：支付、付款、提交订单等可以出现在只读识别字段中，但不能成为点击目标；修改地址、收货地址在可配置点击目标和只读识别字段中都拒绝。完整控件树只在 Android 内存中用于匹配，不保存也不上传。 - 浏览器和 Android 系统包中的 `click` 只允许精确目标 `打开拼多多APP`、`打开拼多多 App` 或 `打开`；其它点击在规则解析阶段拒绝。Android 先以浏览器打开服务端已规范化的 PDD URL，再由这些受控步骤进入拼多多。 ### v2 PDD 商品详情规则 v2 完整示例见 [PDD 商品详情规则](rules/pdd-product-detail-v2.proposed.json)。规则声明： - `ruleType: pddProductDetail`。 - `navigation.steps`：只负责浏览器和系统确认层；不能点击 PDD 页面。 - `pageEvidence`：精确的 PDD 包名、Activity 和非空节点证据。 - `collector.collectorId: pddProductDetailV1`：引用 Agent 中经过测试的类型化能力，不下发可执行代码。 - `hooks.afterSpecPanelOpen`：固定阶段的安全动作；当前只允许对语义目标 `specPanel` 执行 `swipe`，方向为上下左右、单动作次数 1～5、等待 0～2000 毫秒，单阶段最多 8 个动作。 - `pageRecovery.transientSoldOut`：商品详情页出现规则配置的 `exactText`，或顶部区域出现 `fallbackTopText` 且缺少主商品规格/购买强证据时，允许对商品页执行一次有界恢复；内置默认值仍为“商品已售罄”与“相似商品”，默认下拉 2 次、间隔 1000 毫秒。推荐卡片自身的标题、价格和销量不属于主商品证据。`fallbackTopText` 缺省时 Agent 使用“相似商品”兼容旧快照。Agent 必须声明无障碍手势能力，且只把系统回调完成的下拉计为成功。规格面板内的 SKU 售罄不触发。恢复后仍异常时失败码为 `PDD_GOODS_SOLD_OUT`。 - `navigationRecovery.reopenBrowser`：首次跳转未通过精确商品详情页证据时，Agent 重新显式打开任务 `urlSnapshot` 并重放安全导航步骤；最多恢复 1 次，重开后等待 500～5000 毫秒。登录、验证码、风控、无效链接和进入详情页后的采集失败不触发。 - `collector.dimensionAliases`、`collector.textAliases`、`timeoutsMs` 和 `limits`：分别管理颜色/尺码分类别名、只读页面识别文案、超时和遍历/SKU 上限。`textAliases` 可选；旧规则快照缺省时 Agent 使用当时内置默认值。新规则可在 `specPanel`、`dimension`、`selection`、`review`、`soldOut`、`purchase` 六组中配置面板、维度、选择摘要、评价入口、主商品证据和购买入口文字；每个数组为 1～20 项、单项不超过 30 个 Unicode 字符、不得有首尾空白或重复项。维度分类只依据规则的 `dimensionAliases`，代码不再以“颜色/款式/尺码/尺寸”字面量兜底，因此规则可以真实收窄。订单和支付文字允许作为只读识别证据；`修改地址`、`收货地址` 始终拒绝。用于阻止创建订单、确认订单、支付和付款控件成为采集点击目标的拒绝清单固定保留在 Agent，不能由规则覆盖。 例如规格面板打开后向上滑动两次，只修改规则： ```json {"hooks":{"afterSpecPanelOpen":[{"action":"swipe","target":"specPanel","direction":"up","count":2,"settleMs":350}]}} ``` Agent 使用可扩展的类型化动作注册表，而不是任意脚本。采集规则不能创建订单；采购规则可以引用单独审核的创建订单能力。当前契约不实现支付动作，`pay` / `payment` 动作仍被拒绝；订单和支付文字只允许作为只读识别信号，不能成为点击目标。 Android 的 `pddProductDetailV1` 采集器执行以下固定流程： 1. 以规则中的包名、精确 Activity 和节点选择器验证商品详情页，并持续识别登录、验证码、风控和失效商品页面。 2. 在商品页有限次纵向查找安全规格入口；规格面板必须同时具备规格维度和确认摘要或可滚动区域等强证据。 - 入口候选排除评价、评论、晒单和问答上下文，不使用全页面“规格词 + 任意数字”猜测；底部兜底必须命中真实购买/拼单文字及其可点击链路，且排除提交订单与支付语义。 - 商品评价页与详情页共用 `NewPageActivity` 时，首次误触允许全局返回、重新验证详情页并重新定位一次；第二次误触停止。点击无变化、误入评价页和面板证据不匹配分别返回 `SPEC_ENTRY_CLICK_NO_EFFECT`、`SPEC_ENTRY_OPENED_REVIEW`、`SPEC_PANEL_EVIDENCE_NOT_MATCHED`。 3. 规格面板以有界稳定读取恢复到顶部；横向颜色容器和纵向面板容器必须由已识别规格节点的祖先关系锁定，不能只按屏幕中最大滚动区域猜测。 4. 颜色先归左，再按视觉行执行左到右、右到左交替的蛇形遍历；每次点击都在最新无障碍树中重新定位唯一文字控件。点击后必须取得目标选中、已选摘要或规格面板选中状态/价格变化证据，等待短暂刷新后连续读取相同价格；其他颜色残留选中标记不能阻塞当前颜色，同价合法，但动作无效果时不能沿用点击前旧价格。结构化轨迹只记录短颜色标签、点击结果、证据类型、价格采样和 `selection_not_confirmed`、`price_not_found`、`price_not_stable` 原因。 5. 滚动优先调用目标容器的无障碍前进/后退动作；回退坐标手势时必须等待系统完成回调。视口签名包含规格文字和 bounds，连续稳定后才确认到边。 6. 尺码仅通过有限次纵向滑动读取，不点击尺码；首次定位后保存容器和选项结构，标题滚出屏幕后仍可续页。颜色价格展开到该颜色下的可用尺码 SKU。 7. 缺失颜色价格、尺码、第三规格维度或超过 SKU 上限时提交有界的 `completed_partial`；不猜测缺失值。采集期间离开商品页或出现验证码、登录、风控时明确失败。 无障碍节点只投影为 Agent 进程内的瞬时不可变模型，不序列化、不上传、不写入文件。完整状态机接入后 Agent 才上报 `collector.pdd.product-detail.v1`。 ## 管理端：AI 规格匹配设置 ```http GET /api/admin/v1/ai-matching-settings PUT /api/admin/v1/ai-matching-settings POST /api/admin/v1/ai-matching-settings/test ``` 这是采购规格匹配的单例配置，Provider 固定为 `openai_compatible`。管理员可读取、保存和测试连接；保存请求包含 `enabled`、`baseUrl`、`model`、`timeoutSeconds` 与 `apiKey`。`timeoutSeconds` 默认 15，允许范围为 3～600 秒。根据 #62 已确认的内部部署例外，管理员 `GET` 响应会返回已保存的明文 `apiKey`，供下次查看和替换；采购员 `GET` 只返回 `enabled`，不能读取 Provider、地址、模型或 API Key，也不能保存或测试。 Base URL 支持内网或公网的 `http://`、`https://`，不限制为局域网地址。服务端只在管理员点击测试或采购规格没有唯一确定性结果时，才向 Provider 发送目标颜色/尺码和 PDD 可选颜色/尺码；请求中不包含控件树、截图、地址、账号或订单。HTTP 不加密 API Key 的传输，生产环境建议使用 HTTPS。服务端禁止跟随 Provider 重定向，Provider 返回的颜色/尺码必须逐字等于当前候选原始标签，否则按无匹配处理。 ## 管理端：采集任务 ```http POST /api/admin/v1/collection-tasks POST /api/admin/v1/collection-tasks/batch GET /api/admin/v1/collection-tasks GET /api/admin/v1/collection-tasks/{taskId} POST /api/admin/v1/collection-tasks/{taskId}/reset DELETE /api/admin/v1/collection-tasks/{taskId} ``` 创建请求： ```json { "requestId": "uuid", "pddProductId": "product-id", "ruleId": "rule-id", "deviceId": "device-id-or-null" } ``` 服务端在事务中复制当前 `url`、`goods_id` 和完整规则内容到任务。同一商品已有 `pending` 或 `running` 任务时返回 `PDD_PRODUCT_TASK_ACTIVE`。 批量创建请求： ```json { "requestId": "batch-uuid", "pddProductIds": [1, 2, 3], "ruleId": 2, "deviceId": null } ``` `pddProductIds` 必须包含 1～100 个不重复的有效 ID。一个批次统一使用当前规则和可选设备；每个商品独立调用单任务创建事务并固化自己的 URL、goods_id、规则和设备快照。批次 `requestId` 与商品 ID 派生稳定的逐项创建标识，同一请求重放返回原任务，不重复创建。 HTTP 200 响应返回 `successCount`、`failureCount` 和按请求顺序排列的 `items`。成功项包含 `pddProductId`、`success: true`、`taskId` 和可选 `replayed`；失败项包含 `success: false`、稳定 `code` 和普通人可理解的 `message`。商品已停用返回 `PDD_PRODUCT_DISABLED`，活动任务冲突返回 `PDD_PRODUCT_TASK_ACTIVE`。逐项失败不回滚其它成功项；请求 JSON、批次 UUID、重复商品或数量上限无效时整体返回 `INVALID_REQUEST`。 重置只允许 `completed`、`completed_partial` 或 `failed`： - 保留 `pddProductId`、`deviceId`、`urlSnapshot`、`goodsIdSnapshot`、`ruleId` 和 `ruleSnapshot`。 - 删除全部规格维度、规格值、SKU 和 SKU 值关联。 - 清空标题、店铺、销量、评价、错误与执行时间。 - 状态恢复为 `pending`。 `running` 禁止重置和删除。失败任务允许删除后重新创建。 `reset` 请求体和失败任务 `DELETE` 请求体均为 `{"requestId":"uuid"}`。只允许删除 `failed`；重置允许 `completed`、`completed_partial`、`failed`。二者均按 `requestId` 幂等。 ## Android：注册与心跳 ```http POST /api/agent/v1/register POST /api/agent/v1/heartbeat ``` 客户端首次启动生成并持久化 `installId`，直接提交设备信息；服务端收到合法请求即创建或更新设备，不要求注册码、后台审核或人工确认。`installId` 在服务端唯一，硬件标识不能作为替代唯一键。响应返回 `deviceId`、Device Token 和心跳间隔，客户端安全保存 Token，服务端只保存其不可逆摘要。后续用 `installId` 保持同一安装实例的设备身份；心跳上报设备状态和 `currentTaskId`，服务端据此判断在线/空闲，但任务领取仍以数据库原子约束为准。 注册请求： ```json { "requestId": "uuid", "installId": "uuid", "name": "OPPO-PKG110", "manufacturer": "OPPO", "model": "PKG110", "androidVersion": "16", "agentVersion": "0.1.0", "pddVersion": "7.72.0", "capabilities": ["rule.schema.v2", "action.swipe.v1", "collector.pdd.product-detail.v1"] } ``` - 新 `installId` 立即创建设备并返回一次 `deviceToken`；响应带 `Cache-Control: no-store`。 - 相同 `requestId` 重放只幂等返回原 `deviceId`，不再次返回 Token，也不覆盖设备信息。 - 已存在 `installId` 的新请求必须携带该设备的 Bearer Token，认证成功后幂等更新设备信息，不轮换 Token。 - 缺少或使用错误/已吊销 Token 返回 HTTP 409 和 `DEVICE_INSTALL_ID_CONFLICT`。 - 生产模式默认只接受 TLS。只有服务部署在可信反向代理之后并显式设置 `GOAUTO_TRUST_FORWARDED_PROTO=true` 时，服务端才接受代理的 `X-Forwarded-Proto: https`；不得在服务直接暴露公网时开启。管理员显式设置 `GOAUTO_ALLOW_INSECURE_AGENT_HTTP=true` 后，注册、心跳、采集、采购、Agent 版本检查与下载等全部 `/api/agent/v1/**` 可直接使用 HTTP；Device Token、任务内容、设备状态和执行结果会以明文经过链路。注册接口仍有单实例、按直连来源 IP 的基础限流，网关仍须设置共享限流。该开关不影响管理端和第三方服务的 HTTPS 约束。 - `capabilities` 最多 32 项，使用小写的版本化能力名。旧 Agent 可以不提交该字段并继续执行 v1；v2 任务只能由包含规则所需全部能力的设备领取。 管理员设备动作： ```http POST /api/admin/v1/devices/{deviceId}/disable POST /api/admin/v1/devices/{deviceId}/token/revoke ``` 两者都要求 go-admin 管理端认证与角色授权。吊销同时停用设备；重新启用和重新签发 Token 不在本工单范围。 心跳请求使用设备 Bearer Token： ```json { "requestId": "uuid", "currentTaskId": "task-id-or-null", "capabilities": ["rule.schema.v2", "action.swipe.v1"] } ``` 服务端校验 `currentTaskId` 必须与该设备唯一的执行中任务一致；执行中任务统一覆盖采集任务的 `running`，以及采购任务的 `running` / `order_submit_started`。不一致返回 HTTP 409 和 `DEVICE_TASK_MISMATCH`，不更新心跳。响应返回服务端确认的 `currentTaskId`、`online`、由两类任务统一派生的 `busy`、服务端时间和下一次心跳间隔。相同 `requestId` 重放不推进心跳时间；若数据库异常存在跨任务域同时运行，服务端返回内部一致性错误，不静默选择其中一条。 默认心跳间隔 15 秒、离线阈值 45 秒、扫描间隔 15 秒。超过阈值后设备标为 `offline`：运行中的采集任务和未进入订单提交边界的采购任务清除租约与运行 guard，转为 `failed`，对应采购 attempt 同步失败并结束，错误码为 `DEVICE_OFFLINE`，且不自动重试或换机。采购任务已处于 `order_submit_started` 时必须转为 `order_result_unknown`，释放设备/账号运行槽并等待人工核对，禁止自动重派或再次点击创建订单。设备重新发送合法心跳后可以恢复 `online`，但失败或结果未知的任务不会自动恢复。 ## Android：获取、领取和开始任务 ```http GET /api/agent/v1/tasks/next POST /api/agent/v1/tasks/{taskId}/claim POST /api/agent/v1/tasks/{taskId}/start ``` `claim` 和 `start` 请求体都为 `{"requestId":"uuid"}`。相同 `requestId` 重放返回首次成功后的当前任务载荷，不延长租约、不增加租约版本。`next` 没有可用任务时返回 HTTP 204。 领取规则： 1. 指定设备的任务只能由指定设备领取。 2. `deviceId` 为空的任务可由在线且没有活动任务的设备领取。 3. `claim` 在一个数据库事务中设置设备和租约，竞争失败返回 `TASK_ALREADY_CLAIMED`。 4. 设备已有活动任务时返回 `DEVICE_BUSY`。 5. 指定设备和领取设备必须具备规则快照要求的全部能力；不兼容时返回 `DEVICE_CAPABILITY_MISMATCH`。未指定设备任务会跳过不兼容设备。 `claim` 保持任务为 `pending`，写入设备、两分钟领取租约和递增的 `leaseVersion`；`start` 只接受当前设备持有的有效租约，将状态原子改为 `running`、记录开始时间并续租。Android 进程还必须以本地互斥锁确保同一时刻只有一个任务进入执行器。 任务载荷包含： ```json { "taskId": "task-id", "pddProductId": "product-id", "urlSnapshot": "https://mobile.yangkeduo.com/goods.html?goods_id=123", "goodsIdSnapshot": "123", "ruleId": "rule-id", "ruleSnapshot": {}, "timeoutSeconds": 120 } ``` 规则已经软删除不影响载荷和执行。 ## Android：提交结果 ```http POST /api/agent/v1/tasks/{taskId}/result ``` ```json { "requestId": "uuid", "status": "completed_partial", "product": { "pddGoodsId": "123", "title": "商品标题", "shopName": "店铺名", "salesText": "已拼5872件", "reviewCount": 64 }, "dimensions": [ {"key": "color", "name": "颜色", "values": ["黑色", "白色"]}, {"key": "size", "name": "尺码", "values": ["M", "L"]} ], "colorPrices": [ {"color": "黑色", "priceCent": 1000}, {"color": "白色", "priceCent": 1200} ], "skus": [ {"specs": {"color": "黑色", "size": "M"}, "priceCent": 1000, "available": true} ], "missing": ["白色/L"] } ``` 服务端验证任务当前设备和状态后，在一个事务中更新 `collection_task` 结果字段并重建结果子表。终态任务拒绝不同内容的再次提交；相同 `requestId` 幂等返回原响应。 规格值规范化属于服务端最终契约防线： - size 规格值只允许剥离位于文本尾部的 ¥ / ￥ 数字价格片段，括号说明、体重区间和其他规格身份文本原样保留；Android 与服务端使用相同语义。 - 服务端在结果完整性校验前执行规范化。规范化后为空、同维度重复、仍残留货币符号或无法由最小安全规则确定时，整维不接受，并原子丢弃引用该维度的 SKU；color 被拒时同时丢弃 colorPrices。 - 服务端强制将任务收敛为 completed_partial，并在 missing 增加稳定值 spec_dimension_invalid:，例如 spec_dimension_invalid:size。客户端应把它展示为对应规格维度无法安全采集，不得视为完整档案，也不得自行猜测或补齐候选。 - 被拒维度不得以污染值覆盖商品已有档案；历史任务和既有商品数据不自动清洗，须在修复后的 Agent 上重新采集。 ## Android：提交失败 ```http POST /api/agent/v1/tasks/{taskId}/fail ``` | 错误码 | 含义 | 默认重试 | |---|---|---| | `DEVICE_OFFLINE` | 执行中连接中断 | 否 | | `ACCESSIBILITY_NOT_READY` | 无障碍未绑定 | 否 | | `PDD_LOGIN_REQUIRED` | PDD 登录失效 | 否 | | `PDD_CAPTCHA_REQUIRED` | 验证码或人机验证 | 否 | | `PDD_RISK_CONTROL` | 风控页面 | 否 | | `PDD_LINK_INVALID` | 商品链接无效、商品不存在或已下架 | 否 | | `PDD_GOODS_SOLD_OUT` | 商品页一次性下拉恢复后仍显示商品已售罄，或恢复动作失败 | 否 | | `PDD_DETAIL_ENTRY_FAILED` | 一次性重开浏览器后仍未进入精确 PDD 商品详情页 | 否 | | `RULE_NOT_MATCHED` | 找不到唯一控件或页面 | 否 | | `SPEC_ENTRY_CLICK_NO_EFFECT` | 规格入口点击后页面没有变化 | 否 | | `SPEC_ENTRY_OPENED_REVIEW` | 规格入口误进入商品评价页且受控恢复失败 | 否 | | `SPEC_PANEL_EVIDENCE_NOT_MATCHED` | 页面发生变化，但规格面板强证据不足 | 否 | | `RULE_AMBIGUOUS` | 规则同时匹配多个控件 | 否 | | `TASK_ALREADY_CLAIMED` | 未指定任务已被其他设备领取 | 否 | | `DEVICE_BUSY` | 设备已有活动任务 | 否 | | `DEVICE_CAPABILITY_MISMATCH` | 设备缺少任务规则要求的版本化能力 | 否 | ## 采购任务共享契约（#33、#34、#36、#42、#44、#53、#67、#164、#166） 本节固定采购域的数据和接口边界；`purchase_task`、`purchase_task_attempt`、规则校验、服务端 HTTP 状态机、Admin 已有任务管理、SYB 创建入口、Android 演练执行及 #36 正式地址/订单动作已经落地。#36 尚未获得真机创建订单授权和验收。当前项目没有自动支付动作、入口或测试；后续支付能力必须另行建单并通过显式能力位、服务端开关、金额上限和人工授权门禁。 ### 任务与快照 - `executionMode` 只能是 `rehearsal` 或 `live`，创建后不可修改。 - 正式 `live` 任务必须引用一条 `syb_product`；无副作用的 `rehearsal` 可以不引用 SYB。 - 创建时固化 SYB、蝦皮订单号、虾皮商品、PDD 商品、目标规格、数量、价格区间、币种、URL、`goods_id`、规则和可选 PDD 账号引用。新建 SYB 任务的执行映射初始为空，首趟当次 PDD 规格探测决策成功后才固化 `mappedColor` / `mappedSize`；正式任务的 `shopeeOrderNoSnapshot` 来自创建时的 `syb_product.order_code`，之后来源商品修改不会改写任务快照。 - Android 无法可靠读取当前 PDD 账号，因此 `pddAccountId` 和 `pddAccountRefSnapshot` 均可空。已知账号时参与账号级串行，未知时不阻止任务。 - 地址后缀由任务 ID 唯一确定为 `_cg{taskId}`；#34 创建任务时必须在同一事务内回写快照。 - 一个任务最多对应一个 PDD 订单；重新采购必须新建任务，旧任务和旧订单保留。 状态集合： | 状态 | 含义 | 是否占用 SYB 活动槽 | |---|---|---| | `pending` | 待执行 | 是 | | `spec_probe_pending` | 第一趟探测结束，服务端规格匹配中；当前设备保留同任务连续流程且不得领取其他任务 | 是 | | `running` | Agent 执行中 | 是 | | `rehearsal_completed` | 演练安全结束，未改地址、未创建订单 | 否 | | `order_submit_started` | 不可逆标记已落库，只能核单，禁止再次点击 | 是 | | `order_created` | 已取得唯一 PDD 订单号和下单时间 | 是 | | `order_result_unknown` | 无法确认是否下单，必须人工处理 | 是 | | `failed` / `cancelled` | 终态 | 否 | 同一个 `sybProductId` 最多一个占用活动槽的任务；一个设备最多一个执行中的采购任务；已知的同一个 PDD 账号最多一个执行中的采购任务。终态历史不删除。 `purchase_task.task_type` 固定为 `syb_order` 或 `stock`，旧记录迁移为 `syb_order`。`stock` 的 `sybProductId`、`shopeeProductId` 及对应身份快照为空，颜色和尺码必须逐字命中当前 `active` PDD 档案中的可选值，`specSource=direct_select`；同商品的多个活动备货任务可以共存，但执行期仍受设备和可选账号互斥约束。`stock` 不进入 SYB 批量预检/批量重试、Agent 重试、商品替换、重新采购授权或 SYB 回填；失败后返回“重新创建备货采购”的可读提示。 ### 规则快照与能力 采购规则是 JSON 对象。#53 在既有 schema v1 中增加受限参数，不引入任意脚本： ```json { "schemaVersion": 1, "ruleType": "pddPurchase", "requiredCapabilities": ["purchase.rehearsal.v1"], "actions": [ { "type": "openProduct", "textAliases": ["打开拼多多APP", "打开"], "waitAfterMs": 1000 }, { "type": "openSpecPanel", "textAliases": ["选择规格"], "swipeAfter": { "direction": "up", "count": 2, "durationMs": 500, "intervalMs": 1000 } }, { "type": "probeSpecs", "dimensionAliases": { "color": ["颜色分类", "颜色", "款式", "颜色款式", "花色", "组合"], "size": ["尺码", "尺寸", "套餐", "参考分类"] } }, {"type": "selectSpec"}, {"type": "setQuantity"}, {"type": "verifyUnitPrice"}, {"type": "verifyOrderSummary"} ] } ``` 安全动作参数矩阵： | action | `textAliases` | `waitAfterMs` | `swipeAfter` | `dimensionAliases` | |---|---:|---:|---:|---:| | `openProduct` | 是 | 是 | 是 | 否 | | `verifyProduct` | 是 | 是 | 否 | 否 | | `openSpecPanel` | 是 | 是 | 兼容读取、不执行（0.9.60+，见 #238） | 否 | | `selectSpec` | 是 | 是 | 是 | 否 | | `setQuantity` | 是 | 是 | 否 | 否 | | `verifyUnitPrice` | 是 | 是 | 否 | 否 | | `verifyOrderSummary` | 是 | 是 | 否 | 否 | | `probeSpecs` | 是 | 是 | 是 | 是 | 参数规则： - `dimensionAliases` 仅允许配置在 `probeSpecs`，并同时提供 `color` 与 `size`；每组包含 1～20 个互不重复、无首尾空白的非空文字，每项最多 30 个 Unicode 码点。它只用于只读规格维度探测，不参与 `selectSpec` 点击；旧规则快照缺省时使用 Agent 内置兼容别名。 - `textAliases` 省略时使用 Agent 对该类型化动作的内置语义目标；显式提供时必须包含 1～16 个互不重复、无首尾空白的非空文字，每项最多 64 个字符。 - 文字候选按控件文字或内容描述**精确匹配**；候选合并后必须唯一命中。点击动作只允许点击唯一文字节点或其最近的可点击父容器，不允许模糊匹配、猜测相近候选、改点兄弟节点。 - 动作 `textAliases` 不能包含地址修改、创建/提交订单、订单号或支付相关文字，防止用安全 action 绕过危险动作类型和能力门禁。只读识别字段使用独立校验：允许订单和支付证据，仍拒绝修改地址、收货地址，并沿用各字段声明的数量、长度、去重和空白限制。 - `waitAfterMs` 表示动作成功后的等待时间，范围为 0～30000 毫秒；省略时为 0。 - `swipeAfter` 通常表示动作成功后执行一个有限滑动计划；Android 0.9.60+ 的 `openSpecPanel` 例外，只兼容读取而不执行预滑动（见 #238）。`direction` 只能为 `up` / `down` / `left` / `right`，`count` 为 1～10，`durationMs` 为 100～2000，`intervalMs` 为 0～5000 且省略时为 0。 - 未在矩阵中授权的 action/参数组合、未知字段、空候选和越界值一律拒绝。`updateShippingAddress`、`createOrder`、`readOrderResult` 等正式动作在其独立高风险契约完成前不接受上述参数。 - 旧的仅含 `actions[].type` 的规则继续有效：候选使用 Agent 内置语义，等待为 0，不执行动作后滑动。 - 服务端保存创建任务时收到的完整原始规则快照；规则后来更新为规则 B，不会改变已有任务中的规则 A 快照。 演练规则必须包含 `purchase.rehearsal.v1`，并且不能包含 `updateShippingAddress`、`createOrder`、`readOrderResult`。正式规则必须包含 `purchase.live.v1`；改地址和创建订单还分别要求 `purchase.address-update.v1`、`purchase.order-create.v1`。`probeSpecs` 要求 `purchase.spec-probe.v1`。任意模式下，尚未实现的 `pay`、名称包含 `payment` 的动作以及未知动作一律拒绝；服务端不下发任意脚本。 ### Android 规格动作执行边界（#214） 本工单不改变采购规则 schema、Agent HTTP 字段或能力标识，只收紧 Android 对 `openSpecPanel` 与 `selectSpec` 的执行语义： - 每次操作从最新 `rootInActiveWindow` 重新定位；规格入口必须是解析器已接受的唯一安全候选，规格值必须逐字等于任务固化的服务端映射值且在当前维度唯一、可用。 - 动作前先检查后置条件；规格已精确选中时直接成功，不重复点击。否则最多分发一次 `ACTION_CLICK`，再从新快照验证规格面板强证据或精确选中证据。 - `ACTION_CLICK` 后页面结构完全无变化时，Android 可以重新定位同一唯一目标，并在目标可见、启用、中心点位于屏幕内且边界有效时执行一次中心手势。手势后仍未取得后置证据时明确失败，不继续点击。 - 点击后页面已变化但面板分类仍为未知时返回 `PURCHASE_SPEC_PANEL_EVIDENCE_NOT_MATCHED`；两种点击后页面均无变化时返回 `PURCHASE_SPEC_ENTRY_CLICK_NO_EFFECT`。诊断只携带面板类型、滚动容器数、标题数、选项数及证据布尔值，不携带节点文字或完整控件树。 - 有界查找规格时只使用当前解析结果中的唯一 `specPanelContainer`；每次滚动前重新定位该容器，优先使用节点滚动动作，失败后才在容器边界内使用手势。缺少唯一容器时停止，不回退到全页面最大滚动区域。 - 受控中心手势接口固定拒绝地址、保存地址、创建/提交/确认订单、确认购买和支付/付款语义；`updateShippingAddress`、`createOrder`、`readOrderResult` 不使用该兜底。创建订单的一次性不可逆状态机与禁止支付契约不变。 ### 管理端接口 | 方法 | 路径 | 幂等键 / 说明 | |---|---|---| | `GET` | `/api/admin/v1/purchase-tasks` | 分页列表；可按任务 ID、蝦皮订单号 `shopeeOrderNo`、状态、模式、SYB 商品 ID 和 PDD 订单号筛选 | | `GET` | `/api/admin/v1/purchase-tasks/{taskId}` | 只读任务详情与 attempt 历史；不返回规则原文、Token、凭据、完整地址、控件树或截图 | | `POST` | `/api/admin/v1/purchase-tasks` | `requestId`；单条创建 | | `POST` | `/api/admin/v1/purchase-tasks/stock` | 创建备货采购；`requestId`、`executionMode`、`pddProductId`、可选 `deviceId` / `pddAccountId`、`color`、可选 `size`、`quantity`、`minUnitPriceCent`、`maxUnitPriceCent`。服务端使用内置规则并从所选颜色归档派生参考价；相同 `requestId` 幂等返回原任务 | | `POST` | `/api/admin/v1/purchase-tasks/batch-preview` | `sybProductIds`（1～100）和可选 `deviceId`；逐条返回采购是否可创建、价格区间、原因和下一步，并独立返回 PDD 采集资格 `collectionEligible` / `collectionDisabledReason` 与长期规格匹配资格 `aiMatchEligible` / `aiMatchDisabledReason`，不创建任务且不调用 AI Provider。自 #215 起，长期映射缺失或失效不再单独使 `eligible=false`；新任务会在首趟当次 PDD 页面探测中决定执行规格 | | `POST` | `/api/admin/v1/purchase-tasks/batch-spec-match` | `sybProductIds`（1～100）；仅处理服务端预检 `aiMatchEligible=true` 的明细，其他明细按具体禁用原因返回 `skipped`，并逐条返回 `auto_confirmed` / `pending` / `failed` / `skipped`。资格要求 SYB 采购规格解析成功、蝦皮与 PDD 关联完整、PDD 当前规格可用，且最近一次成功或部分成功采集存在完整可售 SKU 组合证据；未人工确认的 `parse_status=uncertain` 不进入自动确认，`manuallyConfirmed=true` 与 `parse_status=success` 同等视为可信规格。唯一确定性 `exact_match` 不调用 Provider，直接通过独立路径保存为 `confirmed`；其余结果只有 `ai_match` 置信度达到 `autoConfirmMinConfidence`、理由非空、返回值属于当前候选且颜色+尺码命中同一个可售 SKU 组合时才保存为 `confirmed`。低置信度、无效组合和 Provider 异常不改写现有映射 | | `POST` | `/api/admin/v1/purchase-tasks/batch` | 批次 `requestId`、`sybProductIds`（1～100）和可选 `deviceId`；每条派生稳定幂等键并独立创建，部分失败不回滚成功项 | | `POST` | `/api/admin/v1/purchase-tasks/{taskId}/authorize-repurchase` | 一次性授权；创建新任务后自动消耗 | | `POST` | `/api/admin/v1/purchase-tasks/{taskId}/payment-review` | `paid` 或 `unpaid`，管理员和采购员可操作 | | `POST` | `/api/admin/v1/purchase-tasks/{taskId}/writeback-candidate` | 人工选择回填候选；后选的已支付订单覆盖同一 SYB 明细的旧选择 | | `POST` | `/api/admin/v1/purchase-tasks/{taskId}/cancel` | 人工取消；执行中和已开始提交订单时禁止直接取消 | | `POST` | `/api/admin/v1/purchase-tasks/{taskId}/resolve-unknown` | 人工把结果未知解除为已创建订单或已取消 | | `POST` | `/api/admin/v1/purchase-tasks/{taskId}/spec-decision` | 固化第一趟规格探测决策；同一 attempt 不可改写 | Admin 列表与详情由 #35 实现；#67 增加 `shopeeOrderNoSnapshot` 的列表/详情返回和 `shopeeOrderNo` 筛选，空快照返回空字符串并由页面显示“—”，不与 `pddOrderNo` 混用；#44 在 SYB 商品列表提供单条/当前页批量创建入口。页面预检只负责提前解释，`batch` 提交时仍逐条执行现有单任务事务和活动任务、订单、支付、设备能力门禁；返回项包含任务号，或失败原因与下一步建议。只有管理员和采购员可以调用。 创建请求的价格保护使用整数分：`referenceUnitPriceCent`、`minUnitPriceCent`、`maxUnitPriceCent` 和 `currency`。执行时以 PDD App 实际单价校验；低于最小值或高于最大值均返回普通人可理解的价格越界错误，不考虑优惠券，不以订单总价替代单价判断。批量创建不接受浏览器提交价格：服务端读取当前采购规则的可选 `priceGuard`，`minRatio` 允许 0.1～1.0，`maxRatio` 允许 1.0～3.0 且前者不得大于后者；字段缺省时使用 0.2 / 1.5。最低边界按“最低颜色价 × minRatio”向下取整，最高边界按“最高颜色价 × maxRatio”向上取整，均使用定点整数计算以保持旧默认逐分一致；没有可用颜色价格时逐条拒绝。SYB/Shopee 的 TWD 售价不参与 PDD 采购价格保护。 ### Android 接口（由 #34 实现） | 方法 | 路径 | 说明 | |---|---|---| | `GET` | `/api/agent/v1/purchase-tasks/next` | 优先返回当前设备的运行任务；存在 `spec_probe_pending` 时返回同一等待任务以阻止其他任务插队，否则返回能力兼容的指定任务或空闲任务 | | `POST` | `/api/agent/v1/purchase-tasks/{taskId}/claim` | `requestId` 原子领取，并建立设备/可选账号租约 | | `POST` | `/api/agent/v1/purchase-tasks/{taskId}/start` | 创建不可变 `taskAttemptId` | | `POST` | `/api/agent/v1/purchase-tasks/{taskId}/order-submit-started` | 创建订单前先落不可逆标记；演练任务和 `spec_probe` attempt 永远拒绝 | | `POST` | `/api/agent/v1/purchase-tasks/{taskId}/result` | 请求体携带 `taskAttemptId` 和 `requestId`；幂等提交演练、规格探测、订单或失败结果 | 自 #215 起，新建 SYB 采购任务不再从 PDD 档案创建持久匹配工作项，也不在首次派发前调用外部 AI；部署前已存在的 `purchase_spec_match_work_item` 继续按原状态兼容处理。新任务首次 `start` 固定得到 `phase=spec_probe`，Android 通过浏览器打开任务链接一次并经既有结果字段回传当次候选；匹配成功后的第二次 `start` 才得到 `phase=purchase` 和服务端固化的精确 PDD 原始标签。连续第二阶段仅在当前 PDD 页面仍有商品页或规格面板强证据时复用首趟页面、不再次打开浏览器链接；手动同任务重试，或当前为 Agent、其他应用及缺少上述强证据时，Android 重新打开任务 `urlSnapshot`。两种路径都不以标题、goodsId 或页面指纹做严格同页校验，仍必须通过 PDD 包名和商品/规格/订单页面结构安全证据。Android 不接收 AI 配置或自由决策权限。 结果提交至少关联 `taskId`、`taskAttemptId`、`deviceId`、规则快照哈希和结构化结果。相同 attempt 的相同结果重复提交返回同一事实；不同内容拒绝覆盖。每个新 SYB 采购任务的第一趟只读遍历当次 PDD 规格面板并提交颜色、尺码原始候选，随后释放数据库租约和已知账号运行守卫并进入 `spec_probe_pending`，但服务端调度与 Agent 必须把当前设备保留给同一采购流程：`next` 返回该等待任务，Agent 只轮询等待，不领取其他采购或采集任务。服务端只以任务冻结的 SYB 目标和当次候选先做繁简、空白/全半角/大小写及公斤/斤的唯一确定性匹配，仍无唯一结果才调用 AI。AI 的颜色和尺码必须逐字属于当次对应候选，否则按无匹配失败。第二趟只会收到服务端固化的精确 PDD 原始标签；Agent 复用首趟仍打开的页面，只在已打开的规格面板内做有限纵向滑动，每次重新读取节点并按完整规范化文字精确点击，连续没有新证据或达到上限即停止。尺码的任务目标与页面值在选择边界使用同一安全尾价规范化；不改写任务快照，规范化为空、仍含货币符号或多个原始候选折叠为同一值时安全失败。 任务 payload 的必传布尔字段 `specResolutionAllowed` 是 Android 是否可以提交规格探测的唯一资格事实。新建 `taskType=syb_order` 任务必须由声明 `purchase.spec-probe.v1` 的规则创建，初始 `SpecDecisionRequestID` 为空且 `specSource=unresolved`，首趟返回 `true`；当次决策固化后返回 `false`。`stock`、`direct_select`、已固化规格决策、能力缺失及其他组合均返回 `false`。普通 Agent 重试使用就地 `/reset`，保留 `SpecDecisionRequestID`、目标规格、映射规格和规格决策快照，不能恢复探测资格；映射不完整时必须拒绝，不能进入正式采购阶段。只有替代商品“继续采购”或 Admin 批量重试创建的新任务才按 #215 重新取得一次探测资格。Android 不得根据映射是否非空、错误文字或本地判断扩大资格。 Android 规格失败使用五个稳定阶段：`PURCHASE_SPEC_TARGET_NOT_VISIBLE`、`PURCHASE_SPEC_TARGET_AMBIGUOUS`、`PURCHASE_SPEC_SAFE_TARGET_MISSING`、`PURCHASE_SPEC_CLICK_FAILED` 和 `PURCHASE_SPEC_SELECTION_UNCONFIRMED`。`PURCHASE_SPEC_CLICK_FAILED` 的 `errorMessage` 只允许稳定子原因 `root_unavailable`、`target_stale`、`no_clickable_ancestor`、`action_click_false` 或 `unknown`；其他阶段的消息不得包含规格原文、坐标、控件树或截图。只有 `PURCHASE_SPEC_TARGET_NOT_VISIBLE && specResolutionAllowed=true` 可以提交规格探测，其他四态直接提交真实失败，服务端原样保留稳定阶段/子原因。旧 Agent 在资格已用尽后再次提交 `spec_probe_completed` 时，服务端以 `PURCHASE_SPEC_REPROBE_REJECTED` fail-closed，释放租约并保留第一次规格决策，不再冒充新的选择根因或再次派发。无匹配、候选不完整、歧义或 Provider 异常同样使任务失败。`order_result_unknown` 只允许管理员或采购员人工解除，永不自动重派。 `openSpecPanel.textAliases` 是可选的候选过滤条件，不是原始页面文本选择器。省略该字段时，Agent 使用语义安全的规格入口或底部购买入口；提供时也只能与这些安全候选取交集，匹配不到即返回 `PURCHASE_SPEC_ENTRY_NOT_FOUND`。 底部购买入口同时保留语义文字锚点和已经验证的最近可点击卡片。评价文字出现在锚点、卡片、祖先或后代上下文时拒绝候选；fresh 点击必须绑定该卡片，卡片由可点击变为不可点击时按节点失效处理，不得继续向更宽父容器漂移。点击后只有识别到规格面板才算成功；若进入具有顶部评价标题及至少两项评价页信号的评价列表，Agent 最多执行一次系统返回，确认回到 PDD 商品页后以 `PURCHASE_SPEC_ENTRY_OPENED_REVIEW / returned_to_product` 失败并停止，不得自动再次点击同一入口。返回失败或无法确认分别使用稳定子原因 `back_failed` / `return_unconfirmed`。入口诊断不保存文字、坐标、控件树或截图。 Android #42/#36 使用本地 SQLite 保存恢复与重传所需的任务、attempt 和 Outbox；最终结果和 Outbox 在同一事务写入。演练执行器仍在安全点停止。Agent 0.2.0 另外声明 `purchase.live.v1`、`purchase.address-update.v1` 和 `purchase.order-create.v1`，仅在 `live` 规则同时包含受限 `updateShippingAddress`、`createOrder`、`readOrderResult` 动作时启用。 正式地址动作在已经选好规格、数量的当前规格/下单面板内执行，不额外点击进入确认页。若脱敏手机号地址入口被裁切，Agent 只在唯一、可见且占据主要屏幕宽度的纵向面板容器内执行有限向下拉动，每次重新读取页面；不得退化为选择页面最大滚动区域。地址入口通过唯一脱敏手机号文字节点确认并在每次动作前重新定位；即使文字节点不可点击，也只允许在该文字节点中心执行一次精确手势，禁止向上查找并点击可能覆盖整个下单面板的宽泛可点击祖先。近乎完全重叠无障碍重复节点合并为一个目标，多个独立目标、多个候选面板、滚动无进展或页面切换超时均以分阶段错误结束并禁止创建订单。入口出现后，Agent 精确选择唯一修改按钮和详细地址输入框；“修改”“保存”和“提交订单”等文字节点即使要沿父链执行点击，也始终保留原始文字、类名和位置作为新鲜定位锚点，可点击父节点只用于验证和最终动作，禁止用无文字父节点替换锚点。按首个 `-` 或 `_` 截断旧后缀，追加任务 `addressSuffix`，保存并回读完整新地址。地址全文只在本次执行内存中存在，不进入本地最终确认快照、日志或服务端。 地址编辑页存在多个输入框时，以“详细地址”标签为结构锚点，只接受与标签纵向相交且位于标签右侧的唯一、可见、启用、非空输入框；不能要求页面只有一个输入框，也不能按输入框顺序猜测。 创建订单前先在本地事务保存 `order_submit_started`、不可逆时间、稳定的 `orderSubmitRequestId` 和脱敏最终确认快照，再调用服务端同名接口；只有两侧标记完成并重新校验商品、规格、数量、单价、地址后缀、PDD 包/Activity 与唯一创建订单按钮后，才点击一次。重启时重放同一标记请求并只读核单；无法取得唯一未付款订单号和 PDD 下单时间时提交 `order_result_unknown`。支付文字仅用于识别未付款/离开支付页，永不点击。服务端数据库仍是最终事实来源；双方均不保存原始控件树、截图、PDD 凭据或完整收货地址。 创建订单后若出现 Android 多微信应用选择器，只读核单器必须同时确认前台包为 `android` / `com.android.intentresolver`、Activity 为白名单 `ChooserActivity` / `ResolverActivity`、页面出现已知系统选择器标题且至少一个候选以“微信”开头，才允许执行一次系统返回；不得点击任何微信候选。若前台已经是精确微信包 `com.tencent.mm`，只读核单器不得点击、输入、登录、支付或强制停止微信，只允许执行一次无参数 PDD 启动 Intent 并等待既有 PDD 任务栈回到前台；`startActivity()` 成功只表示恢复请求已发起。请求后在固定最多 15 次、每次 200ms 的宽限期内允许微信或空窗口短暂残留，不执行点击、返回、输入或滑动；观察到 PDD 后结束宽限，宽限超时、已经观察到 PDD 后再次进入微信或出现稳定未知应用时返回未知结果。随后若前台为 PDD `com.xunmeng.pinduoduo.app_pay.core.PayActivity` 或当前页面出现支付动作文字，最多再返回一次。返回后只读解析唯一订单号和下单时间；选择器或支付页重复出现、白名单不成立、恢复动作重复、无法到达订单详情、结果不唯一或超时均返回未知结果，禁止再次点击创建订单、取消订单或支付。 Agent 主动提交 `order_result_unknown` 时保持订单号和下单时间为空，但允许携带创建订单前已经严格验证的 `actualUnitPriceCent`。Agent 同时提交脱敏稳定失败阶段，服务端只接受白名单错误码，并按错误码写入固定提示作为面向人的主文案；不采信 Agent 文本作为权威描述，也不保存原始控件树或截图。阶段覆盖空窗口超时、选择器返回失败、微信恢复失败/超时、未知应用、支付页返回失败/重复、订单上下文缺失、订单号缺失/歧义、下单时间缺失/无效和待付款证据缺失。任务与 attempt 保存同一错误阶段，Admin 和 Agent 历史读取数据库最终事实；旧 Agent 未提交阶段时归一为 `PURCHASE_ORDER_RESULT_UNKNOWN`。 #271 修订：`errorMessage` 的语义由「仅固定提示」改为「**固定提示 + Agent 诊断证据**」。固定提示仍由错误码唯一决定并排在最前，Agent 提交的脱敏诊断追加在其后。 `[必须]` 追加前压平为单行：去除控制字符与零宽不换行空格、连续空白合并为一个空格；按 `error_message` 列宽 1000 截断，且**固定提示优先完整保留**，被截断的证据以 `…` 结尾。证据与固定提示相同时不重复拼接。Agent 文本为空或错误码不在白名单时行为不变，仍返回 `INVALID_REQUEST`。 改动原因：原做法丢弃了 Agent 已经算出并上报的诊断。`#210` 为 `PURCHASE_ORDER_PAYMENT_REPEATED` 计算 `paymentBackAttempts` 与 `consecutivePaymentSamplesAfterBack`，但 2026-09-07 至 09-11 线上 61 次该错误的 `error_message` 无一携带这两个值，导致「返回动作未生效」「页面渲染慢于容忍窗口」「页面已是订单页但关键词未命中」三种情形无法区分。相邻的 `failed` 结果分支本就原样保存 Agent 文本，因此本修订不引入新的信任假设。 `[必须]` `failed` 结果分支同样把错误码与消息写入 attempt，不再只写任务。此前该路径产生的 attempt 行 `error_code` 为 NULL，按 attempt 统计失败时这些记录是隐形的。 #241 追加：全局订单号唯一性校验在人工处理结果未知、取消及 lifecycle 保存路径返回 `PURCHASE_ORDER_NUMBER_ALREADY_USED`（HTTP 409、`retryable=false`），提示“订单号已属于任务 CG-任务ID”；批量回填继续使用原有 `PURCHASE_BACKFILL_ORDER_ALREADY_USED`。不可逆边界后的 `order_created` 结果回传为例外：发现该号已属于其他任务时成功受理结果，将 `order_submit_started` 降级为 `order_result_unknown`，不回滚或自动重派。冲突订单号不写入 `pdd_order_no`，而以“读到订单号 X，但该号已属于任务 CG-yy”保存到任务和 attempt 的 `error_message`，两者 `error_code` 均为 `PURCHASE_ORDER_NUMBER_ALREADY_USED`；保留下单时间、不可逆时间及实际单价。attempt 以 failed 结束并保留原始 `order_created` 结果类型、请求 ID 和摘要，重复提交按原幂等协议返回；任务释放租约和运行槽，进入既有人工处理结果未知通道，权限不变。 | 错误码 | 普通提示 | |---|---| | `PURCHASE_MODE_NOT_ALLOWED` | 当前任务模式不允许执行此操作 | | `PURCHASE_RULE_INVALID` | 采购规则不可用，请联系管理员 | | `AGENT_CAPABILITY_MISMATCH` | 当前手机版本不支持这个任务 | | `PURCHASE_SPEC_NOT_MATCHED` | 没有找到可用的商品规格 | | `PURCHASE_SPEC_TARGET_NOT_VISIBLE` | 有界搜索后没有看到完整精确规格 | | `PURCHASE_SPEC_TARGET_AMBIGUOUS` | 同一维度存在多个严格等价候选 | | `PURCHASE_SPEC_SAFE_TARGET_MISSING` | 目标可见但无法确定安全且唯一的点击目标 | | `PURCHASE_SPEC_CLICK_FAILED` | 精确目标点击失败；`errorMessage` 为稳定子原因 | | `PURCHASE_SPEC_SELECTION_UNCONFIRMED` | 点击成功但无法确认精确选中状态 | | `PURCHASE_SPEC_REPROBE_REJECTED` | 规格探测资格已使用，重复探测被拒绝 | | `PURCHASE_SPEC_ENTRY_NOT_FOUND` | 没有找到安全且唯一的商品规格入口 | | `PURCHASE_SPEC_ENTRY_TARGET_AMBIGUOUS` | 规格入口候选不唯一 | | `PURCHASE_SPEC_ENTRY_CLICK_FAILED` | 规格入口 fresh 点击失败；`errorMessage` 为稳定子原因 | | `PURCHASE_SPEC_ENTRY_OPENED_REVIEW` | 规格入口误入评价页；`errorMessage` 记录一次安全返回结果 | | `PURCHASE_SPEC_PANEL_NOT_OPENED` | 点击后未识别到商品规格面板 | | `PURCHASE_PRICE_OUT_OF_RANGE` | 当前商品单价超出允许范围 | | `PURCHASE_ADDRESS_UPDATE_FAILED` | 收货地址修改失败，未创建订单 | | `PURCHASE_ORDER_RESULT_UNKNOWN` | 无法确认订单是否创建，请人工检查 | | `PURCHASE_PAYMENT_FORBIDDEN` | 系统禁止自动付款 | ## Agent 当前设备任务历史（#90） 四个只读接口统一使用设备注册所得的 Device Token，只返回该 Token 对应设备最近 30 天内的任务；设备 A 查询设备 B 的任务时按不存在处理，不泄露任务是否存在。 ```http GET /api/agent/v1/collection-tasks?page=1&pageSize=20&status=failed&taskNo=%2335 GET /api/agent/v1/collection-tasks/{taskId} GET /api/agent/v1/purchase-tasks?page=1&pageSize=20&status=failed&taskNo=CG-12 GET /api/agent/v1/purchase-tasks/{taskId} ``` - `pageSize` 最大为 50；`status` 与 `taskNo` 可以组合过滤。 - 采集任务编号允许 `35` 或 `#35`，采购任务编号允许 `12` 或不区分大小写的 `CG-12`；服务端按精确编号匹配。 - 列表和详情不返回 Device Token、URL、收货地址、规则快照或原始控件树。采购项额外返回服务端计算的 `retryable` 和可选 `retryDisabledReason`；除受控失败重试外，不提供取消、修改既有订单或支付入口。 - 采集摘要返回当前 `attemptNumber`；采集详情返回标题、店铺、销量、评价数、规格维度、颜色价格、SKU、缺失项、结构化错误，以及不含规则快照的历史 attempt 序号、状态、规则 ID、错误和时间摘要。详情另返回 `colorImages` 数组，元素为 `{color,imagePath,width,height}`，只包含 `source_task_id` 等于当前任务的颜色图片并按颜色排序；无图时必须为 `[]`。`imagePath` 是既有 `/static/uploadfile/goauto-color/` 相对路径，Agent 使用已配置服务端 Origin 加载，加载失败不得影响其他详情字段。 - 采购列表和详情分别返回任务目标规格 `targetColor` / `targetSize` 与最终执行规格 `mappedColor` / `mappedSize`。Agent 界面必须分开展示；自动化只执行服务端下发的 `mapped*` 精确规格，映射为空时仍可查看原始目标，不得以目标值替代执行值。详情另返回蝦皮订单号、PDD 商品、数量、实际单价、PDD 订单号、下单时间和结构化错误。 - Agent 提交采购结果时可携带 `actualUnitPriceCent`（人民币分，非负）。服务端只保存 Agent 实际观察到的值；历史任务或未观察到价格的结果保持 `null`，客户端显示“未记录”。 ## Agent 受控重新采集（#91） ```http POST /api/agent/v1/collection-tasks/{taskId}/reset Authorization: Bearer Content-Type: application/json {"requestId":""} ``` - 只允许任务原关联设备使用自身 Device Token 重采：所有来源的 `failed` 任务均可重采；Admin 来源继续允许 `completed`、`completed_partial` 重置，Agent 当前页来源只允许失败后重采。跨设备统一返回 `TASK_NOT_FOUND`。 - `requestId` 必须为 UUID。同一请求重复提交不会重复归档、递增 attempt 或清空结果，响应中的 `replayed` 为 `true`。 - 服务端在事务内锁定设备和任务，重新校验设备在线、同商品无其他 `pending/running` 采集任务，并确认该设备没有正在执行或持有有效租约的其他采集/采购任务。 - 成功时复用原 `collection_task.id`，把旧终态执行归档到 `collection_task_attempt`，将 `attemptNumber` 加一，再清理主表当前结果/错误/租约并恢复为 `pending`；不会新建采集任务。 - 新 attempt 使用最新有效规则：Admin 来源读取原 `ruleId` 的当前存活内容，Agent 当前页来源读取当前手动采集默认规则。规则不存在、不可用或与设备能力不兼容时拒绝且不修改任务。 - 当前页任务尚未识别商品时允许下一 attempt 首次绑定；已有商品身份时重新识别必须逐字命中原 goods_id，不同商品返回身份冲突。 - 响应返回 `taskId`、`attemptNumber`、`status` 和可选的 `replayed`，不返回规则快照、URL、Token、控件树或截图。 - 设备离线、任务非终态、设备忙、规则不可用或同商品存在活动任务时返回明确冲突，不支持离线排队。 ## Agent 受控采购重试（#95、#157、#217、#225） 替代商品匹配完成后的“继续采购”调用新任务接口；普通失败任务的“重试采购”使用下方同任务重置接口： ```http POST /api/agent/v1/purchase-tasks/{taskId}/retry Authorization: Bearer Content-Type: application/json {"requestId":""} ``` 成功响应： ```json { "data": { "sourceTaskId": 12, "sourceTaskNo": "CG-12", "taskId": 13, "taskNo": "CG-13", "replayed": false } } ``` - 来源任务必须属于当前 Device Token、在最近 30 天内、状态为 `failed`，且是分配给该设备的正式 SYB 采购任务；跨设备或超期按任务不存在处理。 - 来源任务不得存在 `irreversibleAt`、`orderSubmitRequestId`、PDD 订单号或下单时间。已有任何不可逆证据时返回 `PURCHASE_RETRY_UNSAFE`，提示走“授权重新采购”，不得创建新任务。 - `AgentRetry → BatchRetry → Create` 保留来源失败任务并创建不同 `purchase_task.id` 的新任务；新任务重新读取当前 SYB、虾皮/PDD 档案、当前采购规则、价格保护和设备能力，重新生成地址后缀，不继承来源任务的旧规格决策。 - 新 SYB 任务按 #215 固定从 `spec_probe` 开始。相同 `requestId` 重放返回同一新任务且 `replayed=true`；不同 requestId 再次请求受同一 SYB 商品最新任务和设备并发门禁约束。 - 本新任务接口只供替代商品“继续采购”；确认和成功反馈必须说明保留来源任务、按当前替代商品档案创建新任务、可能产生待付款订单且系统不会支付。 - 规则无效、当前档案或价格不合格、设备离线/忙、能力不匹配、任务状态变化或同一 SYB 商品已有更新任务时，服务端明确拒绝且不得部分创建。 - Admin 批量重试继续使用相同的新任务语义；替代商品“继续采购”仍在 AgentRetry 前额外验证替换分项与继续采购资格。 普通失败任务的“重试采购”调用同任务重置接口： ```http POST /api/agent/v1/purchase-tasks/{taskId}/reset Authorization: Bearer Content-Type: application/json {"requestId":""} ``` - `/reset` 只允许当前设备的安全失败任务且不得存在不可逆证据或更新任务；它复用原 `purchase_task.id`、新增 attempt、刷新当前有效规则，并保持商品、目标/执行规格、数量、价格、地址和规格决策等业务快照不变。 - 目标颜色存在但映射颜色为空，或目标尺码存在但映射尺码为空时，必须返回 `PURCHASE_SPEC_MAPPING_REQUIRED`，不得创建 `purchase` attempt 或下发正式采购 payload。相同 `requestId` 重放返回同一 task ID 和 attempt，不重复递增；Android 必须明确提示复用原任务和新的 attempt 序号。 - 两个入口都不执行支付。真机调用可能创建待付款订单，必须先取得人工授权。 ## Agent 任务记录范围与同步（#99） 采集、采购任务列表接口新增可选查询参数 `days`： ```http GET /api/agent/v1/collection-tasks?page=1&pageSize=20&days=7&status=failed&taskNo=%2335 GET /api/agent/v1/purchase-tasks?page=1&pageSize=20&days=7&status=failed&taskNo=CG-12 ``` - `days` 只允许 1–30 的正整数；省略时为 30，保持旧客户端兼容。详情接口仍限制最近 30 天。 - 记录范围、状态、任务编号和分页只作用于当前 Device Token 对应设备，不能查询其他设备。 - Agent 采集/采购 Tab 的顶部下拉只重新读取当前 Tab、当前筛选、当前编号和当前页；不领取、执行、重置或重试任务。 - 设置 Tab 可输入最近 1～30 天的任意整数，默认 7 天；空值、非整数或越界时不发起请求并提示“请输入 1～30 天”。一次同步当前设备的采集与采购列表摘要；同步为服务端到 Agent 的单向读取，允许分别成功并显示部分同步结果。 - 本地只缓存列表摘要和同步时间；详情仍按需请求。缓存不得包含 Device Token、完整规则快照、PDD URL、地址、控件树或截图。同步本身不打开 PDD、不修改地址、不创建订单、不支付。 ## Agent 当前页面临时采集（#101） ### 管理端默认规则 ```http GET /api/admin/v1/collection-rules/agent-manual-setting PUT /api/admin/v1/collection-rules/agent-manual-setting Content-Type: application/json {"requestId":"","ruleId":3} ``` - 只允许管理员读取和修改“Agent 手动采集默认规则”；PUT 的 `requestId` 必须为 UUID，重复请求幂等。 - 规则必须是仍存在的 PDD 商品详情 v2 规则。数据库迁移首次执行时，优先选择最近成功/部分成功任务使用的存活规则；没有成功历史时选择最近更新的存活 v2 规则；仍没有时保持未配置。 - 创建任务时重新验证规则与设备能力，并把完整规则快照固化到第 1 次 attempt；以后修改默认规则不影响正在执行的 attempt，但失败任务人工重采时会读取当前默认规则并固化到新的 attempt。 ### 创建并占用当前设备 ```http POST /api/agent/v1/current-page-collection-tasks Authorization: Bearer Content-Type: application/json {"requestId":""} ``` - Device Token 确定设备。服务端在事务中锁定设备，校验在线、空闲、无活动采集/采购任务、默认规则和 `collector.pdd.current-page-share.v1` 能力。 - 成功即创建来源为 `agent_current_page` 的标准采集任务，固定当前设备、状态为 `running`、建立租约并返回规则快照；不再调用普通 `next → claim → start`。 - 同一设备与 `requestId` 重放返回原任务且 `replayed=true`，不创建第二条任务、不续租。 - 身份识别前响应中的 `pddProductId` 为 `null`，`urlSnapshot` 与 `goodsIdSnapshot` 为空字符串；普通 `admin` 来源任务仍必须在创建时具备完整商品身份。 ### 识别当前商品 ```http POST /api/agent/v1/current-page-collection-tasks/{taskId}/identify Authorization: Bearer Content-Type: application/json {"requestId":"","shareUrl":"https://p.pinduoduo.com/..."} ``` - Android 只上传从本次新鲜剪贴板内容中唯一提取出的分享 URL，不上传完整分享文案。 - Agent 从剪贴板文本提取唯一白名单链接：含 goods_id 的链接直接提交；白名单内但 URL 本身无 goods_id 的链接（包括 `p.pinduoduo.com` 短链和 `mobile.yangkeduo.com/goods2.html?ps=...`）优先在手机侧用无 Cookie、无项目凭据的移动端 GET 展开，最多跟随 4 次跳转、每跳校验 HTTPS/主机/端口/userinfo，连接与读取各超时 5 秒，正文最多读取 64KB。URL 或正文只接受边界明确的 `goods_id`，不得把 `refer_goods_id` 等相近字段当作商品身份。展开失败可提交原链接，由服务端以相同白名单、最多 4 次重定向和 10 秒总超时兜底；请求字段仍只传 `shareUrl`。 - 服务端提取 5～32 位纯数字 `goods_id`，形成标准 URL，并在事务中创建或复用唯一 PDD 商品；同商品已有活动采集任务或身份冲突时拒绝。 - 相同识别 `requestId` 直接返回已确认身份且不再次访问短链；任务首次确认身份后，不允许不同请求覆盖为其他商品。 - 识别后继续复用 `POST /api/agent/v1/tasks/{taskId}/result` 与 `/fail`。结果接口要求任务已绑定身份且结果 goods_id 一致；完成、部分完成和失败继续按既有状态机释放设备槽。 - Agent 历史的任务摘要返回 `source` 和当前 `attemptNumber`；详情返回不含规则快照的历史 attempt 摘要。所有 `failed` 当前页任务均可通过既有 reset 接口复用原任务重采；发起前 Android 必须确认无障碍就绪、没有本地执行中任务、最近见过 PDD 前台并通过采集冷却。 ### 失败任务采集替代商品（#130） 失败采集详情和失败采购详情增加以下服务端计算字段： ```json { "replacementEligible": true, "replacementDisabledReason": null, "replacementMappingStatus": "matching", "replacementActivationStatus": "activated", "replacementActivationErrorMessage": null } ``` - 采集来源的 `replacementEligible=true` 不再要求任务为 `failed`，也不检查错误码；当前 Device Token 对应设备、源商品存在、没有生效或待处理替换，且该商品名下不存在 `running`、`order_submit_started`、`order_result_unknown` 采购任务时即可返回。命中采购硬拦截时 `replacementDisabledReason` 明确说明正在执行或结果待核对。采购来源仍要求失败任务且错误码逐字等于 `PDD_LINK_INVALID` 或 `PDD_GOODS_SOLD_OUT`；其他设备、无源商品或进行中的替换均不得由 Android 自行放宽。 - `replacementMappingStatus` 取当前来源对应的分项状态：`matching`、`matched` 或 `manual_required`。采购来源必须限定到该任务的 `shopeeProductId`；不能以替换主表总体状态代替。 - `replacementActivationStatus` 为 `pending`、`activated` 或 `failed`；激活失败时已采集数据仍为完成态，并返回限长的 `replacementActivationErrorMessage`。 创建替代商品采集任务仍调用： ```http POST /api/agent/v1/current-page-collection-tasks Authorization: Bearer Content-Type: application/json { "requestId": "", "replacementOrigin": {"type": "collection", "taskId": 123} } ``` `replacementOrigin.type` 只能是 `collection` 或 `purchase`。服务端在创建事务内重新检查资格，并把来源、可选纠错记录和初始 `pending` 激活状态固化到任务；同一 `requestId` 重放时来源必须完全一致。资格变化返回 HTTP 409 和 `REPLACEMENT_ORIGIN_NOT_ELIGIBLE`。 识别与结果提交继续复用当前页面采集接口。结果事务提交后，服务端调用 #131 的登记/纠错并生效流程：成功返回正常完成详情；生效失败返回 HTTP 409、`REPLACEMENT_ACTIVATION_FAILED`，但采集任务、商品、规格和 SKU 已安全保存。服务启动恢复只重试 `pending` / `failed` 的激活步骤，不重新打开 PDD 或重新采集。 ### 替换匹配完成后继续采购（#132） 采购任务详情在 #130 字段之外增加： ```json { "replacementMappingStatus": "matched", "continuePurchaseEligible": true, "continuePurchaseDisabledReason": null } ``` - `continuePurchaseEligible` 是 Agent 是否显示“继续采购”的唯一资格事实；Android 不组合任务状态、替换状态或既有 `retryable` 自行推断。 - 服务端仅在该采购任务对应虾皮商品的 replacement item 为 `matched` 时计算继续资格，不读取替换主表总体状态。资格包含既有失败重试的终态、最新任务、不可逆边界、档案、持久化映射、PDD 候选、价格、设备与能力门禁。 - 详情资格检查不调用 AI，也不把重新推导出的候选当成已确认映射。资格不通过时返回普通人可理解的 `continuePurchaseDisabledReason`；`matching` / `manual_required` 继续使用对应状态文字且不显示按钮。 - 点击仍调用既有 `POST /api/agent/v1/purchase-tasks/{taskId}/retry`，请求体仍为 `{"requestId":""}`。AgentRetry 在委托 BatchRetry 前重新校验 replacement item 与继续资格，随后由 BatchRetry/Create 执行最终档案和并发校验；没有新增采购任务创建路径。 - Admin 的 BatchRetry 接口和行为不变。相同 `requestId` 重放返回同一新任务；不同 requestId 再点由最新任务门禁拒绝。 ## SYB 商品 PDD 图搜采集（#275～#280） 图搜任务**就是采集任务**：同一张 `collection_task` 表、`source = 'image_search'`、同一个 `/api/agent/v1/tasks/*` 端点。与 `agent_current_page` 的唯一区别是**谁打开那个商品页**—— 后者由采购员手动打开，图搜由 Agent 用 PDD 的拍照搜索找到并打开。打开之后的链路 （分享链接 → goods_id → 身份回填 → 采集 → 提交结果）完全复用，没有新的采集接口。 ### 管理端：批量创建 ```http POST /api/admin/v1/collection-tasks/image-search/batch Content-Type: application/json {"requestId":"","sybProductIds":[1,2,3],"ruleId":3,"deviceId":null,"overwriteLinked":false} ``` - **按 `shopee_product` 去重**：多条共用同一张参考图的 SYB 明细合并为一个任务。请求最多 100 个 `sybProductIds`。 - **批次上限作用于去重后的任务数**，不是入参明细数，上限 50（约 17～33 分钟设备占用， 按单次图搜 20～40 秒估算）。超限整批拒绝，不部分创建。该值是服务端常量，**不可由环境 变量覆盖**：确认对话框必须在提交前禁用按钮，前端持有同一个数字，可覆盖只会让两侧静默 不一致。改动时两侧必须同改。 - `deviceId` 可空，为空由具备能力的空闲设备领取。`overwriteLinked` 为 false 时已关联 PDD 的蝦皮商品返回 `IMAGE_SEARCH_ALREADY_LINKED` 并跳过。 - 响应逐条返回 `shopeeProductId` / `sybProductIds` / `taskId` 或 `code` + `message`。 ### 设备能力 图搜任务要求设备声明 `pdd.image-search.v1`。不具备该能力的设备在领取阶段跳过图搜任务， 不会失败。 ### 任务下发 `GET /api/agent/v1/tasks/next` 与 `claim` 返回的载荷结构对所有来源一致，图搜任务额外携带 `imageSearch`： ```json {"imageUrl":"https://...","mediaType":"image/jpeg","sizeBytes":81234,"sha256":"<64 位小写 hex>"} ``` - **只下发这四个字段。** 关联关系、参考价、价格倍数、去重明细等快照留在服务端的 `image_search_snapshot`，不下发给 Agent。 - 服务端不下发图片字节；Agent 自行下载 `imageUrl` 并按 `sizeBytes` 与 `sha256` 校验。 参考图上限 10MB。 - 身份回填前 `pddProductId` 为 `null`，`urlSnapshot` 与 `goodsIdSnapshot` 为空字符串， 与 `agent_current_page` 相同。 ### 身份回填 图搜复用 `POST /api/agent/v1/current-page-collection-tasks/{taskId}/identify`，该接口已同时 接受 `agent_current_page` 与 `image_search` 两种来源。 - `[已核对]` 该接口要求任务已绑定 `device_id`。批量创建允许 `deviceId` 为空，但 `Claim` 在事务中写入 `device_id = <领取设备>`，因此 Agent 调用 identify 时设备必定已绑定。 - 回填之后的结果提交、失败上报、reset 重采与 `agent_current_page` 完全一致。 **`ruleSnapshot` 结构与普通采集任务同构**，图搜不引入第二种规则形态。 ### 结果自动关联与价格兜底 任务完成后服务端尝试建立 shopee↔PDD 关联，条件全部满足才写入： - 任务 `source = 'image_search'`、状态 `completed`、已回填 `pddProductId`； - 目标蝦皮商品 `pdd_product_id IS NULL AND image_search_linked = false`（CAS 谓词：Agent 执行期间发生的人工改动胜出，不被覆盖）； - 蝦皮商品币种为 CNY。**非 CNY 一律不自动关联**，快照记 `priceGuardSkipped` 与 `CROSS_CURRENCY_TWD_PDD_CNY`，留给人工复核； - 候选价与 `syb_product.unit_price_cent` 的偏离在 `maxPriceRatio`（1～100 的整数）之内。 自动建立的关联置 `shopee_product.image_search_linked = true`，含义是**「机器找的，没人核过」**。 采购员在虾皮商品页手动关联（`LinkPDD`）时置回 false。该标记只读地出现在批量采购预览 （`BatchPreviewItem.imageSearchLinked`）与采购任务列表，**不参与任何采购门禁、资格判定或 下单条件**。 ### 调度：采集 > 图搜 图搜任务在领取队列中垫底，由 `task.Service.Next` 的 `ORDER BY` 实现： ```sql -- 共享候选池 CASE WHEN device_id IS NULL THEN 1 ELSE 0 END, CASE WHEN source = 'image_search' THEN 1 ELSE 0 END, created_at ASC, id ASC ``` - `[必须]` 该排序只能落在服务端。图搜任务是同一端点下发的普通采集任务，Agent 调用 `next` 时服务端已经选好了行，客户端无从推翻。 - `[必须]` 来源降级排在 `device_id` **之后**：指派设备是人的显式选择，必须继续优先于来源 降级，否则未指派的采集任务会抢在运营明确路由到本机的图搜任务前面。 - 采购任务不需要此处排序：它们在独立表、独立端点，Agent 已在检查采集之前处理。 ### 错误码 管理端（批量创建）： | 错误码 | 含义 | |---|---| | `IMAGE_SEARCH_BATCH_TOO_LARGE` | 去重后任务数超过单批上限 | | `IMAGE_SEARCH_ALREADY_LINKED` | 蝦皮商品已关联 PDD，逐条跳过 | | `IMAGE_SEARCH_TASK_ACTIVE` | 该蝦皮商品已有未结束的图搜任务 | | `IMAGE_SEARCH_IMAGE_INVALID` | 参考图下载失败、格式不支持或超过限制 | | `IMAGE_SEARCH_INPUT_CHANGED` | 关联、参考图、价格或币种在请求期间变化 | | `IMAGE_SEARCH_REQUEST_CONFLICT` | 同一 `requestId` 的参数已变化 | | `IMAGE_SEARCH_CONFIG_INVALID` | 价格倍数配置不是 1～100 的整数 | | `IMAGE_SEARCH_SNAPSHOT_INVALID` | 任务快照无效 | Agent 上报（`POST /api/agent/v1/tasks/{taskId}/fail`）： | 错误码 | 含义 | |---|---| | `IMAGE_SEARCH_PERMISSION_REQUIRED` | 未授予相册权限 | | `IMAGE_SEARCH_ASSET_INVALID` | 参考图下载、校验或写入相册失败 | | `IMAGE_SEARCH_ASSET_NOT_LATEST` | 相册中存在更新的图片或视频，无法确认会选中我们准备的图 | | `IMAGE_SEARCH_ENTRY_NOT_FOUND` | 找不到唯一可点的拍照搜索入口，或归位失败 | | `IMAGE_SEARCH_NO_CANDIDATES` | 结果页没有可用候选（含全部为广告） | | `IMAGE_SEARCH_AUTOMATION_UNAVAILABLE` | Agent 版本尚未接入图搜自动化 | ### Agent 执行边界 - 只使用无障碍树，**禁止 OCR / VLM**。 - 相册权限：Android 13+ `READ_MEDIA_IMAGES`，10～12 `READ_EXTERNAL_STORAGE` （`maxSdkVersion=32`）。这是本功能新增的权限，既有设备升级后需重新授权。 - 参考图写入设备相册后，Agent 先确认它是相册中**最新的一项（图片与视频一起比较）**， 再点击网格第一格；不是最新一项时以 `IMAGE_SEARCH_ASSET_NOT_LATEST` 明确失败， 不往后找、不猜测。任务结束（成功或失败）都删除本次写入的图片。 - 归位状态机可从商品详情、规格弹层、订单确认页、结果页、重试弹窗回到图搜入口，上限 50 次动作。**订单确认页只执行返回**；支付与下单文案仅作只读识别信号，任何情况下都不是 点击目标。 - 结果页默认打开第一个候选，跳过带「广告」标记的卡片。 - 「重新采集」对图搜任务的语义是**重采同一个商品**，不重新搜索；搜错了由采购员在管理端 手动改关联（该动作同时清除图搜标记）。 ### PDD 界面判据（2026-09-15 真机核对，设备 1080×2354） 常量集中在 `PinduoduoImageSearchCriteria`。以下为核对结论，PDD 版本更新后需要重新 dump： | 位置 | 判据 | 状态 | |---|---|---| | 首页入口 | `content-desc='拍照搜索'` 且 **clickable** 的唯一节点，实测 `[941,161][1080,228]` | 命中 | | 图搜页 | `我的相册` + `最近搜索` + `历史浏览` + `点击拍照` | 命中 | | 选图网格 | `最近项目` 锚点下方 4 列等宽网格，每格 267px，屏宽 1080，容差 ±24 | 命中 | | 结果页 | `搜图片同款` 且排序控件 ≥ 3（实测 综合/销量/价格/品牌） | 命中 | | 重试弹窗 | `请对准商品或码，保持手机稳定` + `取消` + `再试一次` | **未验证** | `[必须]` 入口判定必须同时要求 clickable：个人中心 tab 的**根节点**也带 `content-desc='拍照搜索'`，覆盖全屏且不可点，而 `visibleTexts()` 会把 `contentDescription` 当文本收集。只按文案匹配会把个人中心判成首页，随后几何兜底会点到该页顶部最靠右的可点 节点——实测那是「设置」按钮。 已知偏差：取景提示真机为「对准商品/条形码/二维码，自动识别」，历史常量 `即可进行自动识别` 不命中，靠 `点击拍照` 兜住。相册网格同时包含视频（实测见到带时长的 格子），这是上面「最新一项须跨图片与视频比较」的由来。 ## 采集颜色图片上传（#133） 结构化采集结果成功提交后，Agent 可为任务已采集的颜色逐张调用： ```http POST /api/agent/v1/tasks/{taskId}/color-images Authorization: Bearer Content-Type: multipart/form-data color=<任务结果中的精确颜色值> file= ``` 成功返回 HTTP 201： ```json { "data": { "color": "紫色", "imagePath": "/static/uploadfile/goauto-color/.jpg", "width": 316, "height": 316 } } ``` 契约约束： - 必须先成功调用 `POST /api/agent/v1/tasks/{taskId}/result`；任务须为当前 Device Token 所属设备的 `completed` 或 `completed_partial` 任务。 - `color` 必须逐字匹配该任务持久化的 `color` 维度值；服务端不做相近颜色推断。 - 只接受实际内容为 JPEG 的文件；单张最大 512 KiB，宽高必须为正且均不超过 1024；单任务最多 64 张。 - 同一 PDD 商品和颜色重复上传以最新图片为准。响应路径供 Admin 商品详情展示，不返回整屏截图、控件树、XML 或个人数据。 - 接口独立于结果提交。任一上传失败都不得修改任务状态、`missing`、规格、颜色价格或 SKU；Agent 不进行会拖长任务的重试。 - 典型错误：`COLOR_IMAGE_TOO_LARGE`（HTTP 413）、`COLOR_IMAGE_UNSUPPORTED`（HTTP 415）、`COLOR_IMAGE_INVALID`（HTTP 422）、任务/设备/状态冲突（HTTP 409）。 ## 采购规则管理接口 | 方法 | 路径 | 说明 | |---|---|---| | `GET` / `POST` | `/api/admin/v1/purchase-rules` | 管理员分页查看或创建严格校验的采购规则 | | `PATCH` / `DELETE` | `/api/admin/v1/purchase-rules/{ruleId}` | 管理员修改或删除非当前规则；当前规则不能删除 | | `GET` / `PUT` | `/api/admin/v1/purchase-rules/current` | 查看或按 `requestId + ruleId` 幂等切换当前规则 | 新采购任务、批量预检、批量创建、批量重试和安全的同任务重试读取当前规则；当前设置缺失、规则已删除或内容不通过正式采购契约时返回明确错误，不回退到内置常量。既有任务的 `ruleSnapshot` 不变。所有接口仅管理员可用。 `priceGuard` 支持以下两种互斥形态： ```json {"enabled":true,"minRatio":0.2,"maxRatio":1.5} ``` ```json {"enabled":false,"absoluteMaxUnitPriceCent":5000} ``` - `enabled` 缺省时视为 `true`，兼容既有倍率规则；整个 `priceGuard` 缺省时继续使用默认倍率 0.2～1.5。 - 启用时必须提供 `minRatio`（0.1～1.0）与 `maxRatio`（1.0～3.0），最多 4 位小数且最低不得大于最高；不得提供绝对上限。 - 关闭时不得提供倍率字段，必须提供整数分 `absoluteMaxUnitPriceCent`，范围 1～100000。服务端仍从精确映射颜色读取参考价用于预检和审计，但新任务固化 `minUnitPriceCent=0`、`maxUnitPriceCent=absoluteMaxUnitPriceCent`。 - Android 严格解析两种形态，但不根据规则自行重算价格范围，只执行任务下发的最小/最大单价；未知字段、混用字段、缺少绝对上限或越界值均以 `PURCHASE_RULE_INVALID` 拒绝。 - `PURCHASE_PRICE_OUT_OF_RANGE` 失败结果应携带本次观察到的 `actualUnitPriceCent`；服务端保存该值用于任务历史诊断。该字段不授权 Agent 放宽任务边界。 ## Agent 应用版本接口 | 方法 | 路径 | 认证与说明 | |---|---|---| | `GET` / `POST` | `/api/admin/v1/agent-app-releases` | 仅管理员；列表或上传不超过 200 MB 的 APK，服务端解析版本并计算 SHA-256 | | `PUT` | `/api/admin/v1/agent-app-releases/current` | 仅管理员；按 `requestId + releaseId` 幂等设置当前版本 | | `GET` | `/api/admin/v1/agent-app-releases/{releaseId}/download` | Admin JWT 鉴权下载，不提供公开静态地址 | | `GET` | `/api/agent/v1/app/latest` | Device Token；返回当前版本元数据或 `data=null` | | `GET` | `/api/agent/v1/app/releases/{releaseId}/download` | Device Token；私有 APK 下载 | Agent 只比较整数 `versionCode`。设备有活动任务时禁止检查、下载和安装；下载到应用私有缓存并校验响应大小与 SHA-256，失败立即删除。安装使用 FileProvider 和 Android 系统安装确认页；未知来源权限必须由用户在系统设置授权，不静默安装。 ## 设备身份恢复（#201） ```http POST /api/admin/v1/devices/{deviceId}/identity-reset POST /api/agent/v1/register X-GoAuto-Device-Recovery-Code: ``` 仅管理员可以对未停用的既有设备发起身份重置。服务端立即使旧 Device Token 无效，并生成 10 分钟内仅能使用一次的恢复码；恢复码只在该管理员操作的响应中返回一次，服务端仅保存不可逆摘要，管理端设备列表、日志、任务接口和 Android 本地持久化均不得保存或返回原文。管理员将恢复码经受控人工渠道输入同一安装实例的 Agent 设置页。 Agent 携带既有 Token（可已失效）及恢复码重新调用注册接口。服务端必须同时校验同一 `installId`、未停用状态、恢复码摘要、未过期和未使用；成功后使用原 `deviceId` 写入新 Token 摘要并返回一次新 Token，清除恢复码摘要和有效期。旧 Token 与恢复码都立即失效，已分配的 pending 采集或采购任务保持原 `deviceId`，不创建替代设备记录。缺少或错误恢复码仍为 `DEVICE_INSTALL_ID_CONFLICT`；过期码为 `DEVICE_RECOVERY_EXPIRED`；停用设备为 `DEVICE_DISABLED`。 自 #223 起，新建 SYB 任务在保持 `mappedColor` / `mappedSize` 为空和首趟 `spec_probe` 不变的同时，把创建时与目标规格对应的 confirmed 商品映射冻结为仅供服务端决策的指导快照。服务端收到当次候选后按角色验证该快照：只有规范化后唯一对应当次候选时才复用，并固化当次候选原文；否则该角色继续执行确定性匹配，仍未解决才把该角色及其封闭候选交给 AI。已解决角色不得重复发送给 AI，最终颜色和尺码仍须逐字属于各自当次候选。任务决策快照通过 `roleSources` 记录每个角色的 `manual_mapping` / `exact_match` / `ai_match` 来源；任务级 `specSource` 使用现有枚举汇总，不新增 Agent 决策权限。 ## 客户端 API 与管理员密钥管理（#237） 实现基线 `71f7751`；以下接口已通过隔离测试；2026-09-07 本机 MySQL 迁移及管理员通过 HTTP 读取列表、模块目录已验证，真实密钥创建/编辑/停用及业务访问仍未联调，线上尚未部署。Android 接口不变。 ### 管理接口 前缀 `/api/admin/v1/client-keys`，要求 Admin JWT 和 admin 角色，默认接受 HTTP/HTTPS，响应 `Cache-Control: no-store`。 | 方法与相对路径 | 输入 | 成功 data | |---|---|---| | GET 空路径 | page，固定每页 20 | items、total、page、pageSize | | GET /modules | 无 | 模块数组：key、title、group、writable、actions | | POST 空路径 | name（1～80 字符）、grants | key 元数据与仅本次返回的 secret | | PATCH /:keyId/grants | version、grants | 更新后的元数据 | | POST /:keyId/disable | version | 停用后的元数据 | 授权示例：`{"module":"pdd_products","write":false,"actions":[]}`；grants 为非空数组。元数据包括 id、name、prefix、enabled、version、grants、createdBy、updatedBy、createdAt、updatedAt、lastUsedAt，不返回摘要或完整密钥。管理请求只接受单个 JSON 对象、拒绝未知字段、最大 64 KiB。成功 code=200；无效输入 422、不存在 404、授权版本冲突或已停用 409。 ### 客户端访问与错误语义 - 前缀 `/api/client/v1`，只接受 `Authorization: Bearer <客户端密钥>`，不接受 Cookie 或 URL 凭据，不与 JWT、Device Token 通用。 - 根据用户 2026-09-07 的明确确认，管理与客户端接口在所有环境默认接受 HTTP/HTTPS，不设置协议开关，也不依赖 X-Forwarded-Proto 或 GOAUTO_TRUST_FORWARDED_PROTO。HTTP 明文传输密钥及业务数据，优先使用 HTTPS；不影响其他接口各自的协议要求。 - 不再因 HTTP 返回 426；401 为缺失、无效或停用密钥；403 为模块/动作未授权；400 为查询参数携带凭据；503 为认证或审计暂不可用。业务错误沿用各既有接口。 - 一般请求体最大 16 MiB；响应只支持有限 JSON（32 MiB），递归过滤凭据与原始载荷字段。不支持直接流式/二进制文件接口。响应不可序列化或超限时返回 502；业务可能已执行，必须先核对结果，不要自动重试。 - 通过密钥认证的请求由服务端生成 `X-Client-Request-Id` 关联审计；它不是业务幂等键，原业务接口要求的 requestId 等字段仍须提供。允许请求必须先落审计意图；完成状态更新失败可留下 status=0。无效密钥没有 key_id 关联审计；拒绝授权的 403 审计为尽力记录。 - GET `/ai-matching-settings` 只返回 `data.enabled`。POST `/ai-matching-settings/resolve` 接受 targetColor、targetSize、colors、sizes；每组最多 200 项，每个值最多 255 字符，总请求最大 64 KiB；确定性优先，必要时使用当前 Provider，返回 mappedColor、mappedSize、source；不保存映射、不创建任务，无法可靠匹配返回 422 安全提示。 ### 明确开放的接口清单 下表路径均相对 `/api/client/v1`；普通业务请求字段沿用本文对应 Admin 业务契约。read=选中模块，write=模块读写，其他值均需 actions 逐项授权。没有列出的 Admin 接口不能用客户端密钥调用；新增 Admin 路由不会自动开放。 | 方法 | 路径 | 模块键 | 能力 | |---|---|---|---| | POST | `/ai-matching-settings/resolve` | ai_matching | match | | GET | `/devices` | devices | read | | GET | `/pdd-products` | pdd_products | read | | GET | `/pdd-products/:productId` | pdd_products | read | | POST | `/pdd-products` | pdd_products | write | | PATCH | `/pdd-products/:productId` | pdd_products | write | | GET | `/shopee-products` | shopee_products | read | | GET | `/shopee-products/:productId` | shopee_products | read | | POST | `/shopee-products` | shopee_products | write | | PATCH | `/shopee-products/:productId` | shopee_products | write | | POST | `/shopee-products/:productId/link-pdd` | shopee_products | write | | POST | `/shopee-products/:productId/specs/values` | shopee_products | write | | PUT | `/shopee-products/:productId/specs/mapping` | shopee_products | write | | DELETE | `/shopee-products/:productId/specs/values` | shopee_products | delete | | DELETE | `/shopee-products/:productId/specs/mapping` | shopee_products | delete | | POST | `/shopee-products/batch-delete` | shopee_products | delete | | POST | `/shopee-products/:productId/specs/mapping/auto-match` | shopee_products | match | | POST | `/shopee-products/:productId/specs/mapping/confirm` | shopee_products | match | | GET | `/syb-products` | syb_products | read | | GET | `/syb-products/:productId` | syb_products | read | | PATCH | `/syb-products/:productId/correction` | syb_products | write | | POST | `/syb-products/:productId/reparse` | syb_products | reparse | | POST | `/syb-products/reparse-batch` | syb_products | reparse | | GET | `/syb-products/sync-runs` | syb_sync_runs | read | | GET | `/syb-products/sync-runs/:runId` | syb_sync_runs | read | | POST | `/syb-products/import` | syb_sync_runs | sync | | GET | `/syb-inner-codes` | syb_inner_codes | read | | GET | `/syb-inner-codes/:recordId` | syb_inner_codes | read | | GET | `/syb-inner-codes/match-jobs/:jobId` | syb_inner_codes | read | | GET | `/syb-inner-codes/apply-batches/:batchId` | syb_inner_codes | read | | POST | `/syb-inner-codes/rematch` | syb_inner_codes | match | | POST | `/syb-inner-codes/import` | syb_inner_codes | import | | POST | `/syb-inner-codes/batch-delete` | syb_inner_codes | delete | | POST | `/syb-inner-codes/apply-preview` | syb_inner_codes | writeback | | POST | `/syb-inner-codes/apply` | syb_inner_codes | writeback | | POST | `/syb-inner-codes/:recordId/recheck` | syb_inner_codes | match | | GET | `/syb-shops` | syb_shops | read | | POST | `/syb-shops` | syb_shops | write | | PATCH | `/syb-shops/:shopId/name` | syb_shops | write | | PATCH | `/syb-shops/:shopId/enabled` | syb_shops | write | | DELETE | `/syb-shops/:shopId` | syb_shops | delete | | GET | `/collection-rules` | collection_rules | read | | POST | `/collection-rules` | collection_rules | write | | PATCH | `/collection-rules/:ruleId` | collection_rules | write | | DELETE | `/collection-rules/:ruleId` | collection_rules | delete | | GET | `/purchase-rules` | purchase_rules | read | | GET | `/purchase-rules/current` | purchase_rules | read | | POST | `/purchase-rules` | purchase_rules | write | | PATCH | `/purchase-rules/:ruleId` | purchase_rules | write | | DELETE | `/purchase-rules/:ruleId` | purchase_rules | delete | | PUT | `/purchase-rules/current` | purchase_rules | activate | | GET | `/collection-tasks` | collection_tasks | read | | GET | `/collection-tasks/:taskId` | collection_tasks | read | | POST | `/collection-tasks` | collection_tasks | collect | | POST | `/collection-tasks/batch` | collection_tasks | collect | | POST | `/collection-tasks/:taskId/reset` | collection_tasks | collect | | DELETE | `/collection-tasks/:taskId` | collection_tasks | delete | | GET | `/purchase-tasks` | purchase_tasks | read | | GET | `/purchase-tasks/:taskId` | purchase_tasks | read | | POST | `/purchase-tasks/batch-preview` | purchase_tasks | purchase | | POST | `/purchase-tasks` | purchase_tasks | purchase | | POST | `/purchase-tasks/batch` | purchase_tasks | purchase | | POST | `/purchase-tasks/batch-retry` | purchase_tasks | purchase | | POST | `/purchase-tasks/stock` | purchase_tasks | purchase | | GET | `/ai-matching-settings` | ai_matching | read | ### openSpecPanel 后置滑动兼容与诊断（#238） 版本边界：Android 0.9.60 / versionCode 73，代码 `58a6c1c`。不修改 JSON schema、能力标识、任务接口或已有快照哈希。`openSpecPanel.swipeAfter` 仍按 direction/count/durationMs/intervalMs 原约束校验；解析成功后不执行该准备性滑动，`waitAfterMs` 保留。其他动作后置滑动沿用旧执行语义。旧 Server 可继续下发原快照；旧 APK 仍按原策略执行，不能将本契约描述当作旧设备已获得兼容。 规格探测与精确选择自行负责按需有界滚动，原始候选、精确点击和选中复核不变。跳过预滑动不作为规格探测成功或订单创建证据。 本地 `GoAutoPurchasePanel` 脱敏结构日志关联 task、attempt、device、rule（规则 SHA-256），不上传原始页面。新增事件：`postSwipe=skipped;action=openSpecPanel;reason=spec_panel_on_demand;panel=<枚举>`；其他必需滑动失败为 `postSwipe=failed;action=<动作枚举>;direction=<方向枚举>;swipeIndex=<本动作内第几次滑动>;reason=<固定分类>`。 固定失败分类：unknown、root_unavailable、no_scrollable、invalid_bounds、gesture_unsupported、gesture_rejected、gesture_cancelled、gesture_timeout。日志不含规格值、节点文本、坐标、地址、订单、凭据、原始树或截图；结果错误码仍为 RULE_ACTION_FAILED，现有结果提交字段不变。 ## SYB 逐页保存与部分成功（#239） 实现绑定 c6a962d；代码已实现不代表当前线上已部署。每页完整明细在外部请求结束后按页事务保存；页回滚不累计明细/新增/覆盖数，已提交页保留。日期局部读取失败继续下一日期，全局数据库/进度/会话/取消故障停止。当天漂移不在一次运行内重扫；后续运行重新扫描并幂等补齐。 同步状态增加 `partial_success`（部分成功，15 字符，复用现有 varchar(16)，无需迁移）。有错误且 created+updated>0 为部分成功；有错误无已提交明细为 failed；完整且无错误为 succeeded（包括无符合店铺的数据）。中断仍为 interrupted，不把中断追认为成功。所有终态沿用活动槽释放规则。 `orderCount` 是已验证页的原始列表读取数量；`detailCount`、`created`、`updated` 为已提交明细及其新增/覆盖数量；`daysProcessed` 是完整通过的日期数，不是已尝试日期数。失败日期/页码/阶段写入现有脱敏限长 errorMessage。部分成功不刷新店铺的完整同步统计。 Web 唯一展示位置为“采集采购 → SYB 同步记录”：列表状态、状态筛选及详情支持部分成功，详情保留已保存数量、错误原因与重新同步补齐提示。定时任务日志只表示异步任务受理，不等于最终业务同步成功。 ## Agent 采购订单批量回填（#241） 本节为 #241 服务端实现契约，2026-09-08 按用户授权直接更新本地镜像；线上 Wiki 与其他长期文档由审核阶段同步。本节不表示已经部署或完成真机验收。 `POST /api/agent/v1/purchase-tasks/order-backfill` 使用 `Authorization: Bearer `，沿用 `RequireAgentHTTPS`、`GOAUTO_ALLOW_INSECURE_AGENT_HTTP` 与既有可信转发协议策略。无需 Admin JWT、claim、start 或 attempt。设备号只从认证读取，请求不得指定 deviceId、地址全文、收件人、手机号或原始控件树；未知 JSON 字段拒绝。此接口只记录已观察到的订单事实，不执行设备动作、创建订单或付款。 请求示例（页面时间先按 Asia/Shanghai 理解，再以带时区 RFC3339/RFC3339Nano 发送）： ```json { "requestId": "5826cdda-dcd6-442e-90c3-9b75ba6fb8d8", "items": [ {"addressSuffix": "_cg7", "pddOrderNo": "EXAMPLE-ORDER-7", "orderSubmittedAt": "2026-09-08T20:30:00+08:00"}, {"addressSuffix": "_cg72", "pddOrderNo": "EXAMPLE-ORDER-72"} ] } ``` - requestId 必须为 UUID；items 为 1～50 条，保持输入顺序；请求体上限沿用 1 MiB。 - addressSuffix 只接受 `AddressSuffix(id)` 生成的完整字符串。任务号为非零 uint64，拒绝前导零、正负号、空格、尾随文本、多个后缀与溢出；`_cg7` 与 `_cg72` 分别定位任务 7 和 72。 - pddOrderNo 必填，最多 100 个 Unicode 字符，不接受首尾空白、换行或制表符，不自动裁剪后覆盖旧值。 - orderSubmittedAt 缺失或 null 时回落任务 irreversible_at；空字符串、无时区文本及非法时间是条目错误，不触发回落。存储统一 UTC。页面值与 irreversible_at 都缺失时该条失败。 有效批次返回 HTTP 200，包括全部条目失败的批次；每条独立事务，失败不撤销其他条目已提交的数据。响应包裹为 `data`，并设 `Cache-Control: no-store`： ```json { "data": { "requestId": "5826cdda-dcd6-442e-90c3-9b75ba6fb8d8", "items": [ {"index": 0, "taskId": 7, "result": "backfilled", "code": "BACKFILLED", "status": "order_created", "statusVersion": 5, "pddOrderNo": "EXAMPLE-ORDER-7", "orderSubmittedAt": "2026-09-08T12:30:00Z", "timeSource": "page", "retryable": false}, {"index": 1, "taskId": 72, "result": "backfilled", "code": "BACKFILLED", "status": "order_created", "statusVersion": 4, "pddOrderNo": "EXAMPLE-ORDER-72", "orderSubmittedAt": "2026-09-08T12:31:00Z", "timeSource": "irreversible_at", "retryable": false} ] } } ``` index 从 0 开始；后缀无法解析时不返回 taskId。result 为 `backfilled`、`already_backfilled`、`conflict` 或 `failed`。已认证设备所属任务可返回提交后的状态、版本、已保存订单号及时间；拒绝条目尽可能返回当前已提交事实。跨设备任务和不存在任务不返回这些业务字段，事务回滚后的内存值绝不作为最终事实返回。 timeSource 说明已保存时间的来源：`page` 为页面值，`irreversible_at` 为估算回落，`existing_unknown` 为原先已创建的历史订单且没有可证明的来源。没有已保存时间时省略 timeSource。客户端必须保留估算标记，不得把回落值或 unknown 宣称为页面真实时间。重复回填不会用新页面时间自动校正旧时间。 | 条目 code | result | 含义 | |---|---|---| | `BACKFILLED` | backfilled | 本条完成回填 | | `ALREADY_BACKFILLED` | already_backfilled | 正式任务已为 order_created 且订单号相同，无写入 | | `PURCHASE_BACKFILL_SUFFIX_INVALID` | failed | 非法、非规范、零、溢出或歧义后缀 | | `PURCHASE_TASK_NOT_FOUND` | failed | 任务不存在 | | `PURCHASE_BACKFILL_DEVICE_MISMATCH` | failed | 未绑定设备或不属于认证设备 | | `PURCHASE_STATE_CONFLICT` | failed | 非正式采购，或状态不允许回填 | | `PURCHASE_INVALID_REQUEST` | failed | 订单号非法 | | `PURCHASE_ORDER_TIME_INVALID` | failed | 提供的页面时间无效 | | `PURCHASE_ORDER_TIME_MISSING` | failed | 页面时间与 irreversible_at 均无有效值 | | `PURCHASE_BACKFILL_ORDER_CONFLICT` | conflict | 任务已有不同订单号 | | `PURCHASE_BACKFILL_BATCH_CONFLICT` | conflict | 同批同任务出现多个不同订单号，该任务所有条目均拒绝 | | `PURCHASE_BACKFILL_ORDER_ALREADY_USED` | conflict | 同一订单号已对应其他任务 | | `INTERNAL_ERROR` | failed | 数据库失败、死锁等，retryable=true，可安全重放 | 批级 JSON/UUID/数量错误为 HTTP 422 `PURCHASE_INVALID_REQUEST`；鉴权、停用设备和 HTTPS 限制复用既有错误（401 `DEVICE_TOKEN_INVALID`、403 `DEVICE_DISABLED`、426 `HTTPS_REQUIRED`）。批级失败使用既有 `{code,message,retryable}` 包裹，未开始条目写入。 ### 状态、幂等与并发 新服务在事务中锁定任务并检查来源状态，仅允许当前设备的 `live + order_result_unknown` 首次写入；`live + order_created` 只在订单号相同时返回已回填。其他状态（包括 running、failed、cancelled 与演练）均拒绝。复用 SetStatus 同步占用字段，同一事务递增 statusVersion、设置 statusChangedAt、清空主任务当前错误及租约；原始 attempt、规则快照、支付与物流、SYB 回写字段不变。 requestId 沿用 UUID 约定，不增加批次表或全局幂等缓存。既有 unknown_resolve_request_id 槽存储 `backfill::<由 requestId 和后缀派生的 UUID>`（最多 61 字符），用于任务级关联和保留本功能时间来源。相同任务和订单号即使更换 requestId 也无写入；同 requestId 改内容仍重新执行设备、状态和订单冲突检查，不凭 requestId 直接放行。批内不同任务提交同一订单号时，先成功提交者占用，其余条目返回订单已被使用；已存在的历史重复订单号不自动修复。 订单号尚无唯一索引，本实现不迁移数据库。共享模型保存钩子复用 `purchase_rule_setting.id=1` 行作短事务互斥锁，再以锁定读检查订单号归属，覆盖回填、原人工解除和旧结果提交路径；单例缺失时拒绝写入，数据库死锁时回滚失败事务。原 ResolveUnknown 与 Admin 鉴权代码保持不变。禁止通过跳过模型钩子的直接 SQL 写入宣称具备此保证。 新回填路径禁用包含绑定参数的 SQL 日志，不记录请求正文、订单号、地址或原始树；任务号和认证设备号沿既有任务关联不可变 ruleSnapshot。此接口未新增日志载荷或任务/attempt。 本地测试覆盖事务回滚、并发服务调用和旧写入路径，使用 SQLite；MySQL 8.4 多连接/多进程的实际行锁、生产数据和真机端到端回填尚待环境验收，不以单元测试替代。 ## 蝦皮详情匹配等待与回读（#254） 实现绑定 `9088e6b`（2026-09-10，分支 fix/254-match-loading）；已通过合成数据测试，尚未合并 main 或发布线上。 本节是 Admin 蝦皮详情接口补充，不修改 Android 请求或采购协议。 - `GET /api/admin/v1/shopee-products/:productId` 的 `data` 增加 `autoMatchTimeoutSeconds` 整数，为后端详情一键匹配整次预算 `2 × AI timeoutSeconds + 10`，配置范围3～600对应16～1210秒。它是非敏感派生预算，沿用商品详情读取权限；不是开放 AI 管理配置读取，响应不包含 Key、Provider、BaseURL 或 Model。现有客户端路由若复用本 Handler 同样仅获得这个数字。 - `POST /api/admin/v1/shopee-products/:productId/specs/mapping/auto-match` 请求字段、业务权限、版本核对与响应映射语义不变。服务端按收到请求时的 AI 配置确定整次父预算，读取配置耗时扣除；Provider 请求仍受自身超时及父 context 剩余时间中更短者约束。 - Admin 点击前先GET新详情取得预算，POST timeout=(autoMatchTimeoutSeconds+10)×1000毫秒；缺字段、非整数或超范围时明确拒绝开始匹配，不猜配置。前后端需配套升级。 - 准备后配置可能变化，浏览器仍可能先超时；不要据超时响应断言事务是否提交。POST失败/断连/超时只执行有限GET回读，不自动重发POST；失败回读显示结果未知。回读结果表示当前已保存状态，不保证这次请求已经永久不再写入，也不保证全部项目都匹配成功。 - 普通GET默认10秒；本轮未修改建议接口610秒、其他AI功能或后台批量匹配600秒预算。T=60时130/140秒、T=180时370/380秒。 ## SYB 行内一键关联最近采集（#253） 实现绑定 `b1594dc`，2026-09-10；分支 feat/253-one-click-link，包含 #254 依赖。已完成合成数据测试及构建，未合并 main、未部署，不代表当前线上已具备此能力。 本节仅补充 Admin API；Android 和客户端密钥旧请求不变。 `POST /api/admin/v1/shopee-products/{productId}/link-pdd` 新增与非零 pddProductId 互斥的可选模式： ```json {"requestId":"UUID","latestCollection":{"sybProductId":1,"deviceId":2,"specContextVersion":"详情返回的未关联版本"}} ``` - 校验当前 SYB→Shopee、未关联、规格版本和设备存在/未停用；离线可用。短事务选择最新已结束成功或部分成功的临时采集，排序 finished_at DESC、id DESC；部分成功不跳过回退旧记录。只接受 completed、存在 finishedAt/PDD、PDD active 且存在可选颜色或尺码。 - 成功返回原 `product`，及 `collectionSource: {taskId, deviceId, pddProductId, requiresSpecConfirmation}`。product.specContextVersion 是此次事务写入后的冻结版本；requiresSpecConfirmation 对应 failed 且没有人工或AI确认，完整资格仍由现有 batch-preview 派生。不得把后续其他人的商品版本当作本次自动匹配上下文。 - 409 `PDD_LINK_CONFLICT` 表示已有关联；409 `LATEST_COLLECTION_UNAVAILABLE` 表示设备/最近采集/候选不可用；409 `SPEC_CONTEXT_VERSION_STALE` 沿用现有语义。非法参数422。重复请求不会覆盖已有关联，成功响应丢失后重发也会冲突，客户端应回读而非自动重试。last_update_request_id 保留本次请求标识；不承诺额外持久化完整重放响应。 - `/api/client/v1/.../link-pdd` 带 latestCollection 时返回403 FORBIDDEN，不扩大API Key授权模块；原手动 pddProductId 模式行为不变。 - Web 先GET详情及 #254 autoMatchTimeoutSeconds，再提交关联；关联响应中的冻结版本交给现有 auto-match。其匹配仍自动保存，无额外“保存修改”写请求。普通请求/回读每次10秒，auto-match 单独使用派生前端预算2T+20秒；业务拒绝直接提示，网络/匹配失败至多一次详情回读，再刷新准备状态，禁止自动POST重试。 - Server/Web 需配套更新并包含 #254；无需迁移/Android升级。现有人工关联、匹配阈值、规格/采购资格、任务与支付边界不变。 ## Admin 一键替换最近采集候选（#258） 实现绑定 `2b01974`；仅补充 Admin，Android/API Key 不变。沿用 `POST /api/admin/v1/shopee-products/{productId}/link-pdd` 和原权限，不新增路由或迁移。 先请求只读预览（仍需 UUID requestId）： ```json {"requestId":"UUID","latestCollection":{"sybProductId":1,"deviceId":2,"specContextVersion":"当前详情版本","replacement":{"preview":true,"expectedPddProductId":3}}} ``` 响应 `product` 保持原关联，`collectionSource` 返回 taskId、deviceId、pddProductId、requiresSpecConfirmation，并增加 targetVersion、title、goodsId、previousTitle、previousGoodsId、deviceName。预览没有关联写入。 确认提交沿用同一 SYB/设备/详情版本与原商品ID，replacement 改为： ```json {"preview":false,"expectedPddProductId":3,"taskId":4,"targetPddProductId":5,"targetVersion":"预览返回值"} ``` - 提交按指定 taskId 核对临时采集来源、设备、completed/finishedAt、目标ID、可用规格及 targetVersion；不重新选择最新任务。旧关联、旧/目标规格版本变更返回现有409上下文冲突；阶段不再允许返回409 PDD_LINK_CONFLICT；来源不可用409 LATEST_COLLECTION_UNAVAILABLE；缺字段422。 - 不同商品条件更新旧关联，返回更新后的 product.specContextVersion；同商品不更新关联及 last_update_request_id，但仍返回用于后续匹配的当前版本。请求不是持久化重放协议；客户端超时只回读、不自动重发。 - 预览与提交都校验当前允许阶段；采集中拒绝。复用现有人工更换关联的映射语义，后续 auto-match 自动保存及预算沿用 #254。部分匹配/AI故障不回滚已提交关联。 - 不提供 replacement 时 #253 行为不变；`/api/client/v1` 携带 latestCollection（包括 replacement）仍403，不扩大客户端密钥授权。 ## 辅助信息缺失的采集关联（#259） 实现绑定 `e467706`，仅 Server；部署/验收见 #259。替代 #253/#258 中“部分完成一律拒绝”的限制，不改变 completed 原有路径。 - completed_partial 的 missing 必须是非空合法列表且仅包含 salesText、shopName、reviewCount，才进入辅助信息兼容检查；title、规格/价格缺失、遍历截断、SKU数量上限及未知原因仍拒绝。 - `shopeeproduct/partial_collection.go` 核对本次 task 的维度和值、可售SKU的完整标记/规格引用/非负价格、本次颜色价格，以及当前档案可选值由本次有效SKU覆盖，不能借旧档案合并残留的规格或价格通过。真实单维度允许，不虚构另一维度；本次明确报告缺少规格仍拒绝。 - 一键关联、替换预览及确认提交共用验证。失败沿用409 LATEST_COLLECTION_UNAVAILABLE及现有提示，不回退更早采集、不换手机。状态 completed_partial 和 missing 原样保留；辅助字段缺失仍可在任务详情查看。 - 无接口字段、数据库迁移、Android/Web或权限变更；普通人工关联与采购/AI资格不变。不将“允许关联”视为“已匹配或已采购”。 ## 采购规格现场一次重新匹配（#263） 2026-09-11 实现绑定 `c6ee6c0`，Server采购与Android Agent；未发布、未安装、未完成真实采购验收。 - 正式采购阶段仅在服务端下发 `specRematchAllowed=true`、Android 返回稳定的 `PURCHASE_SPEC_TARGET_NOT_VISIBLE` 且尚未进入地址/下单阶段时触发；颜色/尺码选中复核失败、售罄、点击失败、歧义、价格、地址和订单错误不触发。 - Agent 在当前PDD规格面板重新读取候选并提交同一采购任务的 `spec_rematch_completed` 结果；Server复用现有确定性优先/必要时AI匹配，结果必须属于当次候选。匹配成功后同task重新领取正式attempt，Agent沿用当前页面继续正式规格、数量、价格、地址和下单校验，不新建任务、不重新打开浏览器链接；页面证据失效时仍按原安全路径处理。 - 每个采购任务最多一次；结果attempt和服务端状态原子记录，旧决策指针清除后只允许最新attempt固化新决策。重复请求、无资格、已有不可逆证据或旧attempt覆盖均拒绝；不新增数据库列，依赖现有attempt result_type审计。 - 新共享字段 `specRematchAllowed` 和结果类型仅供现有Agent采购接口；旧Agent缺省false，旧 `spec_probe_completed` 重复探测拒绝规则不变。未改变设备租约、并发、支付禁止和任务重试语义。 ## 人工订单回填的可选实付金额（#306） 实现绑定：8c01329（2026-09-18，feat/306-order-paid-amount，待验收，尚未合并/部署/执行业务库迁移）。本节补充并覆盖 #241 中“相同订单号一律无写入”的金额相关描述；订单号、时间、设备归属和状态校验保持原契约。 POST /api/agent/v1/purchase-tasks/order-backfill 的 items 可增加 pddOrderAmountCent：可空/可省略的 int64，单位人民币分，表示订单详情明确“实付”标签的整单金额。缺失或 null 保留原值；负整数局部忽略，不影响订单号和时间回填。字符串、非整数或 int64 溢出属于 JSON 契约错误，仍按既有解码器返回批级 422；Agent 对识别异常只省略字段，不能发送异常值。 - unknown 首次回填：可同时填充空金额；不会改变支付、物流或 SYB 回写字段。 - order_created 且订单号相同：原金额为空时可补写，statusVersion 增加一次；订单号、下单时间不变。result/code 仍为 already_backfilled/ALREADY_BACKFILLED。 - 同值或本次缺失金额：幂等，不增加版本；已有不同金额：保留原金额和正确订单事实，成功结果附 warningCode=PURCHASE_BACKFILL_AMOUNT_CONFLICT、warningMessage。不触发重新采购。 - 条目响应可增加 pddOrderAmountCent（已提交数据库值）及上述 warning 字段。跨设备/不存在任务仍不返回业务字段。Android 缓存仅采纳服务端确认值，成功 warning 单独保存，不写为任务 errorCode。 - Admin 采购任务查询/详情提供同名可选字段，详情按 CNY 展示，空值显示“尚未获取”。旧 Agent 省略字段仍可使用新 Server。 Android 仅人工“回填”扫描识别单节点“实付”标签，兼容实付:,金额元,(免运费)及中英文冒号/逗号/空格，金额整数或最多两位小数，以十进制定点转换。不使用裸人民币数字、不跨节点拼金额；缺失、无效、溢出或多个不同金额时只省略金额。同一订单跨视口去重，切换订单清空。并不据此判断已付款。 追加迁移：1789800100000_purchase_order_amount.go，仅扩展 purchase_task 的可空非负 pdd_order_amount_cent；旧行 NULL，不推算单价×数量。先授权迁移并发布新 Server，再升级 Agent；旧 Server 严格拒绝未知字段，不能先装新 Agent 后向旧 Server 发送金额。本单不扩展普通采购 readOrderResult，也不增加 SYB cost 数据流。 ## SYB 采购单号回填（#305） 实现绑定 e89de1a（2026-09-18，feat/305-syb-order-writeback），已完成代码及隔离测试；未合并、未部署、未执行业务库迁移或真实 SYB 写入。 - 普通 Agent order_created 结果和人工 order-backfill 首次成功/同单号 already_backfilled 共用事务内 ensureOrderWriteback。仅 live + syb_order + 有效 PDD 单号与 SYB stock/detail 关联时建立唯一 pending 记录（#326 起不限制任务状态）；网络写入由事务外 worker 执行。不改变 Agent 请求/响应字段；金额缺失/冲突不阻止单号入队，不依赖 paymentReviewStatus。 - POST /api/admin/v1/purchase-tasks/syb-order-writeback：沿用管理员/采购员采购管理权限；body 为 {requestId: UUID, purchaseTaskIds: 正整数数组}，1～100条，不允许重复ID。单条补偿也使用本接口。 - 返回 HTTP 200、{code:200,data:{items:[{taskId,result,reason?}]}}；result 为 pending/succeeded/skipped/conflict。pending 仅表示受理，不代表远端已写入。无资格或不存在的条目独立 skipped，其他条目继续；数据库事务故障整次命令回滚。服务端校验与冲突错误沿用采购错误信封。 - requestId 持久幂等：对排序后的 ID 集合取摘要，相同 requestId/集合返回原接受结果，即使后台状态已推进；改变集合返回422。查询当前完成状态应重新GET，不能以重放响应判断最终成功。 - Admin 列表/详情 task 新增 orderWriteback={status,reason?,completedAt?,canSubmit}。无队列时符合资格显示 not_started，否则 not_applicable；队列状态 pending/running/succeeded/failed/conflict/unknown。仅未发起、failed/unknown 且任务仍有资格、租约已过期时 canSubmit=true；running/pending/succeeded/conflict 不提供重复发起。 - 回填只写 PDD 订单号；cost 固定0，created为空，绝不传 pddOrderAmountCent 或 actualUnitPriceCent。旧 writebackStatus/支付/物流字段不复用，旧物流 paid 规则不扩展到本接口。 - 批量勾选取“可采购重试 OR 可单号回填”的并集，两个按钮各自过滤子集；不得把 order_created 任务送入采购重试。冲突只查看，不提供覆盖。unknown 人工补偿仍先回读，成功仅指回读确认相同单号与 pdd 平台。 追加迁移 1789800200000_purchase_order_writeback.go 建立独立记录、命令和单例租约表。先授权迁移及权限对账后再运行新版 Server/Web；本实现基于 #306，发布时同时核验其金额列迁移依赖。历史记录不在迁移时自动入队。 ## Chrome 客户端采购订单回填（#316） `POST /api/client/v1/purchase-tasks/order-backfill` - 认证：`Authorization: Bearer <客户端密钥>`；模块 `purchase_tasks`，必须显式具有 action `writeback`。模块 read、通用 write 或 purchase action 均不隐含 writeback；不接受 Admin Cookie/JWT、Device Token、URL 凭据或客户端指定 deviceId。 - 请求和逐项响应沿用本文“Agent 采购订单批量回填”契约，`requestId` 为 UUID、每批 1～50 条。客户端先扫描并按 CG 与订单号双向聚合全部冲突，再分批提交；金额缺失省略，不能发送 0 代替。 - 客户端入口不要求任务归属某一 Android 设备，但仍复用任务状态、订单号唯一、同批冲突、金额和时间校验。Agent 入口继续要求认证设备归属，两个入口的错误回读范围不得互相扩大。 - `order_created` 且订单号相同只补空金额和空下单时间；已有金额或时间不覆盖。补入页面时间时保存 `backfill:page:` 来源标记并返回 `timeSource=page`；历史已有时间且无来源仍返回 `existing_unknown`。 - 扩展必须冻结启动时的 Origin、客户端身份和天数窗口；禁止 content script 接触密钥。网络超时或服务端逐项 `retryable=true` 时使用原稳定批次 UUID 重试，只有通过数量、索引和字段完整性校验的响应才确认批次。 ## 下单结果可选应付总额（#325） 实现分支 fix/325-order-result，2026-09-19；未部署、未真机下单验收。POST /api/agent/v1/purchase-tasks/:taskId/result 的 resultType=order_created 新增可省略/可空 int64 字段 pddOrderAmountCent，人民币分，语义为本次待付款页明确“应付”的订单总额。actualUnitPriceCent 仍为商品单价。仅在唯一订单号和下单时间完整时随成功结果发送，金额缺失/冲突/无效/溢出时 Agent 省略金额，不影响订单事实。服务端拒绝负数或其他 resultType 携带非空金额，字符串/小数/溢出按现有严格 JSON 解码失败。 服务端只为已成功确认且无订单号占用冲突的任务补写空 pdd_order_amount_cent；省略、null 或已有非空值均不清空/覆盖。字段纳入现有结果哈希，相同 requestId/attempt/载荷幂等，不同载荷拒绝。不改支付状态，不传金额到 SYB。原列已存在，无追加迁移；新 Agent 上报前须先发布此 Server，旧 Server 不接受新结果字段。 本单不修改 #306 人工订单回填、#316 Chrome 回填、Web“实付价格”显示或历史值：这些路径仍沿用原语义，不能据此宣称全局金额已统一为应付。此节仅定义新增采购结果入口。 ## Admin 订单资料补全与字段型 SYB 入队（#326） 实现提交 3a2472d，2026-09-19，feat/326-order-information；隔离测试及构建通过，未合并 main、未发布、未执行真实 SYB 写入。 复用 POST /api/admin/v1/purchase-tasks/:id/resolve-unknown 及其原有管理员/采购员权限：live 的 order_result_unknown 可人工确认订单或取消；live 的 order_created 可补全订单信息，但不能通过此接口改成 cancelled。status=order_created 时沿用 pddOrderNo、orderSubmittedAt，增加可选非负整数分 pddOrderAmountCent，复用原数据库列。订单号非空、无首尾空白/换行且不超过100字符，时间须为有效非零时间；旧客户端省略金额仍接受并保留已有值。新 Admin 补录表单要求金额，0元合法，最多两位小数，转换为整数分后提交。 已保存非空字段只补缺，不覆盖不同单号、时间或金额；订单号唯一归属仍由原模型保护。相同 requestId/已保存内容重放不重复保存，改变处理结果或已保存字段返回原采购冲突错误。前端网络失败保留输入及相同载荷的 requestId；修改载荷使用新 requestId。复用原审计字段 UnknownResolveRequestID，无新增表或持久化状态。 资料完整性由订单号、有效下单时间和非空非负订单金额推导，页面显示“信息完整”或“订单信息待补全”。order_created 仍表示已创建订单，缺金额不转 failed，不代表已付款，不重新采购。 人工确认/补录订单在同一事务中 ensureOrderWriteback；原 Agent order_created 与插件/Agent order-backfill 保持兼容。SYB 回填仅要求 live + syb_order + 非空订单号 + 有效关联 stock/detail；不检查任务状态、时间、金额、支付复核或地址后缀。列表批量读取有效关联，提交与 worker 校验相同目标范围。既有 pending/running/succeeded 不重复入队，conflict 不覆盖，unknown 保留原回读及租约规则。字段补全不恢复已失败队列，失败队列仍通过原“回填 SYB 单号”补偿操作处理。 仅回填单号，cost=0/created为空；金额、时间只存 Admin。旧物流 paid 候选流程不改，Android 与 Chrome 上传定位契约未改；今后停用插件和 Agent 回填须另行实施。本次无需数据库迁移；先发布新 Server 再发布发送金额字段的新 Web。 ## Admin 采购列表已回填单号筛选（#327） 实现368f2c2（2026-09-19），feat/327-syb-writeback-filter；测试和构建通过，未合并发布。 GET /api/admin/v1/purchase-tasks 的既有 status 参数新增查询专用值 syb_writeback_succeeded。该值按独立 purchase_order_writeback.status=succeeded 且 purchase_task_id 对应当前采购任务过滤，不查询旧物流 writeback_status，不新增或改写任务状态。原 status 合法值及其他参数行为保持不变。 匹配成功回填的历史任务，不额外要求当前采购状态为 order_created；返回的 task.status 仍为真实采购状态。无单号队列及 pending/running/failed/unknown/conflict 不命中。count及分页共用子查询过滤，可与 taskId、executionMode、taskType、sybProductId、shopeeOrderNo、pddOrderNo 组合；status为空恢复不限制状态。权限与返回信封不变，不写入数据、不触发采购或SYB请求。先发布Server再发布新增筛选值的Web，无数据库迁移或Android变更。