docs/国内货柜履约/国内货柜履约装柜闭环开发前确认单-2026-08-08.md

国内货柜履约装柜闭环开发前确认单

整理日期：2026-08-08
用途：产品、业务、仓库、研发在直接开发前确认最小闭环细节
当前建议：不补完整高保真原型，确认本清单后直接开发

一、已确认，不再重复讨论

1. 国内货柜履约不新增独立出仓单，现有订单列表和订单详情承载国内货柜履约主状态。
2. 国内国内货柜履约终点为 LOADED/装柜完成。
3. DELIVERED 只能在货物到达海外仓后由海外仓可信回传推进，国内 Admin/PDA 不提供手工操作。
4. 空仓、半仓、满仓、锁仓、带锁码照五类证据各至少提交 1 张有效真实图片，可同类型多张追加；带锁码照同时填写锁码文本。
5. PDA 只能现场拍照，Admin 可人工上传；错图不硬删除，以作废记录保留原因、操作人和时间。
6. PDA 正式作业必须联网；进入任务即标记“拣货中”，扫描先形成持久化本地草稿，点击提交时一次批量写入后端。
7. 重复提交返回原结果；版本冲突提示员工刷新重试。部分拣货或跳拣必须逐项填写异常原因，未解决前不能完成任务或进入 LOADED。

二、建议采用的最小闭环

WAIT_SPLIT / 待分柜
  -> 确认订单与柜次关系
  -> 下发并开始 PDA 拣货任务
LOADING / 装柜中
  -> 拣货完成
  -> 五类证据各至少一张有效图片真实上传并取得 fileId
  -> 锁码文本保存
  -> 服务端门禁校验
LOADED / 装柜完成
  -> 国内只读，允许授权冲正
  -> 海外仓可信回传
DELIVERED / 海外仓已收货

订单主状态只表达阶段结果。排柜、订舱、拖车、拣货、装柜证据和报关使用关联子状态，不扩展成多个重复主单。

三、仍待产品确认

编号	需要确认	建议默认方案	不确认的影响	产品结论
C1	LOADING 在什么时点触发？	PDA 作业员进入任务时自动标记“拣货中”；仅确认排柜不进入 LOADING	订单状态可能提前或延后	已确认
C2	“拣货完成”如何判定？	柜次下全部必拣明细达到完成态，数量差异已处理或完成授权复核	可能绕过未拣货物进入装柜完成	待填写
C3	是否允许部分拣货、跳拣？	允许；每个未完成项必须填写异常原因，任务挂起待处理，不能完成装柜	异常任务无法收口或被错误放行	已确认
C4	照片是否允许从相册选择？	PDA 只允许现场拍照；Admin 可人工上传	影响 PDA 交互和真实性校验	已确认
C5	同类型照片能否替换？	同类型允许多张追加；错误/重复照片作废并保留审计，不硬删除、不替换历史记录	证据可能被无痕覆盖	已确认
C6	锁码格式和唯一性规则是什么？	去除首尾空格，按原值保存；同一有效柜次不可重复，是否限定长度/字符由业务确认	无法稳定校验重复或录入错误	待填写
C7	谁触发 LOADED？	PDA 点击“完成装柜”后由服务端自动校验并推进，不要求 Admin 二次确认	若增加二次确认，需要新增待复核状态、权限和操作页	待填写
C8	订舱、拖车、报关是否是 LOADED 硬门禁？	首版均作为关联信息，不阻断 LOADED；以后按配置加入门禁	直接影响服务端门禁和验收范围	待填写
C9	装柜完成后谁可以冲正？	仅平台授权角色；原因必填，保留原证据和反向审计事件	错照、错锁码、错柜无法合规修正	待填写
C10	一单多柜、拼柜、拆批首版开放哪些操作？	数据关系支持多对多，首版页面只开放业务确认的高频场景	决定订单何时整体进入 LOADED	待填写
C11	海外仓回传后的用户文案是什么？	将现有“派送完成”改为“海外仓已收货”，展示来源和回传时间	“派送完成”容易与末端派送混淆	待填写
C12	五类照片保存多久、哪些角色可查看？	沿用文件服务权限隔离；留存期限由业务/合规确认	影响存储、清理和审计策略	待填写

四、直接开发的交互细节

4.1 PDA 装柜取证

• 拣货完成后进入装柜取证步骤，固定展示五类证据，不允许用户自定义图片类型；每类至少 1 张有效照片，可追加多张。
• PDA 仅允许调用相机现场拍摄，不提供相册选择；Admin 人工上传属于独立受权入口。
• 每张照片独立显示未拍摄、上传中、上传失败、上传成功或已作废；上传失败可单张重试。
• 上传成功以服务端返回 fileId 为准，本地临时路径不能作为业务证据。
• 带锁码照片和锁码文本同时存在才算该项完成。
• 提交时 PDA 做一次完整性提示，服务端再做权威门禁校验。
• 错误或重复照片不得硬删除，作废时记录原因、操作人和时间。
• 重复点击、网络重试和前后台切换不得产生重复状态迁移；同类型正常追加的多张照片都是独立有效证据，不按“单槽位替换”去重。

