docs: 归档任务 #250

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)