优化

README.md

@@ -8,6 +8,7 @@
 - [二期文档](二期/README.md)：预约取货、到仓收货、实测差异和指定库位闭环。
 - [三期文档](三期/README.md)：智能排柜、订舱、拖车、PDA 拣货、报关协同和国内出仓闭环。
 - [四期文档](四期/README.md)：国内出仓后的船节点定时查询、海外接柜、合作仓卸货入库、库存与库内操作，以及海外采购、本土卡车和本土散板；不包含海外仓出库业务。
+  - [船节点标准化契约](四期/船节点标准化契约.md)：统一船司原始状态、十个标准节点、预计/实际时间、异常事实、还柜停止规则和新增船司接入门禁。
 - [独立任务协作登记](独立任务协作登记.md)：只维护总控与用户可见独立任务的稳定 `task_id`、父子关系和职责范围，不记录动态进度或归档状态。
 
 ## 跨阶段参考

四期/README.md

@@ -3,7 +3,7 @@
 ## 已确认业务边界
 
 - 一期、二期、三期覆盖国内头程仓内操作，三期完成装柜及国内出仓交接；柜子确认离开国内仓库后的节点查询不属于三期。
-- 四期从柜子确认国内出仓后开始定时查询船节点，持续跟踪国内出仓、港口、开航及海运在途节点，直到目的港到达并为海外提柜提供依据；海外仓作业继续覆盖安排车辆提柜、运抵合作海外仓、卸货、入库、形成库存和库内操作。
+- 四期从柜子确认国内出仓后开始定时查询船节点，持续跟踪国内出仓、港口、开航、海运在途、到港、卸船、清关、提柜及还柜事实；统一语义和停止规则见[船节点标准化契约](船节点标准化契约.md)。海外仓作业继续覆盖安排车辆提柜、运抵合作海外仓、卸货、入库、形成库存和库内操作。
 - 四期止于海外仓库存和库内作业，不包含海外仓出库单、出库履约、海外派送或其他库存离仓业务。
 - “尾程订单”属于本期已确认的订单管理范围，但不得据此把海外仓出库、派送履约或 `海外派送` 原型模块整体纳入四期。
 - 历史文档中把高级 BI、开放平台、移动端或性能优化称为“四期”的内容不再作为当前四期范围依据。
@@ -17,7 +17,7 @@
 | 海外业务 | 本土散板、采购订单、本土卡车；Admin 入口 `../../apps/admin-web/src/modules/overseas-business/` | 原型 `../悦/货代SAAS平台后台/prototype-src/modules/07-overseas-business.html`；Backend `../../baiyue-firstleg/lastleg-service/` 的 `procurement/`、`trucking/` 及后续本土散板子域 |
 | 头程仓库主数据 | 在现有仓库类型中增加“海外仓合作仓”；实际海外仓资源独立维护 | Admin `../../apps/admin-web/src/modules/warehouses/`；国内公共主数据 `../../baiyue-firstleg/warehouse/`；海外仓资源 `../../baiyue-firstleg/warehouse-overseas-service/` |
 | 通用资料 | 海外仓报价、汇率管理、车辆列表；Admin 入口 `../../apps/admin-web/src/modules/overseas-master-data/` | `../悦/货代SAAS平台后台/prototype-src/modules/10-general.html` |
-| 国内出仓后船节点 | 对已确认离开国内仓库的订舱/柜次定时查询船节点，保存最新节点和查询历史，并衔接目的港提柜 | Admin `../../apps/admin-web/src/modules/port-schedules/`、`ocean-bookings/` 及货柜详情；Backend `../../baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/portschedule/`、`../../baiyue-firstleg/integration-service/` |
+| 国内出仓后船节点 | 对已确认离开国内仓库的订舱/柜次定时查询船节点，保存最新节点、异常和查询历史，贯通目的港提柜至还柜事实 | 标准语义见[船节点标准化契约](船节点标准化契约.md)；Admin `../../apps/admin-web/src/modules/port-schedules/`、`ocean-bookings/` 及货柜详情；Backend `../../baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/portschedule/`、`../../baiyue-firstleg/integration-service/` |
 
 ## 原型页面定向索引
 
