fix: 多件档口入库码逐件回写 (#250)

docs/admin/08-顺运宝接口.md

@@ -410,21 +410,30 @@ SKU（平均每商品 1.17 个），**查无此 SKU 是常态**，不是异常
 `[建议]` 登录后**只调 `/am/user/get` 验证会话**，其余几个是网页自己的初始化请求，
 Go 侧不用跟着调。
 
-### 7.1 档口入库码写入（工单 #234）
+### 7.1 档口入库码逐件写入（工单 #234、#250）
 
-档口入库码最终写入货运明细的 `innerExpCode`（页面名称“快递单号”）。两个写接口来自
-现有 Python 流程和线上响应样本：
+档口入库码最终写入货运明细的 `innerExpCode`（页面名称“快递单号”）。接口来自
+现有 Python 流程和 HAR 响应样本：
 
 ```text
 GET /am/stock/detail/deleteInnerCode?detailId={detailID}
-GET /am/stock/detail/updateDetailCode?t=0&id={stockID}&detailId={detailID}&code={innerCode}
+POST /am/stock/detail/createDetail
+POST /am/stock/detail/updateDetailCode?t={当前毫秒时间戳}&id={stockID}&detailId={detailID}&code={单件innerCode}
 ```
 
-- 旧值为空时不调用删除；旧值非空时，只有删除明确成功才发送写入。
+`createDetail` 使用 JSON 请求体：`id=null`、稳定占位标题、`productSpec=null`、
+`productQty=1`、`productPrice=0`、`stockId`；成功响应的 `data` 是新 `detailId`。
+
+- 回写前必须同时核对目标码数量、Excel 合并源行数和原商品 `productQty`；任一不一致时
+  零写入。一个远端明细只写一个单件码，原明细为空时承载第一个缺失码，其余缺失码创建
+  零价占位明细。
+- 同一货运单任意明细已有目标码时直接复用，不删除、不搬移。稳定占位标题可用于识别
+  “已创建但检查点未保存”的明细，防止崩溃后重复创建。
+- 规划时的旧值为空时不调用删除；旧值非空且仍与规划快照一致时，只有删除明确成功才继续。
 - 删除和写入请求都只允许发送一次，不使用自动重试。超时、5xx、响应读取失败或成功响应
   无法解析时，结果可能已经在远端生效，必须标为“需核对”。
-- 每条写入前重新调用 `listByStock`，核对 stock/detail、规格、采购平台、采购单号和规划时
-  的旧值；写入后再次读取，只有 `innerExpCode` 与目标一致才标为已回写。
+- 每件动作前后把检查点写入 `remote_items_json`；每个单件码写入后重新读取整张货运单，
+  只有它唯一出现在预期明细中才继续。全部目标码确认后才标为已回写。
 - “重新核对”只调用 `listByStock`，绝不能再次调用上述两个写接口。
 - 页面提交数量不限制为 20 条。所选记录先在 MySQL 同一业务表中进入 `queued`，HTTP 请求
   随即返回；后台每次最多读取 20 条，再逐条执行上述远端门禁。Admin 重启不会自动继续