diff --git a/docs/task/232-档口入库码确定性匹配.md b/docs/task/232-档口入库码确定性匹配.md new file mode 100644 index 0000000..168842b --- /dev/null +++ b/docs/task/232-档口入库码确定性匹配.md @@ -0,0 +1,50 @@ +# 232 Admin:档口入库码确定性匹配与顺运宝回写规划 + +- 类型:需求 +- 父级大工单:#14 +- 所属 MVP / 版本:#224 +- 状态:已完成 +- 日期:2026-08-15 +- Gitea 工单: + +## 背景与目标 + +把已导入的线下标签安全定位到唯一顺运宝货运单商品,生成只读回写计划;歧义或不满足 +安全条件时必须跳过,不能猜测。 + +## 最终方案 + +- 从本地 `syb_orders.syb_data` 解析 stock ID,同一订单没有 stock 时失败、存在多个 stock + 时跳过;有效 stock 每 100 个批量读取一次顺运宝最新详情。 +- 先匹配 `productSpec` 原文,再用与参考 Python 一致的标准化键;档口存在时必须匹配 + sku、variationSku 或规格中的档口/货号,远端没有档口身份时才允许唯一规格兜底。 +- 只使用采购平台和采购单号都为空的候选;Excel 重复组、空规格、候选歧义、档口不符和 + 同一远端 detail 二次占用均不会变成可回写。 +- 全部远端读取成功并验证完整后,才在一个数据库事务保存规划;没有调用删除或写入接口。 + +## 改了哪些 + +- `admin/repository/inner_code.go`:增加可规划记录、本地 SYB 快照查询和规划原子保存。 +- `admin/service/inner_code_match.go`:增加 stock 解析、批量只读查询、规则匹配和状态统计。 +- `admin/service/inner_code_match_test.go`:覆盖精确/标准化、档口、重复、采购门禁、歧义和占用。 + +## 验收结果 + +| 验收标准 | 结果 | +|---|---| +| 精确或标准化规格与档口唯一时生成可回写计划 | 通过 | +| 远端已是目标码时标记已存在 | 通过 | +| 重复、空规格、档口不符、歧义和采购字段非空均阻断 | 通过 | +| 同一远端 detail 不会被两条记录占用 | 通过 | +| 规划阶段只有详情读取,没有远端写请求 | 通过 | + +## 测试 + +- 执行的命令:`go test ./service ./repository -run InnerCode -count=1`; + `go test ./... -count=1`;`go vet ./...` +- 结果:全部通过。 +- **没验证到的部分**:没有连接真实顺运宝验证线上响应字段;远端详情使用结构化测试数据。 + +## 相关提交 + +- `82ab80d` feat: 规划档口入库码确定性匹配 (#232)