cmautobuy/docs/task/133-商品目录批量导入接口.md

133 Admin：实现商品目录批量导入接口

• 类型：需求
• 父级大工单：#14
• 所属 MVP / 版本：#15 / 商品目录批量接入
• 状态：已完成
• 日期：2026-08-11
• Gitea 工单：#133

背景与目标

让第三方脚本把不同来源 Excel 归一化后，通过稳定 JSON 契约批量提交蝦皮、PDD 及两者对应关系，替代由 Admin 猜测不同 Excel 格式。

最终方案

新增 POST /api/v1/integrations/catalog/batches，限制 5 MB、500 个商品和 5000 个 SKU。请求先完整校验，再在单事务中按实体、SKU、关联顺序 upsert。PDD 规格使用 结构化字段并由服务端生成规范 JSON；缺席数据不删除。批次按请求哈希重放，关联或 SKU 所属冲突整批回滚并返回稳定错误码。

改了哪些

• admin/handler/integration/catalog_api.go：请求限制、严格 JSON 解析和错误映射。
• admin/service/catalog_import.go：契约、校验、事务、幂等和统计。
• admin/repository/catalog_import.go：带来源时间的 upsert 与安全关联。
• admin/main.go：注册独立 integration 路由。
• docs/admin/10-商品目录接入接口.md：第三方调用契约与示例。

验收结果

验收标准	结果
合法批次原子写入蝦皮、SKU、PDD 和关联	通过
不覆盖人工 PDD 关联和 SKU 手工标记	通过
相同请求重放，不同内容返回 409	通过
旧 observed_at 不覆盖较新接口数据	通过
关联冲突、SKU 跨商品冲突整批回滚	通过
非法 JSON、字段、金额、数量和体积返回稳定 4xx JSON	通过
Client 四接口保持不变	通过

测试

• 执行的命令：$env:GOTOOLCHAIN="go1.23.0"; go build ./...; go test ./... -count=1; go vet ./...
• 结果：构建、全量测试和静态检查通过；SQLite 隔离测试覆盖原子写入、成功/失败重放和冲突回滚。
• 没验证到的部分：未在真实 MySQL 8.4 _test 库执行高并发同批次提交；数据库复合主键负责最终并发防重。

相关提交

• 273bcc1 feat: 实现商品目录批量导入接口 (#133)