cmautobuy/docs/task/132-商品目录接入基础.md

132 Admin：建立商品目录接入鉴权、批次与幂等基础

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