Admin：规范 CSV 预检与安全入库 #281

New Issue

2026-08-24T11:29:15+08:00

ila commented

2026-08-24 11:29:15 +08:00

基本信息

类型：单元任务
父级大工单：#14
所属 MVP/版本：#15（商品目录接入后续批量数据准备）
阶段：第三方商品目录安全入库
依赖：#280（已完成，待验收的规范 CSV 导出）

要解决什么

#280 已将 20 个第三方工作簿导出为规范 CSV，共 1,049,441 行。现有商品目录接口虽支持 fill_missing，但缺少面向大规模 CSV 的数据库预检、跨 CSV 去重、数据库既有关联冲突报告和可续跑执行工具。

需要把 CSV 中的蝦皮商品、蝦皮 SKU、PDD 商品及关联安全导入 Admin。已有数据必须优先保留，特别是已采集或人工维护的 PDD 标题、店铺、规格、价格和状态。

做什么 / 不做什么

做：

增加规范 CSV 的流式读取、业务键去重、接口批次构建和可重复执行命令。
增加 Admin 侧只读预检能力，按当前数据库统计新增、补空、跳过和冲突，且不写入业务表、不记录幂等成功批次。
正式执行固定使用 fill_missing：蝦皮商品和 SKU 仅补空字段；PDD 商品只补空规范 URL，不覆盖 PDD 采集结果、价格、状态或人工数据。
精确匹配的蝦皮—PDD 关联幂等跳过；数据库已有不同 PDD 关联时不替换，输出冲突报告。
将 PDD URL 无效的 4,760 行列入报告，保留其蝦皮数据入库但不创建 PDD 商品/关联。

不做：

不覆盖已有非空商品字段，不清空表，不删除既有数据。
不把第三方来源的蝦皮价格或促销价写入 PDD 价格。
不采集 PDD 商品、不过滤或猜测未明确的颜色和尺码。
不修改 Client 接口或采购逻辑。

已确认实现方案

新增本地导入工具，读取 #280 生成的 CSV，按以下业务键归并并分批调用商品目录接口：蝦皮商品 shopee_goods_id、蝦皮 SKU shopee_goods_id + spec_raw、PDD 商品 pdd_goods_id、关联 (shopee_goods_id, pdd_goods_id)。
扩展 Admin 商品目录接入接口/服务，支持受 Token 保护的预检请求：同一批数据在事务内只查询当前数据库，返回新增、仅补空、跳过、冲突及行级问题；预检绝不写入 catalog_import_batches 或业务表。
对关联预检：无关联=新增；相同关联=跳过；同一蝦皮商品已有不同 PDD 关联=冲突。正式写入遇到冲突亦跳过该关联并返回报告，不能替换。
正式执行使用既有 fill_missing 更新语义，按接口的 500 商品/5000 SKU/5MB 限制分批；批次 ID 对相同 CSV、参数和内容稳定，可失败后重跑。
导入工具分别输出预检汇总和正式结果报告；报告只含业务 ID、行号与安全错误信息，绝不记录 Token、Cookie 或密码。

预计修改：

