html/docs
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

优化

Browse Source
This commit is contained in:
ouyangxq
2026-08-18 16:39:42 +08:00
parent 0b24cc5a98
commit 8dd39ff20b
2 changed files with 35 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files
三期/货柜履约原型字段验收矩阵-2026-08-17.md
+4 -4
View File
@@ -16,12 +16,12 @@
| 列表 | 原型字段 | Admin 当前列 | 后端事实字段 | 真实 fixture 来源 | 结论 |
|---|---|---|---|---|---|
| 货柜 | 操作、集装箱号、装柜清单号、状态、异常、柜号、清关/DO/PU、车队、仓库、提单、船名航次、箱型、船公司、港口、容量、装柜/开船/到港时间 | 操作第一且左固定；柜号、订舱、集装箱号、状态、仓库、车队、提单、航线、箱型、容量、船名航次、船公司及关键时间 | `ContainerBookingEntity` 的稳定身份、来源/记录状态、客户/仓库/渠道、订舱、规格、运输及 `planId/planStatus`；overview 承载异常、单证、轨迹 | `phase3-container-loading` 本轮模拟柜合并真实订舱柜后的 ACTIVE 唯一行 | `LANDED`；清关/DO/PU、异常、轨迹摘要不在列表 DTO，见 UNKNOWN |
| 货柜 | 操作、集装箱号、装柜清单号、状态、异常、柜号、清关/DO/PU、车队、仓库、提单、船名航次、箱型、船公司、港口、容量、装柜/开船/到港时间 | 操作第一且左固定；柜号、订舱、集装箱号、状态、仓库、车队、提单、航线、箱型、容量、船名航次、船公司及关键时间 | `ContainerBookingEntity` 的稳定身份、来源/记录状态、客户/仓库/渠道、订舱、规格、运输及 `planId/planStatus`；overview 承载异常、单证、轨迹 | `phase3-container-loading` 本轮模拟柜在港口取得真实柜号后按订舱需求原地关联的 ACTIVE 唯一行 | `LANDED_STATIC`；清关/DO/PU、异常、轨迹摘要不在列表 DTO，见 UNKNOWN |
| 预装清单 | 预装单号、集装箱号、柜号、客户、仓库、船名航次、箱型、状态、SKU数、总件数、体积、重量、创建时间、操作 | 操作第一且左固定；其余列与原型一致 | `PreloadSummary` 全部对应字段及 readiness/version | 同 marker 智能排货、push-preload、真实柜合并和计划级确认 | `LANDED`；“总件数”按当前契约解释为 `totalPackageCount` |
| 装柜清单 | 操作、仓库、清单号、集装箱号、柜号、状态、总箱/毛重/净重/体积/数量、备注、创建人/时间 | 操作第一且左固定；字段与原型一致 | `ConfirmedSummary` 及 `ConfirmedDetail.items/histories` | 同一计划 PDA 完成后生成的 COMPLETED 清单 | `LANDED` |
| 订舱 | 委托单位、主票号、放舱、MB/L 当事方、港口、箱量、船公司、截关、ETD/ATD/ATA、船名航次、订舱代理、退仓、单号、操作员、状态 | 操作第一且左固定；订舱号、客户、船公司、代理、船名航次、港口、ETD/ETA、状态、更新时间 | `OceanBookingDtos.Detail`：`oceanBooking/parties/containers/histories`，创建必填五项运输快照和逐柜 `containers[]` | `ocean-bookings` 本轮一单两真实柜，创建即 CONFIRMED，随后 RELEASED | `LANDED`；截关/ATD/ATA、退仓公司、操作员未进入当前列表，见 UNKNOWN |
| 装柜清单 | 操作、仓库、清单号、集装箱号、柜号、状态、总箱/毛重/净重/体积/数量、备注、创建人/时间 | 操作第一且左固定；明细分列客户备注、内部备注、仓库备注，仅仓库备注可编辑 | `ConfirmedSummary` 及 `ConfirmedDetail.items/histories`；三备注随 `FirstLegLoadingPlanCompletedV2` 下发 | 同一计划 PDA 完成后生成的 COMPLETED 清单 | `LANDED_STATIC`：仓库备注 EDITING/LOADING PATCH，COMPLETED 只读 |
| 订舱 | 委托单位、主票号、放舱、MB/L 当事方、港口、箱量、船公司、截关、ETD/ATD/ATA、船名航次、订舱代理、退仓、单号、操作员、状态 | 操作第一且左固定；订舱号、客户、船公司、代理、船名航次、港口、ETD/ETA、状态、更新时间 | `OceanBookingDtos.Detail`：`oceanBooking/parties/containerRequirements/containers/histories`；DRAFT 可部分保存，RELEASED 完整冻结，订舱本身不登记 `containerNo` | `ocean-bookings` 本轮 DRAFT 编辑及完整放舱；港口关联后 `containers` 才回显 allocation | `LANDED_STATIC`；截关/ATD/ATA、退仓公司、操作员未进入当前列表，见 UNKNOWN |
| 船期 | 原型订舱区域提供船名、航次、港口和关键时间 | 操作第一且左固定；船期号、来源、船名航次、港口、ETD/ETA、观测/更新时间、过期 | `ScheduleView.schedule+expired`，含来源、港口、ETD/ETA、截单/截关/截港、观测和过期时间 | `phase3-port-schedules` 本轮正式订舱关联观测 | `LANDED` |
| 拖车 | 派车单号、运输公司、司机、车头号、门店、应付/应收、预计装箱、状态、附件、操作 | 操作第一且左固定；预约号、柜号、客户、运输公司、司机、车辆、门店、计划装货、状态、附件、更新时间 | `TruckAppointmentEntity` 及附件端点；客户和 ACTIVE TRUCKING 承运商为必填快照，订舱/柜次/计划/仓库为可选关联 | `truck-appointments` 使用同 marker 客户独立开立，不借订舱；上传正式附件并完成自身状态机；另以本轮柜次执行计划不匹配负向 | `LANDED`；附件列来自独立附件接口，不伪造实体字段 |
| 拖车 | 派车单号、运输公司、司机、车头号、门店、应付/应收、预计装箱、状态、附件、操作 | 操作第一且左固定；预约号、柜号、客户、运输公司、司机、车辆、门店、计划装货、状态、附件、更新时间 | `TruckAppointmentEntity` 及附件端点；客户和 ACTIVE TRUCKING 承运商为必填快照，订舱/柜次/计划/仓库为可选关联；DISPATCH 前强制提单号与有效 `BILL_OF_LADING` | `truck-appointments` 使用同 marker 客户独立开立，覆盖无提单拒绝、正式提单上传及自身状态机 | `LANDED_STATIC`；附件列来自独立附件接口，不伪造实体字段 |
| 报关协同 | 模块 13 的传统报关/清关表包含订单、客户、状态、资料与时间等历史字段 | 操作第一且左固定；报关编号、订单/入库关联、资料清单及版本、状态、更新时间 | `CustomsCaseEntity` 与聚合详情的 documents/supplements/submissions/receipts/histories | `phase3-customs` 本轮实际订单、入库、柜次及不可变清单版本 | `LANDED_WITH_OVERRIDE`：当前“报关协同”模型覆盖历史原型；客户名和文件摘要见 UNKNOWN |
| 国内出仓 | 模块 04 为海外末端派送原型，非当前国内出仓门禁模型 | 操作第一且左固定；入库单、客户、柜号、订舱/拖车/PDA 状态、出仓状态、门禁 | `OutboundDispatchDtos.Aggregate/Detail` 的订单、入库、客户、柜次、计划、PDA、订舱、拖车、状态、版本和 gate/timeline | `phase3-outbound-dispatch` 同 marker LOADED 柜次聚合 | `LANDED_WITH_OVERRIDE`：当前确认契约优先；Admin“柜号”列实际绑定 `containerNo`，建议文案校准 |
三期/货柜管理全链验收矩阵-2026-08-13.md
+31 -20
View File
@@ -19,10 +19,10 @@
| 数据代号 | 必备状态/形态 | 生成前置 | 自动化断言 | 人工可点击入口 | 当前状态 |
|---|---|---|---|---|---|
| CT-D01 | 线下已确认订舱登记 N 个真实柜 | 创建请求必须携带五项运输快照及 `containers[1..20]`；每柜唯一 `containerNo` 和固定规格 | 同一事务直接产生 `CONFIRMED`、N 个 quantity=1 requirement、N 个 `OCEAN_BOOKING/ACTIVE` 操作柜及 N 个 allocation；任一柜失败整单零写入 | 订舱和货柜列表均可逐柜打开 | 已冻结，待环境验收 |
| CT-D01 | 订舱 DRAFT 登记柜型需求并最终放舱 | DRAFT 可部分保存/编辑/删除；完整资料含五项运输事实及 `containerRequirements(type/kind/quantity/spec)` | release 完整性校验后进入 `RELEASED` 并冻结；订舱不含 `containerNo`，不生成货柜或 allocation | 订舱列表/详情仅显示 DRAFT、RELEASED | `LANDED_STATIC`，待环境验收 |
| CT-D02 | 不同渠道各一单 | 渠道主数据可用 | 柜次/清单/任务不得跨渠道混装或串查 | 排柜候选可按渠道辨识 | 待契约 |
| CT-D03 | 内部模拟柜已排货、已 push，但无真实柜号/订舱 | 正式装柜仓库、ACTIVE 物流渠道、箱型和容量可用 | 服务端生成稳定 `containerBookingId/cabinetNo`；同仓同渠道 WAIT_SPLIT 可排；无号 `push-preload` 成功并冻结明细、建立唯一 bridge、使预装 `EDITING` 可见，但 PDA 查询必须为 `A0404` | 货柜列表可新增模拟柜，预装清单显示待关联/待补号 | 新时序已冻结，待环境验收 |
| CT-D04 | 模拟柜合并真实柜、订舱放舱且预装已确认，PDA 可领取 | CT-D03；选择未消费 `OCEAN_BOOKING/ACTIVE` 真实柜合并；订舱进入 `RELEASED`；预装进入 `CONFIRMED` | link 将真实柜号/订舱/规格快照原子复制到原模拟柜，任务四元身份只使用存活的模拟柜 ID；三项前置任缺一项都无 PDA，claim 后才进入 `LOADING` | PDA 任务列表可进入 | 新合并契约已冻结，待环境验收 |
| CT-D04 | 港口真实柜号关联、订舱放舱且预装已确认，PDA 可领取 | CT-D03；订舱 `RELEASED`；港口取得唯一 `containerNo`；选择未满配 `requirementId`；预装进入 `CONFIRMED` | link 四字段在原模拟柜上补齐订舱、真实柜号和运输快照并创建 allocation；四元身份稳定，三项前置任缺一项都无 PDA，claim 后才进入 `LOADING` | PDA 任务列表可进入 | `LANDED_STATIC`，待环境验收 |
| CT-D05 | 作业中更换真实柜号 | CT-D04，PDA 已开始 | 柜号变化但柜次 ID、任务、清单、证据归属不漂移 | 详情与 PDA 同步显示新柜号 | 待契约 |
| CT-D06 | 预装清单已生成/确认 | CT-D03 | push 后 `EDITING` 清单可补真实柜号；订舱 `RELEASED` 后通过计划级 `/loading-plans/{loadingPlanId}/confirm` 原子确认全部关联预装票据，返回 `confirmationStatus=CONFIRMED`、`readyForPda=true` 和唯一 `pdaTaskId`；版本、明细、数量及确认历史可追溯 | 预装清单列表/详情可点击 | 计划级确认已冻结，待环境验收 |
| CT-D07 | 装柜清单进行中/已完成 | CT-D04 | 装载明细、数量、状态与预装来源一致 | 装柜清单列表/详情可点击 | 待契约 |
@@ -38,10 +38,10 @@
| 用例 | 场景 | 服务端/契约断言 | UI/设备断言 | 证据要求 | 状态 |
|---|---|---|---|---|---|
| CT-E01 | 模拟柜原地合并真实订舱柜 | 订舱创建的真实柜先以 `OCEAN_BOOKING/ACTIVE` 出现在货柜列表；link 请求只传 `realContainerBookingId+expectedVersion`，成功后模拟柜 ID/cabinetNo/计划/明细稳定，来源变 `MERGED` 且 allocation 改指模拟柜 | 货柜详情只显示合并后的一个可操作身份 | link 前后柜次、计划、明细、allocation 及 ACTIVE 列表唯一性快照 | 已冻结，待环境验收 |
| CT-E01 | 模拟柜原地关联 RELEASED 订舱需求 | link 请求为 `oceanBookingId+requirementId+containerNo+expectedVersion`；成功后模拟柜 ID/cabinetNo/计划/明细稳定并新建 allocation，不存在中间真实柜 | 货柜详情只显示关联后的一个可操作身份 | link 前后柜次、计划、明细、allocation 及 ACTIVE 列表唯一性快照 | `LANDED_STATIC`，待环境验收 |
| CT-E02 | 渠道隔离 | 不同渠道不能进入同一排柜结果；交叉 ID 请求失败 | 候选、清单和详情不串渠道 | 双渠道正向及交叉负向响应 | 待契约 |
| CT-E03 | 无真实柜号排柜与 push | 临时身份可完成排柜；`push-preload` 在无 `containerNo` 时成功，只冻结计划、建立 bridge、开放 `EDITING` 预装，不创建 PDA；exact replay 原样返回且计划/版本/历史/link/task 零漂移 | 页面明确展示待补号，不伪造柜号 | push 原始 path/body/key、重放前后全快照、PDA `A0404` | 新时序已冻结，待环境验收 |
| CT-E04 | 合并及三项前置开放 PDA | 无号 push 后仍无 PDA；未合并真实柜、订舱未 `RELEASED`、预装未 `CONFIRMED` 分别查询 PDA 均为 `A0404`；合并本身带入唯一真实柜号，最后一个前置完成后仅生成一个 task，claim 才推进 `LOADING` | 关联、放舱、确认前后 PDA 入口状态同步 | 三个逐项负向、唯一 task 四元身份、禁止 MERGED 来源 ID、claim 前后状态 | 新合并契约已冻结，待环境验收 |
| CT-E04 | 四字段关联及三项前置开放 PDA | 无号 push 后仍无 PDA；未关联、订舱未 `RELEASED`、预装未 `CONFIRMED` 分别查询 PDA 均为 `A0404`；关联时录入唯一真实柜号，最后一个前置完成后仅生成一个 task，claim 才推进 `LOADING` | 关联、放舱、确认前后 PDA 入口状态同步 | 三个逐项负向、唯一 task 四元身份、claim 前后状态 | `LANDED_STATIC`，待环境验收 |
| CT-E05 | 作业中换号身份不漂移 | 只变更展示柜号；柜次 ID、任务 ID、清单、证据关联不变 | Admin/PDA 刷新后显示新号且进度不丢 | 换号前后关联快照 | 待契约 |
| CT-E06 | 预装/装柜清单 | push 自动生成/关联预装聚合；仅允许按 `loadingPlanId` 原子确认整份计划，禁止旧单票 `/preload/confirming`、`/preload/confirm`；返回唯一 task 后 claim 才进入 `LOADING` | 两类列表和详情均可人工点击 | `PENDING -> EDITING -> CONFIRMED`、计划版本、readiness、taskId、幂等重放与历史 | 计划级确认已冻结，待环境验收 |
| CT-E07 | PDA 主链 | 领取、扫码、批量提交、复核、完成；幂等与版本冲突有效 | 真机/目标设备可完成，失败不假成功 | 请求链、设备记录 | 待契约 |
@@ -77,6 +77,18 @@
| 可选计划 | `loadingPlanId` 仅能与 `containerBookingId` 同时提供，且必须是该柜次当前计划 | 同 marker 柜次派生错误计划 ID 的 HTTP 负向已接线 |
| PDA 隔离 | 未关联拖车不受 PDA 影响；同柜零/一/多条均不阻断 PDA 主事务；唯一拖车同步失败也只影响拖车自身 | 静态合同已锁定提交后同步与独立事务；部署后按零/一/多 fixture 验证 |
| Admin 表单 | 客户、承运商、预计装箱时间必填；订舱和柜次明确标注可选，清空后不得残留派生计划/仓库/客户 | Admin 静态合同已接线 |
| 派车提单门禁 | DRAFT 可先独立开立；DISPATCH 前必须有 `billOfLadingNo` 和有效 `BILL_OF_LADING` 文件，缺任一项明确拒绝 | `truck-appointments` 已覆盖缺失拒绝、正式上传/回查与完整自身状态机；待部署后 HTTP |
## 装柜清单三备注
| 验收点 | 冻结契约 | 自动化证据 |
|---|---|---|
| 来源隔离 | `customerRemark` 来自订单客户备注；`internalRemark` 来自最新内部备注，禁止冒用 `cargoRemark` | `orders` 写入三条互异 marker；`phase3-loading` 精确比较来源与非串值 |
| 仓库备注 | `warehouseRemark` 仅在 EDITING/LOADING 通过正式 item PATCH 维护；空白归一化为 null | 覆盖保存、空白清空、版本递增、旧版本 A0409 后回查零漂移 |
| 幂等与终态 | 同 operationId 同参数精确重放不重复递增；异参冲突；COMPLETED 后 A0409 且零写 | OpenAPI/Service 静态合同已锁定；COMPLETED HTTP 负向待部署后与 finalize 串联 |
| 动态增量 | assignment/数量调整/删除不得覆盖已有仓库备注 | `phase3-loading` 在 LOADING 增量前后断言原明细仓库备注保持，调整明细备注保持 |
| 海外事件 | `FirstLegLoadingPlanCompletedV2` 每个 item 含 customer/internal/warehouse 三备注，事件哈希与幂等基于同一稳定 payload | `loading-list-remarks-contract.test.mjs` 锁定 V2 类型与三字段映射；海外消费者仓库不在本仓，列为跨仓部署依赖 |
| Admin | 客户/内部备注只读，仅仓库备注显示编辑入口；COMPLETED 隐藏编辑 | Admin 静态合同已锁定 |
- 结算版本缺陷证据：task `2089254643058184193`、inbound `2089181999189299202` 在 taskVersion=1/inboundVersion=6、PICKED 2/2 与五证据齐备时返回 A0409；requestId=`12a913ba-9845-45f6-91ec-bdba28e3eb9d`、traceId=`395d11b5c0da45eca948a39a08e29d3d`。回归锁定 settle 后重新读取 full/partial 实际完成分片版本；真实并发仍冲突，失败必须零写入。
## PDA 进行中增量预装冻结回归
@@ -92,9 +104,9 @@
## P3-Q14 文档同步待总控统一
- 当前冻结验收时序以用户最新确认的“两类柜并存”为准：订舱逐柜登记会生成可直接排货的 `OCEAN_BOOKING/ACTIVE` 真实柜；未订舱时也可先建 `SIMULATION/ACTIVE` 模拟柜并排货、无号 push，之后按 `realContainerBookingId` 原地合并一个未消费真实柜。
- `docs/三期/三期需求确认表.md` 的 P3-Q14 尚未完整描述 `SIMULATION/ACTIVE -> 合并 -> OCEAN_BOOKING/MERGED` 的来源/状态模型。本任务不擅改需求确认表，标记为 `WAIT_CONTROLLER_DOC_SYNC`，由总控统一文档；本矩阵及自动化以当前冻结 DTO/OpenAPI 为准。
- P3-Q14 关于“五项运输快照在订舱创建时冻结、`RELEASED` 不覆盖首次快照”的部分无冲突，继续作为验收基线。
- 当前冻结验收时序：订舱只登记 `containerRequirements` 并在完整 release 后进入 `RELEASED`；不会生成真实货柜。未订舱时先建 `SIMULATION/ACTIVE` 模拟柜并排货、无号 push，港口取得真实 `containerNo` 后用四字段 link 原地补全模拟柜并创建 allocation。
- `docs/三期/三期需求确认表.md` 的 P3-Q14 尚未完整描述新的 DRAFT/RELEASED 与港口四字段关联模型。本任务不擅改需求确认表，标记为 `WAIT_CONTROLLER_DOC_SYNC`，由总控统一文档；本矩阵及自动化以当前冻结 DTO/OpenAPI 为准。
- 五项运输事实保存在 DRAFT 聚合，release 只校验完整性并冻结持久化快照；RELEASED 不接受编辑或删除。
## 契约冻结清单
@@ -104,10 +116,10 @@
| 能力标识 | 冻结边界 | 事实来源 | 状态 |
|---|---|---|---|
| `booking-real-containers-and-simulation-merge` | 订舱按 `containers[]` 原子生成真实柜；模拟柜是独立预排货能力；link 消费一个真实柜并保留模拟柜稳定身份，正常列表只返回 ACTIVE | `PlatformContainerController`、`ContainerService`、`OceanBookingService`、`firstleg-v1.yaml`、`ocean-bookings-v1.yaml` | 本轮目标冻结，待环境验收 |
| `booking-requirements-and-port-link` | 订舱按 `containerRequirements[]` 保存箱型数量，不生成真实柜；link 在港口取得真实柜号后补全模拟柜并创建 allocation | `PlatformContainerController`、`ContainerService`、`OceanBookingService`、`firstleg-v1.yaml`、`ocean-bookings-v1.yaml` | 本轮目标冻结，待环境验收 |
| `channel-isolation` | 渠道隔离与禁止跨渠道混装 | 三期产品确认版及既有排柜契约 | 既有冻结，待环境验收 |
| `container-number-lifecycle` | 模拟柜无真实柜号允许排柜及 push；push 本身不开放 PDA；link 从未消费真实柜带入唯一 `containerNo`，内部柜、计划、bridge 身份稳定；作业中换号身份稳定 | `ContainerService`、`SmartLoadingService`、`SplitPreloadService`、`LoadingListService`、相关 OpenAPI 与合同测试 | 新时序已冻结，待环境验收 |
| `preload-and-loading-list` | `PENDING -> EDITING -> CONFIRMED`；计划级确认原子确认全部关联票据并唯一建 task；存活 ACTIVE 柜已合并 `RELEASED` 订舱、真实柜号和 readiness 全部满足后 `readyForPda=true`，claim 才推进 `LOADING` | `LoadingListService.confirmPreload`、`LoadingPickService`、`POST /loading-plans/{planId}/confirm` 及 Loading List OpenAPI/DTO | 计划级确认已冻结，待环境验收 |
| `preload-and-loading-list` | `PENDING -> EDITING -> CONFIRMED`；计划级确认原子确认全部关联票据并唯一建 task；ACTIVE 模拟柜已关联 `RELEASED` 订舱需求、真实柜号和 readiness 全部满足后 `readyForPda=true`，claim 才推进 `LOADING` | `LoadingListService.confirmPreload`、`LoadingPickService`、`POST /loading-plans/{planId}/confirm` 及 Loading List OpenAPI/DTO | 计划级确认已冻结，待环境验收 |
| `customs-documents-lock` | 清关/报关专用流程、完成态禁止替换 | 既有 `LoadingListService`、专用 Controller 与专项测试 | 既有冻结，待环境验收 |
### 本轮新增冻结契约
@@ -172,7 +184,7 @@
| 平台渠道目录 | `GET /api/platform/v1/ocean-bookings/channels?originWarehouseId=...` 只返回当前 ACTIVE 价格簿渠道；HTTP fixture 记录本轮 marker、`originWarehouseId` 与服务端路径，不借 Merchant 身份或历史资源 | OpenAPI 已冻结；真实查询生产者已发布 `createdResources.platformLogisticsChannels` |
| 双有效渠道 fixture | 跨渠道负向必须使用同一起运仓下两个真实有效渠道；只有一个有效渠道时输出 `BLOCKED_FIXTURE`，禁止派生 `-OTHER` 伪渠道 | 脚本门禁与正式渠道生产者已落地；待环境数据验证是否存在双渠道 |
| 船公司与物流渠道独立 | `shippingCompanyId/shippingCompanyName` 与渠道选择分别建模，不用船公司字段代替渠道字段 | `LANDED`：Admin 与写请求模型分别承载船公司和物流渠道，静态合同已转绿 |
| `CONFIRMED` 柜次继承渠道 | 订舱确认生成柜次后，货柜详情 `channelCode` 必须等于所选有效渠道；异渠道入库单不能分配到该柜次 | 既有 HTTP 断言保留；异渠道负向已移除伪渠道来源；写 DTO 不再发送服务端拥有的 `channelName` |
| 关联柜继承渠道 | 港口 link 后货柜详情 `channelCode` 必须等于 RELEASED 订舱的有效渠道；异渠道入库单不能分配到该柜次 | HTTP 断言已准备；异渠道负向只使用真实 ACTIVE 渠道；写 DTO 不发送服务端拥有的 `channelName` |
## 订舱资料字段与可选客户增量
@@ -183,12 +195,12 @@
| `serviceTerm` | 原型第 516 行以 `*` 标记主要运输条款必填；P3-Q14 未删除该业务快照 | Admin 必填自由文本；Java `@NotBlank`；OpenAPI `required` 且非 nullable；模块基线和统一 SQL 均为 `NOT NULL`；不保留无来源的 `CY-DOOR/DOOR-CY/DOOR-DOOR` 自造字典；验收 fixture 使用原型展示值 `CY-CY` | `LANDED` |
| `freightTerm` | 原型第 518 行以 `*` 标记运费条款必填；示例值为 `NINGBO`，不构成枚举事实来源 | Admin 必填自由文本；Java `@NotBlank`；OpenAPI `required` 且非 nullable；模块基线和统一 SQL 均为 `NOT NULL`；不保留无来源的 `PREPAID/COLLECT` 自造字典；验收 fixture 使用原型展示值 `NINGBO` | `LANDED` |
| 可选客户 | 原型第 527 行“客户/公司名称”无必填标记；当前产品确认允许平台先建订舱后关联客户 | Admin 可清空选择；前端类型、Java DTO 与 OpenAPI 均允许 `customerId/customerName` 同时为空，单边填写必须拒绝 | `LANDED` |
| 无客户 HTTP fixture | 不以历史客户或占位 ID/名称替代可空契约 | `ocean-bookings` 使用本轮 marker、正式渠道和仓库创建无客户订舱，详情回读真实 `bookingNo` 后按订舱号查询列表，断言空客户快照、`CONFIRMED` 及稳定柜次；发布 `createdResources.oceanBookingUnassignedCustomer` | 已准备，待部署后 HTTP 验收 |
| 可选客户合同 | 不以历史客户或占位 ID/名称替代可空契约 | 共享 builder 保留无客户能力；当前默认 `ocean-bookings` 主链使用正式可选客户字段并验证 DRAFT/RELEASED，不生成柜次 | 离线合同已覆盖；独立无客户 HTTP 链待总控决定 |
| 指定客户隔离链 | 保留来自本轮入库单的正式客户范围 | `phase3-container-loading` 与既有订舱主链继续断言客户、仓库、渠道一致和跨渠道拒绝，不借历史资源 | 已准备，待部署后 HTTP 验收 |
| 提单号、船名、航次、ETD、ETA | 原型存在相关展示/录入字段；最新 P3-Q14 确认线下已订妥资料在创建订舱时完整登记，创建直接进入 `CONFIRMED`；`RELEASED` 仅作为后续放舱/PDA 门禁，不覆盖首次快照 | 创建 payload、持久化详情和列表必须完整携带五字段并返回 `CONFIRMED`；正常路径不得再调用订舱 `/submit`、`/confirm`；后续 `ReleaseRequest` 仍须携带五字段且不得改变首次快照 | `LANDED` |
| 提单号、船名、航次、ETD、ETA | 原型存在相关展示/录入字段；DRAFT 可部分保存，release 前必须补齐 | 五字段属于持久化 DRAFT；`ReleaseRequest` 只传 `expectedVersion`，服务端校验并冻结已存快照；RELEASED 不可修改 | `LANDED_STATIC` |
| 单证号 | 原型第 529 行存在“单证号”，但当前阶段 DTO/OpenAPI 未冻结对应写字段 | 不猜字段名或复用提单号；本轮不扩展写契约 | 非本轮能力，不标记接口阻断 |
离线合同：`ocean-booking-prototype-contract.test.mjs` 锁定原型证据、跨端可选客户、条款字段、创建即确认和放舱门禁时序；`ocean-booking-fixture-contract.test.mjs` 与 `full-regression-entry-contract.test.mjs` 锁定无客户/指定客户双链和默认编排。DRAFT/SUBMITTED/FAILED 不再作为订舱人工矩阵的可稳定生成状态，仅保留正式列表负向覆盖。
离线合同：`ocean-booking-prototype-contract.test.mjs` 锁定原型证据、跨端可选客户、DRAFT 编辑与 release 完整性门禁；`ocean-booking-fixture-contract.test.mjs` 与 `full-regression-entry-contract.test.mjs` 锁定 `containerRequirements` 和默认编排。订舱正式状态仅为 DRAFT/RELEASED。
## 内部模拟柜关联真实订舱增量
@@ -196,15 +208,14 @@
| 验收项 | 自动化断言 | 当前结论 |
|---|---|---|
| 正式订舱列表 | 仅允许 `CONFIRMED/CHANGE_PENDING/RELEASED/CANCELLED`；`DRAFT/SUBMITTED` 查询失败且默认列表不返回未确认记录；内部模拟柜不进入订舱列表 | 契约与 HTTP fixture 已落地，待部署后验证 |
| 正式订舱列表 | 仅允许 `DRAFT/RELEASED`；DRAFT 可编辑删除，RELEASED 不可编辑删除；内部模拟柜不进入订舱列表 | 契约与 HTTP fixture 已落地，待部署后验证 |
| 新增内部模拟柜 | `POST /api/platform/v1/containers` 只接收正式装柜仓库、当前 ACTIVE 物流渠道、箱型、容量和限重；不接收真实柜号或订舱；服务端生成稳定 `containerBookingId/cabinetNo` | 契约与 HTTP fixture 已落地，待部署后验证 |
| 订舱逐柜建柜 | `POST /ocean-bookings` 必填 `containers[1..20]`；一单至少两柜 fixture 逐项断言唯一柜号、固定规格、独立 requirement/allocation、`OCEAN_BOOKING/ACTIVE` 身份及订舱/货柜列表一致；请求内重复号、全局重复号、行数或规格错误均整单零写入 | DTO/OpenAPI/静态合同及 HTTP fixture 已落地，待部署后验证 |
| 真实柜直接排货 | 未经过模拟柜时，订舱生成的 `OCEAN_BOOKING/ACTIVE` 真实柜本身可创建计划并接收同仓同渠道货物 | 静态契约已冻结；部署后补定向 HTTP 正向 |
| 排货后首次合并 | 同仓、同渠道、箱型/容量/限重及指定客户范围一致时，已有预排货的 `SIMULATION/ACTIVE` 模拟柜可用 `{realContainerBookingId,expectedVersion}` 合并；模拟柜 `containerBookingId/cabinetNo/loadingPlan/items` 不变，真实柜号与运输快照补入 | 契约与 HTTP fixture 已落地，待部署后验证 |
| ACTIVE 唯一操作身份 | 合并后来源真实柜置 `MERGED`、清空 `containerNo`、`mergedIntoContainerBookingId` 指向模拟柜，allocation 改指模拟柜；正常列表/详情只返回一条存活 ACTIVE 操作柜，PDA 禁止使用 MERGED 来源 ID | 静态合同与 HTTP 列表/详情断言已落地，待部署后验证 |
| 隔离与唯一占用 | 跨仓、跨渠道、箱型/容量/限重/客户范围不匹配拒绝；同一 `realContainerBookingId` 在 MERGED 时不可再次关联；所有失败必须保持柜、计划、明细、allocation 和列表零漂移 | 静态合同已锁定；双渠道和主要 HTTP 负向待部署后验证 |
| 订舱柜型需求 | `POST /ocean-bookings` 保存 `containerRequirements(type/kind/quantity/capacityCbm/maxWeightKg)`；不接收真实柜号，不创建货柜/allocation | DTO/OpenAPI/静态合同及 HTTP fixture 已落地，待部署后验证 |
| 港口逐柜关联 | 真实柜号取得后，对已有 `SIMULATION/ACTIVE` 柜调用 `{oceanBookingId,requirementId,containerNo,expectedVersion}`；模拟柜 `containerBookingId/cabinetNo/loadingPlan/items` 不变 | 契约与 HTTP fixture 已落地，待部署后验证 |
| ACTIVE 唯一操作身份 | link 直接补全原模拟柜并创建 allocation；不存在另一条真实柜或 MERGED 中间记录 | 静态合同与 HTTP 列表/详情断言已落地，待部署后验证 |
| 隔离与唯一占用 | 跨仓、跨渠道、箱型/容量/限重/客户范围不匹配、需求超量或重复柜号拒绝；所有失败保持柜、计划、明细、allocation 和列表零漂移 | 静态合同已锁定；双渠道和主要 HTTP 负向待部署后验证 |
| 首次关联不可逆门禁 | 存在 PDA、有效装柜证据、业务单证或已进入 `LOADING/COMPLETED` 时首次 link 拒绝 | 服务端静态门禁已锁定；需部署后以独立 marker fixture 验证 |
| 解绑与换绑 | 服务端仍仅允许完全空的 `WAIT_LOADING` 合并柜执行原子 unlink，并恢复来源为 ACTIVE；一旦已有排货、PDA、证据或单证事实，unlink/rebind 均拒绝 | 静态门禁已锁定；排货后负向 HTTP fixture 已落地，待部署后验证 |
| 全量编排 | 默认入口先运行 `phase3-container-loading` 完成“模拟柜新增 -> 同仓同渠道排货 -> 首次 link -> PDA”，再由证据、finalize、出仓模块沿本轮 marker 的稳定 ID 继续；禁止历史数据和 mock 回退 | Node 入口合同已锁定，待默认全量 HTTP 验证 |
离线合同：`container-simulation-association-contract.test.mjs` 锁定跨层契约及全量顺序；`phase3-producer-chain-contract.test.mjs`、`phase3-order-splitting-contract.test.mjs`、`ocean-booking-channel-contract.test.mjs` 锁定现有生产者不再依赖 `CONFIRMED` 自动建柜。
离线合同：`container-simulation-association-contract.test.mjs` 锁定跨层契约及全量顺序；`phase3-producer-chain-contract.test.mjs`、`phase3-order-splitting-contract.test.mjs`、`ocean-booking-channel-contract.test.mjs` 锁定生产者只使用 DRAFT/RELEASED、需求关联且不在订舱阶段自动建柜。