@@ -56,10 +56,12 @@
 
 ## 船节点定时查询边界
 
+- 所有供应商统一节点、时间语义、异常事实、停止规则和新增船司接入门禁以[船节点标准化契约](船节点标准化契约.md)为准；供应商缺失的节点保持缺失，不推测补齐。
+
 - 现有 `CarrierScheduleQuery` 查询任务及其查询尝试、历史、来源、过期标识和频率约束整体重新归入四期；不再把它列作三期港务/船期查询能力，也不得另建一套重复任务。
 - 定时查询对象必须关联真实订舱、柜次以及可用的船司/船名航次或跟踪标识，不建立脱离业务单据的孤立轮询任务。
 - Firstleg `portschedule/` 负责任务编排、业务关联、最新节点、节点历史、幂等和停止条件；`integration-service/` 只负责船司或轨迹供应商适配、限流、超时、重试和错误归一化，不保存业务主数据。
-- 查询从确认柜子离开国内仓库后开始，到确认目的港到达并完成海外提柜衔接后停止；失败不能伪造成功节点，需保留来源、观测时间、最近成功时间和失败原因。
+- 查询从确认柜子离开国内仓库后开始，贯通目的港到达、卸船、清关、提柜和还柜事实，默认在实际 `EMPTY_RETURNED` 后停止；这只扩展货柜轨迹事实，不纳入海外派送、海外仓出库或库存离仓业务。失败不能伪造成功节点，需保留来源、观测时间、最近成功时间和失败原因。
 - 现有“每 3 天一次、窗口最多 3 次”、六家船公司来源、最近有效结果和过期标识是同一查询能力的既有约束，归四期继续核对；后续若调整自动轮询频率、供应商额度、退避或停止规则，应只修改四期契约和这套任务。
 - 当前原型没有独立的“船节点定时查询”页面；涉及页面展示时从订舱、船期或货柜详情进入，不得为了匹配原型菜单把它归入海外派送。
 

四期/四期后端缺口清单.md

@@ -56,11 +56,11 @@
 ### 批次 1：到港衔接与接柜入仓最小闭环
 
 1. 在 Integration 建立标准船节点查询请求/响应、供应商错误归一、超时/限流/重试配置和内部服务令牌接口。
-2. 在 Firstleg 增加出仓后自动建任务、到期任务租约领取、重试/退避、标准节点幂等落库、目的港到达停止条件。
+2. 在 Firstleg 增加出仓后自动建任务、到期任务租约领取、重试/退避，并按[船节点标准化契约](船节点标准化契约.md)完成十个标准节点、异常事实、预计/实际时间、幂等落库和实际还柜停止条件。
-3. 新增“目的港到达/可提柜”版本化跨区事件；Lastleg Inbox 消费后建立接柜/入仓衔接事实。
+3. 新增目的港到达、卸船、可提柜、已提柜及已还柜的版本化跨区事实；Lastleg Inbox 按实际业务需要消费接柜/入仓衔接事实，不因中间节点缺失而补造事件。
 4. 补齐入仓单列表/详情、接柜/运抵/卸货状态，复用现有入仓计划、PDA 实收/上架和库存落账。
 
-验收终点：一条真实装柜/订舱/柜次链路从国内确认出仓，经节点查询，到港后在海外形成可操作入仓单，PDA 完成后生成库存；重复事件和重复任务不产生重复单或库存。
+验收终点：一条真实装柜/订舱/柜次链路从国内确认出仓，经节点查询，到港后在海外形成可操作入仓单，PDA 完成后生成库存，并持续记录提柜与还柜事实直至查询停止；重复事件和重复任务不产生重复节点、单据或库存。
 
 ### 批次 2：海外仓管理面闭环
 

四期/船节点标准化契约.md

