feat: add editable order collaboration remarks

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

@@ -774,20 +774,21 @@ paths:
         content: {application/json: {schema: {$ref: '#/components/schemas/SmartLoadingRemoveUnpickedRequest'}}}
       responses:
         '200': {description: 成功或业务失败，data 为最新 SmartLoadingPlan}
-  /api/platform/v1/first-leg/smart-loading/plans/{planId}/items/{itemId}/warehouse-remark:
+  /api/platform/v1/first-leg/smart-loading/plans/{planId}/items/{itemId}/remarks:
     patch:
-      summary: 修改装柜明细仓库备注
+      summary: 修改装柜明细协作备注
       description: >-
-        需要 platform:firstleg:preload:edit 权限。EDITING/LOADING 可修改或清空 warehouseRemark；
+        需要 platform:firstleg:preload:edit 权限。客户备注只读；EDITING/LOADING 可修改或清空
+        internalRemark、warehouseRemark 和 customerServiceRemark；
         COMPLETED、计划/明细版本冲突返回 A0409 且事务零写入，写入历史且与 PDA final complete 使用同一并发门禁。
         成功响应中的 version 是递增后的 planVersion，items[].version 是递增后的 itemVersion；调用方同时使用
-        canEdit、items[].canAdjust/canRemove 与自身权限决定操作可用性。数量调整或动态增量不会覆盖已有 warehouseRemark。
+        canEdit、items[].canAdjust/canRemove 与自身权限决定操作可用性。数量调整或动态增量不会覆盖已有协作备注。
       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'}}}
+        content: {application/json: {schema: {$ref: '#/components/schemas/SmartLoadingRemarksRequest'}}}
       responses:
         '200': {description: 成功或业务失败，data 为最新 SmartLoadingPlan}
   /openapi/v1/inbound-measurements:
@@ -2323,11 +2324,13 @@ components:
       properties:
         expectedPlanVersion: {type: integer, minimum: 0}
         operationId: {type: string, minLength: 1, maxLength: 128}
-    SmartLoadingWarehouseRemarkRequest:
+    SmartLoadingRemarksRequest:
       type: object
       required: [expectedPlanVersion, expectedItemVersion, operationId]
       properties:
+        internalRemark: {type: string, nullable: true, maxLength: 1000, description: 内部备注；null/空字符串均表示清空}
         warehouseRemark: {type: string, nullable: true, maxLength: 1000, description: 仓库备注；null/空字符串均表示清空}
+        customerServiceRemark: {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}
@@ -2518,8 +2521,9 @@ components:
         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}
+        internalRemark: {type: string, nullable: true, description: 内部备注；预装阶段可修改}
         warehouseRemark: {type: string, nullable: true, description: 仓库人员逐条维护，可在 EDITING/LOADING 修改}
+        customerServiceRemark: {type: string, nullable: true, description: 客服备注；预装阶段可修改}
         packageCount: {type: integer, minimum: 1}
         totalPackageCount: {type: integer, minimum: 1, description: 当前入仓明细可在计划内分配的总箱数，包含已用与未用箱数}
         remainingPackageCount: {type: integer, minimum: 0, description: 当前入仓明细尚未分配到本计划的箱数}

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

@@ -405,6 +405,7 @@ components:
         internalRemark: {type: string, nullable: true, description: 内部备注}
         customerRemark: {type: string, nullable: true, description: 客户备注}
         warehouseRemark: {type: string, nullable: true, description: 仓库备注}
+        customerServiceRemark: {type: string, nullable: true, description: 客服备注}
         loadSequence: {type: integer, format: int32, minimum: 0, description: 装柜顺序}
         frozenAt: {type: string, format: date-time, nullable: true, description: 明细冻结时间}
         itemVersion: {type: integer, format: int32, minimum: 0, description: 明细乐观锁版本；更新仓库备注时作为 expectedItemVersion}