From 103610a0121f2105138a3e817c5fe1f44843b9a2 Mon Sep 17 00:00:00 2001 From: chengma Date: Tue, 18 Aug 2026 15:19:10 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BD=92=E6=A1=A3=E4=BB=BB=E5=8A=A1=20?= =?UTF-8?q?#250?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/task/250-多件档口入库码逐件回写.md | 54 +++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 docs/task/250-多件档口入库码逐件回写.md diff --git a/docs/task/250-多件档口入库码逐件回写.md b/docs/task/250-多件档口入库码逐件回写.md new file mode 100644 index 0000000..141ecb9 --- /dev/null +++ b/docs/task/250-多件档口入库码逐件回写.md @@ -0,0 +1,54 @@ +# 250 Admin：多件档口入库码按件创建顺运宝明细回写 + +- 类型：缺陷 +- 父级大工单：#14 +- 所属 MVP / 版本：#224 / 档口入库码回写 MVP +- 状态：已完成 +- 日期：2026-08-18 +- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/250 + +## 背景与目标 + +顺运宝不接受把同一商品的多个档口入库码用逗号写进一个“快递单号”。本次保留本地单表和聚合值，将真实远端操作改成“一码一明细”，并保证未知结果不会自动重试。 + +## 最终方案 + +- MySQL v27 在原业务表追加 `remote_items_json`，保存逐件明细 ID、来源和动作状态。 +- 回写和匹配阶段都校验单件码数量、Excel 源行数及顺运宝商品数量。 +- 原明细写一个码，额外码通过 HAR 确认的 `createDetail` POST 契约创建数量 1、价格 0 的稳定标题占位明细。 +- `updateDetailCode` 改为 POST，并携带当前毫秒时间戳。每个写动作只发一次并在成功后复读整张货运单。 +- 已存在的目标码和中断遗留的稳定标题占位明细直接复用。创建或写码结果未知时停止并转为“需核对”；重新核对只读，不重发远端请求。 +- 页面确认信息展示记录数、单件码总数和预计最多新增的明细数，逐条结果显示完成进度。 + +## 改了哪些 + +- `admin/repository/mysql_db.go`：增加 MySQL v27 迁移和 JSON 列结构自检。 +- `admin/model/inner_code.go`、`admin/repository/inner_code.go`：读写逐件检查点并在重新规划时安全清理旧检查点。 +- `admin/syb/client.go`：增加零价明细创建接口，修正写码请求方法和时间戳。 +- `admin/service/inner_code_apply.go`：实现逐件规划、复用、创建、写入、复读、未知结果门禁和只读核对。 +- `admin/service/inner_code_match.go`：增加三方数量一致门禁和整单已有目标码判断。 +- `admin/templates/inner_code/list.html`、`admin/static/js/app.js`：补充逐件回写确认统计。 +- `docs/admin/03-data-model.md`、`docs/admin/08-顺运宝接口.md`：记录 v27 和真实接口契约。 + +## 验收结果 + +| 验收标准 | 结果 | +|---|---| +| 单件继续使用原明细并复读确认 | 通过 | +| 两件、三件按一码一明细创建零价占位明细 | 通过 | +| 已有人工目标码及中断占位明细不重复创建 | 通过 | +| 码数、源行数或商品数量不一致时零写入 | 通过 | +| 创建和写码使用 HAR 确认的 POST 契约且不自动重试 | 通过 | +| 未知结果保存进度并进入需核对，重新核对只读 | 通过 | +| MySQL v27 追加字段且启动自检 | 通过 | +| 页面显示单件码数量和预计新增明细数 | 通过 | + +## 测试 + +- 执行的命令：`go test ./service ./repository ./syb ./handler/web -run InnerCode -count=1`、`go test ./... -count=1`、`go build ./...`、`go vet ./...`、`git diff --check`（Go 1.23.0）。 +- 结果：全部通过。 +- **没验证到的部分**：未对生产顺运宝真实货运单执行新增明细；未在本机连接生产 MySQL 执行 v27，迁移由自动化测试、编译和结构自检代码覆盖。 + +## 相关提交 + +- `b8f49fe` fix: 多件档口入库码逐件回写 (#250)