@@ -0,0 +1,167 @@
+# 四期船节点标准化契约
+
+> 状态：已确认
+>
+> 确认日期：2026-08-21
+>
+> 适用范围：国内确认出仓后的船司轨迹查询、目的港提柜及还柜事实闭环
+
+## 1. 目的与适用边界
+
+本契约统一不同船司、港口和轨迹供应商的节点语义，防止后续逐家接入时因原始文案、字段数量或页面结构不同而改变平台业务含义。
+
+- 每家供应商保留自己的原始节点编码和文案，再映射到本契约的标准节点。
+- 供应商没有提供的标准节点保持缺失，不推测、不补造，也不要求所有船司返回相同数量的节点。
+- 四期船节点从国内确认出仓开始，持续记录至已还柜 `EMPTY_RETURNED` 后停止。
+- `PICKED_UP`、`EMPTY_RETURNED` 在本契约中只是货柜轨迹事实，不代表启用海外派送、海外仓出库或库存离仓业务。
+- Firstleg 拥有查询任务、标准节点、异常事实和停止条件；Integration Service 只负责供应商访问、解析、标准化和错误归一化。
+
+## 2. 标准节点
+
+标准节点使用固定递增序号。新增供应商只能映射这些节点；需要新增或修改节点时，必须先修改本契约并完成跨端同步。
+
+| 序号 | 标准节点 | 中文定义 | 实际进度说明 |
+|---:|---|---|---|
+| 10 | `DEPARTED_WAREHOUSE` | 已离开国内仓库 | 国内出仓确认产生的首个实际节点 |
+| 20 | `AT_ORIGIN_PORT` | 重箱已进入起运港或码头 | 货柜已进入起运港区，但未必装船 |
+| 30 | `LOADED_ON_VESSEL` | 已装船 | 货柜已装上船舶，但船舶未必已经开航 |
+| 40 | `DEPARTED_ORIGIN_PORT` | 船舶已离开起运港 | 必须有实际离港事实，不得用装船或预计开航代替 |
+| 50 | `IN_TRANSIT` | 海运途中 | 船舶处于起运港至目的港之间的海运阶段 |
+| 60 | `ARRIVED_DESTINATION_PORT` | 船舶已到目的港 | 仅表示船舶到港，货柜未必已经卸船 |
+| 70 | `DISCHARGED_FROM_VESSEL` | 已卸船、未清关 | 货柜已从船上卸下，不代表已经清关或可提柜 |
+| 80 | `PICKUP_READY` | 已清关、可提柜 | 必须有清关完成、放行或码头明确可提柜事实 |
+| 90 | `PICKED_UP` | 已提柜 | 重箱已被提离码头，不得用“可提柜”代替 |
+| 100 | `EMPTY_RETURNED` | 已还柜 | 空箱已归还，船节点查询闭环完成并停止 |
+
+### 2.1 旧节点调整
+
+| 旧节点 | 处理方式 |
+|---|---|
+| `DEPARTED_WAREHOUSE` | 保持不变 |
+| `AT_ORIGIN_PORT` | 保持不变 |
+| `DEPARTED_ORIGIN_PORT` | 保持不变 |
+| `IN_TRANSIT` | 保持不变 |
+| `ARRIVED` | 改名为 `ARRIVED_DESTINATION_PORT`，消除“船到港”与“货柜卸船”的歧义 |
+| `PICKUP_READY` | 名称保持不变，语义收敛为“已清关、可提柜” |
+
+新增节点为 `LOADED_ON_VESSEL`、`DISCHARGED_FROM_VESSEL`、`PICKED_UP`、`EMPTY_RETURNED`。当前项目尚未上线，不保留旧 `ARRIVED` 的兼容枚举或双写逻辑。
+
+## 3. 时间语义与状态推进
+
+每条供应商节点事实可同时包含以下时间：
+
+| 字段 | 含义 | 是否推进实际节点 |
+|---|---|---|
+| `estimatedAt` | 供应商提供的预计发生时间，例如预离、预抵 | 否 |
+| `actualAt` | 供应商确认的实际发生时间 | 是 |
+| `observedAt` | 平台本次查询到该事实的时间或供应商声明的观测时间 | 否 |
+| `createdAt` | 标准化事实写入平台的时间 | 否 |
+
+规则：
+
+1. 只有存在 `actualAt` 的标准节点才能推进任务的最新实际节点。
+2. 只有预计时间时可以保存预计事实，但不得把任务推进为已开航、已到港、已卸船或已清关。
+3. 节点按固定序号单调推进；迟到的较早节点仍保存为历史事实，但不能回退最新实际节点。
+4. 同一供应商事件使用稳定 `providerEventId` 幂等；重复查询不得重复插入。
+5. 一个供应商事件只映射一个最精确的标准节点，不因中间节点缺失而自动补齐整条链路。
+
+## 4. 异常事实
+
+扣留、异常和限制不属于单调业务节点，必须与标准节点分开保存和展示，不能覆盖最近正常节点。
+
+| 异常编码 | 中文定义 |
+|---|---|
+| `CUSTOMS_HOLD` | 海关扣留或等待海关处理 |
+| `TERMINAL_HOLD` | 码头、堆场或港区扣留 |
+| `DOCUMENT_HOLD` | 单证、放货文件或提单问题导致扣留 |
+| `UNKNOWN_HOLD` | 无法进一步分类的其他扣留 |
+
+异常事实至少保存供应商编码、原始状态、观测时间、地点、来源引用和原始响应哈希。异常解除时保存解除事实，不删除原异常记录。
+
+## 5. 供应商原始字段保存规则
+
+标准化节点不得丢失供应商来源，节点事实至少包含：
+
+- `providerCode`：供应商或船司适配器编码。
+- `providerEventId`：供应商事件 ID；无原生 ID 时使用稳定字段组合的 SHA-256。
+- `providerNodeCode`：供应商原始节点编码或规范化原始文案。
+- `standardNode`：本契约定义的标准节点。
+- `observedAt`、`estimatedAt`、`actualAt`。
+- `locationCode`、`locationName`，供应商缺失时允许为空。
+- `sourceReference`：不含密钥和敏感参数的可审计来源引用。
+- `rawPayloadHash`：原始响应的 SHA-256；业务表不保存完整网页或敏感原文。
+
+供应商返回空字段时保持空值，不使用 `0`、当前时间、预计时间或其他字段伪造实际事实。
+
+## 6. 已确认供应商映射
+
+### 6.1 美森 MATSON
+
+美森通过公开查询页动态取得网页会话和 `ttr`，再调用其网页查询代理。以下映射只有在响应出现对应原始状态时生效：
+
+| 美森原始状态 | 标准化结果 |
+|---|---|
+| `INGATE` | `AT_ORIGIN_PORT` |
+| `LOAD TO VESSEL` | `LOADED_ON_VESSEL` |
+| 明确的实际离港状态，例如 `VESSEL DEPARTURE` | `DEPARTED_ORIGIN_PORT` |
+| `IN TRANSIT` | `IN_TRANSIT` |
+| 明确的船舶到达目的港状态 | `ARRIVED_DESTINATION_PORT` |
+| `DISCHARGE FROM VESSEL` | `DISCHARGED_FROM_VESSEL` |
+| `AVAILABLE FOR PICKUP` | `PICKUP_READY` |
+| 明确的重箱出场状态 | `PICKED_UP` |
+| 明确的空箱归还状态 | `EMPTY_RETURNED` |
+| `CONTAINER ON HOLD - Customs Clearance` | `CUSTOMS_HOLD`，不推进标准节点 |
+
+`vesselETA` 仅可作为 `ARRIVED_DESTINATION_PORT.estimatedAt`，不得生成实际到港节点。未在真实响应样本中确认的美森文案不得仅凭名称猜测映射。
+
+### 6.2 合德 HEDE
+
+合德返回 UTF-8 HTML。适配器从“提单箱时间线信息”主表精确匹配目标柜号，当前不对可能包含多个柜子的提单查询自动选柜。
+
+| 合德字段 | 标准化结果 |
+|---|---|
+| 预离 | `DEPARTED_ORIGIN_PORT.estimatedAt`，不推进实际节点 |
+| 预抵 | `ARRIVED_DESTINATION_PORT.estimatedAt`，不推进实际节点 |
+| 空箱出场 | 不进入当前标准节点 |
+| 重箱进场 | `AT_ORIGIN_PORT` |
+| 装船 | `LOADED_ON_VESSEL` |
+| 卸船 | `DISCHARGED_FROM_VESSEL` |
+| 重箱出场 | `PICKED_UP` |
+| 空箱还回 | `EMPTY_RETURNED` |
+
+合德当前没有明确的实际离港、海运途中、船舶到达或清关完成字段，因此不得生成 `DEPARTED_ORIGIN_PORT`、`IN_TRANSIT`、`ARRIVED_DESTINATION_PORT` 或 `PICKUP_READY` 的实际节点。
+
+## 7. 查询停止规则
+
+1. 自动查询在写入实际 `EMPTY_RETURNED` 后幂等停止，停止原因固定记录为“已还柜”。
+2. 供应商不提供还柜节点时，只能由可信内部业务事件或具备权限的人工操作确认还柜并停止。
+3. `ARRIVED_DESTINATION_PORT`、`DISCHARGED_FROM_VESSEL`、`PICKUP_READY` 和 `PICKED_UP` 均不是默认停止条件。
+4. 停止后的迟到供应商回调不得重新激活任务；如需恢复必须由独立、可审计的恢复契约处理。
+5. 长期缺少节点、供应商失败或网页结构变化只进入失败/人工状态，不得伪造 `EMPTY_RETURNED`。
+
+## 8. 新增船司接入门禁
+
+每新增一家船司或轨迹供应商，必须逐项完成：
+
+1. 保存至少一份脱敏真实成功样本，以及空结果、无效号码、限流和结构异常样本。
+2. 列出所有实际出现的原始字段、状态文案、时间格式、时区和地点字段。
+3. 建立“原始状态 → 标准节点或异常事实”映射表；无法确认的状态保持未映射。
+4. 明确哪些时间是预计、实际或观测时间，不允许混用。
+5. 验证同一业务事件重复查询的幂等键稳定。
+6. 配置连接超时、请求超时、最小访问间隔、限流和重试归一化。
+7. 对 HTML 页面验证字符集、目标行选择和页面结构变化失败关闭；不得按固定行号或整票第一条猜测目标柜。
+8. 对 JSON 接口验证目标业务键与请求一致，防止返回错误柜号、提单或订舱结果。
+9. 默认关闭真实外部调用，通过环境开关显式启用；页面和任务能力描述必须与部署开关一致。
+10. 完成 Provider 单元测试、Firstleg 标准节点测试、OpenAPI/SQL 合同、真实环境 HTTP 及 Admin 展示验收。
+
+## 9. 跨端同步清单
+
+本契约的节点、时间或异常编码变化时，必须同步核对：
+
+- Integration Service 的标准节点枚举、Provider DTO、各船司适配器和配置。
+- Firstleg 的标准节点枚举、任务状态推进、节点事实、查询历史、停止条件、SQL 约束和 OpenAPI。
+- Admin 的 TypeScript 类型、节点中文文案、时间展示、状态标签和页面测试。
+- HTTP 验收脚本中的节点枚举、详情和历史断言。
+- 四期 README、相关 `AGENTS.md` 和新增供应商映射证据。
+
+不得只修改某一家适配器而跳过统一模型，也不得为单一供应商新增含义重复的业务节点。

