docs: SYB excluded-product marking and recompute contract (#340)

Mirrors of Wiki revisions Architecture-and-Code-Map 4bf8482e,
Business-Rules-and-Glossary c0b1a842, SYB-ERP-Interface-Contract 5979a142,
Android-Agent-API-Contract 92e9f856: filter hits are stored and marked
(first creation only), PDD isolation, 无需采购 stage position, purchaseType
list filter, recompute preview/execute with fingerprint and 409, hit vs
markedCount wording. SYB-ERP page also restores #343's unified-session
paragraph (was only in the mirror) and corrects the structure rule to #286's
single `-#` all-characters rule.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NTDbDcwbDw1TSAcE6wfh2F

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: 1e87b8832cecd454e58f0ff49dbe05bbf8d61544
-synchronized_at: 2026-09-29T03:47:39Z
+wiki_revision: 4bf8482e49509812b41ee678f40cf3c7c0cf5474
+synchronized_at: 2026-09-29T08:16:37Z
 <!-- gitea-wiki-mirror:end -->
 
 <!-- gitea-wiki-mirror:start -->
@@ -578,3 +578,12 @@ Web 唯一展示位置为“采集采购 → SYB 同步记录”：列表状态
 - 原页面默认用户浏览器本地今天范围，工具栏“匹配 N”复用现有 rematch 和任务进度；只处理本页合格项，同日提交，原回写需独立确认。
 
 实现绑定：`fix/350-inner-code-matching`，源码提交 `9c5e20e`；未合并 main、未部署，正式环境仍需发布后启用。
+
+## SYB 过滤商品标记与规则重算（#340）
+
+- 数据：`syb_product` 新增 `pdd_purchase_excluded`（索引）、`excluded_rule_id`、`excluded_rule_kind`、`excluded_rule_keyword`、`excluded_at`；新表 `syb_product_filter_recompute_log`（操作人、两方向变更数、两类跳过数、时间）。迁移 `1789801500000_syb_pdd_purchase_excluded`，只新增，存量行默认需 PDD 采购。
+- 入库：`sybimport/sync.go applyStockDetail` 命中规则不再 `continue`，把规则快照随明细交给 `apply.go ApplyDetail`；仅新建分支写标记，更新分支保留原标记。
+- 阶段与隔离：`purchase/process_stage.go` 新增 `pdd_excluded`（「无需采购」）；`purchase/return_match_block.go rejectIfPDDExcluded`（`service.create`，覆盖单条/批量）、`batch.go` 预检、`collection_eligibility.go`、`ai_match_eligibility.go`、`task/image_search.go` 统一拒绝；`returnmatch` 的参与阶段包含 `pdd_excluded`。
+- 列表：`sybimport/service.go List` 的 `purchaseType`（`pdd` 默认 / `excluded` / `all`），与 `processStage`、`createdFrom/To` 为 AND。
+- 重算：`sybproductfilter/recompute.go`——`recomputeChanges` 规划（只读所需列）；`recomputeFingerprint` 对排序后的（id、方向、规则 ID、类型、关键词）JSON 做 sha256；`writeRecomputeChanges` 逐行 `FOR UPDATE` 锁 `syb_product`，并以 `FOR SHARE` 加锁读复查 `purchase_task` / `return_match`（MySQL REPEATABLE-READ 下普通读看不到快照后的提交）。`recompute_mysql_integration_test.go` 在设置 `GOAUTO_IT_MYSQL_DSN` 时于临时库做双连接并发验证。
+- Web：`syb-products/index.vue`（采购类型筛选、阶段自动切换、规则显示、按钮计数）、`syb-product-filters/index.vue`（命中/标记口径、重算预览与执行）、`syb-sync-runs/index.vue`（「其中本次规则命中 N 条」）。

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: 32c6b496de47b54ca04e081271114c28ff439e0c
-synchronized_at: 2026-09-29T06:57:51Z
+wiki_revision: c0b1a842c79b4d1dba4c4435df106349e65e5eb1
+synchronized_at: 2026-09-29T08:16:48Z
 <!-- gitea-wiki-mirror:end -->
 
 <!-- gitea-wiki-mirror:start -->
@@ -75,6 +75,7 @@ synchronized_at: 2026-09-22T02:56:27Z
 - SYB 商品页保留“解析状态”，另按 SYB、蝦皮、PDD、采集任务和采购任务的当前事实动态派生唯一“处理阶段”；不在 `syb_product` 保存容易过期的阶段字段。
 - 对采购人员展示的阶段固定为：待人工处理、未关联 PDD、PDD 待采集、PDD 采集中、PDD 采集失败、规格待匹配、可创建采购、已创建任务、采购成功、待人工核对。
 - 主阶段优先级为：待人工核对 → 采购成功 → 已创建任务 → 待人工处理 → 未关联 PDD → PDD 待采集/采集中/采集失败 → 规格待匹配 → 可创建采购。每行只显示一个阶段和对应下一步。
+- #338/#340 后在「已创建任务」之后、「待人工处理」之前依次插入：有效退货匹配（退货待确认 / 已用退货）→ 无需采购（`pdd_purchase_excluded`）。即进行中、已成功及结果不明的采购任务仍优先显示；失败/取消的旧任务不占主阶段时，标记为无需 PDD 采购的行显示「无需采购」。
 - “待人工核对”表示订单结果不明确，必须先人工核查并禁止自动重试；“采购成功”表示已取得 PDD 订单号和下单时间，不代表已经支付。
 - 一个 PDD 订单号只能属于一个采购任务，该唯一性在采购任务保存路径上全局强制（#241）。人工处理结果未知、取消及 lifecycle 保存路径撞号时返回 `PURCHASE_ORDER_NUMBER_ALREADY_USED`，提示订单号已属于哪个任务，由采购员人工核对，不静默覆盖原值。
 - 不可逆边界之后的 `order_created` 结果回传是上述规则的例外：此时 PDD 真单已创建，发现订单号已属于其他任务时不回滚、不判失败，而是把任务降级为 `order_result_unknown`，冲突订单号以「读到订单号 X，但该号已属于任务 CG-yy」保存在任务与 attempt 的 `error_message`，`pdd_order_no` 留空以维持唯一性，保留下单时间与不可逆时间，进入既有人工处理结果未知通道。首要目标是保住「真单已存在」这一事实，不制造无记录的真实订单。
@@ -749,3 +750,13 @@ SYB 回填与资料完整性独立：正式SYB任务已有单号且仍关联有
 ### 档口入库码混选回写范围（#351）
 列表“回写 N”仅统计当前页勾选且 ready 的唯一记录，混选其他状态不阻塞合法项。打开确认弹窗时冻结本次选中数量及合格 ID；只预览、确认提交这些 ID，不随列表刷新或勾选变化扩大范围。弹窗明确显示选中/可回写/跳过数量，入库码、占位及替换旧码指标仅针对待提交记录。
 预览发现候选状态变化时剔除 blocked 项，最多再进行一次只读预览以刷新指标；无合格项、预览失败/范围不一致或再次变化时禁用确认，提示重新预览。确认提交中防重复，未知提交结果不自动重试，沿用批次查询与只读复核。服务端原 ready 状态、唯一匹配计划及执行校验不变；仅用户人工确认后才进入回写，不自动写入。
+
+## SYB 过滤商品入库与「无需采购」（#340）
+
+- 命中 SYB 过滤规则（结构 `-#` 或关键词）的订单明细不再跳过，而是入库并标记「无需 PDD 采购」，同时保存命中规则快照；店铺过滤不变。
+- 标记只在明细首次入库时确定；重复同步不改标记，规则启停或删除也不自动改变已有标记。历史被跳过的明细不自动补同步。
+- 带标记的商品**硬性隔离所有 PDD 流程**：创建采购（单条、批量）、采购预检可采购结果、创建采集资格、AI 规格匹配、图搜采集均由服务端拒绝或判为不可用，错误码 `PURCHASE_PDD_EXCLUDED`；前端隐藏只是辅助。
+- 带标记的商品可参与退货匹配：匹配后「退货待确认」，确认后「已用退货」，取消后回到「无需采购」。
+- SYB 商品页新增「采购类型」筛选：需 PDD 采购（默认、重置后同）/ 无需 PDD 采购 / 全部，与处理阶段、创建时间等筛选同时生效；选择「退货待确认」「已用退货」「无需采购」阶段时自动切到「全部」，可手动改回。无需采购行显示命中规则，可勾选但只计入「匹配退货」，不显示单条「采购」。
+- 管理员「按当前规则重算」：先预览（两个方向的变更数、因已有采购任务 / 有效退货匹配跳过的数量、最多 20 条样例）再确认执行。执行必须携带预览指纹，数据、规则或其证据变化时拒绝并提示重新预览，不静默执行另一批。执行时逐行加锁并以加锁读复查：该商品有任何采购任务或有效退货匹配则跳过；审计日志与返回数量按实际写入/跳过计。规则变更从不自动重算。
+- 统计口径：同步记录与规则列表的「命中」是本次同步命中规则的次数（含已存在明细）；「当前带此规则标记的明细 N 条」按数据库实际统计。两者不得混用。

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: da26af9e01087c4970b01783a4807c689fd79d51
-synchronized_at: 2026-09-29T03:47:57Z
+wiki_revision: 92e9f8568c9c0da1d78159391c1545f09c4cec14
+synchronized_at: 2026-09-29T08:17:45Z
 <!-- gitea-wiki-mirror:end -->
 
 <!-- gitea-wiki-mirror:start -->
@@ -87,7 +87,7 @@ PATCH /api/admin/v1/syb-products/{productId}/correction
 
 `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[]` 元素，未做任何改写）。
+列表返回结构化字段（`orderCode`、`shopeeItemId`、`productTitle`、`targetColor`、`targetSize`、`quantity`、`unitPriceCent`、`imageUrl`、`parseStatus`、`parseNote`、`manuallyConfirmed`，#340 起另有 `pddPurchaseExcluded`、`excludedRuleId`、`excludedRuleKind`、`excludedRuleKeyword`、`excludedAt`），不含原始 JSON；`purchaseType`（#340）取 `pdd`（默认）/ `excluded` / `all`，其他值 422，与 `processStage`、`createdFrom`/`createdTo` 同时生效；`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 不存在通常是操作员选错了页面）。
 
@@ -115,9 +115,11 @@ 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}
+GET    /api/admin/v1/syb-product-filters/recompute/preview
+POST   /api/admin/v1/syb-product-filters/recompute/execute
 ```
 
-同步时按 `variationSku` 决定明细是否入库。规则分两类，由 `kind` 区分：`char` 是结构判据
+同步时按 `variationSku` 判定明细是否「无需 PDD 采购」（#340 起命中者照常入库并打标记，不再跳过）。规则分两类，由 `kind` 区分：`char` 是结构判据
 （`-`、`#`），`keyword` 是关键词清单。列表支持 `kind`、`keyword` 和分页，返回 `keyword`、
 `normalizedKeyword`、`enabled`、`lastHitCount`、`lastHitAt`、`note`，`char` 另有
 `lastChangedBy`、`lastChangedAt`。
