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

- 类型：需求
- 父级大工单：#14
- 所属 MVP / 版本：#15 / 商品目录批量接入
- 状态：已完成
- 日期：2026-08-11
- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/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)