html/docs
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
083c56790536fb7aa46ba26b5d38697c2e2e9964
docs/头程到尾程分阶段流程/阶段三-国内货柜履约与出仓.md
T
ouyangxq 083c567905 优化
2026-09-18 16:48:32 +08:00

20 KiB
Raw Blame History

阶段三：国内货柜履约与出仓

对应全景流程：F14～F23。
阶段起点：入库单主状态为 WAIT_SPLIT，不存在有效 HOLD。
阶段终点：整柜满足国内出仓门禁，产生唯一实际 DEPARTED_WAREHOUSE 节点并开始出仓后的船节点查询。
本阶段复用订单、入库单、柜次和装柜计划，不新建独立“出仓单”。

1. 阶段目标和边界

本阶段把可分柜货物转化为可追溯的真实整柜离仓事实，覆盖：

  1. 模拟柜、智能推荐、人工分配和同柜不可拆组；
  2. 海运订舱草稿、资料补齐和放舱；
  3. 订舱级国内拖车预约；
  4. 模拟柜与订舱柜型需求、真实集装箱号关联；
  5. 预装确认、动态增减和普通散货托盘标签；
  6. 国内 PDA 拣货、整托装柜和异常闭环；
  7. 四步装柜照片、铅封照片与铅封号；
  8. 装柜完成、部分装载分片和跨区交接快照；
  9. 客户资料、整柜出口报关与放行；
  10. 国内出仓门禁、离仓确认和拖车费用归集。

LOADED 表示货物已经完成实际装柜，不等于柜子已经离开国内仓。报关放行等条件在国内出仓环节统一校验；国内 Admin/PDA 不得把订单推进到海外派送完成 DELIVERED。

2. 角色、终端和对象

角色 终端 主要操作
排柜操作员 Admin 创建模拟柜、搜索候选、推荐/人工加入、调整预装
订舱操作员 Admin 建订舱草稿、维护运输资料、上传文件、放舱
国内调度 Admin 建订舱级拖车预约、选择供应商、维护时间和附件
仓库主管 Admin 预装确认、真实柜号补录、任务和证据监督
PDA 拣货员 国内 PDA 领取唯一柜次任务、扫码、异常、拍照、完成装柜
报关操作员 Admin 汇总整柜资料、开始报关、上传完成文件、完成报关
企业操作员 Client 上传本客户退税/报关资料、查看本企业进度和回执
出仓操作员 Admin 查看组合门禁，必要时人工确认离仓

核心对象：

对象 业务作用 稳定标识
入库单 每票/分片货物履约主体 inboundId、入仓码
模拟柜/柜次 多票货物共享的装载容器 containerBookingId、cabinetNo
装柜计划 柜次唯一预装/PDA 作业聚合 loadingPlanId
海运订舱 船司运输和柜型需求聚合 oceanBookingId、OB-yyMMdd-####
拖车预约 一个已放舱订舱的国内提柜/送柜任务 truckAppointmentId
PDA 任务 单柜次单作业员的现场任务 taskId、任务版本
整柜报关 柜次级资料冻结和回执 柜次及报关记录标识

3. 前置检查

  • 候选入库单已完成阶段二，实际箱数、重量和体积可用；
  • 一件代发已按实际托盘封托；
  • 当前入库单无有效 HOLD；
  • 柜型规格、国内中转仓、有效渠道和供应商主档可用；
  • 操作员理解模拟柜、真实柜号、订舱和拖车是不同对象；
  • 同柜不可拆组、已占用数量和版本冲突均以服务端返回为准；
  • 费用仍可并行维护，但已经确认/发送或客户已确认版本不得被静默改写。

4. F14 模拟柜与智能排柜

4.1 创建模拟柜

入口：Admin → 国内货柜/智能装柜。

  1. 选择正式装柜仓；
  2. 选择九类计划渠道组之一；
  3. 选择平台有效柜型，核对额定容量和限重；
  4. 填写计划日期和必要备注；
  5. 提交后系统原子创建稳定柜次、cabinetNo 和唯一装柜计划；
  6. 此时可以没有真实集装箱号，也不会因创建模拟柜自动产生订舱。

容量和重量当前允许达到柜型额定值的 150%，超过时服务端拒绝。页面显示仅用于预判，最终以服务端重新计算为准。

4.2 查询候选

