chengma/cmautobuy
2
0
Fork 0
Code Issues 89 Pull Requests Actions Packages Projects Releases Wiki Activity

Admin：档口入库码使用原始 SKU 辅助确定性匹配 #259

New Issue
Open
opened 2026-08-17 17:46:52 +08:00 by ila · 4 comments
ila commented 2026-08-17 17:46:52 +08:00
Owner
Copy Link
Copy Source

基本信息

  • 类型：缺陷
  • 父级大工单：#14
  • 所属 MVP / 版本：#224
  • 阶段：确定性匹配兼容修复

要解决什么

2026-08-17 的档口入库码 Excel 中，订单 26081387A2EC2N 有两条记录的规格可以唯一命中顺运宝商品，但最终被标记为“规格能匹配，但档口及货号与候选商品不一致”。

复现与已确认事实：

  1. Excel 第 31、32 行的档口名称为“上寮-青春网购工厂店”，档口货号为 8916，导入后现有代码拼成 上寮-青春网购工厂店#8916。
  2. 两行的“原始SKU（源Excel C列，原样直拷）”均为 上寮-青春网购工厂店8916##(&9)。
  3. 顺运宝对应规格候选的 variationSku 与上述原始 SKU 完全相同。
  4. 当前 Excel 导入器没有读取或保存原始 SKU；匹配器只能用拼接后的档口及货号校验 sku / variationSku / productSpec，因为候选在店名和货号之间没有 #，导致有效候选被排除。

目标是在不放宽现有安全门禁的前提下，把 Excel 原始 SKU 作为高优先级、可审计的确定性匹配证���，兼容档口和货号在顺运宝中无分隔符或排列不规则的情况。

做什么 / 不做什么

  • 做：在 syb_inner_code_records 增加可空的 Excel 原始 SKU 字段，保留源数据并参与匹配。
  • 做：兼容“原始SKU”“原始sku”“原始 SKU”以及带“源Excel C列，原样直拷”说明的表头；旧格式 Excel 没有该列时继续允许导入。
  • 做：先按订单和规格筛选候选，再优先用原始 SKU 与候选 sku 或 variationSku 做确定性匹配；没有唯一命中时保留现有档口及货号规则作为兜底。
  • 做：原始 SKU、档口规则指向不同候选或任一规则命中多个候选时停止自动选择并给出明确原因。
  • 做：重复导入补充原始 SKU；尚未完成的失败/跳过记录可以重新规划，已经回写或结果未知的记录不得丢失审计状态。
  • 不做：不改变“日期 + 订单号 + 档口及货号 + 标准化规格”业务键，不用原始 SKU 替换页面上的档口字段。
  • 不做：不通过全局删除 #、模糊包含或只比较短货号来放宽匹配；不使用 AI，不新增页面按钮，不改变采购流程。
  • 不做：匹配阶段仍只读顺运宝，不调用创建、删除或更新远端明细接口。

怎么做

  • admin/repository/mysql_db.go：追加下一版可重放 MySQL 迁移，在 syb_inner_code_records 增加可空 source_sku_raw（长度应覆盖顺运宝 SKU 原文），并补充字段和迁移版本自检；已发布迁移不得改写。
  • admin/model/inner_code.go、admin/repository/inner_code.go：在导入模型、业务模型、插入、幂等更新和扫描中传递 source_sku_raw。重复导入时更新该源字段；终态记录继续保留匹配和回写审计结论。
  • admin/service/inner_code_import.go：通过规范化表头名称识别原始 SKU 列，保存源值；仅处理单元格边界空白/换行用于比较，数据库中保留原文。原始 SKU 为可选字段，字段超长时返回带 Excel 行号的错误。
  • admin/service/inner_code_match.go：
    1. 保留订单唯一、采购字段为空、规格精确/标准化、同一 detail 只占用一次等现有门禁；
    2. 在规格候选中，原始 SKU 与 sku 或 variationSku 唯一精确相等时，允许命中，即使派生的档口字符串因分隔符不同而未命中；
    3. 原始 SKU 未提供或没有命中时，再执行现有档口及货号过滤，保证旧 Excel 兼容；
    4. 原始 SKU 命中多个候选，或者原始 SKU 与档口规则分别唯一指向不同候选时，标记为跳过并显示“原始 SKU 候选重复”或“原始 SKU 与档口货号冲突”，禁止猜测。
  • 补充导入、repository、迁移和纯匹配函数测试；用脱敏测试数据覆盖本缺陷，不把生产 Excel 加入 Git。
  • 预计修改文件：admin/repository/mysql_db.go、admin/model/inner_code.go、admin/repository/inner_code.go、admin/service/inner_code_import.go、admin/service/inner_code_match.go、对应测试及 docs/admin/03-data-model.md。

