feat: enforce canonical container identity across regions

firstleg/src/main/resources/openapi/carrier-schedule-query-v1.yaml

@@ -96,7 +96,7 @@ components:
       type: string
       enum: [MATSON, SML, ZIM, COSCO, EMC, HEDE, OTHER]
       description: OTHER is frozen on the ocean booking and creates a manual-only task after outbound confirmation.
-    TrackingType: {type: string, enum: [BOOKING_NO, BILL_OF_LADING, CONTAINER_NO]}
+    TrackingType: {type: string, enum: [CONTAINER_NO], description: Only the normalized physical containerNo frozen by Firstleg is accepted; cabinetNo, orderNo, bookingNo and bill of lading are never fallbacks.}
     QueryStatus: {type: string, enum: [READY, MANUAL_REQUIRED, STOPPED]}
     StandardNode:
       type: string
@@ -104,15 +104,15 @@ components:
     ExceptionCode: {type: string, enum: [CUSTOMS_HOLD, TERMINAL_HOLD, DOCUMENT_HOLD, UNKNOWN_HOLD]}
     CreateRequest:
       type: object
-      required: [expectedVersion, customerId, oceanBookingId, carrierCode, trackingType, trackingNo]
+      required: [expectedVersion, customerId, oceanBookingId, containerBookingId, carrierCode, trackingType, trackingNo]
       properties:
         expectedVersion: {type: integer, minimum: 0, maximum: 0}
         customerId: {type: integer, format: int64, minimum: 1}
         oceanBookingId: {type: integer, format: int64, minimum: 1}
-        containerBookingId: {type: integer, format: int64, minimum: 1, nullable: true}
+        containerBookingId: {type: integer, format: int64, minimum: 1}
         carrierCode: {$ref: '#/components/schemas/CarrierCode'}
         trackingType: {$ref: '#/components/schemas/TrackingType'}
-        trackingNo: {type: string, minLength: 1, maxLength: 128}
+        trackingNo: {type: string, minLength: 1, maxLength: 128, description: Normalized physical containerNo; must equal the linked Firstleg container snapshot.}
         remark: {type: string, nullable: true, maxLength: 1000}
     ManualResultRequest:
       type: object
@@ -136,13 +136,13 @@ components:
         reason: {type: string, minLength: 1, maxLength: 1000}
     Task:
       type: object
-      required: [id, queryNo, customerId, oceanBookingId, carrierCode, trackingType, trackingNo, status, triggerSource, version]
+      required: [id, queryNo, customerId, oceanBookingId, containerBookingId, carrierCode, trackingType, trackingNo, status, triggerSource, version]
       properties:
         id: {type: integer, format: int64}
         queryNo: {type: string}
         customerId: {type: integer, format: int64}
         oceanBookingId: {type: integer, format: int64}
-        containerBookingId: {type: integer, format: int64, nullable: true}
+        containerBookingId: {type: integer, format: int64}
         carrierCode: {$ref: '#/components/schemas/TaskCarrierCode'}
         trackingType: {$ref: '#/components/schemas/TrackingType'}
         trackingNo: {type: string}

firstleg/src/main/resources/openapi/firstleg-v1.yaml

@@ -295,16 +295,10 @@ paths:
   /api/platform/v1/containers/{id}/ocean-booking-link:
     post:
       summary: 将内部模拟柜关联到已发布订舱需求并补录真实柜号
