优化

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

@@ -579,6 +579,18 @@ paths:
       parameters: [{ name: customerId, in: query, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }]
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/OneClickOutboundCreate' } } } }
       responses: { '200': { description: 一件代发出库 PDA 任务 }, '409': { description: 库存或幂等冲突 } }
+  /api/platform/v1/last-leg/outbound-orders/one-click-dropship/candidates:
+    get:
+      summary: 查询一件代发出库候选库存
+      description: 权限 platform:overseas-warehouse:outbound:create；按客户及可选海外仓一次查询服务端权威候选，仅返回 ACTIVE 一件代发档案、OCCUPIED 正可用库存、AVAILABLE 箱唛与 SKU 余额共同覆盖且未被排车、转仓或待执行出库占用的维度。创建命令会再次校验，不信任前端候选快照。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: customerId, in: query, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+        - { name: warehouseId, in: query, required: false, schema: { type: string } }
+      responses:
+        '200':
+          description: 最多 500 条一件代发出库候选；单次 SQL 返回，不逐行补查
+          content: { application/json: { schema: { type: array, items: { $ref: '#/components/schemas/OneClickOutboundCandidate' } } } }
   /api/platform/v1/last-leg/outbound-orders/{outboundNo}:
     get:
       summary: 查询出库单详情
@@ -597,13 +609,13 @@ paths:
   /api/platform/v1/last-leg/delivery-orders:
     get:
       summary: 分页查询平台派送单
-      description: 权限 platform:overseas-warehouse:delivery:list；customerId 仅为可选平台筛选条件。
+      description: 权限 platform:overseas-warehouse:delivery:list；customerId 仅为可选平台筛选条件。每行返回服务端计算的 allowedActions，页面不得自行推导状态门禁。
       security: [{ bearerAuth: [] }]
       responses: { '200': { description: 派送单分页 } }
   /api/platform/v1/last-leg/delivery-orders/{deliveryNo}:
     get:
       summary: 查询平台派送单详情
-      description: 权限 platform:overseas-warehouse:delivery:list；列表权限包含详情只读。
+      description: 权限 platform:overseas-warehouse:delivery:list；列表权限包含详情只读；order.allowedActions 为当前可执行动作。
       security: [{ bearerAuth: [] }]
       parameters: [{ name: deliveryNo, in: path, required: true, schema: { type: string } }]
       responses: { '200': { description: 派送单详情 }, '404': { description: 派送单不存在 } }
@@ -643,18 +655,18 @@ paths:
   /api/platform/v1/last-leg/delivery-orders/{deliveryNo}/complete:
     post:
       summary: 标记派送完成并生成回访记录
-      description: 权限 platform:overseas-warehouse:delivery:status。
+      description: 权限 platform:overseas-warehouse:delivery:status。仅 WAIT_DELIVERY/DELIVERING 可完成；DELIVERED 同状态重放成功，其他终态或倒退返回 409。
       security: [{ bearerAuth: [] }]
       parameters: [{ name: deliveryNo, in: path, required: true, schema: { type: string } }]
       responses: { '200': { description: 派送状态与回访记录 } }
   /api/platform/v1/last-leg/delivery-orders/{deliveryNo}/status:
     put:
       summary: 更新派送状态
-      description: 权限 platform:overseas-warehouse:delivery:status。
+      description: 权限 platform:overseas-warehouse:delivery:status。只允许 WAIT_DELIVERY→DELIVERING/DELIVERED/REJECTED/CANCELLED、DELIVERING→DELIVERED/REJECTED；同状态幂等，终态不可倒退。
       security: [{ bearerAuth: [] }]
       parameters: [{ name: deliveryNo, in: path, required: true, schema: { type: string } }]
-      requestBody: { required: true, content: { application/json: { schema: { type: object } } } }
-      responses: { '200': { description: 更新后的派送状态 } }
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/DeliveryStatusChange' } } } }
+      responses: { '200': { description: 更新后的派送状态 }, '409': { description: 非法状态迁移 } }
   /api/platform/v1/last-leg/customer-visits:
     get:
       summary: 分页查询客户回访
@@ -1650,6 +1662,16 @@ components:
         sellerName: { type: string, nullable: true, maxLength: 128 }
         remark: { type: string, nullable: true, maxLength: 1000 }
         fees: { type: array, minItems: 1, maxItems: 20, items: { $ref: '#/components/schemas/DeliveryFeeInput' } }
+    DeliveryStatusChange:
+      type: object
+      required: [status]
+      properties:
+        status: { type: string, enum: [WAIT_DELIVERY, DELIVERING, DELIVERED, REJECTED, CANCELLED] }
+        remark: { type: string, nullable: true, maxLength: 500 }
+    DeliveryAllowedAction:
+      type: string
+      enum: [START_DELIVERY, COMPLETE_DELIVERY, REJECT_DELIVERY, CANCEL_DELIVERY, MARK_RETURN]
+      description: START/COMPLETE/REJECT/CANCEL 使用通用 status 接口；MARK_RETURN 使用 mark-return 接口。
     DeliveryFeeInput:
       type: object
       required: [feeType, currency, amount]
@@ -1676,6 +1698,18 @@ components:
               inventoryPositionId: { type: string, pattern: '^[1-9][0-9]*$' }
               packages: { type: integer, format: int64, minimum: 1 }
               sku: { type: string, maxLength: 128 }
+    OneClickOutboundCandidate:
+      type: object
+      required: [inventoryPositionId, overseasWarehouseId, palletNo, skuCode, availablePackages]
+      properties:
+        inventoryPositionId: { type: string, pattern: '^[1-9][0-9]*$', description: 创建命令提交键，不作为用户展示编号 }
+        overseasWarehouseId: { type: string }
+        overseasWarehouseName: { type: string, nullable: true }
+        palletNo: { type: string }
+        inboundCode: { type: string, nullable: true }
+        skuCode: { type: string }
+        productName: { type: string, nullable: true }
+        availablePackages: { type: integer, format: int64, minimum: 1, description: 库存位置、SKU余额和AVAILABLE箱唛三者的可用最小值 }
     OutboundCancel:
       type: object
       required: [reason]