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

docs/admin/03-data-model.md

@@ -129,6 +129,8 @@ v19（#212）将产品概念收敛为唯一店铺名称和唯一启停状态。
 则保持停用”的安全规则合并 v18 状态，重建由 `shops` 派生的兼容数据和两侧关联。
 v26（#254）新增 `purchase_spec_resolutions`，用一张表保存采购执行中的候选观察、
 幂等身份和最终规格决策；不修改历史 SQLite migration，也不覆盖 PDD 商品主数据。
+v27（#250）为 `syb_inner_code_records` 增加可空 JSON 字段 `remote_items_json`，保存
+多件商品逐个入库码对应的远端明细、来源和动作状态；仍不拆分新的业务表。
 
 **v3 为什么丢弃旧 `sku_mappings` 数据（见 #20）：** 新主键需要 `pdd_option_key`，
 这是 Go 的 `service.OptionKey()` 用 `json.Marshal` 算出来的规范化键，SQL 语句
@@ -1025,7 +1027,7 @@ CREATE UNIQUE INDEX idx_client_assignment_current
 `ai_spec_match_decisions`。Admin 重启把未完成明细改为 `interrupted` 并完成批次计数，已经
 成功写入的 `spec_mappings` 不回滚。
 
-## 17. `syb_inner_code_records` 档口入库码记录（MySQL v23，软删除 v24，后台回写 v25）
+## 17. `syb_inner_code_records` 档口入库码记录（MySQL v23，软删除 v24，后台回写 v25，逐件检查点 v27）
 
 档口入库码使用一张业务表完成导入、匹配、回写和异常恢复。Excel 只是导入载体，系统
 不保存原文件、文件哈希，不再拆批次表或尝试记录表。
@@ -1055,6 +1057,10 @@ CREATE UNIQUE INDEX idx_client_assignment_current
   不新增批次表：提交时所选 `ready` 记录必须在同一事务内全部转为 `queued`；后台每次最多
   读取 20 条并逐条领取为 `applying`。页面按 `apply_batch_id` 聚合当前批次进度。Admin
   重启时，`queued` 恢复为 `ready` 且不会自动写远端，`applying` 转为 `needs_check`。
+- v27 增加 `remote_items_json`。`inner_code` 继续保留英文逗号连接的本地聚合值，但远端
+  不再接收聚合字符串：原商品明细承载一个码，额外单件使用数量 1、价格 0 的占位明细。
+  JSON 数组按单件码保存 `detail_id/source/title/status` 检查点；新增或写入结果未知时立即
+  转为 `needs_check`，重启后只读扫描整张货运单，不自动重发请求。
 
 ## 18. `purchase_spec_resolutions` 采购运行时规格解析（MySQL v26）
 

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 重启不会自动继续