工作台可查询 PENDING_REVIEW、WAIT_MEASURE、WAIT_SPLIT、LOADING 等未完成候选。状态是展示维度，能否加入必须看响应中的 canAssign 和原因。

  • 待审核或待测量订单可提前占位；
  • 预装确认和启动 PDA 前，实际作业成员必须进入 WAIT_SPLIT；
  • 普通订单按剩余箱数分配；
  • 一件代发按每个未占用的已封托托盘独立返回和分配，禁止拆托；
  • 同柜不可拆组必须成员完整、满箱并原子加入；
  • 推荐顺序以入库时间先进先出为基础。

4.3 智能推荐和人工加入

智能推荐：设置筛选范围和装载目标，系统逐项校验渠道、仓库、剩余箱数、体积、重量、托盘完整性、组锁和占用，再返回推荐结果。

人工加入：选择候选，填写普通货分配箱数或选择一件代发整托，携带计划版本提交。系统重新校验资格；页面旧结果不能作为写入依据。

一件代发一票多托时逐托展示，其中一托已分配不得隐藏其他未分配托盘。容量不足时跳过整托，不能回退成按箱拆托。

4.4 调整与费用影响

  • 未产生物理拣货的普通明细可增减或移除；
  • 已拣数量是可调整下限；
  • 同柜组只有全组都未拣时才能整组移除；
  • 单行一件代发只能按该行 palletId 整托移除；
  • 成员变化需要重算未冻结的柜级/客户级费用；
  • 已确认、已发送或客户已确认的费用版本不得直接改写，应按费用规则生成新版本或拒绝。

5. F15 海运订舱与放舱

5.1 创建草稿

入口：Admin → 海运订舱。

  1. 选择启用的国内中转仓；
  2. 选择该仓当前有效渠道；
  3. 选择 ACTIVE/BOOKING 订舱供应商；
  4. 填写三类参与方和已知运输资料；
  5. 至少维护一项、最多二十项柜型需求，数量为正整数；
  6. 保存为 DRAFT，系统生成 OB-yyMMdd-#### 订舱号。

草稿允许资料不完整、替换文件和继续编辑。柜型需求只表达需要多少个什么柜型，不创建真实货柜行。

5.2 补齐并放舱

放舱前核对：

  • 提单号全局唯一；
  • 船名、航次、起运港、目的港、ETD、ETA 和运输条款完整；
  • 渠道仍有效；
  • 柜型需求与平台规格一致；
  • 存在有效 BOOKING_CONFIRMATION 或 BILL_OF_LADING 文件；
  • 订舱供应商仍为有效主档。

点击放舱后状态从 DRAFT 进入 RELEASED，运输快照永久只读。放舱不要求真实柜号，不得为了通过校验伪造柜号。

6. F16 订舱级国内拖车

入口：Admin → 国内拖车预约。

  1. 从服务端候选中选择已 RELEASED、有提单号和有效订舱文件的订舱；
  2. 选择 ACTIVE/TRUCKING/DOMESTIC 供应商；
  3. 填写计划装柜时间、联系人和附件；
  4. 保存/提交预约；
  5. 重复创建时返回现有非终态预约，不生成第二张。

拖车单只绑定订舱，不绑定客户、柜次、装柜计划或真实柜号。一个订舱最多一张非终态预约，已有有效完成单不能再次创建收费。

PDA 装柜完成不推进拖车状态。只有订舱要求的全部柜型数量均已关联，并且所有柜均确认国内离仓后，拖车才自动完成。正金额应付拖车费按各柜最终实装体积守恒分摊并发送 Finance；缺供应商归属、有效体积或费用配置时失败关闭，不做伪造均分。

7. F17 柜次关联和真实柜号

入口：Admin → 柜次详情 → 关联订舱/补录柜号。

  1. 选择已放舱订舱的未满配柜型需求；
  2. 选择对应模拟柜；
  3. 校验仓库、渠道映射、柜型、容量、限重和需求剩余数量；
  4. 录入真实集装箱号；
  5. 提交后在原柜次上冻结订舱、需求和柜号快照。

关联不会更换 containerBookingId、cabinetNo、装柜计划或明细。真实集装箱号在同一订舱内唯一，不同提单可按业务规则复用。

订舱关联、预装确认和任务创建技术上可先于柜号，但正式操作应在 PDA 最终完成前补齐。已有柜号纠正仅限计划 EDITING、任务未领取且没有物理作业事实。

8. F18 预装确认、动态增减与标签

8.1 预装核对与确认

