docs: 归档任务 #88

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)`