优化

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]*$'}}