cmautobuy/docs/task/250-多件档口入库码逐件回写.md

250 Admin：多件档口入库码按件创建顺运宝明细回写

• 类型：缺陷
• 父级大工单：#14
• 所属 MVP / 版本：#224 / 档口入库码回写 MVP
• 状态：已完成
• 日期：2026-08-18
• Gitea 工单：#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)