docs: 归档任务 #133

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

@@ -0,0 +1,50 @@
+# 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)