cmautobuy/docs/task/88-顺运宝规格主链路重构.md

88 Admin：顺运宝主链路重构——规格映射改键，蝦皮报表降级为参考数据

• 类型：重构
• 父级大工单：#14
• 所属 MVP / 版本：#15
• 状态：已完成（待验收）
• 日期：2026-08-10
• Gitea 工单：#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)