docs/三期/货柜履约原型字段验收矩阵-2026-08-17.md

货柜履约原型字段验收矩阵

更新时间：2026-08-18 范围：货柜、预装/装柜清单、订舱、船期、拖车、报关协同与国内出仓列表。 口径：原型只提供字段与交互参考；当前确认契约、后端 DTO/OpenAPI 和已落地 Admin 优先。UNKNOWN 不生成假值、不改名借用其他字段，也不以空值通过验收。

跨列表统一门禁

• 操作列必须是第一业务列并固定左侧；原型中拖车、预装把操作列放在末尾的布局由当前统一表格规则覆盖。
• 平台内部业务单号统一为 前缀-YYMMDD-NNNN，按北京时间创建日、单据类型分别从 0001 递增：订舱 OB、派车单 TA、内部货柜登记 CB、稳定柜次 CAB、预装/装柜清单 LP。预装确认后沿用同一 LP 编号，不因状态变化更换身份；真实集装箱号、提单号等外部编号不适用本规则。
• 柜号/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 仅在测试环境重新部署且当前对话明确授权后执行。