Admin：档口入库码确定性匹配与顺运宝回写规划 #232

New Issue

2026-08-24T11:28:29+08:00

ila commented

2026-08-24 11:28:29 +08:00

基本信息

类型：需求
父级大工单：#14
所属 MVP / 版本：#224
阶段：确定性匹配

要解决什么

导入记录必须安全地定位到唯一顺运宝货运单商品，才能生成“可回写”计划。当前匹配只存在于独立 Python 脚本，Admin 没有等价的标准化、候选过滤和歧义保护。

做什么 / 不做什么

做：从本地 syb_orders 找到订单对应的 stock/detail 标识，再复用 Admin 顺运宝会话读取最新详情；按已确认规则做精确规格、标准化规格和档口货号匹配。
做：只允许 purchasePlatform 与 purchaseCode 均为空的商品成为可回写候选；一条远端商品在同次规划内最多占用一次；保存远端原值和明确原因。
不做：不调用删除/更新接口；不使用 AI；歧义时不猜测；不改变采购任务或 syb_orders 数据。

怎么做

新增 admin/service/inner_code_match.go，把规格和档口匹配实现为无网络纯函数，再由规划服务编排 repository 与 syb.Client.DetailListByStock。
spec_match_key 与已确认 Python 流程一致：去备注和“建议”尾部、压缩空白、拆颜色尺码、去颜色档口前缀、统一尺码代码和“碼/体重”尾部。
Excel 同订单 + 同规格 + 同档口重复组全部跳过；先 productSpec 精确命中，再使用标准化键；存在档口时必须能在 sku、variationSku 或 productSpec 中确认；候选不唯一时标为已跳过并保存原因。
匹配前通过 service.EnsureSybSession 恢复已有会话；未登录或会话失效时给出可操作错误，不记录凭据。

验收标准

精确规格唯一命中生成可回写计划，远端已是目标码时标为已存在。
标准化规格与档口均唯一时可命中；档口不符、候选歧义、Excel 重复组和空规格均不会生成可回写计划。
有采购平台或采购单号的远端商品不会成为候选，并显示明确原因。
同一远端 detail 不会被两条导入记录占用。
匹配只读远端，不调用删除或更新接口；会话缺失和网络错误可诊断。

怎么验证

在 admin/ 执行 go test ./service ./syb -run InnerCode -count=1 和 go test ./... -count=1；使用 httptest.Server 模拟多商品、歧义、会话失效和远端字段组合，不连接真实顺运宝。

风险和回退

风险：规则偏宽会匹配错误商品；通过唯一命中、档口校验、候选占用、采购字段为空四重门禁阻止。
回退：移除页面规划入口即可停止新匹配；既有记录保留，可重新规划，不影响顺运宝远端。

## 基本信息 - 类型：需求 - 父级大工单：#14 - 所属 MVP / 版本：#224 - 阶段：确定性匹配 ## 要解决什么导入记录必须安全地定位到唯一顺运宝货运单商品，才能生成“可回写”计划。当前匹配只存在于独立 Python 脚本，Admin 没有等价的标准化、候选过滤和歧义保护。 ## 做什么 / 不做什么 - 做：从本地 `syb_orders` 找到订单对应的 stock/detail 标识，再复用 Admin 顺运宝会话读取最新详情；按已确认规则做精确规格、标准化规格和档口货号匹配。 - 做：只允许 `purchasePlatform` 与 `purchaseCode` 均为空的商品成为可回写候选；一条远端商品在同次规划内最多占用一次；保存远端原值和明确原因。 - 不做：不调用删除/更新接口；不使用 AI；歧义时不猜测；不改变采购任务或 `syb_orders` 数据。 ## 怎么做 - 新增 `admin/service/inner_code_match.go`，把规格和档口匹配实现为无网络纯函数，再由规划服务编排 repository 与 `syb.Client.DetailListByStock`。 - `spec_match_key` 与已确认 Python 流程一致：去备注和“建议”尾部、压缩空白、拆颜色尺码、去颜色档口前缀、统一尺码代码和“碼/体重”尾部。 - Excel 同订单 + 同规格 + 同档口重复组全部跳过；先 `productSpec` 精确命中，再使用标准化键；存在档口时必须能在 sku、variationSku 或 productSpec 中确认；候选不唯一时标为已跳过并保存原因。 - 匹配前通过 `service.EnsureSybSession` 恢复已有会话；未登录或会话失效时给出可操作错误，不记录凭据。 ## 验收标准 - [ ] 精确规格唯一命中生成可回写计划，远端已是目标码时标为已存在。 - [ ] 标准化规格与档口均唯一时可命中；档口不符、候选歧义、Excel 重复组和空规格均不会生成可回写计划。 - [ ] 有采购平台或采购单号的远端商品不会成为候选，并显示明确原因。 - [ ] 同一远端 detail 不会被两条导入记录占用。 - [ ] 匹配只读远端，不调用删除或更新接口；会话缺失和网络错误可诊断。 ## 怎么验证在 `admin/` 执行 `go test ./service ./syb -run InnerCode -count=1` 和 `go test ./... -count=1`；使用 `httptest.Server` 模拟多商品、歧义、会话失效和远端字段组合，不连接真实顺运宝。 ## 风险和回退 - 风险：规则偏宽会匹配错误商品；通过唯一命中、档口校验、候选占用、采购字段为空四重门禁阻止。 - 回退：移除页面规划入口即可停止新匹配；既有记录保留，可重新规划，不影响顺运宝远端。

ila commented

2026-08-24 11:42:02 +08:00