-      description: 需要 platform:firstleg:container:edit；请求指定 RELEASED oceanBookingId、未满配 requirementId 和港口提柜后取得的唯一 containerNo。首次关联允许 WAIT_LOADING 或已有预排货的 EDITING 模拟柜，保留原 containerBookingId/cabinetNo/loadingPlanId/items，原子写入订舱、运输和范围快照并创建 allocation；不会创建或消费另一条真实柜记录。存在跨仓、跨渠道、柜型规格不一致、超量、重复柜号、PDA、有效装柜证据、业务单证或 LOADING/COMPLETED 等事实时拒绝。
+      description: 需要 platform:firstleg:container:edit；请求指定 RELEASED oceanBookingId、未满配 requirementId 和港口提柜后取得的唯一 containerNo，服务端规范化并校验ISO 6346结构、设备类别和校验位。首次关联允许 WAIT_LOADING 或已有预排货的 EDITING 模拟柜，保留原 containerBookingId/cabinetNo/loadingPlanId/items，原子写入订舱、运输和范围快照并创建 allocation；不会创建或消费另一条真实柜记录。存在跨仓、跨渠道、柜型规格不一致、超量、重复柜号、PDA、有效装柜证据、业务单证或 LOADING/COMPLETED 等事实时拒绝。
       parameters: [{$ref: '#/components/parameters/ContainerBookingId'}]
       requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ContainerOceanBookingLinkRequest'}}}}
       responses: {'200': {description: 关联后的同一模拟柜 containerBookingId/cabinetNo；列表仍只有这一条 ACTIVE 操作身份}}
-    delete:
-      summary: 解除内部模拟柜的真实订舱关联
-      description: 需要 platform:firstleg:container:edit；解绑或换绑仅允许完全空的 WAIT_LOADING 模拟柜；原子清除当前柜订舱/运输快照和 allocation，不恢复或创建其他柜记录。任何排货、PDA、有效装柜证据或业务单证事实均拒绝。
-      parameters: [{$ref: '#/components/parameters/ContainerBookingId'}]
-      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ContainerOceanBookingUnlinkRequest'}}}}
-      responses: {'200': {description: 解除后的同一 containerBookingId/cabinetNo}}
   /api/platform/v1/containers/{id}:
     get:
       summary: 查询平台货柜详情
@@ -315,8 +309,8 @@ paths:
         '200': {description: 成功或货柜不存在}
         '403': {description: 无货柜查询权限}
     put:
-      summary: 草稿阶段完整编辑货柜
-      description: 需要 platform:firstleg:container:edit 权限；仅待装柜或计划为 EDITING（预装柜中）时允许
+      summary: 草稿阶段编辑货柜基础资料
+      description: 需要 platform:firstleg:container:edit 权限；仅待装柜或计划为 EDITING 时允许；请求不包含 containerNo/cabinetNo，不形成真实柜号或内部柜次号写入口
       parameters:
         - {$ref: '#/components/parameters/ContainerBookingId'}
       requestBody:
@@ -327,21 +321,6 @@ paths:
       responses:
         '200': {description: 成功或状态、版本、重复号冲突}
         '403': {description: 无货柜编辑权限}
-  /api/platform/v1/containers/{id}/transport:
-    patch:
-      summary: 修改集装箱号和航次
-      description: 需要 platform:firstleg:container:edit 权限；LOADING 仅开放此白名单，COMPLETED 全部只读；相同幂等键精确重放零新增历史，相同业务字段为无效变更且不递增版本、不写历史
-      parameters:
-        - {$ref: '#/components/parameters/ContainerBookingId'}
-        - {$ref: '#/components/parameters/IdempotencyKey'}
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema: {$ref: '#/components/schemas/ContainerTransportUpdateRequest'}
-      responses:
-        '200': {description: 成功或状态、版本、重复号冲突}
-        '403': {description: 无货柜编辑权限}
   /api/platform/v1/containers/{id}/clearance:
     get:
       summary: 查询货柜目的港清关资料
@@ -1051,7 +1030,6 @@ components:
         expectedArrivalDate: {type: string, format: date, nullable: true}
         feeReviewStatus: {type: string, maxLength: 32, nullable: true}
         channelName: {type: string, maxLength: 128, nullable: true}
-        containerNo: {type: string, maxLength: 64, nullable: true}
         cabinetNo: {type: string, maxLength: 64, nullable: true}
         sailingDate: {type: string, format: date, nullable: true}
         loaded: {type: boolean, nullable: true}
@@ -1652,14 +1630,6 @@ components:
       properties:
         version: {type: integer, minimum: 0}
         data: {$ref: '#/components/schemas/ContainerSaveRequest'}
