海外仓业务/海外仓PDA拆柜收货改造方案评审稿.md

@@ -1,6 +1,6 @@
 # 海外仓 PDA 拆柜收货设计复核：现场效率优先
 
-日期：2026-09-10。状态：业务设计评审稿，仅修改本文档，尚未实施业务代码。
+日期：2026-09-10。状态：业务设计评审定稿，可进入技术设计与开发；仅修改本文档，尚未实施业务代码。
 
 本稿根据用户确认的真实操作及合并后的工作区代码复核，修正前序讨论中的不合理设计。后端读取基于 `5ffd6c01`，海外 PDA 基于 `cb1dfc5`；工作区同时存在其他未提交修改。代码引用证明检查时的实现，不代表测试环境已部署或真机已验收。
 
@@ -9,13 +9,14 @@
 用户已确认：
 
 - 一件代发在国内打好托；一个实物托盘只贴一个统一 DP 托盘码，每箱各有箱码。扫 DP 或托盘内任一箱码，都必须带出整个托盘，按整托收货。
+- DP 仅用于一件代发。普通 FBA 不使用 DP，继续使用现有的“柜号-FBA 仓编码-三位序号”托盘码。
 - 同一个托盘允许包含多个客户的货。客户归属由后台处理，不能成为仓库扫码或混托的操作障碍。
 - 普通 FBA 国内散货装柜，海外拆柜时按 FBA 目的仓打托。扫某一箱，带出当前柜该 FBA 的总箱数及全部相关入仓码；之后连续扫托盘，录入各托箱数。
 - 一件代发、普通 FBA、海外仓中转均不展示客户名称、编号、客户数，不提供客户选择或绑定操作。
 - 少货、超收暂时只记录差异，不建设完整异常处理流程。
 - 一台 PDA 操作。当前任务是 review 和编写设计，不改业务代码。
 
-评审结论：主方向可行，正常路径应收敛为“一件代发一次扫码收一托；FBA 一次扫箱选组，每托扫码加数量回车”。实现前必须处理跨客户托盘的下游约束，并明确 FBA 数量分摊的事实边界。以下推荐项尚未等同于用户逐项确认。
+评审结论：主方向可行，正常路径冻结为“一件代发一次扫码收一托；FBA 一次扫箱选组，每托扫码加数量回车”。开发必须同时处理跨客户托盘的下游约束，并遵守 FBA 组级数量记录的事实边界。本文“推荐”均指评审确定的实现建议；若开发发现必须改变现场操作或业务结果，应先回到业务评审，不能自行增加仓库步骤。
 
 | 前序方案中的问题 | 本次推荐修正 | 对现场效率的作用 |
 |---|---|---|
@@ -24,7 +25,7 @@
 | 每次提交清空当前入仓码/目的仓，再扫箱重新定位 | 持续保留 FBA 目的仓组，下一托直接扫码 | 同一 FBA 只需首次扫箱 |
 | 整柜扫描结果只存在设备，最后统一保存 | 每笔在服务端保存收货事实，整柜结束时统一完成入库 | 退出、重试不必重新扫描整柜 |
 | 自动分摊视作准确箱货位置，少货默认落最后一票 | 标明计划分摊；未知差异保留在目的仓组 | 避免把后续找货错误归咎于仓库 |
-| DP 被定义为柜级对象，混托要求改整套客户事件 | DP 独立存在，封托后整托分柜；先定义清单完整性再选事件方案 | 国内打托不必等分柜，减少改造范围 |
+| DP 被定义为柜级对象，混托要求改整套客户事件 | DP 独立存在，封托后整托分柜；现有客户事件分片共同携带整托完整性依据 | 国内打托不必等分柜，减少改造范围 |
 
 ## 2. 推荐现场流程
 
@@ -49,7 +50,7 @@
 - 同一 DP 的多个箱码连续被扫，或 DP 与箱码交替扫描，都只产生一次有效整托实收。重复扫描提示“已收”，不弹阻塞对话框，不重复入账，也不把重复当作撤销。
 - 成功后记录保存到服务端；“撤销最近一托/调整记录”是独立低频动作，整柜完成前允许，必须有反向记录和汇总更新。仅删除页面记录不算撤销。
 - 扫码确认的是“按国内清单整托接收”，不能声称已在海外逐箱验货。发现破托、少箱时，选该托标记差异；只知道少几箱时不猜具体 SKU/客户。