入口：Admin → 预装清单。

  1. 打开柜次唯一预装计划；
  2. 核对每个入仓码、客户、目的仓、普通箱数或一件代发托盘；
  3. 查看容量、重量、已占用和异常提示；
  4. 确认所有现场成员已到 WAIT_SPLIT 且未 HOLD；
  5. 点击计划级确认，生成或开放唯一 PDA 任务；
  6. 记录确认快照、操作人和版本。

预装进入 CONFIRMING/CONFIRMED 只冻结确认快照，不锁死尚未完成柜次。计划仍为 EDITING/LOADING 时可继续增加合法明细；未拣明细可调整，已拣明细保持锁定。

新增或调整后计划和任务版本递增，PDA 旧版本必须刷新再作业。

8.2 普通散货托盘标签

普通、非一件代发 FBA 明细在计划 LOADING/COMPLETED 且真实柜号有效时生成正式托盘标签：

  1. 系统按平台柜次号、FBA 地址内部编号和三位序号生成冻结托盘码；新柜次号为全局连续且不按日期重置的 D0001、D0002，托盘码不依赖可跨提单复用的真实柜号；
  2. 地址内部编号从 Warehouse 启用主数据读取；
  3. 缺编号或同柜重复时拒绝生成；
  4. 重复生成必须与已有明细一致；
  5. Admin 全部打印或按仓指定张数打印；
  6. A4 横版每托一页，标签与海外补打复用同一编号。

该标签与阶段二一件代发 DP 托盘不同：一件代发托盘在测量后已实际清点封托，装柜时按冻结整托分配。

9. F19 国内 PDA 拣货装柜

9.1 领取和开始

入口：国内 PDA → 拣货装柜。

  1. 操作员选择当前作业仓；
  2. 打开或扫描柜次任务；
  3. 核对真实柜号、装柜计划和任务版本；
  4. 领取任务后绑定当前作业员、任务和柜次；
  5. 单柜次只允许一名作业员，不支持多人并行或无审计接管；
  6. 进入任务后计划/入库履约按规则进入 LOADING。

正式作业当前只支持在线。设备本地草稿按作业员、任务和柜次隔离；批量提交是否具备完整原子事务仍需在优化/验收中持续核实。

9.2 普通散货扫码

  • 扫描稳定箱码，一箱一码；
  • 不能用 SKU、件数、入仓码或自由文本代替箱码；
  • 系统核对箱码属于当前入库单、当前任务且尚未处理；
  • 连续扫描先进入当前任务草稿，操作员核对后批量提交；
  • 重复扫描不重复增加实装数量。

9.3 一件代发整托装柜

  • 扫描 DP 托盘码，或扫描成员箱码定位所属已封托托盘；
  • 页面展示托盘、入仓码、箱数和 SKU 汇总；
  • 使用 PICK_PALLET 一次提交整托；
  • 禁止部分拣货、拆托或将同托不同订单成员分开提交；
  • 装柜完成按 palletId 精确冻结每托箱唛和 SKU，不能按整票模糊复制。

9.4 部分拣货、跳拣和异常

允许分批扫描和暂时跳过，但每个未完成项必须选择/填写异常原因。存在未解决异常、缺少处理单元、数量不平或版本冲突时不能完成任务。

提交超时后先查询任务明细和操作结果，禁止更换幂等键盲目重复提交。版本冲突时刷新任务，保留未提交草稿并重新核对。

10. F20 装柜证据与铅封

PDA 按现场顺序拍摄：

  1. PHOTO_STEP_1：装柜初始/空柜；
  2. PHOTO_STEP_2：装载过程；
  3. PHOTO_STEP_3：接近完成；
  4. PHOTO_STEP_4：满柜/关门前；
  5. SEAL：带有效铅封号的封柜照片。

每类至少一张有效照片，同类允许追加。PDA 仅允许现场相机拍摄；有权限的 Admin 操作员/理货员可人工补充，普通拣货员不开放后台上传。

证据先上传 File 获得合法文件引用，再绑定柜次/任务。错误图片只能作废，不能硬删除；需保留上传、作废、操作者、时间、文件哈希和幂等记录。照片及铅封号当前不对客户展示。

11. F21 装柜完成与分片

PDA 点击“完成装柜”时，服务端重新校验：

  • 任务属于当前柜次和仓库且版本一致；
  • 真实集装箱号存在；
  • 所有普通箱码或一件代发整托均核平；
  • 没有未解决异常；
  • 四步照片和带铅封号的 SEAL 完整；
  • 计划明细、已拣数量和最终实装数量守恒。

