docs/国内货柜履约/国内货柜履约需求确认表.md

# 虫虫出海国内货柜履约需求确认表

> 创建日期：2026-07-28  
> 当前状态：已进入开发规划（已确认结论按本表执行；技术实现项仍需契约评审）  
> 用途：记录会影响国内货柜履约范围、流程、数据模型、页面和验收的产品决策。

## 一、维护规则

- 状态统一使用：待确认、确认中、已确认、已取消。
- 阻断级别统一使用：开工阻断、模块阻断、非阻断。
- 结论确认后同步更新 `归档/国内货柜履约开发规划.md`、`归档/国内货柜履约开发进度表.md` 和受影响的页面原型。
- 未确认事项只能作为候选方案，不能直接写成固定开发或验收承诺。

## 二、确认事项

| 编号 | 决策/问题 | 当前建议 | 阻断级别 | 状态 | 负责人 | 计划确认 | 最终结论 | 影响模块 |
|---|---|---|---|---|---|---|---|---|
| P3-Q1 | 智能排柜需考虑哪些硬约束和软偏好？ | 业务提供可执行规则表，建议可解释并由人工确认 | 开工阻断 | 已确认 | 产品/业务 | 2026-08-10 | 装载率上限 110%；税率高排前暂作为可配置排序，不作为不可变硬编码；系统给出可解释建议，人工确认后生成任务 | 智能排柜、拣货任务 |
| P3-Q2 | 是否存在拼柜、一单多柜和拆批出仓？ | 通过订单-柜次关系预留能力，页面按高频场景逐步开放 | 开工阻断 | 已确认 | 产品/业务 | 2026-08-10 | 支持一单多柜、一个柜拼多个订单；采用“父订单→子订单→柜次”关系。已装载数量形成子订单，未装载数量自动生成待后续处理的子订单；不新建独立出仓单 | 订单、柜次、排柜、拣货 |
| P3-Q3 | 原型“预约托车”是否统一为“预约拖车”？ | 建议使用行业常用的“拖车”，同时确认业务实际含义 | 非阻断 | 已确认 | 产品/业务 | 2026-08-10 | 页面、接口和文档统一使用“预约拖车” | 页面文案、接口字段说明 |
| P3-Q4 | PDA 开发、扫描与发布方式是什么？ | 保持设备适配层，不绑定厂商 SDK | 非阻断 | 已确认 | 用户当前对话确认 | 2026-08-10 | 采用 uni-app 开发并支持在线更新；Android 广播方式已接入：Action=`android.intent.action.SCANRESULT`、字符串 Extra=`value`。设备型号不构成开发、发布或验收门禁，扫描适配保持厂商无关 | PDA 拣货、在线更新、真机验收 |
| P3-Q5 | 拣货是否依赖实时库存和库位可用量？ | 默认使用入库测量与计费处理单元和当前位置；如需完整库存，单独评估 WMS 范围 | 开工阻断 | 已确认 | 产品/业务 | 2026-08-10 | PDA 拣货必须依赖实时库存和库位可用量；首版复用入库测量与计费处理单元、当前位置和可用量接口，超量、库存不足和库位不可用由服务端拒绝；不扩展完整 WMS | 入库测量与计费及国内货柜履约契约、拣货、库存边界 |
| P3-Q6 | 柜封照片有哪些必传类型、数量、采集方式、处理规则和留存期限？ | 五类证据、角色和留存按确认版直接进入契约 | 模块阻断 | 已确认 | 产品/业务 | 2026-08-10 | 空仓、半仓、满仓、锁仓、带锁码照五类各至少 1 张有效照片，同类型可无限追加；PDA 只能现场拍照；后台操作员和理货员可人工上传；拣货员只负责 PDA 现场采集，不开放后台人工上传；错图不硬删除，按原因、操作人、时间作废；带锁码照必须填写锁码文本；照片无限期保留，客户不可见照片和锁码 | 装柜、PDA 拍照、Admin 上传、文件存储、订单后程门禁 |
| P3-Q7 | 报关资料清单是否按国家、渠道和货物类型变化？ | 清单配置化，并保存业务使用的清单版本 | 模块阻断 | 已确认 | 产品/业务 | 2026-08-10 | 首版不对接海关或代理系统；按人工维护资料清单、收集/补件并保存版本，具体清单可配置 | 客户资料、报关审核、文件版本 |
| P3-Q8 | 报关代理如何接收资料并返回回执？ | 首版系统内整理、线下提交，正式接口后续评估 | 模块阻断 | 已确认 | 产品/业务 | 2026-08-10；2026-09-24 更正 | `LOADED` 后平台按客户/入仓码收集资料并线下发给报关行；授权人员上传每轮报关行回执，发给对应客户确认。客户打回后重新上传、重新发报关行并生成新回执，直到该客户确认；记录资料版本、回执版本、roundNo、发送时间和确认/打回审计 | 报关协同、客户确认、回执上传 |
| P3-Q9 | “港务信息”指船期、港口作业状态还是两者，包含哪些字段，由谁维护？ | 国内货柜履约只维护订舱与出仓前船期资料 | 已重新归期 | 已确认 | 产品/业务 | 2026-08-19 | 柜子确认离开国内仓库后的船公司/货物跟踪查询、每 3 天最多 3 次、来源、更新时间和过期标识整体归海外仓业务；国内货柜履约不建设或验收该查询 | 国内货柜履约订舱资料、海外仓业务船节点查询 |
| P3-Q10 | 订单进入“装柜完成”后发现错误如何处理？ | 仅保留线下人工处理和审计，不建设在线冲正 | 模块阻断 | 已确认 | 产品/业务 | 2026-08-10 | `LOADED` 后不提供在线冲正/回退入口，统一线下人工处理；系统保留原状态和审计记录，不由国内 Admin/PDA 推进 `DELIVERED` | 装柜完成门禁、权限、审计 |
| P3-Q11 | 九个动作中哪些是强制前置，哪些允许并行？ | 统一门禁按已确认前置执行；PDA 单柜次单人作业 | 开工阻断 | 已确认 | 产品/业务 | 2026-08-10；2026-09-24 更正 | 费用确认不阻断排柜、预装、PDA 或装柜。进入 `LOADED` 只校验物理装柜、PDA、数量、真实柜号和五类证据；`LOADED` 后报关线和送港线同时启动，客户报关确认不阻断送港，送港/进港也不替代客户确认；只有实际开船前才汇合检查报关结果、港口和船次条件；PDA 单柜次单人作业 | 全流程、状态机、PDA、报关、送港、页面进度 |
| P3-Q12 | 报关回执包含哪些类型，客户确认和海关放行如何衔接？ | 首版人工上传回执并保留版本 | 开工阻断 | 已确认 | 产品/业务 | 2026-08-10；2026-09-24 更正 | `LOADED` 后按客户/入仓码收集资料并发送报关行；报关行回执发对应客户确认，客户打回则重新上传、重新发送并生成新回执；所有客户确认后才向报关行提交整柜资料并正式申报；之后分别记录查验、不查验放行、补件/退回等海关结果。回执上传不等于客户确认，客户确认也不等于海关放行 | 报关状态、客户回执、整柜申报、海关结果 |
| P3-Q13 | 国内货柜履约终点以什么状态为准？ | 国内系统以能掌控的最后环节为终点 | 开工阻断 | 已确认 | 用户当前对话确认 | 2026-08-08 | 国内货柜履约终点为 `LOADED`/装柜完成；`DELIVERED`/派送完成只能在到达海外仓后由海外仓可信回传推进，不属于国内国内货柜履约操作和验收范围 | 阶段边界、状态、里程碑、验收、海外仓回传 |
| P3-Q14 | 订舱、渠道柜次、放舱与智能排柜的先后关系是什么？ | 线下已订妥的订舱在创建时完整登记五项真实运输快照并直接确认；放舱不覆盖首次快照 | 开工阻断 | 已确认 | 用户当前对话确认 | 2026-08-12 | 订舱创建请求必须携带提单号、船名、航次、预计开船时间、预计到港时间五项真实运输数据，并直接进入 `CONFIRMED`；渠道、箱型和数量同时确定，系统按箱型需求数量生成绑定渠道的稳定内部柜次。未放舱不影响候选查询、智能推荐、人工调整和保存装柜计划；同一柜次只能装同渠道入库单，服务端禁止跨渠道混装。`RELEASED` 仅作为后续放舱/PDA 门禁，不补录、不覆盖首次五项运输快照；真实集装箱号可在放舱时或之后录入 | 订舱、柜次、智能排柜、预装、PDA、运输信息 |
| P3-Q15 | 客户未确认费用是否阻断排柜、装柜？装柜完成后如何处理？ | 费用作为并行事实，装柜完成时对当前有效版本做系统默认确认 | 模块阻断 | 已确认 | 用户当前对话确认 | 2026-09-24 | 客户费用确认不阻断排柜、预装、PDA 或装柜。装柜完成后，针对本次已装范围的当前有效且已发布费用版本，若客户未确认则记录“系统默认确认（装柜完成）”；保留客户确认与 `SYSTEM_AUTO_AT_LOADED` 来源、版本、柜次/入仓码、时间和幂等标识。没有有效费用版本不得伪造确认；部分装载不确认余量或整张未完成订单 | 费用版本、装柜完成、客户进度、审计、部分装载 |
| P3-Q16 | 报关资料何时收集、何时正式报送？ | 装柜后通知报关，按客户确认轮次完成后正式提交 | 模块阻断 | 已确认 | 用户当前对话确认 | 2026-09-24 | `LOADED` 后以最终实装清单通知报关行，按客户/入仓码收集资料并发送报关行；回执发客户确认，打回则重新上传、重新发送并产生新回执，循环至所有客户通过；全部客户确认后再提交整柜资料给报关行确认，由报关行正式申报；海关查验/不查验放行等结果单独记录。送港线与报关线并行，谁先到都保留事实 | 客户资料、回执轮次、客户确认、整柜申报、送港/海运 |
| P3-Q17 | 送港和报关是否互相等待？甩柜何时发生？ | 两条线并行，实际开船才进入海运 | 开工阻断 | 已确认 | 用户当前对话确认 | 2026-09-24 | `LOADED` 后可同时安排拖车、送港和报关；送港可先到港，报关也可先完成客户确认/正式申报。船舱不足记录 `ROLLED_OVER`，保存原船次、改配船次、滚动次数和通知；只有承运船舶真实开航才写 `VESSEL_DEPARTED`/海运节点 | 送港、船次、甩柜、海运节点 |