@@ -126,9 +128,20 @@ DELETE /api/admin/v1/syb-product-filters/{id}
 `FORBIDDEN`（`结构过滤不可新增` / `结构过滤不可删除`），不得只依赖前端隐藏按钮。
 `kind=char` 的 `PATCH enabled` 允许，并记录操作人与时间。
 
-`[必须]` `lastHitCount` 是每条规则各自的命中数，由同步结束时回写；未命中的规则写 0，
-从未同步过为 `null`。停用 `kind=char` 的二次确认提示条数必须取该行实时的 `lastHitCount`，
-不得写死——写死的数字在数据变化后会给出错误警告。
+`[必须]` `lastHitCount` 是每条规则各自在上次同步中的**命中次数**（新建与已存在明细都计），
+由同步结束时回写；未命中的规则写 0，从未同步过为 `null`。页面称「上次同步命中」。
+列表另返回 `markedCount`（#340）：查询时按数据库实际统计的「当前 `pdd_purchase_excluded=true`
+且 `excluded_rule_id` 为该规则」的明细数，一次分组查询得出。停用 `kind=char` 的二次确认提示
+条数必须取实时的 `markedCount`，不得写死，也不得用 `lastHitCount` 冒充已标记数量。
+
+`recompute/preview`、`recompute/execute` 仅管理员可用（其他角色 403）。预览只读，返回
+`excludedToPdd`、`pddToExcluded`、`skippedHasTask`、`skippedReturnMatch`、最多 20 条
+`samples`（`orderCode`、`shopeeItemId`、`direction`=`excluded_to_pdd`/`pdd_to_excluded`、
+`ruleKind`、`ruleKeyword`）及 `fingerprint`。执行请求体 `{"fingerprint": "..."}` 必填（空值 422）；
+服务端在事务内重新规划并比对指纹（涵盖商品、方向、规则 ID、类型、关键词），不一致返回
+`409 RECOMPUTE_PREVIEW_STALE`（「数据或规则已变化，请重新预览后再执行」）且不写入。
+执行逐行加锁复查，有采购任务或有效退货匹配的商品跳过；返回实际写入/跳过数量与 `operator`，
+并写 `syb_product_filter_recompute_log`。
 
 关键词归一化与店铺一致：去首尾空白、全角/半角统一、忽略大小写；**不做简繁转换**，SYB 数据
 为繁体。唯一性按 (`kind`, `normalizedKeyword`) 判定，重复添加返回