独立任务协作登记.md

@@ -39,9 +39,9 @@
 | `01a018d1-70cf-7c63-8ade-0bca11970566` | `01a018cb-a435-7c61-91ca-4f3e484dca75` | 四期专项一：海外仓入库与库存 | 负责 Admin 四期海外仓的尾程订单、入库单、换标单、托盘、箱号、产品库和库存管理正式页面、模块内路由片段、模块内前端契约与测试；明确排除海外仓出库、退货出库、海外派送和其他库存离仓业务，不修改共享导航、根路由或全局权限装配 |
 | `01a018d1-7277-7230-8bd6-2cd5e92c078e` | `01a018cb-a435-7c61-91ca-4f3e484dca75` | 四期专项二：海外业务 | 负责 Admin 四期海外采购订单、本土卡车和本土散板正式页面、模块内路由片段、模块内前端契约与测试；不扩展海外派送，不修改共享导航、根路由或全局权限装配 |
 | `01a018d1-7437-7432-867d-abf33b2d66aa` | `01a018cb-a435-7c61-91ca-4f3e484dca75` | 四期专项三：通用资料与合作仓 | 负责 Admin 四期海外仓合作仓类型、海外仓报价、汇率管理和车辆列表/详情正式页面及模块内契约与测试；仓库类型只扩展现有仓库主数据，不把海外库存写入国内 Warehouse 领域，不修改共享导航、根路由或全局权限装配 |
