diff --git a/docs/task/69-admin可复用规格映射与采购任务创建.md b/docs/task/69-admin可复用规格映射与采购任务创建.md new file mode 100644 index 0000000..aa1cecb --- /dev/null +++ b/docs/task/69-admin可复用规格映射与采购任务创建.md @@ -0,0 +1,64 @@ +# 69 Admin:实现可复用规格映射与采购任务创建 + +- 类型:需求 +- 父级大工单:#14 +- 所属 MVP / 版本:#15 Admin 四模块可用闭环 +- 状态:已完成 +- 日期:2026-08-09 +- Gitea 工单: + +## 背景与目标 + +顺运宝规格匹配和创建采购任务原先仍是 501 骨架。此次完成从动态 PDD 规格选择、可复用映射,到人工确认人民币价格上限并创建指定客户端采购任务的安全闭环。 + +## 最终方案 + +- 从 PDD `skus_json.dimensions` 动态生成规格组合,不写死颜色和尺码;不可购买组合不进入候选。 +- 映射以 `(shopee_sku_id, pdd_goods_id)` 为唯一范围保存,打开相同上下文时自动带出。 +- 每次显示和建任务前重新确认 option key 仍存在于最新采集结果;PDD 换品或选项消失会回到待匹配。 +- 顺运宝阶段增加规格待匹配、可创建采购任务、采购数据异常和已创建任务。 +- 采购确认弹窗只接受可采购行,要求选择当前账号可见客户端,并逐行确认人民币价格上限。 +- 服务端在事务中重新校验蝦皮 SKU、当前 PDD、采集结果、有效映射、数量、人民币价格、客户端范围和重复任务。 +- 业务失败按明细返回原因,合法行仍可创建;数据库错误整批回滚。 +- 采购任务以 `assigned` 状态写给指定客户端,同一明细已有 `pending` / `assigned` / `claimed` 采购任务时拒绝重复创建。 + +真实下单开关未改,仍默认关闭;没有增加 Client 接口,也没有触发采集、采购或付款。 + +## 改了哪些文件 + +- `admin/repository/mapping.go`:增加映射读取和 upsert。 +- `admin/repository/syb.go`:采购上下文联查当前映射、PDD 采集数据和进行中任务。 +- `admin/repository/task.go`、`admin/repository/client.go`:增加重复任务检查、采购任务插入和客户端范围校验。 +- `admin/service/purchase_workflow.go`:动态规格、映射有效性、人民币金额解析及采购任务安全校验。 +- `admin/service/syb.go`:完善处理阶段、映射详情、可采购判断和默认 PDD 价格。 +- `admin/handler/web/others.go`:实现规格映射和批量创建采购任务处理。 +- `admin/templates/syb/`、`admin/static/js/app.js`、`admin/static/css/app.css`:增加动态映射控件和采购确认弹窗。 +- `admin/service/purchase_workflow_test.go`:覆盖动态维度、映射复用、换品隔离、失效选项、权限、价格、部分失败和重复提交。 +- Admin 需求、数据、接口、UI 和质量文档:记录稳定规则与兼容边界。 + +## 验收结果 + +| 验收标准 | 结果 | +|---|---| +| PDD 规格按 dimensions 动态渲染 | 通过 | +| 相同蝦皮 SKU + 当前 PDD 商品自动复用映射 | 通过 | +| 换品或选项消失不复用旧映射 | 通过 | +| 只有安全条件满足的行可在页面勾选创建 | 通过 | +| 必须选择可见客户端并逐行填写人民币价格上限 | 通过 | +| 校验失败逐条说明,重复提交不建重复进行中任务 | 通过 | +| 创建任务满足现有 Client 领取契约 | 通过 | +| 顺运宝台币售价不写入人民币价格上限 | 通过 | +| 真实下单默认关闭,未修改 Client 四接口 | 通过 | +| Go 1.23.0 build、test、vet 与 Client 契约测试通过 | 通过 | + +## 测试 + +- 从 `admin/` 执行:`node --check static/js/app.js`、Go 1.23.0 的 `go build ./...`、`go test ./... -count=1`、`go vet ./...`。 +- 从仓库根目录执行:`git diff --check -- admin docs/admin`。 +- 从 `client/` 执行:`C:/Python310/python.exe -m unittest discover -s test -p "test_admin_gateway_contract.py"`(13 项通过)和 `C:/Python310/python.exe -m unittest discover -s test -p "test_http_admin_gateway.py"`(12 项通过)。 +- 首次尝试用模块名运行 Client 测试时,因为 `test/` 不是 Python package 而导入失败;改用项目实际支持的 `unittest discover` 后全部通过,代码无需修改。 +- **未验证到的部分**:未在真实浏览器人工检查采购确认弹窗;未让真实 Client 领取本次页面创建的任务;未连接真实设备,未执行任何采集、采购、下单或付款。 + +## 相关提交 + +- `4433e3a` 完成可复用规格映射与采购任务创建