-- 国内已确认 DP 对应实物且清单完整时，海外资源由后台建立关联。正常路径不要求重新贴另一张业务托盘码或再扫一个海外码；若实际换托，则记录显式换托关系。
+- 国内已确认 DP 对应实物且清单完整时，海外资源由后台建立关联。一个有效来源 DP 在当前接柜仓只映射一个公共物理托盘占用，多个客户计划共同引用该映射；收货、盘点、移库都可用 DP 定位。正常路径不要求重新贴另一张业务托盘码或再扫一个海外码。若实际换托，则新建有效映射并保留原 DP 清单和换托关系，不能覆盖国内封托快照。
 
 ### 2.3 普通 FBA：一箱选组，每托扫码加箱数
 
@@ -68,7 +69,7 @@
 - 数量字段明确为“本托累计实收箱数”。再次扫已收托盘显示现有数量，修改后替换原总量并按差额更新，不把改成45误解成再增加45。
 - 保存后保留 FBA 组，清空当前托盘与数量。末托可预填剩余数，仍需回车确认，不能自动将计划剩余数算作实收。
 - 切换到另一 FBA 或 DP 前，如果当前托盘有未保存数量，先保留并处理该笔；不能静默清空或把数量提交到新组。
-- 沿用已生成的 FBA 托盘标签与后台资源准备。已有“柜号+FBA仓标识+序号”只表示标签/计划位置，不能宣称国内已形成实装托盘明细。跨入仓码混托不能受标签原先归属某客户/计划的限制。
+- 沿用已生成的 FBA 托盘标签与后台资源准备。普通 FBA 托盘码固定使用“柜号-FBA 仓编码-三位序号”，不使用 DP。该码在当前柜、当前 FBA 目的仓内唯一，只表示标签/计划位置，不能宣称国内已形成实装托盘明细。跨入仓码混托不能受标签原先归属某客户/计划的限制。
 - 计划托数用于资源和标签准备。100箱实际打3托，不因预生成4张标签而要求扫满4托。未用标签/预留资源由后台处理；需要额外托盘时提供一次补充动作，不重新给各入仓码建计划。
 
 ### 2.4 海外仓中转：先减少重复操作，再按交接粒度优化
@@ -92,7 +93,7 @@
 | FBA 完整组按计划确认 | 箱数相符，按来源清单接受该组 | 所有箱唛/SKU都经过现场验证 |
 | FBA 后台数量分摊 | 可审计的账务/计划分摊 | 扫某托就保证能取出某客户指定货物 |
 
-正常按目的仓统一交接可保持高速。后续按某客户、某入仓码、指定箱唛部分提货、扣货或换标时，必须读取这种精度差异：无法证明箱在哪托时，现场按所选箱码定位/拆托，并修订实际分配后出库。不能把推定分摊直接塞入现有精确拣货接口。若业务要求任意托盘都能准确按票出库，就必须增加按票/箱落托采集，不能同时声称“只录每托总数”且“精确到票”。
+正常按目的仓统一交接可保持高速。组级接收形成的 FBA 库存、排车和出库记录必须一直携带“组级/推定分配”精度，不能被现有精确拣货接口当作箱到托事实。整组同目的仓交接可以消费这类库存；后续按某客户、某入仓码、指定箱唛部分提货、扣货或换标时，必须先由现场扫描目标箱码或拆托，形成已确认的箱/明细落托记录，再扣减对应库存并修订实际分配。若业务要求任意托盘都能准确按票出库，就必须增加按票/箱落托采集，不能同时声称“只录每托总数”且“精确到票”。
 
 因此推荐将精准识别放在确实需要挑选具体货物的操作中；不要为所有正常 FBA 收货增加逐箱扫描。FBA 分组收货上线前，必须把此规则与现有排车/出库消费端一起落实。
 
@@ -100,22 +101,22 @@
 
 “只标记差异”不等于把计划数填成实收，也不等于责任已核清。
 