docs/12-syb-erp-interface.md

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: SYB-ERP-Interface-Contract
 wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/SYB-ERP-Interface-Contract.-
-wiki_revision: 03ea269058b50fea2be7842b9c284018987c82d9
-synchronized_at: 2026-09-21T08:15:30Z
+wiki_revision: 5979a14250c96c3c92348a947c2bc8d3a078c9f4
+synchronized_at: 2026-09-29T08:18:40Z
 <!-- gitea-wiki-mirror:end -->
 
 # 12 顺云宝（SYB）ERP 接口契约
@@ -496,12 +496,14 @@ POST /am/stock/detail/updateDetailCode?t=0&id={stockID}&detailId={detailID}&code
 店铺过滤只决定明细获取和入库，不能减少原始列表完整性校验范围；已保存不代表整日完整。
 
 `[必须]` **店铺准入之后再按 `variationSku` 过滤商品（#269）。** 顺序固定为：店铺准入 →
-结构过滤 → 关键词过滤 → 入库。两类规则都存在 `syb_product_filter`，由 `kind` 区分：
+结构过滤 → 关键词过滤 → 入库。两类规则都存在 `syb_product_filter`，由 `kind` 区分。
+自 #340 起命中规则的明细**同样入库**，只在 `syb_product` 上标记「无需 PDD 采购」，不再跳过（见本节末尾）：
 
