feat: complete tail order controls and terminal drayage

lastleg-service/src/main/resources/openapi/overseas-business-v1.yaml

@@ -192,25 +192,46 @@ paths:
       responses:
         '200': { description: 新增后的费用明细, content: { application/json: { schema: { $ref: '#/components/schemas/LastMileFeeApiResponse' } } } }
         '404': { description: 尾程订单不存在或不属于操作客户 }
-  /api/platform/v1/last-leg/orders/{id}/detained:
+  /api/platform/v1/last-leg/orders/{id}/hold:
     put:
       summary: 设置或解除尾程订单暂扣
-      description: 权限 platform:overseas-warehouse:last-mile-order:edit；库存同步转入或释放暂扣，并通过跨区事件回写国内入仓单。
+      description: 权限 platform:overseas-warehouse:last-mile-order:edit；使用订单版本和 Idempotency-Key 原子写入计费标记、原因及不可变历史。已进入出库流程的订单不得新增暂扣；暂扣只作用于当前票，不影响同柜其他订单。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: id, in: path, required: true, schema: { type: integer, format: int64 } }
         - { name: customerId, in: query, required: false, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 128 } }
       requestBody:
         required: true
         content:
           application/json:
-            schema:
-              type: object
-              required: [detained, remark]
-              properties:
-                detained: { type: boolean }
-                remark: { type: string, minLength: 1, maxLength: 500 }
-      responses: { '200': { description: 暂扣状态已更新 } }
+            schema: { $ref: '#/components/schemas/LastlegOrderHoldRequest' }
+      responses:
+        '200': { description: 暂扣状态已更新, content: { application/json: { schema: { type: object, properties: { code: { type: string }, data: { $ref: '#/components/schemas/LastlegOrderHoldResponse' } } } } } }
+        '409': { description: 版本冲突、幂等键冲突、重复状态或订单已进入出库流程 }
+  /api/platform/v1/last-leg/orders/{id}/manual-nodes:
+    get:
+      summary: 查询尾程订单人工展示节点
+      description: 权限 platform:overseas-warehouse:last-mile-order:list；人工覆盖开启后返回完整且固定顺序的8行快照，行值允许为空。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: integer, format: int64 } }
+        - { name: customerId, in: query, required: false, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+      responses: { '200': { description: 完整人工展示节点快照 } }
+    put:
+      summary: 永久启用并保存尾程订单人工展示节点
+      description: 权限 platform:overseas-warehouse:last-mile-order:edit；提交完整8行快照且至少一个时间非空，使用订单版本和 Idempotency-Key；保存后 nodeSource 永久为 MANUAL，不回写柜节点，也不提供清除或恢复继承接口。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: integer, format: int64 } }
+        - { name: customerId, in: query, required: false, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 128 } }
+      requestBody:
+        required: true
+        content: { application/json: { schema: { $ref: '#/components/schemas/LastlegOrderManualNodesRequest' } } }
+      responses:
+        '200': { description: 更新后的完整8行人工展示节点快照 }
+        '409': { description: 订单版本或幂等键冲突 }
   /api/platform/v1/last-leg/orders/{id}/pallet-merge-required:
     put:
       summary: 设置尾程订单合托标记
@@ -381,22 +402,22 @@ paths:
       responses:
         '200': { description: 平台入库订单详情, content: { application/json: { schema: { $ref: '#/components/schemas/InboundPlanDetailResponse' } } } }
         '404': { description: 入库订单不存在或不属于指定客户 }
-  /api/platform/v1/last-leg/inbound-plans/convert:
+  /api/platform/v1/last-leg/inbound-plans/manual:
     post:
-      summary: 平台生成入库计划
-      description: 权限 platform:overseas-warehouse:inbound-order:create；必须同时传入真实 customerId 与 orderId，服务端按该客户和订单 ID 锁定归属，缺失 customerId 返回 A0400。
+      summary: 平台按单票手工生成入库计划
+      description: 权限 platform:overseas-warehouse:inbound-order:create；按 customerId 与 orderId 锁定单票，校验订单版本、状态、暂扣状态、真实入仓码、客户归属及有效公共接柜仓。一次只生成当前票的独立计划，不改变同柜其他订单；命令原子且幂等。
       security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 128 } }
       requestBody:
         required: true
         content:
           application/json:
-            schema:
-              type: object
-              required: [customerId, orderId]
-              properties:
-                customerId: { type: string, pattern: '^[1-9][0-9]*$' }
-                orderId: { type: string, pattern: '^[1-9][0-9]*$' }
-      responses: { '200': { description: 统一 ApiResponse 包装的入库计划详情 } }
+            schema: { $ref: '#/components/schemas/ManualInboundPlanRequest' }
+      responses:
+        '200': { description: 统一 ApiResponse 包装的入库计划详情 }
+        '400': { description: 客户、入仓码、仓库主数据或请求字段无效 }
+        '409': { description: 订单版本、状态、暂扣状态、重复计划或幂等键冲突 }
   /api/platform/v1/last-leg/inbound-plans/convert-container:
     post:
       summary: 按整柜批量生成入库计划
