feat(#130): collect replacement products from Agent

docs/03-business-rules-and-glossary.md

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Business-Rules-and-Glossary
 wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Business-Rules-and-Glossary.-
-wiki_revision: 14d111bf1043f9c31f4f54dbfbca38826e986ab9
-synchronized_at: 2026-08-28T09:50:14Z
+wiki_revision: 5f829d4d42583b0654d772043047e93a9e1deb79
+synchronized_at: 2026-08-28T10:14:45Z
 <!-- gitea-wiki-mirror:end -->
 
 # 业务规则与术语
@@ -318,3 +318,11 @@ synchronized_at: 2026-08-28T09:50:14Z
 - 用户于 2026-08-28 确认放宽 #46 的 AI 口径：`ai_match` 仅在置信度存在且不低于服务端阈值（默认 0.9）、结果严格属于当前候选、颜色/尺码角色唯一完整、原因非空且写入前输入版本未变化时自动确认。否则不得猜测或选择相近候选，转 `manual_required`。
 - 自动确认必须保存来源、实际置信度和脱敏限长原因；人工确认完成后同步对应分项及主表总体状态。worker 不得覆盖已由人工改变的映射。
 - 纠错不能简单执行 B→C；必须把原 A→B 记录置为 `superseded`，建立 A→C，并只处理原记录冻结的虾皮商品影响集合。
+
+## Agent 手动采集替代商品（#130）
+
+- 只有同一设备上的失败采集或失败采购任务，且错误码逐字等于 `PDD_LINK_INVALID` 或 `PDD_GOODS_SOLD_OUT` 时，Agent 详情才显示“采集替代商品”；Android 不自行推断资格。
+- Agent 创建当前页面采集任务时携带 `replacementOrigin.type`（`collection` / `purchase`）和来源 `taskId`。服务端再次校验设备、任务终态、错误码、源商品、既有替换与进行中的替换流程，并把来源和激活状态持久化到采集任务，保证进程重启后仍可恢复。
+- 替代商品采集结果先按普通采集事务完整保存。随后调用 #131 的原子生效流程；生效失败不得回滚或覆盖已采集商品、规格和 SKU，而是记录稳定的 `failed` 激活状态与限长错误，服务启动后可按同一幂等键仅重试生效，不重新采集。
+- 任务详情的 `replacementMappingStatus` 必须由来源任务对应的替换分项推导，不能只读取主表总体状态。状态为 `matching` 时等待自动匹配，`manual_required` 时由 Admin 人工处理，`matched` 后才进入 #132 的继续采购流程。
+- 替换采集沿用设备级单任务互斥、采集间隔、无障碍安全边界和禁止支付规则；不会增加轮询，也不会创建采购任务或订单。

docs/08-agent-api-contract.md

@@ -2,8 +2,8 @@
 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: 0bbe3f1041a0795a156dcd1205dbe85474e80f8c
-synchronized_at: 2026-08-27T10:14:59Z
+wiki_revision: 345d3b29ff7532ba4fd48d64aa3309b9d33225af
+synchronized_at: 2026-08-28T10:15:31Z
 <!-- gitea-wiki-mirror:end -->
 
 # MVP 共享 API 契约
@@ -647,3 +647,38 @@ Content-Type: application/json
 - 相同识别 `requestId` 直接返回已确认身份且不再次访问短链；任务首次确认身份后，不允许不同请求覆盖为其他商品。
 - 识别后继续复用 `POST /api/agent/v1/tasks/{taskId}/result` 与 `/fail`。结果接口要求任务已绑定身份且结果 goods_id 一致；完成、部分完成和失败继续按既有状态机释放设备槽。
 - Agent 历史的任务摘要增加 `source`；`agent_current_page` 展示为“Agent 当前页面”，不新增任务状态。该来源任务不支持重置，失败后由用户从当前商品页重新发起新任务。
+
+### 失败任务采集替代商品（#130）
+
+失败采集详情和失败采购详情增加以下服务端计算字段：
+
+```json
+{
+  "replacementEligible": true,
+  "replacementDisabledReason": null,
+  "replacementMappingStatus": "matching",
+  "replacementActivationStatus": "activated",
+  "replacementActivationErrorMessage": null
+}
+```
+
+- `replacementEligible=true` 仅适用于当前 Device Token 对应设备、任务状态为 `failed`，且错误码逐字等于 `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 <device-token>
+Content-Type: application/json
+
+{
+  "requestId": "<uuid>",
+  "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 或重新采集。