校验通过后：

  1. PDA 任务和装柜计划进入 COMPLETED；
  2. 实装来源入库单进入 LOADED；
  3. 生成最终实装箱码、托盘、SKU 和证据快照；
  4. 对部分装载执行一次分片；
  5. 生成跨区 Outbox，但后续消费必须保持幂等。

部分装载时，已装数量形成当前柜次的 LOADED 子入库单，余量形成可继续 WAIT_SPLIT 的后续子单；只允许一层分片，所有子项总和必须等于来源数量。客户订单身份和入仓码关联不能丢失。

12. F22 客户资料与整柜出口报关

12.1 客户上传资料

入口：Client → 头程订单 → 报关资料。

客户只可对本企业订单上传退税/报关资料，选择资料类型并填写说明。文件归属、订单归属和客户身份由服务端校验，文件名不能代替合法文件 ID。

12.2 平台整柜报关

入口：Admin → 柜次详情 → 出口报关。

  1. 查看柜内所有入仓码及其资料覆盖情况；
  2. 对退税资料逐项核对，缺件时联系对应客户补充；
  3. 开始报关时冻结当前参与资料和版本；
  4. 线下向报关代理提交；首版不做外部系统直连；
  5. 完成后为每份退税资料上传一一对应的完成文件；
  6. 全买单柜由平台确认买单，并从导出中心获取最终实装买单明细；
  7. 点击完成整柜报关，写入放行结果和历史。

报关完成后系统立即尝试国内出仓；若其他门禁尚未齐全，保留明确阻断项并由受控补偿重试，不能伪装为已离仓。

13. F23 国内出仓

13.1 出仓硬门禁

整柜所有关联入库单逐项检查：

  • 无有效 HOLD；
  • 入库单为 LOADED；
  • 装柜计划为 COMPLETED；
  • PDA 柜次任务为 COMPLETED；
  • 订舱已 RELEASED 且分配当前柜次；
  • 四步照片与有效铅封完整；
  • 整柜报关已完成并放行。

独立拖车状态和独立船期字段提供调度参考，但不是当前确认离仓的硬门禁。拖车在全部订舱柜次离仓后自动完成。

13.2 自动与人工确认离仓

报关完成或其他门禁变化时系统自动尝试收敛。未自动完成时，平台在柜次/国内出仓页面：

  1. 打开门禁清单；
  2. 逐项处理未通过原因；
  3. 全部通过后点击确认离仓；
  4. 携带当前版本和幂等键提交；
  5. 查看唯一离仓历史和第一条实际节点。

成功后系统：

  • 写入整柜唯一国内离仓事实；
  • 创建 CarrierScheduleQuery；
  • 写入实际 DEPARTED_WAREHOUSE 节点；
  • 触发出仓后船节点查询；
  • 检查并尝试完成订舱级拖车；
  • 保持跨区交接事件可重试且不重复建单。

实际离仓节点产生后禁止撤销。发现错误转入线下和后续阶段异常处理，不提供修改历史伪装未离仓的能力。

14. 状态和动作总表

对象 关键状态 推进动作
入库单 WAIT_SPLIT → LOADING → LOADED 分配/开始 PDA/完成装柜
装柜计划 EDITING → LOADING → COMPLETED 预装调整/PDA 作业/最终完成
订舱 DRAFT → RELEASED 补齐资料并放舱
拖车 非终态 → COMPLETED 所有要求柜次实际离仓后自动完成
报关 资料收集 → 已冻结办理中 → 已完成/放行 客户上传、平台开始、上传回执并完成
国内出仓 等待门禁 → 可出仓 → 已离仓 自动尝试或平台确认

主状态只表达阶段结果。订舱、拖车、PDA、证据和报关保持关联子状态，页面应汇聚展示，但不能互相覆盖。

15. 异常与恢复

场景 处理方式
候选显示可用但提交失败 以服务端最新占用/版本为准，刷新后重排
待测量订单已占位 可保留计划占位，确认预装前必须到 WAIT_SPLIT
一件代发整托容量不足 跳过整托或换柜，禁止拆托
订舱资料不全 保持 DRAFT，补齐后再放舱
放舱后资料错误 不原地篡改冻结快照，按业务异常处置
真实柜号暂缺 可先关联/确认，但最终装柜前必须补齐
PDA 旧版本 刷新计划，不以旧版本覆盖新增明细
扫描错箱/重复箱 拒绝或提示已处理，核对稳定箱码
未完成项有异常 记录原因并解决，禁止完成任务
照片错误 作废并重拍，不硬删除证据
部分装载 一次分片，已装与余量数量守恒
报关资料缺失 定位对应客户/入仓码补件，办理批次不伪造完成
出仓门禁未齐 展示具体阻断项，条件变化后受控重试
离仓请求超时 查询唯一离仓历史/节点后再处理，不重复写事实