-- FBA 计划100实收97：保存本组实收97、少货3。无法定位缺少哪票时，差异留在本组，不默认记给最后一个入仓码。不能声称所有入仓码已精确核平。
+- FBA 计划100实收97：保存本组实收97、少货3。无法定位缺少哪票时，不仅少货3的归属未知，已收97的票/SKU组成也未经现场确认；因此该 FBA 组全部97箱保持“待核接收量”，不按排序、比例或 FIFO 转成任一客户可用库存。其他无差异的独立目的仓组可正常入账。若后续取得箱码或其他可靠明细，再按已确认事实核定可用库存。
 - FBA 计划100实收103：保存实物103及超出计划3；无归属的超出部分不得计入任意客户可用库存。不为了通过校验修改原计划100。
-- 一件代发整托未收到：清单能确定该 DP 的缺失成员，可按来源明细标记未到。一托内部少几箱但未知箱码时，仅确定托级差异，不能随机减 SKU。
+- 一件代发整托未收到：清单能确定该 DP 的缺失成员，可按来源明细标记未到。一托国内清单45箱、整托扫码后发现少3箱时，计划数仍为45，托级实际收货修正为42，差异为-3；若缺失箱码未知，该 DP 的全部42箱保持托级待核，不能激活完整45箱清单或随机减某个 SKU。若能识别具体缺箱，则其余42箱可按清单准确入账。
 - 收到不属于当前柜的已知托盘：先作为错柜码拦住正常收货，不能当本柜超收并自动转移其他柜货权。
 - 正常全部相符时，后台按来源清单完成各入仓码账；数量有差异且归属未知时，现场可结束，后台保留“差异待核”状态和相关已收事实。未核部分不凭自动分摊变成某客户可用货。
 
-推荐整柜结束只出现一次汇总确认，正常无差异直接完成；有差异时一并确认差异数量即可，不要求仓库填写逐客户归责或新建异常单。没有结清差异不应迫使唯一 PDA 一直锁在上一柜。
+推荐整柜结束只出现一次汇总确认，正常无差异直接完成；有差异时一并确认差异数量即可，不要求仓库填写逐客户归责或新建异常单。没有结清差异不应迫使唯一 PDA 一直锁在上一柜。带差异结束只释放当前收货作业会话；待核实收仍形成有效的物理托盘和库位占用，参与托盘非空、盘点和资源占用判断，不得释放、报废或分配给其他收货批次。
 
-实现必须区分“现场收货结束”和“账务核平/可用库存”。现有代码将完整入库、库存入账和柜级卸柜事件绑在一起，多层要求计划数等于实收数；不能只放开按钮。需定义正常完成、带差异结束的处理及完成事件真实含义：全柜实物已卸完才能形成卸柜完成事实，不能把差异结束自动解释为所有计划已足量入库。推荐现场结束、差异记录、可确认部分库存处理和对应 Outbox 在同一事务完成，不补造缺货库存；未知归属部分留在接收事实中待核。
+实现必须区分“现场收货结束”“计划已核平”和“库存可用”。现有代码将完整入库、库存入账和柜级卸柜事件绑在一起，多层要求计划数等于实收数；不能只放开按钮。全柜实物已卸完才能形成卸柜完成事实，但带差异结束不能解释为所有计划已足量入库。现场结束、差异记录、可确认库存处理、物理占用和对应 Outbox 应在同一事务中形成一致结果：正常组正常入账；组成明确的实收按事实入账；组成未知的受影响组或 DP 整体留在待核接收事实中，不补造缺货库存，也不靠算法挑选部分客户入账。
 
 ## 5. 托盘与跨区数据的最小改造原则
 
 1. **DP 先于柜存在。** 当前国内顺序是清点→绑托→封托→待分柜。DP 应是独立稳定托盘身份，箱明细持有客户/入仓码；分柜后建立装载关系。同一封托 DP 的成员原子分配到同一柜，不能把混托成员分别装不同柜。跨客户不必阻断，同一实际交接路径/业务约束仍由后台校验。
 2. **公共实物资源已有，不重复建设。** `warehouse-overseas-service` 的托盘/库位已经是平台公共资源。改造重点是一个实物托盘对应多客户货物组成、统一物理占用、各自库存记账。保留现有独立客户订单/计划，不为了隐藏客户把所有订单合并成一张公共订单。
 3. **客户隐藏在服务端。** PDA 专用响应省去客户名称/编号/客户数，写入只带扫码值、数量和必要业务凭证。实际仓来自登录身份与会话，客户由真实货物明细解析。内部事件与库存账仍保留客户，不删除安全隔离字段，不要求客户端传入客户。