-- `kind=char`：`-` 和 `#` 两条，命中任意一条即跳过（**OR，不是 AND**）。这两个字符是
-  「档口-供应商#货号」编码格式的判据。2026-09-11 核验线上 13010 行明细：含 `#` 8498 行、
-  含 `-` 6392 行、两者都含 6386 行、任一 8504 行（65%）。用 AND 只命中 6386 行，会漏掉
-  `DD#004`、`300斤牛奶絲圓領#A057` 这类只含 `#` 的 2118 行。
+- `kind=char`：当前只有一条结构规则 `-#`，`variationSku` 须**同时包含** `-` 和 `#` 才命中
+  （#286 起合并为一条、要求全部字符；代码见 `sybproductfilter.RuleSet.Match` 的 `containsAllRunes`）。
+  这是「档口-供应商#货号」编码格式的判据。`[历史]` #269 初版曾是 `-`、`#` 两条、任一命中
+  （2026-09-11 核验线上 13010 行：含 `#` 8498、含 `-` 6392、两者都含 6386）；#286 改为
+  同时包含，只含 `#` 的编码（如 `DD#004`）不再命中结构规则。
 - `kind=keyword`：关键词清单，匹配 `variationSku`，**不匹配 `productTitle`**。同一次核验
   中六条初始关键词在 `productTitle` 上命中为 0，且全部已被结构过滤覆盖，净增为 0；保留它
   是为档口改用不含 `#` 的编码时兜底。
@@ -516,6 +518,15 @@ POST /am/stock/detail/updateDetailCode?t=0&id={stockID}&detailId={detailID}&code
 `[必须]` `kind=char` 不可新增、不可删除，只能停用，且停用需要二次确认并记录操作人与时间。
 判据本身需要变更（例如档口改用 `/` 或 `@`）属于范围变化，应另建工单评估。
 
+`[必须]` **命中规则 = 标记无需 PDD 采购，不再跳过入库（#340）。** 启用店铺内命中结构或关键词规则的
+明细照常写入 `syb_product`，并记录 `pdd_purchase_excluded=true` 与命中规则快照
+（`excluded_rule_id`、`excluded_rule_kind`、`excluded_rule_keyword`、`excluded_at`）。
+标记**只在该明细首次创建时**按当次启用规则确定；之后重复同步同一明细不改变标记，
+规则启停或删除也不会自动改变已有标记，只能由管理员「按当前规则重算」变更。
+历史上被跳过的明细不自动补同步；需要时按日期手动导入即可补入并打标记。
+`char_filter_skipped` / `keyword_filter_skipped` 与每条规则的 `last_hit_count` 仍是**本次命中次数**
+（新建与已存在明细都计），不是「本次被标记的数量」，页面文案须称「命中」。
+
 `[必须]` 同步开始时只读取一次启用店铺，整次运行使用同一个快照。列表允许但明细
 响应中的 `shopName` 变为空或非允许店铺时再次拦截。没有启用店铺时在会话/OCR/
 验证码等任何顺运宝请求之前停止，并且不推进覆盖游标。该过滤只影响后续入库，