-    ContainerTransportUpdateRequest:
-      type: object
-      required: [version, reason]
-      properties:
-        containerNo: {type: string, maxLength: 64, nullable: true, description: 真实集装箱号；PDA任务创建前可空，任务创建后允许替换但禁止清空}
-        voyageNo: {type: string, maxLength: 64, nullable: true}
-        version: {type: integer, minimum: 0}
-        reason: {type: string, maxLength: 500}
     SmartLoadingPushRequest:
       type: object
       required: [expectedVersion]
@@ -1960,14 +1930,8 @@ components:
       properties:
         oceanBookingId: {type: integer, format: int64, minimum: 1, description: RELEASED订舱ID}
         requirementId: {type: integer, format: int64, minimum: 1, description: 未满配的订舱柜型需求ID}
-        containerNo: {type: string, maxLength: 64, description: 港口提柜后取得的全局唯一真实集装箱号}
+        containerNo: {type: string, maxLength: 64, description: 港口提柜后取得的全局唯一真实集装箱号；服务端移除格式空白、转大写并校验ISO 6346结构、设备类别和校验位}
         expectedVersion: {type: integer, minimum: 0}
-    ContainerOceanBookingUnlinkRequest:
-      type: object
-      required: [expectedVersion, reason]
-      properties:
-        expectedVersion: {type: integer, minimum: 0}
-        reason: {type: string, minLength: 1, maxLength: 500}
     ContainerFeeAdjustRequest:
       type: object
       additionalProperties: false

firstleg/src/main/resources/openapi/loading-lists-v1.yaml

@@ -34,7 +34,9 @@ paths:
   /api/platform/v1/first-leg/loading-plans/{planId}/transport:
     patch:
       summary: 修改预装运输信息
-      description: 已推送且仍为 EDITING 的预装清单可补录或修改集装箱号与航次；LOADING 阶段按稳定柜次身份规则维护，不能清空已创建 PDA 任务的柜号。
+      description: >-
+        唯一纠错入口。仅已推送且仍为 EDITING、真实柜号已由 ocean-booking-link 首次写入、PDA任务尚未领取且无任何物理作业事实时允许；
+        containerNo 为空表示保持当前值，非空时服务端移除格式空白、转大写并校验ISO 6346结构、设备类别和校验位。禁止清空，LOADING/COMPLETED全部拒绝。
       x-permission: platform:firstleg:preload:edit
       parameters:
         - {$ref: '#/components/parameters/PlanId'}
@@ -280,7 +282,7 @@ components:
           items: {type: string, enum: [PRELOAD_NOT_PUSHED, LOADING_PLAN_NOT_EDITING, CONTAINER_NO_MISSING, PRELOAD_LINK_MISSING, OCEAN_BOOKING_NOT_LINKED, OCEAN_BOOKING_NOT_RELEASED, PDA_TASK_ALREADY_CREATED, PRELOAD_ALREADY_CONFIRMED]}
     ConfirmPreloadRequest:
       type: object
-      required: [expectedVersion]
+      required: [expectedVersion, operationReason]
       additionalProperties: false
       properties:
         expectedVersion: {type: integer, format: int32, minimum: 0, description: 当前装柜计划 version}
@@ -385,7 +387,7 @@ components:
       required: [expectedVersion]
       additionalProperties: false
       properties:
-        containerNo: {type: string, maxLength: 64, nullable: true, description: 真实集装箱号；PDA任务创建前可空，任务创建后允许替换但禁止清空}
+        containerNo: {type: string, maxLength: 64, nullable: true, description: 新真实集装箱号；null表示保持当前值，空白字符串非法，禁止清空}
         voyageNo: {type: string, maxLength: 64, nullable: true, description: 航次}
         expectedVersion: {type: integer, format: int32, minimum: 0, description: 当前乐观锁版本}
-        operationReason: {type: string, maxLength: 500, nullable: true, description: 操作原因}
+        operationReason: {type: string, minLength: 1, maxLength: 500, description: 必填纠错原因}