-4. **不直接拍板新增柜级事件。** 当前装柜事件按客户拆分。可在新冻结契约中用共同 DP、清单版本/哈希、整托总量和预期分片标识，聚合各客户片段；也可采用一次完整公共交接清单。两者都必须证明组成已到齐、无重复、同版、同柜。先对比改造范围与完整性，再确定协议；不能仅对“当前已收到的片段”求和便开放整托收货。
+4. **跨区保留客户事件分片。** 当前装柜事件按客户拆分，本轮以最小改造保留该隔离方式；同一混客户 DP 的各分片引用同一 DP 清单版本、整托总量、内容哈希及预期组成标识。海外只有在预期组成集合全部到齐、无重复、同版、同柜且总量一致后才允许整托收货；同事件 ID/同哈希重放幂等，同版本异哈希或组成冲突必须拒绝并留待处理。本轮不并行引入第二套公共完整清单协议。
 5. **扫码不回国内查业务。** 海外用已验证的本地交接快照解析 DP/箱码与 FBA 组；缺快照是资料准备问题，不要求海外仓扫码补客户。保留现有网关实时身份校验，不为提速绕开鉴权。
 6. **FBA 标签预生成不等于物理货物预分配。** 资源可提前准备，但在海外实际录入各托箱数后才形成该组真实托数。不要再建设“普通 FBA 国内逐箱打托”来支持用户明确的国内散货流程。
 
@@ -126,12 +127,15 @@
 ## 6. 一台 PDA 的连续扫码设计
 
 - 单入口、顺序处理，扫码进入队列。不能像当前页面那样忙时直接丢弃输入。
+- 队列区分“待识别扫码”和“已冻结业务命令”。FBA 扫到托盘后形成不可被后续扫码替换的当前编辑项；等待输入数量时，后续扫码只能暂存，不切换目的仓、不替换当前托盘、不提交空数量。回车后把柜会话、FBA 组、托盘码、累计数量和操作意图冻结成一条命令，随后才处理下一码；服务端不得在执行时根据页面的当前选择重新推导归属。
 - 已保存成功才播放成功音；等待处理与保存成功分开显示。队列满或请求失败时明确暂停并保留输入，不悄悄吞码。
 - 每笔使用稳定幂等键；请求超时保留原键重试。应用退出后恢复未确认命令和服务端收货状态，不重复生成新命令。
 - DP/箱码两条入口还需按真实 DP 判断是否已收，不能只靠请求键去重；撤销后可重新收货，历史保留。
 - 收货请求直接返回本托结果、组进度和柜进度；正常每笔不再 POST 后立即全量 GET current。全量读取用于入页、恢复和冲突对账。
 - 网络不可用时显示待处理，不声称已入库。第一版只做可靠恢复，不额外建设完整离线作业、多人抢占和分布式协同平台。
+- 同一托盘存在结果未确定的命令时，后续修改或撤销必须先以原幂等键重试或对账。“首次收货”“设置累计数量”“撤销”是三个明确意图，各自使用稳定命令 ID；修改/撤销携带服务端返回的收货记录版本或操作序号，过期命令不能覆盖新事实。FBA 减少数量时同步撤回相关推定分配和汇总，不能只改页面总数。
 - 撤销/改数量优先服务“刚才扫错”的小范围操作。任何修正同步更新明细、SKU实收、托盘/组/柜汇总；柜已完成或货物已出库后走对应更正业务，不允许静默删记录。
+- 整柜结束前暂停接收新扫码，完成当前数量编辑，排空扫码队列，并确认不存在待对账或结果未知的命令；随后读取服务端最终摘要做一次汇总确认。每条命令绑定创建时的接柜会话标识，服务端验证一致，不能仅按请求到达时的 `current` 会话解释。应用重启先对账原柜未决命令，完成后不得把旧柜命令重放到新柜。
 
 ## 7. 当前代码事实与差距
 