4.2 PDA 拣货提交

• 正式作业必须联网；断网时不能进入正式拣货、提交、完成任务或推进 LOADED，恢复网络后由员工刷新重试。
• 进入任务即调用服务端开始动作，并标记为“拣货中”。
• 扫码过程只更新本地草稿；草稿绑定作业员、任务和柜次并持久化到设备，不能被其他账号继承。
• 仅在员工点击提交时，将本次草稿的全部明细批量写入后端；成功后清理草稿，明确放弃时按权限和确认流程清理。
• 提交使用轻量不可见幂等键和服务端版本；重复提交返回原结果，版本冲突提示员工刷新后重试。
• 一柜多人并行、退出/换班时任务是否释放以及最终完成触发人仍待产品确认。
• 批量提交超时、后端业务错误和网络恢复后的具体提示、按钮与重试交互仍待产品确认；底层幂等和版本规则不受该交互结论影响。

4.3 Admin 订单详情

• 在现有订单详情增加“国内货柜履约作业”区域，不新增出仓单详情。
• 展示柜次、柜号、拣货进度、五类证据、锁码、各子流程摘要和整体时间线。
• 门禁未通过时展示具体阻塞项，例如“半仓照未上传”“拣货差异待复核”。
• LOADED 后隐藏普通编辑动作，仅授权角色可发起冲正。
• DELIVERED 显示海外仓回传来源、业务时间、接收时间和回传结果，国内端只读。

4.4 订单列表

• 保留待分柜、装柜中、装柜完成等现有页签。
• 原“派送完成”按 C11 的最终结论调整文案，但底层兼容状态可以继续使用 DELIVERED。
• 操作列继续放在第一列；不同状态只展示当前允许的操作。
• 状态更新失败、权限不足或版本冲突时不得在前端模拟成功。

五、服务端最低门禁

进入 LOADED 时至少同时满足：

• 当前订单/履约状态允许从 LOADING 迁移；
• 订单已关联有效柜次；
• 柜次拣货任务满足 C2/C3 的最终结论；
• 五种证据各至少有一条有效且未作废的记录和真实 fileId；
• 锁码文本已保存并满足 C6 的规则；
• 请求身份、客户、仓库和权限合法；
• 幂等键未产生冲突，状态版本未过期；
• C8 最终确认的其他硬门禁均已满足。

门禁失败时返回稳定错误码和阻塞项清单，不得只返回模糊的“操作失败”。

六、异常与冲正

• LOADED 前：允许在权限范围内重新拣货、追加拍摄、重传和修改锁码；错图通过作废处理，所有记录保留历史。
• LOADED 后：禁止直接覆盖证据或修改数据库状态，必须发起冲正。
• 冲正记录原因、申请人、审核/执行人、前后状态、原证据版本和请求关联 ID。
• 冲正后重新满足门禁才能再次进入 LOADED。
• 已由海外仓回传进入 DELIVERED 后，国内冲正是否允许必须单独制定跨业务域处理规则；国内货柜履约当前不提供该操作。

七、验收用例

正向

• 同一真实订单从 WAIT_SPLIT 关联柜次、完成 PDA 拣货和五类证据上传，最终进入 LOADED。
• Admin 能追溯柜次、拣货明细、五类多图证据及其有效/作废状态、锁码、操作人和状态时间线。
• 海外仓合法回传后进入 DELIVERED，国内页面只读展示。

负向

• 未完成拣货不能进入 LOADED。
• 缺任意一张照片、照片无真实 fileId 或缺锁码文本不能进入 LOADED。
• 无权限、跨客户、跨仓库和过期版本请求必须失败。
• 两个并发完成请求只产生一次有效状态迁移。
• 网络失败重试不重复创建同一张照片记录；业务主动追加的同类型多张照片允许同时有效。
• 国内 Admin/PDA 无法手工进入 DELIVERED。
• 伪造、过期、重放或重复的海外仓回传不能重复推进状态。

八、本次不自动纳入

• 不新增独立出仓单和对应列表/详情。
• 不把装船、清关、海外仓入库、海外仓出库和末端派送纳入国内国内货柜履约。
• 报关、Client 回执和港务信息是否作为国内货柜履约上线必交付，以产品对 P3-Q7/P3-Q8/P3-Q9/P3-Q12 的结论为准。
• 未确认前，不把订舱、拖车和报关默认设置为 LOADED 硬门禁。

九、会议输出

产品确认后应形成以下结果：

1. C1 至 C12 均填写最终结论；不能确认的事项明确排除范围和临时方案。
2. 更新 国内货柜履约需求确认表.md 中对应的 P3-Q2/P3-Q4/P3-Q5/P3-Q6/P3-Q10/P3-Q11/P3-Q12。
3. 明确是否允许按“服务端门禁 -> PDA -> Admin -> 联调验收”的顺序直接开发。
4. 将本清单作为接口、页面和测试验收的共同依据。