From 4d6ee8c86d3e01af9c37c0a2f623c5e956983571 Mon Sep 17 00:00:00 2001 From: chengma Date: Fri, 14 Aug 2026 17:12:17 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BD=92=E6=A1=A3=E4=BB=BB=E5=8A=A1=20?= =?UTF-8?q?#227?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/task/227-确认回填PDD规格可用于采购.md | 74 ++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 docs/task/227-确认回填PDD规格可用于采购.md diff --git a/docs/task/227-确认回填PDD规格可用于采购.md b/docs/task/227-确认回填PDD规格可用于采购.md new file mode 100644 index 0000000..793a574 --- /dev/null +++ b/docs/task/227-确认回填PDD规格可用于采购.md @@ -0,0 +1,74 @@ +# 227 Admin：确认三个 Excel 回填 PDD 规格可用于采购 + +- 类型：缺陷 +- 父级大工单：#14 +- 所属 MVP / 版本：#15 / Admin 四模块可用闭环后续数据修复 +- 状态：已完成 +- 日期：2026-08-14 +- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/227 + +## 背景与目标 + +#226 为三个已处理 Excel 对应的 PDD 规格回填了正式价格并把商品标记为已采集，但规格骨架仍保留 `available=null` 和 `availability_status=unknown`。PDD 详情能够展示规格，SYB 采购流程却只接收 `available=true` 的 SKU，因此无法显示可购买组合、保存规格映射或创建采购任务。 + +用户确认这批商品不再通过 Client 采集，三个固定 Excel 中规格完整且已有正式正价格的 `shopee_backfill` 数据可以作为采购候选。本任务确认其可售状态，使采购员能够继续人工核对和保存规格映射；不自动创建采购任务、下单或付款。 + +## 最终方案 + +- 新增一次性命令 `confirm-backfilled-pdd-availability`，复用 #226 的三个固定文件白名单、`qwg8fkb044` 店铺和 Excel 中的 PDD 集合。 +- 整件商品必须同时满足：未删除、状态为已采集、`spec_source=shopee_backfill`、SKU 非空、所有选项完整、所有正式价格大于 0、所有 `available` 为空且 `availability_status=unknown`。 +- 满足条件时给该商品全部 SKU 写入 `available=true` 并删除过期的 `availability_status`；价格、规格、列表价、库存、采集状态、采集时间和关联保持不变。 +- 任一 SKU 已有真实 `available=true/false`，或者存在异常 JSON、空规格、非正价格、来源和状态不符时整件跳过，不进行半修复。 +- 工具默认 dry-run；apply 前写出权限为 `0600` 的逐商品原值备份，应用时使用单事务以及原 `skus_json/collect_status/updated_at` 乐观锁，任一冲突整批回滚。 +- 生产执行前另存完整 MySQL 业务库备份；应用后再次 dry-run 并核对目标商品、全量候选、任务和映射均符合预期。 + +## 改了哪些 + +- `admin/cmd/confirm-backfilled-pdd-availability/main.go`：新增固定范围、默认预演、显式应用、备份和汇总的一次性命令。 +- `admin/service/xlsx_availability_confirmation.go`：新增候选判定、JSON 安全转换和整批事务应用逻辑。 +- `admin/repository/availability_confirmation.go`：新增仅替换规格 JSON、带原值乐观锁的更新。 +- `admin/service/xlsx_availability_confirmation_test.go`：覆盖候选确认、字段保留、异常整件跳过和事务回滚。 + +## 验收结果 + +| 验收标准 | 结果 | +|---|---| +| 只处理三个固定 Excel、`qwg8fkb044` 和对应 PDD 集合 | 通过 | +| 只确认完整、正价格、可售状态未知的 `shopee_backfill` SKU | 通过 | +| 已有真实可售值、异常数据、非目标来源和非目标状态不被修改 | 通过 | +| 价格、规格、列表价、库存、关联和采集状态保持不变 | 通过 | +| dry-run 不写库，备份权限为 0600，事务冲突整批回滚 | 通过 | +| 生产更新数与 dry-run 一致，更新后候选为 0 | 通过 | +| 示例 PDD 的 8 个规格均成为 SYB 可购买候选 | 通过 | +| 未自动创建规格映射、采购任务、订单或付款 | 通过 | + +生产执行结果： + +- dry-run 命中 1,735 个 PDD 商品、27,537 个 SKU；6 个非 `shopee_backfill` 商品和 142 个非已采集商品被跳过。 +- apply 实际更新 1,735 个 PDD 商品、27,537 个 SKU；再次 dry-run 候选为 0。 +- 去重核对结果为 1,735 个 PDD、27,537 个 SKU：27,537 个均为 `available=true`、价格非空，`available` 空值和 `availability_status` 残留均为 0。 +- PDD `934053028134` 保持 `collected`，8 个 SKU 均为 `available=true`，规格非空，价格均为 6120 分。 +- SYB 订单 `2608139P0EJWFD` 当前仍没有规格映射，也没有采购或采集任务；数据修复没有绕过采购员保存映射的正常步骤。 +- 完整业务库备份：`/opt/cmautobuy/backups/autobuy-before-227-20260814T090931Z-notablespaces.sql.gz`，大小 4,677,638 字节，权限 `0600`，gzip 完整性检查通过，共含 30 个建表段。 +- 逐商品回退备份：`/tmp/cmautobuy_xlsx_availability_backup_484364457.json`，1,735 项，大小 6,180,927 字节，权限 `0600`。 +- 服务器临时 Excel 副本已删除；一次性程序保留在 `/opt/cmautobuy/maintenance/227-abc37db/`，权限 `0700`。 + +## 测试 + +- 执行的命令： + - `GOTOOLCHAIN=go1.23.0 go test ./... -count=1` + - `GOTOOLCHAIN=go1.23.0 go vet ./...` + - 固定 Go 1.23、Linux amd64、`CGO_ENABLED=0` 构建一次性命令 + - 生产 dry-run、完整备份、apply、再次 dry-run + - 只读 SQL 核对去重商品数、SKU 数、可售值、未知标记、价格、规格、目标订单映射和任务数量 + - 检查 `cmautobuy-admin` 服务状态和本机登录页 HTTP 状态 +- 结果：全部自动化测试、静态检查、构建和生产数据核对通过；Admin 服务保持运行，登录页返回 HTTP 200。 +- **没验证到的部分**：未使用登录后的浏览器人工打开 SYB 详情；采购员尚未为示例订单保存规格映射，未创建真实采购任务，也未执行 Client 真机下单或付款。 + +## 遗留问题 + +采购员需要刷新 SYB 页面，在订单 `2608139P0EJWFD` 详情中核对并保存目标 PDD 规格映射，之后才能创建采购任务。Client 执行时仍须按现有门禁核对真实 PDD 商品、规格、数量和价格。 + +## 相关提交 + +- `abc37db` fix: 确认回填PDD规格可用于采购 (#227)