16. 数据流和阶段完成判定

WAIT_SPLIT 入库单/已封托托盘
  → 模拟柜与唯一装柜计划
  → 已放舱订舱 + 真实柜号 + 订舱级拖车
  → 预装确认/动态调整
  → PDA 实装 + 五类证据
  → COMPLETED / LOADED + 数量分片 + 跨区快照
  → 整柜报关放行
  → 国内离仓 + DEPARTED_WAREHOUSE + 船节点查询任务

阶段完成必须同时满足：

  • 最终柜次、装柜计划、订舱、真实柜号关联可追溯
  • 全部实装箱/托盘/SKU 与入库单数量守恒
  • PDA 任务完成且无未解决异常
  • 四步照片、铅封照片和铅封号完整有效
  • 装柜计划 COMPLETED，实装入库单 LOADED
  • 部分装载时已装子单和余量子单正确
  • 整柜报关已完成并放行
  • 所有入库单无 HOLD
  • 唯一国内离仓历史存在
  • 第一条实际 DEPARTED_WAREHOUSE 存在
  • 船节点查询任务和跨区事件可幂等重试

17. 易用性与数据流评审问题

  1. 排柜工作台是否充分解释“可提前占位”和“可实际作业”的差别？
  2. 推荐结果是否应逐项展示未入选原因、容量影响和费用影响？
  3. 模拟柜、柜次编号、真实柜号、订舱号和提单号是否在页面上容易混淆？
  4. 订舱、拖车、预装、PDA、报关是否需要一个柜次级总控清单，而不是跨页面查找？
  5. 预装确认后仍可动态增减时，如何提示 PDA 版本已过期并保护未提交草稿？
  6. PDA 批量提交需要补齐怎样的原子性、离线/弱网和失败整批回滚验收？
  7. 五类证据是否要提供拍摄引导轮廓、清晰度检查和缺图计数？
  8. 部分装载分片在 Client 应如何展示，避免客户误以为整票已经全部装柜？
  9. 报关资料清单、补件责任人、截止时间和回执匹配是否需要结构化待办？
  10. 出仓门禁失败是否需要直接跳转到对应处理页面？
  11. 拖车不作为出仓硬门禁的现行口径，是否与现场调度责任一致？
  12. 实际离仓不可撤销后，错误柜号或错误时间的合规更正流程由谁负责？

18. 阶段四交接包

交给阶段四的权威数据包括：

  • 柜次、真实集装箱号、订舱号、提单号、船名和航次；
  • 起运港、目的港、ETD/ETA 和运输条款快照；
  • 最终实装订单、入仓单、箱码、托盘、SKU、重量和体积；
  • 装柜五类证据引用和报关完成事实；
  • 国内离仓时间和 DEPARTED_WAREHOUSE 实际节点；
  • 跨区事件版本、事件 ID 和有效载荷哈希；
  • CarrierScheduleQuery 及后续船节点查询上下文；
  • 未冻结费用和拖车应付等并行财务结果。

19. 事实来源

  • docs/国内货柜履约/README.md
  • docs/国内货柜履约/国内货柜履约页面与原型清单.md
  • docs/头程下单到尾程出库现状流程全景清单.md
  • docs/统一订单主状态与操作契约.md
  • apps/admin-web/src/modules/container-loading/
  • apps/admin-web/src/modules/loading-lists/
  • apps/pda-uniapp/AGENTS.md
  • apps/pda-uniapp/pages/picking/picking.vue
  • baiyue-firstleg/firstleg/AGENTS.md
  • baiyue-firstleg/firstleg/src/main/resources/openapi/loading-lists-v1.yaml
  • baiyue-firstleg/firstleg/src/main/resources/openapi/ocean-bookings-v1.yaml
  • baiyue-firstleg/firstleg/src/main/resources/openapi/truck-appointments-v1.yaml
  • baiyue-firstleg/firstleg/src/main/resources/openapi/customs-v1.yaml
  • baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/service/SmartLoadingService.java
  • baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/service/LoadingPickService.java
  • baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/outbound/dispatch/service/OutboundDispatchService.java
Reference in New Issue View Git Blame Copy Permalink