cmautobuy/docs/task/204-syb确定性解析蝦皮规格.md

204 Admin：确定性解析 SYB 规格并补建蝦皮 SKU

• 类型：需求
• 父级大工单：#14
• 所属 MVP / 版本：#15 后续版本
• 状态：已完成，待用户验收
• 日期：2026-08-13
• Gitea 工单：#204

背景与目标

SYB 货运单已有蝦皮商品 ID 和颜色尺码原文，但此前只作为只读观测展示，商品主数据 缺少对应 SKU。目标是只解析格式明确的数据，避免猜测污染主数据。

最终方案

新增纯函数解析“颜色,尺码【建议】”二维格式，兼容全角逗号和常见标准尺码；额外维度、 未知尺码、空字段或括号不完整时返回失败且不写 SKU。成功记录使用商品 ID 与 spec_key 生成稳定内部主键，真实蝦皮 SKU ID 保持空，来源标为 syb。后续目录接口 按同一规格身份补真实 ID，并可把各字段来源提升为权威来源。MySQL v16 回填历史数据。

改了哪些

• admin/spec/shopee_spec.go：确定性解析器。
• admin/service/syb.go、admin/repository/syb.go：同步和历史补建入口。
• admin/repository/catalog_import.go：同规格权威来源升级。
• admin/repository/mysql_db.go：增加 MySQL v16 迁移与自检。
• admin/spec/shopee_spec_test.go、admin/repository/syb_test.go：解析与合并测试。
• docs/admin/：更新“SYB 只读观测”的旧基线。

验收结果

验收标准	结果
明确的颜色、尺码和建议可解析	通过
不明确格式不猜测、不写结构化 SKU	通过
重复同步使用同一内部记录	通过
商品目录可补真实 SKU ID 并升级低优先级字段	通过
v16 可回填历史 SYB 规格	代码与迁移测试已补，待独立 MySQL 8.4 库实跑

测试

• 执行的命令：$env:GOTOOLCHAIN="go1.23.0"; go vet ./...; go build ./...; go test ./... -count=1
• 结果：解析器和非 MySQL 回归通过；MySQL 集成测试因未启用隔离库而跳过。
• 没验证到的部分：真实 MySQL 8.4 v15→v16 历史回填和重放。buy 无 autobuy_test 权限，未使用生产库代测。

相关提交

• ad1ccc2 完善 SYB 蝦皮主数据与软删除