优化

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

@@ -405,6 +405,18 @@ paths:
         content: {application/json: {schema: {$ref: '#/components/schemas/SmartLoadingDeleteRequest'}}}
       responses:
         '200': {description: 成功或业务失败，data 为最新 SmartLoadingPlan}
+  /api/platform/v1/first-leg/smart-loading/plans/{planId}/items/{itemId}/warehouse-remark:
+    patch:
+      summary: 修改装柜明细仓库备注
+      description: EDITING/LOADING 可修改或清空 warehouseRemark；COMPLETED、计划/明细版本冲突返回 A0409，写入历史且与 PDA final complete 使用同一并发门禁。
+      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]*$'}}
+      requestBody:
+        required: true
+        content: {application/json: {schema: {$ref: '#/components/schemas/SmartLoadingWarehouseRemarkRequest'}}}
+      responses:
+        '200': {description: 成功或业务失败，data 为最新 SmartLoadingPlan}
   /api/platform/v1/first-leg/smart-loading/plans/{planId}/push-preload:
     post:
       summary: 推送智能装柜计划到预装清单
@@ -1531,6 +1543,14 @@ components:
         expectedPlanVersion: {type: integer, minimum: 0}
         expectedItemVersion: {type: integer, minimum: 0}
         operationId: {type: string, minLength: 1, maxLength: 128}
+    SmartLoadingWarehouseRemarkRequest:
+      type: object
+      required: [expectedPlanVersion, expectedItemVersion, operationId]
+      properties:
+        warehouseRemark: {type: string, nullable: true, maxLength: 1000, description: 仓库备注；null/空字符串均表示清空}
+        expectedPlanVersion: {type: integer, minimum: 0}
+        expectedItemVersion: {type: integer, minimum: 0}
+        operationId: {type: string, minLength: 1, maxLength: 128}
     SmartLoadingPlan:
       type: object
       required: [id, planNo, status, bookingId, version, canAssign, canEdit, finalCompletionStatus, items]
@@ -1562,6 +1582,9 @@ components:
         orderNo: {type: string, nullable: true}
         inboundCode: {type: string, nullable: true}
         customerName: {type: string, nullable: true}
+        customerRemark: {type: string, nullable: true, readOnly: true, description: 来源为订单 customerRemark}
+        internalRemark: {type: string, nullable: true, readOnly: true, description: 来源为订单最新内部备注，不使用 cargoRemark}
+        warehouseRemark: {type: string, nullable: true, description: 仓库人员逐条维护，可在 EDITING/LOADING 修改}
         packageCount: {type: integer, minimum: 1}
         version: {type: integer, minimum: 0, description: itemVersion，调整/删除写请求使用此值}
         pickedPackageCount: {type: integer, minimum: 0}