44 lines
7.5 KiB
Markdown
44 lines
7.5 KiB
Markdown
# 货柜履约原型字段验收矩阵
|
||
|
||
> 更新时间：2026-08-17
|
||
> 范围：货柜、预装/装柜清单、订舱、船期、拖车、报关协同与国内出仓列表。
|
||
> 口径：原型只提供字段与交互参考；当前确认契约、后端 DTO/OpenAPI 和已落地 Admin 优先。`UNKNOWN` 不生成假值、不改名借用其他字段，也不以空值通过验收。
|
||
|
||
## 跨列表统一门禁
|
||
|
||
- 操作列必须是第一业务列并固定左侧；原型中拖车、预装把操作列放在末尾的布局由当前统一表格规则覆盖。
|
||
- `柜号/cabinetNo` 是平台稳定柜次编号，`集装箱号/containerNo` 是真实物理柜号，两者不得互换。模拟柜可以没有 `containerNo`，真实柜、完成装柜清单和国内出仓聚合必须有。
|
||
- 客户、仓库、渠道、船公司、订舱/拖车/报关供应商名称只能来自服务端冻结快照或正式主数据，不由 fixture 自造名称。
|
||
- ID 使用正整数；数量、重量和体积为非负数；关键时间必须可按 ISO-8601 解析；有供应商 ID 时名称必须非空，无 ID 时不得伪造名称。
|
||
- 文件、异常、轨迹只在正式聚合提供摘要时断言；原型出现但 DTO 未提供的摘要登记为 `UNKNOWN`。
|
||
|
||
## 列表逐字段矩阵
|
||
|
||
| 列表 | 原型字段 | Admin 当前列 | 后端事实字段 | 真实 fixture 来源 | 结论 |
|
||
|---|---|---|---|---|---|
|
||
| 货柜 | 操作、集装箱号、装柜清单号、状态、异常、柜号、清关/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`；三备注随 `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 承运商为必填快照，订舱/柜次/计划/仓库为可选关联；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`，建议文案校准 |
|
||
|
||
## UNKNOWN 登记
|
||
|
||
| 批次 | 字段/摘要 | 当前缺口 | 验收处理 |
|
||
|---|---|---|---|
|
||
| U1 | 货柜列表清关、DO、PU、异常、轨迹摘要 | overview/专项详情有事实，但货柜列表 DTO 未冻结对应摘要字段 | 不向列表脚本注入假摘要；专项 overview 继续验文件下载、异常历史和轨迹 |
|
||
| U1 | 订舱列表截关、ATD、ATA、退仓公司、操作员 | 原型存在，当前列表与 `OceanBookingDtos` 未全部公开 | 不复用 ETA/更新时间代替；待产品确认是否进入列表 |
|
||
| U1 | 报关列表客户名称、文件/补件/回执摘要 | 实体仅有隔离键，聚合详情有文件事实，列表聚合未冻结这些摘要 | 只断言订单/入库/柜次和清单版本；待列表 DTO 冻结 |
|
||
| U2 | 国内出仓“柜号”展示语义 | Admin 列标题为“柜号”，绑定的是物理 `containerNo` | 合同按 `containerNo` 验值；建议 Admin 文案改为“集装箱号”或同时展示 `cabinetNo` |
|
||
| U2 | 清关列表 | 当前目的港清关走货柜 `/clearance` 专项权限/路径，没有独立、已冻结的清关列表 DTO | 继续详情级验收，不猜独立列表接口 |
|
||
|
||
## 自动化接入
|
||
|
||
- `fulfillment-list-field-contract.mjs` 提供八类正式响应的非空、ID、数值与时间格式投影；可选字段使用成对约束，不把 UNKNOWN 强制为必填。
|
||
- `phase3-container-loading` 对 ACTIVE 货柜、预装清单和完成装柜清单执行字段断言。
|
||
- `ocean-bookings`、`phase3-port-schedules`、`truck-appointments`、`phase3-customs`、`phase3-outbound-dispatch` 在既有本轮资源响应上执行字段断言，不增加历史查询或伪造回退。
|
||
- 默认 Admin 全量入口已包含上述生产模块；真实 HTTP 仅在测试环境重新部署且当前对话明确授权后执行。
|