验收标准

  • 下一版 MySQL 迁移在空库、上一版本升级和重复执行时均通过，只有结构自检成功后才记录版本。
  • 17 号 Excel 第 31、32 行能够读出并保存原始 SKU；重新导入不会产生重复业务记录。
  • 订单、规格唯一且原始 SKU 与候选 variationSku 完全一致时，两条记录生成可回写计划，不再报档口及货号不一致。
  • 原始 SKU 与候选 sku 完全一致时同样可以唯一匹配。
  • 原始 SKU 缺失或没有命中时，旧版 Excel 继续走现有档口及货号规则，现有成功场景不退化。
  • 原始 SKU 命中多个候选，或原始 SKU 与档口规则指向不同候选时，远端零写入并显示可诊断的冲突原因。
  • 有采购平台/采购单号、规格歧义、detail 已被其他记录占用等现有安全门禁保持不变。
  • 重复导入时，未完成记录可重新规划；updated、already_filled、applying、needs_check 等需保留的状态及远端审计数据不被重置。
  • 匹配测试确认不会调用顺运宝创建、删除、更新或写码接口。
  • 固定 Go 1.23.0 的定向测试、全量测试、build、vet 和 git diff --check 通过。

怎么验证

从仓库根目录执行：

$env:GOTOOLCHAIN='go1.23.0'
Set-Location admin
go test ./service ./repository ./syb -run InnerCode -count=1
go test ./... -count=1
go build ./...
go vet ./...
Set-Location ..
git diff --check
Remove-Item Env:GOTOOLCHAIN

另使用独立 MySQL 8.4 _test 数据库验证空库、上一版本升级和重复迁移；使用 raw_data/Shopee线下档口入库码映射_20260817_V3.3-R5.xlsx 做本地人工导入验证，生产样本不提交 Git。真实环境只重新规划目标记录，不执行回写，待操作员核对为“可回写”后另行确认。

风险和回退

  • 风险：原始 SKU 可能重复，或者 Excel 原始 SKU 与派生档口信息不一致；必须保持唯一命中和冲突阻断，不能选择第一个候选。
  • 风险：迁移、模型和扫描列顺序不一致会导致启动或查询失败；通过 MySQL 迁移自检、repository 测试和全量测试覆盖。
  • 回退：停止使用原始 SKU 匹配并回退应用代码；新增可空字段保留，不执行逆向迁移、不删除导入���回写审计数据。已经写入顺运宝的结果不由本工单自动撤销。
