docs/国内货柜履约/归档/国内货柜履约Wave1开发任务卡-2026-08-09.md

国内货柜履约 Wave 1 开发任务卡

历史版本声明（2026-09-24）：本文是旧版低风险任务拆分，不能直接作为当前开发排期或门禁依据。当前流程改为“柜前资料预收集 → 物理装柜 LOADED → 按最终实装清单正式报关 → 有效放行回执后 DEPARTED_WAREHOUSE”，费用确认不阻断装柜，装柜完成时按已装范围对当前有效已发布费用版本执行系统默认确认。当前开发范围以 头程到尾程流程节点梳理（重构版）、报关资料与船期价格接入梳理 和最新需求确认表为准。

整理日期：2026-08-09
用途：产品确认后用于研发排期和任务分派。
当前范围：只做低风险基础能力；不提前实现未确认的主状态机规则。

一、统一范围口径

• 不新增独立出仓单主对象、列表或详情页面。
• 现有订单是国内货柜履约唯一主对象；柜次是执行对象。
• 订单与柜次通过履约分片/分配关系表达一单多柜、一柜多单和部分履约。
• 国内国内货柜履约终点是 LOADED/装柜完成；国内端不能手工推进 DELIVERED。
• 五类装柜照片为：空仓、半仓、满仓、锁仓、带锁码照；锁码文本单独保存。

二、第一批可立即开发

编号	端/模块	任务	目标文件或范围	验收标准	依赖
W1-BE-01-R	后端	订单-柜次-履约分片契约设计	现有 order/firstleg/loading DTO、关系表和 OpenAPI；不得创建 fl_outbound_order	支持多对多关系、快照、版本和客户隔离；形成评审稿	产品确认 Q2/Q11 后冻结实现
W1-BE-06	后端	拖车幂等与实际节点修复	TruckAppointmentService、Controller、Mapper、测试	缺少幂等键时拒绝；同键重放返回原结果；冲突返回 409；到仓/离仓时间可追溯	无
W1-BE-08	后端	OpenAPI 盘点与集成测试骨架	订舱、拖车、排柜、PDA、文件、门禁接口文档和契约测试	文档路径与 Controller 一致；建立入库测量与计费终点到装柜完成的测试骨架	仅依赖现有接口
A-01	Admin	订舱 DTO、版本和动作权限对齐	apps/admin-web/src/modules/ocean-bookings/	创建、编辑、提交、确认、放舱、变更、取消均使用真实字段、版本和权限	后端现有契约
A-02	Admin	订单详情挂载国内货柜履约作业组件	apps/admin-web/src/modules/unified-orders/	从订单详情可进入分柜、预装、拣货、装柜；刷新可恢复；错误和无权限有明确提示	订单与入库关联字段确认
PDA-01	PDA	五证据槽位和上传队列基础	apps/pda-uniapp/pages/ 及文件上传适配	五类槽位固定；临时路径不作为业务证据；失败可重试；重复提交不产生重复有效记录	File 上传接口
CLI-01	Client	内部证据字段脱敏	apps/client-web/src/modules/first-leg/	Client 不返回、不展示照片、锁码和 sealNo；订单状态仍可正常展示	后端响应兼容

三、必须等产品确认

编号	决策	未确认前的处理
Q1	排柜硬约束、软偏好和人工确认	不升级算法、不生成正式拣货任务
Q2	拼柜、一单多柜、部分拣货是否开放	只做关系查询，不冻结聚合规则
Q3	LOADING 触发时点	保留现状，暂不改状态触发代码
Q4	PDA 设备、扫描头和仓库权限	先做接口适配，不做真机上线承诺
Q5	是否实时校验库存/库位	不新增库存扣减逻辑
Q7/Q8/Q12	报关资料、代理批次、回执及门禁关系	只做范围设计，不建正式业务状态机
Q9	港务字段、来源、更新时间	不新增客户实时承诺
Q10	LOADED 后冲正和证据修正	不实现直接覆盖或冲正接口
Q11	订舱、拖车、报关等强制前置	不把并行子状态写成硬门禁
Q13	国内终点及海外仓回传映射	国内端移除人工 DELIVERED 操作

四、后续波次

1. Wave 0：完成 Q1～Q13 契约冻结和订单详情低保真确认。
2. Wave 1：完成本表第一批基础能力。
3. Wave 2：实现柜次级证据包、PDA 真实上传和服务端 LOADED 门禁。
4. Wave 3：实现报关协同、Client 只读展示和海外仓可信回传接口。
5. Wave 4：用同一真实订单完成正向、负向、权限、并发、幂等和弱网验收。

五、禁止误开工项

• 新建独立出仓单或独立出仓菜单。
• 允许无拣货、缺照片或缺锁码进入 LOADED。
• 国内 Admin/PDA 手工推进 DELIVERED。
• 在产品未确认前固化部分拣货拆单和一单多柜聚合规则。