### 2.1 PDA 已确认子决策

| 编号 | 确认日期 | 已确认结论 | 实现/验收含义 |
|---|---|---|---|
| P3-PDA-D01 | 2026-08-09 | PDA 正式作业必须联网；断网时不能开始正式拣货、提交、完成任务或推进 `LOADED` | 不建设离线业务提交队列；网络恢复后由员工刷新并重试 |
| P3-PDA-D02 | 2026-08-09 | 进入任务即标记“拣货中” | 进入动作需调用后端开始接口，不能只改本地页面状态 |
| P3-PDA-D03 | 2026-08-09 | 扫描结果先保存在本地草稿，点击“提交”时才批量写入后端，不逐码提交 | 批量请求需携带本次草稿全部明细；提交成功后再清理草稿 |
| P3-PDA-D04 | 2026-08-09 | 未提交草稿需持久化，并绑定作业员、任务和柜次；其他账号不能继承 | 应用退出、前后台切换或设备重启后仍可恢复；成功提交或明确放弃后清理 |
| P3-PDA-D05 | 2026-08-09 | 允许部分拣货和跳拣；每个未完成项必须填写异常原因 | 存在未解决异常时任务进入异常挂起/待处理，不能完成或推进 `LOADED` |
| P3-PDA-D06 | 2026-08-09 | 使用轻量、对员工不可见的幂等与版本控制 | 重复提交返回原结果；版本冲突提示员工刷新后重试，不静默覆盖 |
| P3-PDA-D07 | 2026-08-09 | PDA 只能现场拍照；Admin 可人工上传 | PDA 不提供相册选择；Admin 上传必须受权限、归属和审计约束 |
| P3-PDA-D08 | 2026-08-09 | 同类型证据允许多张并采用追加记录；错误/重复照片不硬删除，只作废 | 每条照片独立保存；作废记录原因、操作人和时间，历史可追溯 |
| P3-PDA-D09 | 2026-08-09 | 空仓、半仓、满仓、锁仓、带锁码照五类证据各至少 1 张有效且未作废的照片，可多张；带锁码照同时要求锁码文本 | 服务端完整性门禁按“每类至少一张有效记录”校验，不能按单槽位替换模型实现 |