@@ -153,7 +157,7 @@
 
 开发可按以下顺序推进，发布必须按完整业务能力交付：
 
-1. 先冻结扫码语义、FBA 分摊精度、差异结束规则和海外仓中转颗粒度；明确DP先封托再分柜。
+1. 按本文冻结扫码语义、FBA 组级分配精度、差异结束规则、普通 FBA 托盘码规则和海外仓中转颗粒度；明确 DP 先封托再分柜且仅用于一件代发。
 2. 补齐一件代发多成员托盘清单、箱码反查及跨区完整性；改好公共托盘占用/释放及相关出库约束。
 3. 实现 FBA 当前柜目的仓聚合、每托累计箱数、计划分摊标识及下游精度约束；复用现有标签和资源准备。
 4. PDA 接单入口持续扫码、数量回车、成功音、队列、防重、恢复、纠错及客户信息隐藏。当前一件代发已有整托服务可作为基础，不将单客户试用当作混客户需求完成。
@@ -167,6 +171,7 @@
 - FBA 三入仓码100箱，首次只扫一箱，随后3托录40/35/25；无重复扫入仓码、额外校验或封托按钮。
 - 同目的 FBA 的一件代发不能进入散货组；不同柜同FBA不能合并；未保存数量不能因换组丢失。
 - 重复扫描、数量从40改45、撤销后重收、超时重试、应用重启均无重复数量；快速扫码不静默丢失。
+- 扫 P1 后尚未输入数量又扫 P2：P1 编辑项不被覆盖，P2 仅暂存；输入40回车后P1正确保存，再进入P2。存在待编辑、排队或结果未知命令时不能完成整柜。
 - FBA计划4托实际3托可以结束，反向需要第4托时有可操作的资源补充路径。
 - 100/97、100/103、整托未到、托内少箱均保留真实差异；未知缺货不自动归责给最后一票，错柜货不自动转入。
 - 一客户出完，另一客户仍在同托，公共托盘及库位不被释放/报废；组级数量分摊不被当成指定箱唛位置。
@@ -174,9 +179,10 @@
 
 效率按交互次数验收：一件代发 N 托为 N 次有效扫描、正常路径0次逐托点击；FBA K 个目的仓、P 个实际托盘为 K 次扫箱选组、P 次扫托和 P 次箱数回车。照片、整柜结束、纠错及异常操作单独统计。真实耗时、网络等待和设备吞吐必须真机测量，本稿不预报百分比提升。
 
-## 9. 仍需业务明确的两处边界
+## 9. 已冻结的实施边界
 
-1. 普通 FBA 是否通常按同目的仓整组交接，还是经常要求拆出某一客户/入仓码单独发运？推荐保留快速计数，对确实需要挑货的后续环节增加箱码确认；若日常必须精准按票拣货，需接受更细的落托记录。
-2. “海外仓中转”是否指纯数量交接的中转散货，还是需保留箱级库存的存储/服务货物？推荐先保持已有箱级能力并去掉重复操作；有可靠整托清单优先整托接收，纯数量中转的简化另行明确。
+1. 普通 FBA 本轮按当前柜、FBA 目的仓做组级快速计数，不采集每票/每箱落托事实；后续确需按客户、入仓码或箱唛部分操作时，在对应操作现场补做箱码确认。不得为了下游声称精确而把逐箱扫描重新塞回所有收货流程。
+2. 海外仓中转本轮保留现有箱级能力，仅优化为选定目标托盘后连续扫箱；有可靠完整来源托盘清单时可整托接收。本轮不把所有中转散货改成纯数量模式，避免在业务边界未确认前丢失箱级库存事实。
+3. 只有一件代发使用 DP。普通 FBA 沿用“柜号-FBA 仓编码-三位序号”托盘码；两种码均是仓库可见业务码，但来源、清单精度和收货语义不同，不得混用。
 
-这两项作为实施前业务边界记录，不要求仓库在每次收货时做选择。收货策略由后台计划预先确定，PDA只执行当前货物对应的最短操作路径。
+以上规则不要求仓库在每次收货时做业务判断。收货策略由后台计划和真实码映射预先确定，PDA只执行当前货物对应的最短操作路径。