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

---
 docs/task/132-商品目录接入基础.md | 48 +++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)
 create mode 100644 docs/task/132-商品目录接入基础.md

diff --git a/docs/task/132-商品目录接入基础.md b/docs/task/132-商品目录接入基础.md
new file mode 100644
index 0000000..0c36d63
--- /dev/null
+++ b/docs/task/132-商品目录接入基础.md
@@ -0,0 +1,48 @@
+# 132 Admin：建立商品目录接入鉴权、批次与幂等基础
+
+- 类型：需求
+- 父级大工单：#14
+- 所属 MVP / 版本：#15 / 商品目录批量接入
+- 状态：已完成
+- 日期：2026-08-11
+- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/132
+
+## 背景与目标
+
+为第三方商品目录脚本建立独立、安全、可追踪的接入基础，不复用网页登录或 Client
+四接口身份，并为后续批量写入提供批次幂等和来源时间字段。
+
+## 最终方案
+
+新增可选的商品目录专用 Bearer Token 配置，未配置时安全禁用接口；MySQL 追加 v7
+迁移，以 `(source, batch_id)` 作为批次唯一键，保存请求哈希、处理状态和计数摘要，
+不保存 Token 或完整请求体。蝦皮商品、SKU 和 PDD 商品增加来源观测时间，较新的
+接口数据可在后续工单中据此阻止旧数据覆盖。
+
+## 改了哪些
+
+- `admin/config/`、`admin/config.example.yaml`：增加独立接入来源和 Token 配置及脱敏。
+- `admin/handler/integration/auth.go`：增加专用 Bearer 鉴权和统一 JSON 错误。
+- `admin/model/catalog_import.go`、`admin/repository/catalog_import.go`：增加批次摘要模型与幂等读写。
+- `admin/repository/mysql_db.go`：追加 MySQL v7 可重放迁移和 schema 自检。
+- `docs/admin/`：同步数据模型、安全规则和术语。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| 未配置 Token 时接口鉴权安全禁用，错误不泄露凭据 | 通过 |
+| 相同来源和批次号由数据库唯一键保证只能登记一次 | 通过 |
+| 可记录相同请求重放和不同请求冲突计数 | 通过 |
+| MySQL v7 迁移可重放，自检失败不记录版本 | 通过（自动化覆盖；真实 MySQL 用例按环境门禁跳过） |
+| 不改变 Client 四接口契约 | 通过 |
+
+## 测试
+
+- 执行的命令：`$env:GOTOOLCHAIN="go1.23.0"; go build ./...; go test ./... -count=1; go vet ./...`
+- 结果：构建、全部单元测试和静态检查通过。
+- **没验证到的部分**：未连接独立 MySQL 8.4 `_test` 数据库执行真实 DDL 集成测试；测试代码已加入环境门禁。
+
+## 相关提交
+
+- `107ee5c` feat: 建立商品目录接入基础 (#132)