55 lines
3.2 KiB
Markdown
55 lines
3.2 KiB
Markdown
# 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)
|