cmautobuy/docs/task/234-档口入库码安全回写.md

234 Admin：档口入库码安全回写、核验与异常恢复

• 类型：需求
• 父级大工单：#14
• 所属 MVP / 版本：#224
• 状态：已完成
• 日期：2026-08-15
• Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/234

背景与目标

在操作员明确勾选并二次确认后，把档口入库码安全写入顺运宝商品明细的 innerExpCode，并对删除旧值、网络未知结果和 Admin 中断提供保守恢复路径。

最终方案

• syb.Client 增加清除旧值和写入新值两个封装；参数先在本地校验，每个动作只发送一次。 网络错误、5xx、响应读取失败或成功响应损坏统一标识为“写入结果未知”。
• 每条记录先用数据库条件状态从 ready 原子领取为 applying，然后重新读取远端并核对 stock/detail、规格、sku、variationSku、采购字段和规划旧值。任一变化都停止写入。
• 旧值为空时直接写；旧值非空时删除明确成功才写。写入成功响应后再次读取，只有远端值 与目标一致才标为已回写；未知或不一致进入需核对，绝不自动重试。
• “重新核对”只读取 listByStock。远端已是目标值时收敛为已回写，否则继续需核对。
• Admin 启动时把遗留 applying 改为 needs_check，不会在启动过程中发送远端请求。

改了哪些

• admin/syb/client.go：增加单次删除/写入接口和未知结果错误分类。
• admin/repository/inner_code.go：增加领取、完成、只读核对和启动恢复。
• admin/service/inner_code_apply.go：增加写前门禁、删后写、写后核验和批量统计。
• admin/handler/web/inner_code.go、admin/handler/web/web.go：接通回写和重新核对 POST。
• admin/main.go：启动时收敛中断记录。
• admin/syb/client_test.go、admin/service/inner_code_apply_test.go、 admin/repository/inner_code_test.go：覆盖单次请求、安全门禁和恢复。
• admin/repository/mysql_db_integration_test.go：增加 v22→v23 隔离 MySQL 测试。
• docs/admin/08-顺运宝接口.md：记录两个写接口和禁止重试规则。

验收结果

验收标准	结果
非 ready 或重复领取记录不发送写请求	通过（条件领取实现）
写前重新核对商品身份、采购字段和旧值	通过
空旧值不删；非空旧值删除成功才写；每个动作一次	通过
写后复读一致才完成，未知结果不自动重试	通过
重新核对只有读取，没有写入	通过
重启把 applying 转为 needs_check	通过

测试

• 执行的命令：go test ./syb ./service ./repository ./handler/web -run InnerCode -count=1； 固定 GOTOOLCHAIN=go1.23.0 执行 go build ./...、go test ./... -count=1、 go vet ./...；git diff --check。
• 结果：全部通过。假服务端验证了请求路径、参数、单次发送、业务失败和未知结果分类。
• 没验证到的部分：没有执行真实顺运宝删除/写入；没有提供 _test MySQL 8.4 配置， 因此新增的 v22→v23 集成测试已编译但按环境门禁跳过；未测试进程恰好在远端写入瞬间被强杀。

相关提交

• 2778eed feat: 安全回写档口入库码并支持核验恢复 (#234)