## 基本信息 - 类型：缺陷 - 父级大工单：#14 - 所属 MVP / 版本：#224 - 阶段：确定性匹配兼容修复 ## 要解决什么 2026-08-17 的档口入库码 Excel 中，订单 `26081387A2EC2N` 有两条记录的规格可以唯一命中顺运宝商品，但最终被标记为“规格能匹配，但档口及货号与候选商品不一致”。 复现与已确认事实： 1. Excel 第 31、32 行的档口名称为“上寮-青春网购工厂店”，档口货号为 `8916`，导入后现有代码拼成 `上寮-青春网购工厂店#8916`。 2. 两行的“原始SKU（源Excel C列，原样直拷）”均为 `上寮-青春网购工厂店8916##(&9)`。 3. 顺运宝对应规格候选的 `variationSku` 与上述原始 SKU 完全相同。 4. 当前 Excel 导入器没有读取或保存原始 SKU；匹配器只能用拼接后的档口及货号校验 `sku / variationSku / productSpec`，因为候选在店名和货号之间没有 `#`，导致有效候选被排除。 目标是在不放宽现有安全门禁的前提下，把 Excel 原始 SKU 作为高优先级、可审计的确定性匹配证���，兼容档口和货号在顺运宝中无分隔符或排列不规则的情况。 ## 做什么 / 不做什么 - 做：在 `syb_inner_code_records` 增加可空的 Excel 原始 SKU 字段，保留源数据并参与匹配。 - 做：兼容“原始SKU”“原始sku”“原始 SKU”以及带“源Excel C列，原样直拷”说明的表头；旧格式 Excel 没有该列时继续允许导入。 - 做：先按订单和规格筛选候选，再优先用原始 SKU 与候选 `sku` 或 `variationSku` 做确定性匹配；没有唯一命中时保留现有档口及货号规则作为兜底。 - 做：原始 SKU、档口规则指向不同候选或任一规则命中多个候选时停止自动选择并给出明确原因。 - 做：重复导入补充原始 SKU；尚未完成的失败/跳过记录可以重新规划，已经回写或结果未知的记录不得丢失审计状态。 - 不做：不改变“日期 + 订单号 + 档口及货号 + 标准化规格”业务键，不用原始 SKU 替换页面上的档口字段。 - 不做：不通过全局删除 `#`、模糊包含或只比较短货号来放宽匹配；不使用 AI，不新增页面按钮，不改变采购流程。 - 不做：匹配阶段仍只读顺运宝，不调用创建、删除或更新远端明细接口。 ## 怎么做 - `admin/repository/mysql_db.go`：追加下一版可重放 MySQL 迁移，在 `syb_inner_code_records` 增加可空 `source_sku_raw`（长度应覆盖顺运宝 SKU 原文），并补充字段和迁移版本自检；已发布迁移不得改写。 - `admin/model/inner_code.go`、`admin/repository/inner_code.go`：在导入模型、业务模型、插入、幂等更新和扫描中传递 `source_sku_raw`。重复导入时更新该源字段；终态记录继续保留匹配和回写审计结论。 - `admin/service/inner_code_import.go`：通过规范化表头名称识别原始 SKU 列，保存源值；仅处理单元格边界空白/换行用于比较，数据库中保留原文。原始 SKU 为可选字段，字段超长时返回带 Excel 行号的错误。 - `admin/service/inner_code_match.go`： 1. 保留订单唯一、采购字段为空、规格精确/标准化、同一 detail 只占用一次等现有门禁； 2. 在规格候选中，原始 SKU 与 `sku` 或 `variationSku` 唯一精确相等时，允许命中，即使派生的档口字符串因分隔符不同而未命中； 3. 原始 SKU 未提供或没有命中时，再执行现有档口及货号过滤，保证旧 Excel 兼容； 4. 原始 SKU 命中多个候选，或者原始 SKU 与档口规则分别唯一指向不同候选时，标记为跳过并显示“原始 SKU 候选重复”或“原始 SKU 与档口货号冲突”，禁止猜测。 - 补充导入、repository、迁移和纯匹配函数测试；用脱敏测试数据覆盖本缺陷，不把生产 Excel 加入 Git。 - 预计修改文件：`admin/repository/mysql_db.go`、`admin/model/inner_code.go`、`admin/repository/inner_code.go`、`admin/service/inner_code_import.go`、`admin/service/inner_code_match.go`、对应测试及 `docs/admin/03-data-model.md`。 ## 验收标准 - [ ] 下一版 MySQL 迁移在空库、上一版本升级和重复执行时均通过，只有结构自检成功后才记录版本。 - [ ] 17 号 Excel 第 31、32 行能够读出并保存原始 SKU；重新导入不会产生重复业务记录。 - [ ] 订单、规格唯一且原始 SKU 与候选 `variationSku` 完全一致时，两条记录生成可回写计划，不再报档口及货号不一致。 - [ ] 原始 SKU 与候选 `sku` 完全一致时同样可以唯一匹配。 - [ ] 原始 SKU 缺失或没有命中时，旧版 Excel 继续走现有档口及货号规则，现有成功场景不退化。 - [ ] 原始 SKU 命中多个候选，或原始 SKU 与档口规则指向不同候选时，远端零写入并显示可诊断的冲突原因。 - [ ] 有采购平台/采购单号、规格歧义、detail 已被其他记录占用等现有安全门禁保持不变。 - [ ] 重复导入时，未完成记录可重新规划；`updated`、`already_filled`、`applying`、`needs_check` 等需保留的状态及远端审计数据不被重置。 - [ ] 匹配测试确认不会调用顺运宝创建、删除、更新或写码接口。 - [ ] 固定 Go 1.23.0 的定向测试、全量测试、build、vet 和 `git diff --check` 通过。 ## 怎么验证 从仓库根目录执行： ```powershell $env:GOTOOLCHAIN='go1.23.0' Set-Location admin go test ./service ./repository ./syb -run InnerCode -count=1 go test ./... -count=1 go build ./... go vet ./... Set-Location .. git diff --check Remove-Item Env:GOTOOLCHAIN ``` 另使用独立 MySQL 8.4 `_test` 数据库验证空库、上一版本升级和重复迁移；使用 `raw_data/Shopee线下档口入库码映射_20260817_V3.3-R5.xlsx` 做本地人工导入验证，生产样本不提交 Git。真实环境只重新规划目标记录，不执行回写，待操作员核对为“可回写”后另行确认。 ## 风险和回退 - 风险：原始 SKU 可能重复，或者 Excel 原始 SKU 与派生档口信息不一致；必须保持唯一命中和冲突阻断，不能选择第一个候选。 - 风险：迁移、模型和扫描列顺序不一致会导致启动或查询失败；通过 MySQL 迁移自检、repository 测试和全量测试覆盖。 - 回退：停止使用原始 SKU 匹配并回退应用代码；新增可空字段保留，不执行逆向迁移、不删除导入���回写审计数据。已经写入顺运宝的结果不由本工单自动撤销。
ila commented 2026-08-18 15:25:18 +08:00
Author
Owner
Copy Link
Copy Source