@@ -1796,6 +1817,61 @@ components:
         - { $ref: '#/components/schemas/MerchantApiResponse' }
         - type: object
           properties: { data: { $ref: '#/components/schemas/InboundPlanDetail' } }
+    LastlegOrderHoldRequest:
+      type: object
+      required: [held, chargeable, reason, expectedVersion]
+      properties:
+        held: { type: boolean }
+        chargeable: { type: boolean, description: 仅 held=true 时生效；解除暂扣后固定为 false }
+        reason: { type: string, minLength: 1, maxLength: 500 }
+        expectedVersion: { type: integer, minimum: 0 }
+    LastlegOrderHoldResponse:
+      type: object
+      required: [orderId, held, chargeable, version]
+      properties:
+        orderId: { type: integer, format: int64 }
+        held: { type: boolean }
+        chargeable: { type: boolean }
+        reason: { type: string, nullable: true }
+        version: { type: integer, minimum: 0 }
+    LastlegOrderManualNodeCode:
+      type: string
+      enum: [DOMESTIC_CUSTOMS_COMPLETED, ESTIMATED_DEPARTURE, ACTUAL_DEPARTURE, ESTIMATED_ARRIVAL, OVERSEAS_CUSTOMS_COMPLETED, ACTUAL_ARRIVAL_WAITING_UNLOAD, PICKUP_APPOINTED, UNLOADED]
+    LastlegOrderManualNode:
+      type: object
+      required: [nodeCode]
+      properties:
+        nodeCode: { $ref: '#/components/schemas/LastlegOrderManualNodeCode' }
+        nodeAt: { type: string, format: date-time, nullable: true }
+    LastlegOrderManualNodesRequest:
+      type: object
+      required: [expectedVersion, nodes]
+      properties:
+        expectedVersion: { type: integer, minimum: 0 }
+        nodes:
+          type: array
+          minItems: 8
+          maxItems: 8
+          description: 必须包含8个枚举节点且各出现一次，至少一个 nodeAt 非空。
+          items: { $ref: '#/components/schemas/LastlegOrderManualNode' }
+    ManualInboundPlanRequest:
+      type: object
+      required: [customerId, orderId, expectedOrderVersion, plannedWarehouseId, plannedWarehouseCode, plannedWarehouseName, plannedArrivalDate, inboundCode, palletCount, palletType, assigned, mergeRequired, urgent]
+      properties:
+        customerId: { type: string, pattern: '^[1-9][0-9]*$' }
+        orderId: { type: integer, format: int64, minimum: 1 }
+        expectedOrderVersion: { type: integer, minimum: 0 }
+        plannedWarehouseId: { type: integer, format: int64, minimum: 1 }
+        plannedWarehouseCode: { type: string, minLength: 1, maxLength: 64 }
+        plannedWarehouseName: { type: string, minLength: 1, maxLength: 255 }
+        plannedArrivalDate: { type: string, format: date }
+        inboundCode: { type: string, minLength: 1, maxLength: 128 }
+        palletCount: { type: integer, minimum: 1, maximum: 999 }
+        palletType: { type: string, minLength: 1, maxLength: 64 }
+        assigned: { type: boolean }
+        mergeRequired: { type: boolean }
+        urgent: { type: boolean }
+        remark: { type: string, nullable: true, maxLength: 1000 }
     PageMetadata:
       type: object
       required: [page, size, total, pages]
@@ -2022,6 +2098,13 @@ components:
         totalVolumeCbm: { type: number }
         expectedPackageCount: { type: integer }
         pickedPackageCount: { type: integer }
+        plannedArrivalDate: { type: string, format: date, nullable: true }
+        palletType: { type: string, nullable: true }
+        assigned: { type: boolean }
+        mergeRequired: { type: boolean }
+        urgent: { type: boolean }
+        creationMode: { type: string, enum: [AUTO, MANUAL] }
+        remark: { type: string, nullable: true }
         lines: { type: array, items: { $ref: '#/components/schemas/InboundPlanLine' } }
         pallets: { type: array, items: { $ref: '#/components/schemas/InboundPlanPallet' } }
         allocations: { type: array, items: { $ref: '#/components/schemas/InboundPlanAllocation' } }
@@ -2044,6 +2127,7 @@ components:
       properties:
         id: { type: string, pattern: '^[0-9]+$' }
         palletNo: { type: string }
+        palletType: { type: string, nullable: true }
         destinationWarehouseId: { type: string, nullable: true }
         destinationWarehouseCode: { type: string, nullable: true }
         destinationWarehouseName: { type: string, nullable: true }