cmautobuy/docs/task/235-档口入库码支持部分匹配.md

235 Admin：档口入库码支持勾选部分记录匹配

• 类型：需求
• 父级大工单：#14
• 所属 MVP / 版本：#224
• 状态：已完成
• 日期：2026-08-15
• Gitea 工单：#235

背景与目标

档口入库码导入后，原“匹配顺运宝商品”会处理业务日期下的全部可重匹配记录，列表复选框只能选择可回写记录。采购员无法先勾选部分导入数据进行匹配，而且页面筛选条件不会限制实际匹配范围。

本任务把匹配范围改为当前页明确勾选的记录，不再提供或隐式执行“匹配全部”，同时保证分批处理同一订单时不会重复占用顺运宝商品明细。

最终方案

• 复选框按动作声明能力：pending、ready、skipped、failed 可用于匹配，只有 ready 可用于回写。
• 匹配按钮改为“匹配已选 N 条”，没有可匹配选中项时禁用；表头全选只处理当前页。
• 浏览器提交匹配或回写前，分别复制当前动作可处理的选中 ID，避免混合勾选时把待匹配记录提交给回写接口。
• 服务端校验选中 ID、业务日期、状态和单页最多 20 条；空选择不会连接顺运宝或执行匹配。
• 匹配只保存选中记录，但会读取同日同订单其他记录，预留其处于可回写、回写中、已回写、已存在或需核对状态时占用的 detail_id。
• 保存计划时按业务日期和订单号排序加行锁，再次核对未选记录的明细占用；并发部分匹配发生冲突时整体回滚，不覆盖已有规划。
• 未修改数据库结构、顺运宝写接口和安全回写流程。

改了哪些

• admin/templates/inner_code/list.html：增加按动作选择属性和“匹配已选 N 条”交互。
• admin/static/js/app.js：分别统计并提交匹配、回写动作可处理的选中 ID。
• admin/handler/web/inner_code.go：解析、去重和限制选中 ID，空选择直接返回。
• admin/service/inner_code_page.go：页面行分别暴露可匹配、可回写能力。
• admin/service/inner_code_match.go：只规划选中记录，并预留同订单其他记录的明细占用。
• admin/repository/inner_code.go：按 ID 查询目标、加载同订单上下文，并在保存时锁定和复核占用。
• admin/handler/web/inner_code_test.go、admin/service/inner_code_match_test.go、admin/service/inner_code_page_test.go、admin/inner_code_template_test.go：补充选中 ID、状态能力、占用保护和模板提交测试。

验收结果

验收标准	结果
允许勾选待匹配、可回写、已跳过、失败记录用于匹配	通过
“匹配已选 N 条”准确计数，空选择不执行匹配	通过
表头全选仅选择当前页，不存在匹配全部入口	通过
服务端只保存选中记录，状态变化时整体拒绝保存	通过
同订单分批匹配保留未选记录的明细占用	通过
回写只提交已选且可回写的记录，既有安全门禁不变	通过
固定 Go 1.23.0 构建、测试和静态检查通过	通过

测试

• 执行的命令：
  • go test ./service ./handler/web ./repository . -count=1
  • go test ./... -count=1
  • $env:GOTOOLCHAIN="go1.23.0"; go build ./...; go test ./... -count=1; go vet ./...
  • git diff --check
• 结果：全部通过。
• 没验证到的部分：未连接真实顺运宝执行选择记录匹配；未在真实 MySQL 8.4 上并发提交两个交叉订单集合；未进行浏览器 1366×768 人工视觉验收。任务无数据库迁移，未执行迁移测试。

相关提交

• 63f8407 feat: 支持勾选部分档口入库码匹配 (#235)