admin/internal/handler/api/*catalog*
admin/internal/service/*catalog*
admin/internal/repository/*catalog*
admin/internal/model/*catalog*
docs/admin/10-商品目录接入接口.md
tools/import_thirdparty_catalog_csv.py 及其测试/依赖说明
docs/task/<工单号>-第三方规范csv安全入库.md（完成后归档）

风险和回退

约 105 万 SKU 行需要流式处理、稳定分批和重试；工具不得一次性把全部 CSV 读入内存。
数据库预检与正式写入之间可能出现人工变更；正式写入仍必须再做相同的非覆盖和冲突判断。
正式导入只新增或补空；若发生业务问题，可按本次稳定批次 ID、来源和报告定位新增数据，再通过独立数据修复工单处理，禁止本任务中批量删除回退。

验收标准

可流式读取 #280 的 20 个 CSV，按已确认的四类业务键去重，不一次性加载全部数据。
预检只读，不写业务表和导入幂等记录；能返回新增、补空、跳过、冲突及无效 PDD URL 统计。
现有蝦皮商品/SKU/PDD 字段只补空，不覆盖非空和人工维护数据；来源价格绝不写入 PDD 价格。
已有相同关联幂等跳过；数据库已有不同 PDD 关联时预检和正式执行都报告冲突且不替换。
正式导入固定 fill_missing、满足 500 商品/5000 SKU/5MB 批次限制，并可安全重跑。
预检及正式结果生成不含凭据的本地报告；4,760 条 PDD 异常行进入报告且不生成 PDD 关联。
自动化测试覆盖预检无写入、字段非覆盖、关联冲突和稳定批次；接口文档同步更新。

验证方式

cd D:\chengma\cmautobuy\admin
$env:GOTOOLCHAIN="go1.23.0"; go build ./...; go test ./... -count=1
Remove-Item Env:GOTOOLCHAIN

cd D:\chengma\cmautobuy
python -m unittest tools.test_import_thirdparty_catalog_csv -v
python tools\import_thirdparty_catalog_csv.py "D:\chengma\全部店铺拼多多商品规范CSV" --base-url http://localhost:8080 --dry-run

预期：预检仅输出统计和报告，不写数据库；正式导入须在预检结果确认后单独执行。

## 基本信息 - 类型：单元任务 - 父级大工单：#14 - 所属 MVP/版本：#15（商品目录接入后续批量数据准备） - 阶段：第三方商品目录安全入库 - 依赖：#280（已完成，待验收的规范 CSV 导出） ## 要解决什么 #280 已将 20 个第三方工作簿导出为规范 CSV，共 1,049,441 行。现有商品目录接口虽支持 `fill_missing`，但缺少面向大规模 CSV 的数据库预检、跨 CSV 去重、数据库既有关联冲突报告和可续跑执行工具。需要把 CSV 中的蝦皮商品、蝦皮 SKU、PDD 商品及关联安全导入 Admin。已有数据必须优先保留，特别是已采集或人工维护的 PDD 标题、店铺、规格、价格和状态。 ## 做什么 / 不做什么做： - 增加规范 CSV 的流式读取、业务键去重、接口批次构建和可重复执行命令。 - 增加 Admin 侧只读预检能力，按当前数据库统计新增、补空、跳过和冲突，且不写入业务表、不记录幂等成功批次。 - 正式执行固定使用 `fill_missing`：蝦皮商品和 SKU 仅补空字段；PDD 商品只补空规范 URL，不覆盖 PDD 采集结果、价格、状态或人工数据。 - 精确匹配的蝦皮—PDD 关联幂等跳过；数据库已有不同 PDD 关联时不替换，输出冲突报告。 - 将 PDD URL 无效的 4,760 行列入报告，保留其蝦皮数据入库但不创建 PDD 商品/关联。不做： - 不覆盖已有非空商品字段，不清空表，不删除既有数据。 - 不把第三方来源的蝦皮价格或促销价写入 PDD 价格。 - 不采集 PDD 商品、不过滤或猜测未明确的颜色和尺码。 - 不修改 Client 接口或采购逻辑。 ## 已确认实现方案 1. 新增本地导入工具，读取 #280 生成的 CSV，按以下业务键归并并分批调用商品目录接口：蝦皮商品 `shopee_goods_id`、蝦皮 SKU `shopee_goods_id + spec_raw`、PDD 商品 `pdd_goods_id`、关联 `(shopee_goods_id, pdd_goods_id)`。 2. 扩展 Admin 商品目录接入接口/服务，支持受 Token 保护的预检请求：同一批数据在事务内只查询当前数据库，返回新增、仅补空、跳过、冲突及行级问题；预检绝不写入 `catalog_import_batches` 或业务表。 3. 对关联预检：无关联=新增；相同关联=跳过；同一蝦皮商品已有不同 PDD 关联=冲突。正式写入遇到冲突亦跳过该关联并返回报告，不能替换。 4. 正式执行使用既有 `fill_missing` 更新语义，按接口的 500 商品/5000 SKU/5MB 限制分批；批次 ID 对相同 CSV、参数和内容稳定，可失败后重跑。 5. 导入工具分别输出预检汇总和正式结果报告；报告只含业务 ID、行号与安全错误信息，绝不记录 Token、Cookie 或密码。预计修改： - `admin/internal/handler/api/*catalog*` - `admin/internal/service/*catalog*` - `admin/internal/repository/*catalog*` - `admin/internal/model/*catalog*` - `docs/admin/10-商品目录接入接口.md` - `tools/import_thirdparty_catalog_csv.py` 及其测试/依赖说明 - `docs/task/<工单号>-第三方规范csv安全入库.md`（完成后归档） ## 风险和回退 - 约 105 万 SKU 行需要流式处理、稳定分批和重试；工具不得一次性把全部 CSV 读入内存。 - 数据库预检与正式写入之间可能出现人工变更；正式写入仍必须再做相同的非覆盖和冲突判断。 - 正式导入只新增或补空；若发生业务问题，可按本次稳定批次 ID、来源和报告定位新增数据，再通过独立数据修复工单处理，禁止本任务中批量删除回退。 ## 验收标准 - [ ] 可流式读取 #280 的 20 个 CSV，按已确认的四类业务键去重，不一次性加载全部数据。 - [ ] 预检只读，不写业务表和导入幂等记录；能返回新增、补空、跳过、冲突及无效 PDD URL 统计。 - [ ] 现有蝦皮商品/SKU/PDD 字段只补空，不覆盖非空和人工维护数据；来源价格绝不写入 PDD 价格。 - [ ] 已有相同关联幂等跳过；数据库已有不同 PDD 关联时预检和正式执行都报告冲突且不替换。 - [ ] 正式导入固定 `fill_missing`、满足 500 商品/5000 SKU/5MB 批次限制，并可安全重跑。 - [ ] 预检及正式结果生成不含凭据的本地报告；4,760 条 PDD 异常行进入报告且不生成 PDD 关联。 - [ ] 自动化测试覆盖预检无写入、字段非覆盖、关联冲突和稳定批次；接口文档同步更新。 ## 验证方式 ```powershell cd D:\chengma\cmautobuy\admin $env:GOTOOLCHAIN="go1.23.0"; go build ./...; go test ./... -count=1 Remove-Item Env:GOTOOLCHAIN cd D:\chengma\cmautobuy python -m unittest tools.test_import_thirdparty_catalog_csv -v python tools\import_thirdparty_catalog_csv.py "D:\chengma\全部店铺拼多多商品规范CSV" --base-url http://localhost:8080 --dry-run ``` 预期：预检仅输出统计和报告，不写数据库；正式导入须在预检结果确认后单独执行。

ila referenced this issue

2026-08-24 11:29:17 +08:00

Admin:???? CSV ??? SKU ??????? #282

ila commented

2026-08-24 11:43:20 +08:00

实施完成，待生产预检与验收

实现提交：fe64d3b
归档提交：efad2ea，归档 docs/task/281-第三方规范csv预检与安全入库.md
新增 dry_run=true 的只读数据库预检：不写商品表、不写 catalog_import_runs，返回关联冲突。
收紧 fill_missing：已有蝦皮标题/主货号、SKU 非空规格、PDD URL/标题/店铺、已采集 PDD 数据均不覆盖。
20 个 CSV 已实际预组装为 212 批；最大 500 商品实体、5,000 SKU、1,142,989 字节，符合接口限制。
Go 1.23 全量 go build ./...; go test ./... -count=1 通过，Python 工具语法检查通过。

尚未部署新版 Admin，因此还没有对生产 MySQL 调用真实 --dry-run，更没有执行 --apply。部署后先运行预检、审阅报告，再由项目负责人确认是否写入。

## 实施完成，待生产预检与验收 - 实现提交：`fe64d3b` - 归档提交：`efad2ea`，归档 `docs/task/281-第三方规范csv预检与安全入库.md` - 新增 `dry_run=true` 的只读数据库预检：不写商品表、不写 `catalog_import_runs`，返回关联冲突。 - 收紧 `fill_missing`：已有蝦皮标题/主货号、SKU 非空规格、PDD URL/标题/店铺、已采集 PDD 数据均不覆盖。 - 20 个 CSV 已实际预组装为 212 批；最大 500 商品实体、5,000 SKU、1,142,989 字节，符合接口限制。 - Go 1.23 全量 `go build ./...; go test ./... -count=1` 通过，Python 工具语法检查通过。尚未部署新版 Admin，因此还没有对生产 MySQL 调用真实 `--dry-run`，更没有执行 `--apply`。部署后先运行预检、审阅报告，再由项目负责人确认是否写入。

ila commented

2026-08-24 11:43:21 +08:00

生产导入已完成：先完成 212/212 批只读预检，再完成 212/212 批正式入库。为保留人工既有关系，跳过 8 条来源关联（其中 1 条目标 PDD 已软删除，未自动恢复）。正式结果：蝦皮商品新建 17,792、更新 983；SKU 新建 1,048,143、跳过 1,066；PDD 新建 6,553、更新 3,925；关联新建 18,709、不变 9。进度报告保存在本机导入目录；线上 cmautobuy-admin 服务为 active。未写入凭据或完整请求体。

ila referenced this issue

2026-08-24 11:43:22 +08:00

Admin:???? CSV ??? SKU ??????? #282

ila referenced this issue

2026-08-24 15:18:43 +08:00

[Epic] Admin 采集采购管理端 #14

ila referenced this issue

2026-08-24 17:37:35 +08:00

[MVP] Admin 四模块可用闭环 #15

Sign in to join this conversation.