优化

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

@@ -251,14 +251,14 @@ paths:
         '403': {description: 无新增按钮权限}
   /api/platform/v1/containers/{id}/ocean-booking-link:
     post:
-      summary: 将内部模拟柜原地合并为指定真实订舱柜
-      description: 需要 platform:firstleg:container:edit；请求指定未消费且尚无装柜计划/PDA/证据/单证的 realContainerBookingId。首次关联允许 WAIT_LOADING 或已有预排货的 EDITING 模拟柜，保留原 containerBookingId/cabinetNo/loadingPlanId/items，将真实柜 containerNo、订舱、运输和范围快照原子复制到模拟柜并把 allocation 改指模拟柜；原真实柜置 MERGED 且不再出现在正常货柜列表。存在跨仓、跨渠道、柜型规格不一致、PDA、有效装柜证据、业务单证或 LOADING/COMPLETED 等事实时拒绝。
+      summary: 将内部模拟柜关联到已发布订舱需求并补录真实柜号
+      description: 需要 platform:firstleg:container:edit；请求指定 RELEASED oceanBookingId、未满配 requirementId 和港口提柜后取得的唯一 containerNo。首次关联允许 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 操作身份}}
+      responses: {'200': {description: 关联后的同一模拟柜 containerBookingId/cabinetNo；列表仍只有这一条 ACTIVE 操作身份}}
     delete:
       summary: 解除内部模拟柜的真实订舱关联
-      description: 需要 platform:firstleg:container:edit；解绑或换绑仅允许完全空的 WAIT_LOADING 模拟柜；任何排货、PDA、有效装柜证据或业务单证事实均拒绝。
+      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}}
@@ -408,7 +408,11 @@ paths:
   /api/platform/v1/first-leg/smart-loading/plans/{planId}/items/{itemId}/warehouse-remark:
     patch:
       summary: 修改装柜明细仓库备注
-      description: EDITING/LOADING 可修改或清空 warehouseRemark；COMPLETED、计划/明细版本冲突返回 A0409，写入历史且与 PDA final complete 使用同一并发门禁。
+      description: >-
+        需要 platform:firstleg:preload:edit 权限。EDITING/LOADING 可修改或清空 warehouseRemark；
+        COMPLETED、计划/明细版本冲突返回 A0409 且事务零写入，写入历史且与 PDA final complete 使用同一并发门禁。
+        成功响应中的 version 是递增后的 planVersion，items[].version 是递增后的 itemVersion；调用方同时使用
+        canEdit、items[].canAdjust/canRemove 与自身权限决定操作可用性。数量调整或动态增量不会覆盖已有 warehouseRemark。
       parameters:
         - {name: planId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
         - {name: itemId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}

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

@@ -29,7 +29,17 @@ paths:
       requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ReleaseRequest'}}}}
       responses: {'200': {description: RELEASED detail}}
   /api/platform/v1/ocean-bookings/channels:
-    get: {summary: List ACTIVE channels for an origin warehouse, responses: {'200': {description: Channel options}}}
+    get:
+      summary: List ACTIVE channels for an origin warehouse
+      description: Requires platform:firstleg:ocean-booking:list. Channel names are resolved from the current ACTIVE price book and frozen by the server on save.
+      parameters:
+        - {name: originWarehouseId, in: query, required: true, schema: {type: integer, format: int64, minimum: 1}}
+      responses:
+        '200':
+          description: Channel options
+          content:
+            application/json:
+              schema: {type: array, items: {$ref: '#/components/schemas/ChannelOption'}}
 components:
   parameters:
     OceanBookingId: {name: oceanBookingId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
@@ -48,8 +58,15 @@ components:
         billOfLadingNo: {type: string, nullable: true}
         shippingCompanyId: {type: integer, format: int64, nullable: true}
         shippingCompanyName: {type: string, nullable: true}
-        bookingAgentId: {type: integer, format: int64, nullable: true}
-        bookingAgentName: {type: string, nullable: true}
+        bookingAgentId:
+          type: integer
+          format: int64
+          nullable: true
+          description: Warehouse supplier ID; release validates ACTIVE category BOOKING; booking suppliers do not use domestic/international scope.
+        bookingAgentName:
+          type: string
+          nullable: true
+          description: Read-only consistency hint; the persisted snapshot always comes from Warehouse.
         vesselName: {type: string, nullable: true}
         voyageNo: {type: string, nullable: true}
         departurePortCode: {type: string, nullable: true}
@@ -68,4 +85,13 @@ components:
     ContainerRequirementRequest: {type: object, required: [containerType, containerKind, quantity, capacityCbm, maxWeightKg], properties: {containerType: {type: string}, containerKind: {type: string}, quantity: {type: integer, minimum: 1}, capacityCbm: {type: number, exclusiveMinimum: true, minimum: 0}, maxWeightKg: {type: number, exclusiveMinimum: true, minimum: 0}}}
     ReleaseRequest: {type: object, required: [expectedVersion], properties: {expectedVersion: {type: integer, minimum: 0}, reason: {type: string, nullable: true}}}
     ActionRequest: {type: object, required: [expectedVersion], properties: {expectedVersion: {type: integer, minimum: 0}, reason: {type: string, nullable: true}}}
+    ChannelOption:
+      type: object
+      required: [priceBookVersionId, channelCode, channelName, priceModel, pricingTaxModes]
+      properties:
+        priceBookVersionId: {type: integer, format: int64}
+        channelCode: {type: string}
+        channelName: {type: string}
+        priceModel: {type: string}
+        pricingTaxModes: {type: array, items: {type: string}}
     Detail: {type: object, required: [oceanBooking, parties, containerRequirements, containers, histories], properties: {oceanBooking: {type: object}, parties: {type: array}, containerRequirements: {type: array}, containers: {type: array, description: Existing containers allocated after port pickup linking}, histories: {type: array}}}