docs: mirror SYB product filter rules and admin API #269
Wiki updated online first, then mirrored: - SYB-ERP-Interface-Contract@f1792b7f — filter order after shop admission, OR-not-AND with the 8498/6392/6386/8504 figures from the 2026-09-11 production check, empty variationSku kept, per-rule hit counts, and the no-add/no-delete rule for structural criteria. - Android-Agent-API-Contract@38869285 — the syb-product-filters endpoints, the server-side refusal of char add/delete, and the live lastHitCount requirement for the disable confirmation. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NTDbDcwbDw1TSAcE6wfh2F
This commit is contained in:
QiuSW
@@ -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: a2e73f5b892385a3c306dfdeca543a3aeb89a32e
|
||||
synchronized_at: 2026-09-10T08:09:35Z
|
||||
wiki_revision: 388692854a5e8c77be512ff6c7b97038d483c59c
|
||||
synchronized_at: 2026-09-11T09:10:18Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# MVP 共享 API 契约
|
||||
@@ -100,6 +100,33 @@ POST /api/admin/v1/syb-shops/discover
|
||||
|
||||
`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
|
||||
@@ -1125,3 +1152,12 @@ requestId 沿用 UUID 约定，不增加批次表或全局幂等缓存。既有
|
||||
- `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` 重复探测拒绝规则不变。未改变设备租约、并发、支付禁止和任务重试语义。
|
||||
|
||||
@@ -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: 214485db630141aeb03d4b49b22a65e572fb592a
|
||||
synchronized_at: 2026-09-08T02:24:10Z
|
||||
wiki_revision: f1792b7fe35925480c25b890e85fa5e551744812
|
||||
synchronized_at: 2026-09-11T09:11:21Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 12 顺云宝（SYB）ERP 接口契约
|
||||
@@ -495,6 +495,27 @@ POST /am/stock/detail/updateDetailCode?t=0&id={stockID}&detailId={detailID}&code
|
||||
`shopName` 去除首尾空白后与启用店铺精确匹配 → 只为接受的货运单请求明细和入库。
|
||||
店铺过滤只决定明细获取和入库，不能减少原始列表完整性校验范围；已保存不代表整日完整。
|
||||
|
||||
`[必须]` **店铺准入之后再按 `variationSku` 过滤商品（#269）。** 顺序固定为：店铺准入 →
|
||||
结构过滤 → 关键词过滤 → 入库。两类规则都存在 `syb_product_filter`，由 `kind` 区分：
|
||||
|
||||
- `kind=char`：`-` 和 `#` 两条，命中任意一条即跳过（**OR，不是 AND**）。这两个字符是
|
||||
「档口-供应商#货号」编码格式的判据。2026-09-11 核验线上 13010 行明细：含 `#` 8498 行、
|
||||
含 `-` 6392 行、两者都含 6386 行、任一 8504 行（65%）。用 AND 只命中 6386 行，会漏掉
|
||||
`DD#004`、`300斤牛奶絲圓領#A057` 这类只含 `#` 的 2118 行。
|
||||
- `kind=keyword`：关键词清单，匹配 `variationSku`，**不匹配 `productTitle`**。同一次核验
|
||||
中六条初始关键词在 `productTitle` 上命中为 0，且全部已被结构过滤覆盖，净增为 0；保留它
|
||||
是为档口改用不含 `#` 的编码时兜底。
|
||||
|
||||
`[必须]` 空 `variationSku` **不过滤**。核验时 2724 行（21%）为空，分布在正常启用店铺且持续
|
||||
产生，属于尚未填写供应商编码的正常商品，不是档口货。
|
||||
|
||||
`[必须]` 两类命中数分别统计并分别回写到每条规则自己的 `last_hit_count`，不得合并成单一
|
||||
「过滤总数」，也不得按 `kind` 写同一个汇总值。前者会使结构判据失效不可观测（关键词净增为 0
|
||||
时无法区分「没漏网」和「规则没生效」）；后者会让停用确认对 `#` 和 `-` 提示同一个数字。
|
||||
|
||||
`[必须]` `kind=char` 不可新增、不可删除，只能停用，且停用需要二次确认并记录操作人与时间。
|
||||
判据本身需要变更（例如档口改用 `/` 或 `@`）属于范围变化，应另建工单评估。
|
||||
|
||||
`[必须]` 同步开始时只读取一次启用店铺，整次运行使用同一个快照。列表允许但明细
|
||||
响应中的 `shopName` 变为空或非允许店铺时再次拦截。没有启用店铺时在会话/OCR/
|
||||
验证码等任何顺运宝请求之前停止，并且不推进覆盖游标。该过滤只影响后续入库，
|
||||
|
||||
Reference in New Issue
Block a user