???:??? MySQL v28 source_sku_raw?Excel ?????????????? SKU ??????????????? SKU/????????????? 2026-08-17 ?? Excel ????? 31?32 ????????? SKU;?????????????????????????

???:??? MySQL v28 source_sku_raw?Excel ?????????????? SKU ??????????????? SKU/????????????? 2026-08-17 ?? Excel ????? 31?32 ????????? SKU;?????????????????????????
ila commented 2026-08-18 15:26:43 +08:00
Author
Owner
Copy Link
Copy Source

????,??:????

????,??:???? - ????:`4383bb8` fix: ????SKU?????? (#259) - ????:`a989e0d` docs: ???? #259 - ??:`docs/task/259-??SKU??????.md` - ??:Go 1.23.0 ??????`go test ./... -count=1`?`go build ./...`?`go vet ./...`?`git diff --check` ????? - ????????:2026-08-17 Excel ? 31?32 ?????????? SKU;????????????? - ???:???? MySQL ?? v28,?????????????????
ila commented 2026-08-18 15:35:23 +08:00
Author
Owner
Copy Link
Copy Source

????????????:?? schema ??? v28,? source_sku_raw ???????????????? utf8mb4_0900_ai_ci;?????? utf8mb4_bin,?? v28 ??????????????????:??? v28,?? v29,????????? VARCHAR(500) COLLATE utf8mb4_bin NULL;??? v27 ??????? v29??????????????????

????????????:?? schema ??? v28,? source_sku_raw ???????????????? utf8mb4_0900_ai_ci;?????? utf8mb4_bin,?? v28 ??????????????????:??? v28,?? v29,????????? VARCHAR(500) COLLATE utf8mb4_bin NULL;??? v27 ??????? v29??????????????????
ila commented 2026-08-18 15:43:17 +08:00
Author
Owner
Copy Link
Copy Source

兼容修复和生产验证完成，状态：待验收。

  • 追加迁移提交：b685d2c（MySQL v29）
  • 归档更新：7175af5、cf0c870
  • 生产验证：v28 中间结构已由 v29 规范为 utf8mb4_bin，最终 schema 为 v29；目标 Admin 启动自检通过。
  • 未触发 Excel 导入、顺运宝匹配或真实回写。
兼容修复和生产验证完成，状态：待验收。 - 追加迁移提交：`b685d2c`（MySQL v29） - 归档更新：`7175af5`、`cf0c870` - 生产验证：v28 中间结构已由 v29 规范为 `utf8mb4_bin`，最终 schema 为 v29；目标 Admin 启动自检通过。 - 未触发 Excel 导入、顺运宝匹配或真实回写。
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
admin ila
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: chengma/cmautobuy#259