# 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)