> 验收映射：当前自动化已真实覆盖五类证据上传、同类型多图追加、跨类型/伪造 `fileId` 拒绝、锁码文本门禁和错图作废审计；设备在线、持久化草稿批量提交仍按[验收任务拆分与待确认清单](归档/国内货柜履约验收任务拆分与待确认清单.md)保留 coverageGap。

## 三、已确认架构决策

| 编号 | 确认日期 | 最终结论 | 影响 |
|---|---|---|---|
| P3-D1 | 2026-08-08 | 国内货柜履约不新建独立出仓单，现有订单列表承载全部主状态；柜次、订舱、拖车、拣货、证据和报关作为订单关联子对象 | 取消出仓单页面和数据模型规划，改为增强现有订单列表/详情及服务端统一编排 |
| P3-D2 | 2026-08-10 | 订单拆分采用“父订单→子订单→柜次”；已装载数量形成子订单，未装载数量自动生成后续子订单；支持一单多柜和多订单拼柜 | 后端必须保留父子订单、柜次、数量分摊和整体时间线；不得把未装载部分静默丢弃 |
| P3-D3 | 2026-08-10；2026-09-24 更正 | `LOADED` 只表示物理装柜完成，门禁包含真实柜号、PDA 拣货、数量守恒和五类证据；装柜后报关线、送港线独立推进，报关客户确认不阻断送港，进港不代表报关完成；实际开船前再校验报关结果、港口和船次条件；`LOADED` 后错误线下人工处理 | 统一门禁服务分别维护物理装柜、报关案例、送港/进港、甩柜和实际开船事实；国内页面不提供在线冲正或 `DELIVERED` 操作 |
| P3-D4 | 2026-08-10；2026-08-19 更正归期 | 船公司官网查询：每 3 天一次、最多 3 次，保存来源、更新时间和过期标识 | 该能力及首批六家来源整体归海外仓业务，国内货柜履约只保留订舱与出仓前船期资料 |
| P3-D5 | 2026-08-10 | 初始化仓库常用角色：操作员、拣货员、理货员；按最小权限授予拣货、证据上传和查看能力 | 角色初始化由 IAM/统一 SQL 任务实现，具体权限矩阵在技术契约评审中落表 |
| P3-D6 | 2026-09-24 | 费用确认不阻断排柜和装柜；装柜完成后对已装范围的当前有效已发布版本执行系统默认确认，来源与客户主动确认分开审计；`LOADED` 后报关采用“报关行回执→客户确认/打回重做→所有客户通过→整柜正式申报→查验/放行”，送港线并行并单独记录甩柜和实际开船 | 同步费用版本、部分装载、客户报关案例、回执轮次、整柜申报、送港/船次和客户/后台节点；该规则覆盖旧的“装柜完成不得代替客户自动确认”和“报关/送港单线串行”口径 |

