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

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

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

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

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

## 二、建议采用的最小闭环

```text
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. 将本清单作为接口、页面和测试验收的共同依据。