-| `01a018d1-75cc-78a2-b026-27c69bdcc7ca` | `01a018cb-a435-7c61-91ca-4f3e484dca75` | 四期专项四：船节点前端承载 | 负责 Admin 现有订舱、船期和货柜详情中“确认国内出仓后至目的港到达”的 CarrierScheduleQuery 展示、历史、来源、时间和失败态前端承载及测试；不新建重复轮询任务、不归入海外派送，不修改共享导航、根路由或全局权限装配 |
+| `01a018d1-75cc-78a2-b026-27c69bdcc7ca` | `01a018cb-a435-7c61-91ca-4f3e484dca75` | 四期专项四：船节点前端承载 | 负责 Admin 现有订舱、船期和货柜详情中“确认国内出仓后至还柜”的 CarrierScheduleQuery 标准节点、异常、预计/实际时间、历史、失败态和人工补录前端承载及测试；不新建重复轮询任务、不归入海外派送，不修改共享导航、根路由或全局权限装配 |
 | `01a01e56-ba99-71e0-8076-b4f40f4b96f0` | `01a0194a-259c-7171-8967-074731a27618` | 四期后端专项一：海外基础设施与权限 | 负责海外 Gateway、三项海外服务与双区域 Event Bridge 的 Jenkins、Compose、service-map、Nacos 部署契约，海外 Token Claims/Audience、统一权限矩阵、IAM/统一 SQL、跨区域事件可靠性及相关 OpenAPI 与测试；不承接具体业务域实现，不部署或执行 SQL |
 | `01a01e56-bc99-7170-a180-7b6e9f25fc9a` | `01a0194a-259c-7171-8967-074731a27618` | 四期后端专项二：海外通用主数据 | 负责 Lastleg 海外仓报价、月度汇率、车辆主数据的表、Controller、DTO、状态、权限、OpenAPI、导出和测试，以及报价创建时服务端读取国内合作仓并缓存；不承接箱号、产品、出库或派送履约 |
 | `01a01e56-bed3-75f3-ba02-cc28479cd8ee` | `01a0194a-259c-7171-8967-074731a27618` | 四期后端专项三：海外入仓与库存 | 负责 Lastleg 与 Warehouse Overseas 的尾程订单、接柜、入仓计划、卸货入库、换标、平台公共托盘、SKU 库存和库内操作后端；排除箱号平台、产品库、海外出库、退货出库、海外派送，不向 Admin 暴露 PDA 或内部事件端点 |
 | `01a01e56-c0f2-71f1-9c74-02f6709233f1` | `01a0194a-259c-7171-8967-074731a27618` | 四期后端专项四：海外本土业务 | 负责 Lastleg 海外采购订单、本土卡车、本土散板完整后端，以及客户/仓库候选、字段清空语义、流水、平台写接口、权限、OpenAPI、SQL 和测试；排除采购出库、海外仓出库、退货出库与海外派送 |
-| `01a01e56-c30b-7513-be9e-03262a387696` | `01a0194a-259c-7171-8967-074731a27618` | 四期后端专项五：船节点自动查询 | 负责国内确认出仓后至目的港到达的 CarrierScheduleQuery 自动任务、租约、幂等、退避、停止条件、Integration 标准节点和供应商适配、节点事实与历史、货柜 DTO 及跨区衔接；不新建重复轮询体系，不承接海外派送、PDA 或前端页面 |
+| `01a01e56-c30b-7513-be9e-03262a387696` | `01a0194a-259c-7171-8967-074731a27618` | 四期后端专项五：船节点自动查询 | 负责国内确认出仓后至还柜的 CarrierScheduleQuery 自动任务、租约、幂等、退避、十个标准节点、异常事实、预计/实际时间、人工补录、还柜停止条件、Integration 供应商适配、查询尝试与历史、货柜 DTO 及跨区衔接；不新建重复轮询体系，不承接海外派送、PDA 或前端页面 |