## 四、建议确认顺序

1. 已完成 P3-Q1～P3-Q3、P3-Q5～P3-Q14 的产品确认，可直接进入契约和实现拆分。
2. P3-Q4 已确认采用 uni-app、在线更新与 Android 广播扫描；后续按既定发布安排完成常规真机验收。
3. P3-Q5 已确认复用入库测量与计费实时库存、当前位置和可用量接口，完整 WMS 不纳入国内货柜履约。

## 五、产品与业务确认会议

### 5.1 参会角色

- 产品负责人：逐项说明问题、候选方案和影响范围，维护最终结论。
- 业务负责人：确认流程、规则、例外、责任边界和客户可见范围。
- 仓库/运营代表：确认现场作业、PDA、照片、拖车、装柜和冲正可执行性。
- 研发与测试代表：识别数据、接口、设备、权限和验收风险，不代替业务作决定。

### 5.2 会议输入

- 本确认表中的 P3-Q1～P3-Q17。
- `归档/国内货柜履约开发规划.md` 的流程、状态、里程碑和任务骨架。
- `国内货柜履约页面与原型清单.md` 中已有参考原型和待补页面。
- 入库测量与计费输出契约、目标 PDA 信息、文件存储能力及报关/港务协作现状。

### 5.3 每项确认要求

1. 必须填写负责人、计划确认日期和可执行的最终结论，不能只记录“按建议处理”。
2. 最终结论需明确正常流程、异常/冲正、权限责任和验收口径。
3. 暂缓事项必须写明当前范围是否排除、临时方案、影响模块和再次确认日期。
4. 开工阻断项未解除时，不得将受影响模块标记为可开发。
5. 会议结束后，将结论同步到开发规划、开发进度表、页面原型和后续验收任务。

### 5.4 会议输出（确认版）

- 14 项确认事项的状态和最终结论已同步；P3-Q4 已确认采用 uni-app、在线更新与 Android 广播扫描。
- 需要新增或调整的原型清单。
- 国内货柜履约范围内/范围外清单及跨期依赖。
- 仍有风险的事项、责任人和完成日期。
- 已允许进入 T02 契约设计与任务拆分；未决技术项只阻断其对应实现，不反向阻断整期已确认范围。