diff --git a/docs/task/88-顺运宝规格主链路重构.md b/docs/task/88-顺运宝规格主链路重构.md new file mode 100644 index 0000000..99e8e25 --- /dev/null +++ b/docs/task/88-顺运宝规格主链路重构.md @@ -0,0 +1,69 @@ +# 88 Admin:顺运宝主链路重构——规格映射改键,蝦皮报表降级为参考数据 + +- 类型:重构 +- 父级大工单:#14 +- 所属 MVP / 版本:#15 +- 状态:已完成(待验收) +- 日期:2026-08-10 +- Gitea 工单:http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/88 + +## 背景与目标 + +旧流程要求顺运宝明细先命中蝦皮 Excel 报表中的 SKU,但报表不是全量目录, +绝大多数真实订单因此无法关联 PDD 和进入采购。本任务改为以顺运宝 +`shopee_goods_id + product_spec` 为主链路,让未出现在蝦皮报表的商品也能完成 +PDD 关联、采集、规格映射和采购任务创建。 + +## 最终方案 + +- 在中立 `admin/spec` 包提供唯一 `SpecKey` 实现,只折叠空白,不做语义猜测;空规格不生成键,超过 191 字符直接报错。 +- MySQL 追加 v3:新增 `spec_mappings`、`syb_orders.spec_key` 和 + `shopee_products.source`;使用 `syb_id` 游标每批 500 行回填。 +- 旧 `sku_mappings` 先复制到受限备份表,再按可命中、无当前命中、无法转换三类统计并转换;日志只记数量和必要业务 ID。 +- 顺运宝同步在同一数据库事务内补建 `source='syb'` 商品骨架; + Excel 导入后提升为 `report`,不覆盖人工 PDD 关联。 +- 移除“确认蝦皮 SKU”接口、页面和全部前置闸门;映射按 + `(蝦皮商品 ID, spec_key, PDD 商品 ID)` 隔离。 +- 空规格显示“采购数据异常:顺运宝未提供规格”,禁止保存映射和创建采购任务。 +- 实施中额外补强了 v3 表形状自检、可空 `source` 中断点回填和“自检失败不记版本”测试,不改变工单交付范围。 + +## 改了哪些 + +- `admin/spec/`:规格身份键单一实现及边界测试。 +- `admin/repository/mysql_db.go`:MySQL v3 迁移、断点收敛、备份转换和表形状自检。 +- `admin/repository/{mapping,shopee,syb}.go`:新映射键、商品来源及骨架写入。 +- `admin/service/`:去除蝦皮 SKU 闸门,重整处理阶段、匹配和采购校验。 +- `admin/handler/web/` 与 `admin/templates/`:移除确认 SKU 入口,显示商品来源和新规格流程。 +- `admin/*_test.go`:真实 MySQL 迁移、规格复用、换品隔离、空值阻断、阶段和权限回归。 +- `docs/admin/01-requirements.md`、`03-data-model.md`、`05-ui-specification.md`:同步新主链路基线。 + +## 验收结果 + +| 验收标准 | 结果 | +|---|---| +| 无蝦皮报表商品可从顺运宝骨架进入 PDD 关联、采集、匹配和建采购任务 | 通过 | +| 同商品同规格第二条明细自动命中;PDD A→B 不命中、B→A 可复用 | 通过 | +| 空规格保持 NULL 并阻断;脏原文可建映射;超长不截断 | 通过 | +| 骨架来源、报表提升和人工 PDD 字段保护 | 通过 | +| MySQL v2→v3、三个中断点、字段/约束分离幂等、错误形状不记版本 | 通过 | +| 旧映射总数与三类结果守恒,完整备份后才删旧表 | 通过 | +| 九个阶段均有逐行推导测试,旧确认规格提示为 0 | 通过 | +| 管理员六页面正常,采购员业务页正常且用户管理拒绝访问 | 通过 | + +## 测试 + +- 执行的命令: + - `cd D:\chengma\cmautobuy\admin; $env:GOTOOLCHAIN='go1.23.0'; go vet ./...; gofmt -l .; go test ./... -count=1` + - 设置隔离 `_test` 库环境变量后执行 `go test ./repository -run 'TestMySQLMigrate_' -count=1 -v` + - 设置相同环境后执行主页面、规格映射、采购任务和骨架事务定向测试 + - `rg "请先确认蝦皮规格" admin` +- 结果:`go vet`、格式检查和普通全量测试通过;真实 MySQL 8 隔离库的迁移与主链路定向测试通过;旧提示搜索为 0。 +- **没验证到的部分**:未在正式 `autobuy` 数据库执行 v3,也未在真实浏览器中人工点击整条流程;正式迁移前必须另行准备逻辑备份和停机窗口。 + +## 遗留问题 + +规格自动建议、预选和保存审计属于后续工单 #90,本任务仍由采购员手动确认 PDD 选项。 + +## 相关提交 + +- `d1165b9` `feat: 重构顺运宝规格主链路 (#88)`