feat(#129): add PDD product replacement model

docs/02-architecture-and-code-map.md

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Architecture-and-Code-Map
 wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Architecture-and-Code-Map.-
-wiki_revision: f82f510e47cf3e74a3510a859ca17bddd2833362
-synchronized_at: 2026-08-28T06:51:01Z
+wiki_revision: d585a906857a46752788c9f25d3ac0361739dada
+synchronized_at: 2026-08-28T09:27:21Z
 <!-- gitea-wiki-mirror:end -->
 
 # 架构与代码地图
@@ -226,3 +226,11 @@ Android Portal/Agent
 - `server/app/goauto/sybclient/` 提供 SYB 读取与三个入库码写接口；匹配器只依赖只读接口，不能取得写能力。真实写入只由用户确认后的回写批次触发。
 - Admin API 注册在 `server/app/goauto/sybinnercode/router.go`，页面位于 `web/src/views/goauto/syb-inner-codes/`，菜单入口为“档口入库码”。
 - 服务启动时，未开始的 `queued` 记录释放回可回写，已经进入远端动作的 `applying` 记录转为 `needs_check`，不自动重放写请求。
+
+## PDD 商品替换数据模型（#129）
+
+- `server/app/goauto/models/replacement.go` 定义审计主表 `pdd_product_replacement` 与分项表 `pdd_product_replacement_item`；版本迁移为 `1787885000000_pdd_product_replacement.go`，只新增表，不修改既有表和数据。
+- 主表用 `origin_type + origin_task_id` 区分失败采集任务和失败采购任务来源，以 `target_collection_task_id` 保存替代商品采集证据，以 `created_by_device_id` 保存发起设备。当前设备模型没有操作人绑定，因此该字段只能追溯到设备，不能追溯到采购员账号。
+- 主表的可空 `active_slot` 与 `source_product_id` 组成唯一索引，使同一源商品跨 SQLite、MySQL 和 PostgreSQL 同时最多存在一条 `active` 替换记录；历史记录使用 `superseded`，不软删除、不提供删除接口。
+- 分项表按 `replacement_id + shopee_product_id` 唯一保存本次实际影响集合，并独立记录 `matching / matched / manual_required`、匹配来源、置信度和持久 worker 的尝试/错误信息。某条采购任务能否续做只能读取对应虾皮商品的分项状态，不能读取主表总体进度。
+- `server/app/goauto/replacement/` 提供内部登记、幂等冲突校验、来源/采集证据校验、目标有效性、活动记录唯一性和环检测，以及只读审计查询；管理端只读路由为 `GET /api/admin/v1/pdd-product-replacements` 与 `GET /api/admin/v1/pdd-product-replacements/{replacementId}`。Agent 没有直接写入该领域的 HTTP 权限。

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: 0798ea888bbc55fd434e9ac31c539da7a4efea5a
-synchronized_at: 2026-08-28T06:14:23Z
+wiki_revision: b31ebf8888da7c3d9b71520938b104ff9e66511f
+synchronized_at: 2026-08-28T09:27:33Z
 <!-- gitea-wiki-mirror:end -->
 
 # 业务规则与术语
@@ -298,3 +298,12 @@ synchronized_at: 2026-08-28T06:14:23Z
 - 回写前弹窗展示业务记录数、入库码总数、预计占位明细数和替换旧码数。只有 `ready` 记录可提交；所有服务实例共用数据库租约全局串行执行。
 - 每个远端写动作只发送一次，动作前重读整张货运单并校验匹配计划未漂移；每件写入后重读确认目标码唯一位于预期明细。超时、5xx、响应无法确认或服务在写入期间重启时转为 `needs_check`，禁止自动重试；“只读复核”只能读取远端状态。
 - 列表支持勾选后批量物理删除。删除必须再次确认；选中项包含 `queued`、`applying` 或 `needs_check` 时整批拒绝，不做部分删除。其余选中业务记录、逐件码、计划和终态执行证据在同一事务中物理删除；已写入 SYB 的远端值不会撤销。
+
+## PDD 失效或售罄商品替换（#129）
+
+- 商品替换是“失效的旧 PDD 商品 → 已成功采集的替代 PDD 商品”的即时生效审计事实，可由失败采集任务或失败采购任务发起；Agent 只提交明确的来源类型、任务编号和采集结果，服务端负责最终校验和登记。
+- 替换记录不删除。同一源商品同时只允许一条生效记录；替代商品必须为 `active`，不得与源商品相同，不得形成替换环，并必须由同一发起设备的一条 `completed` 或 `completed_partial` 采集任务证明。
+- 一个 PDD 商品可能被多个虾皮商品共用，因此规格匹配按受影响的每个虾皮商品分项记录。主表只表达总体进度；Agent 展示和“继续采购”资格必须读取当前任务对应虾皮商品的分项状态。
+- 选错替代商品时，连续执行 B→C 不等于撤销 A→B，因为 B 可能还关联其他虾皮商品。正确纠错语义是把原 A→B 记录置为 `superseded`，再建立 A→C，并只处理原记录分项中冻结的影响集合。
+- 创建请求按 `create_request_id` 幂等；重放时源商品、替代商品、来源类型、来源任务、采集证据和发起设备必须一致，否则返回幂等冲突，不能静默覆盖。
+- `created_by_device_id` 只代表 Agent 设备。当前系统没有设备到采购员账号的绑定，多人多机场景若需要个人责任追踪，必须另建工单实现设备绑定操作员。