From a34393ce7681d4d2c751fca4c7edba23da263e20 Mon Sep 17 00:00:00 2001
From: chengma <chengma2027@gmail.com>
Date: Tue, 11 Aug 2026 10:06:31 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BD=92=E6=A1=A3=E4=BB=BB=E5=8A=A1=20?=
 =?UTF-8?q?#133?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/task/133-商品目录批量导入接口.md | 50 +++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)
 create mode 100644 docs/task/133-商品目录批量导入接口.md

diff --git a/docs/task/133-商品目录批量导入接口.md b/docs/task/133-商品目录批量导入接口.md
new file mode 100644
index 0000000..b1fe751
--- /dev/null
+++ b/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)