feat: complete phase 5 overseas fulfillment contracts

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

@@ -386,7 +386,19 @@ paths:
       responses:
         '200': { description: 统一 ApiResponse 包装的 DispatchResponse }
         '404': { description: 排车单不存在 }
-        '409': { description: 排车单号在不同客户下重复，无法唯一定位 }
+    put:
+      summary: 编辑待发车排车单
+      description: 权限 platform:overseas-warehouse:dispatch:edit；只按全局唯一 dispatchNo 锁定记录并从记录解析客户范围，不接收 customerId。仅允许 PENDING_DEPARTURE，且请求不包含 status/departAt，发车事实只能由 PDA 作业命令产生。
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: dispatchNo, in: path, required: true, schema: { type: string } }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/DispatchUpdate' } } } }
+      responses: { '200': { description: 更新后的 DispatchResponse }, '404': { description: 排车单不存在 }, '409': { description: 排车单已执行或不可编辑 } }
+    delete:
+      summary: 取消待发车排车单
+      description: 权限 platform:overseas-warehouse:dispatch:cancel；只按全局唯一 dispatchNo 锁定记录并解析客户范围，不接收 customerId。仅 PENDING_DEPARTURE 可取消并释放正式托盘锁；重复取消幂等成功。
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: dispatchNo, in: path, required: true, schema: { type: string } }]
+      responses: { '200': { description: 取消成功或已取消 }, '404': { description: 排车单不存在 }, '409': { description: 排车已开始执行 } }
   /api/platform/v1/last-leg/dispatches/candidates:
     get:
       summary: 查询智能排车候选托盘
@@ -411,7 +423,7 @@ paths:
   /api/platform/v1/last-leg/dispatches/pre-arrange:
     post:
       summary: 创建智能预排车单
-      description: 权限 platform:overseas-warehouse:inbound-order:smart-dispatch；服务端根据所选托盘解析并校验唯一客户范围，锁定同一海外仓的托盘并创建 PENDING_DEPARTURE 排车单，前端不传 customerId；不开放编辑、取消、depart、PDA 出库或派送。
+      description: 权限 platform:overseas-warehouse:inbound-order:smart-dispatch；服务端根据所选托盘解析并校验唯一客户范围，锁定同一海外仓的托盘并创建 PENDING_DEPARTURE 排车单，前端不传 customerId；本接口只负责预排车创建，编辑、取消、转出库派送和 PDA 发车使用各自独立接口与权限。
       security: [{ bearerAuth: [] }]
       requestBody:
         required: true
@@ -467,6 +479,50 @@ paths:
         - { name: draftToken, in: path, required: true, schema: { type: string, maxLength: 64 } }
         - { name: containerId, in: path, required: true, schema: { type: string } }
       responses: { '200': { description: 空车厢删除成功 }, '409': { description: 车厢仍绑定托盘或草稿状态冲突 } }
+  /api/platform/v1/last-leg/dispatches/{dispatchNo}/transfer-delivery:
+    post:
+      summary: 排车转出库与派送单
+      description: 权限 platform:overseas-warehouse:dispatch:transfer-delivery；只按全局唯一 dispatchNo 锁定记录并从记录解析客户范围，不接收 customerId；同一幂等键或已转换排车重复调用返回既有单据。
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: dispatchNo, in: path, required: true, schema: { type: string } }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/DeliveryTransfer' } } } }
+      responses: { '200': { description: 出库与派送单转换结果 }, '404': { description: 排车单不存在 }, '409': { description: 状态、托盘或幂等冲突 } }
+  /api/platform/v1/last-leg/outbound-orders:
+    get:
+      summary: 分页查询出库单
+      description: 权限 platform:overseas-warehouse:outbound:list；customerId 仅为可选平台筛选条件。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: customerId, in: query, required: false, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+        - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
+        - { name: size, in: query, schema: { type: integer, minimum: 1, maximum: 200, default: 20 } }
+        - { name: documentNo, in: query, schema: { type: string } }
+        - { name: warehouseId, in: query, schema: { type: string } }
+        - { name: status, in: query, schema: { type: string } }
+      responses: { '200': { description: 出库单分页 } }
+  /api/platform/v1/last-leg/outbound-orders/one-click-dropship:
+    post:
+      summary: 创建一件代发出库单
+      description: 权限 platform:overseas-warehouse:outbound:create；因尚无既有业务单号可解析归属，平台必须显式传 customerId。
+      security: [{ bearerAuth: [] }]
+      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/{outboundNo}:
+    get:
+      summary: 查询出库单详情
+      description: 权限 platform:overseas-warehouse:outbound:list；只按全局唯一 outboundNo 定位并从记录解析客户范围，不接收 customerId。
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: outboundNo, in: path, required: true, schema: { type: string } }]
+      responses: { '200': { description: 出库单及关联派送单详情 }, '404': { description: 出库单不存在 } }
+  /api/platform/v1/last-leg/outbound-orders/{outboundNo}/cancel:
+    post:
+      summary: 取消未执行出库单
+      description: 权限 platform:overseas-warehouse:outbound:cancel；只按全局唯一 outboundNo 锁定并解析客户范围，不接收 customerId。仅未开始拣货/出库的单据可取消，重复取消幂等成功。
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: outboundNo, in: path, required: true, schema: { type: string } }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/OutboundCancel' } } } }
+      responses: { '200': { description: 取消成功或已取消 }, '404': { description: 出库单不存在 }, '409': { description: 出库已开始执行 } }
   /api/platform/v1/last-leg/overseas-procurements:
     get:
       summary: 分页查询海外采购订单
@@ -533,6 +589,39 @@ paths:
         required: true
         content: { application/json: { schema: { $ref: '#/components/schemas/ProcurementReview' } } }
       responses: { '200': { description: 统一 ApiResponse 包装的采购订单详情 } }
+  /api/merchant/v1/last-leg/delivery-orders:
+    get:
+      summary: 客户分页查询自己的派送单
+      description: 权限 merchant:warehouse:delivery:list；客户范围只取认证 Token，不接收 customerId。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
+        - { name: size, in: query, schema: { type: integer, minimum: 1, maximum: 200, default: 20 } }
+        - { name: documentNo, in: query, schema: { type: string } }
+        - { name: warehouseId, in: query, schema: { type: string } }
+        - { name: status, in: query, schema: { type: string } }
+        - { name: dispatchNo, in: query, schema: { type: string } }
+        - { name: waybillNo, in: query, schema: { type: string } }
+        - { name: vehiclePlate, in: query, schema: { type: string } }
+        - { name: driverName, in: query, schema: { type: string } }
+        - { name: deliveryMethod, in: query, schema: { type: string } }
+        - { name: plannedFrom, in: query, schema: { type: string, format: date-time } }
+        - { name: plannedTo, in: query, schema: { type: string, format: date-time } }
+      responses: { '200': { description: 当前客户派送单分页 }, '403': { description: 缺少客户派送查看权限 } }
+    post:
+      summary: 客户从自己的排车单创建派送单
+      description: 权限 merchant:warehouse:delivery:create；客户范围只取认证 Token，dispatchNo 必填，不接收 customerId；同一幂等键或已转换排车重复调用返回既有单据。
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: dispatchNo, in: query, required: true, schema: { type: string, minLength: 1 } }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/DeliveryTransfer' } } } }
+      responses: { '200': { description: 出库与派送单转换结果 }, '403': { description: 缺少客户派送创建权限 }, '404': { description: 当前客户下排车单不存在 }, '409': { description: 状态、参数或幂等冲突 } }
+  /api/merchant/v1/last-leg/delivery-orders/{deliveryNo}:
+    get:
+      summary: 客户查询自己的派送单详情
+      description: 权限 merchant:warehouse:delivery:list；列表权限包含详情只读，客户范围只取认证 Token，不接收 customerId。
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: deliveryNo, in: path, required: true, schema: { type: string } }]
+      responses: { '200': { description: 当前客户派送单详情 }, '403': { description: 缺少客户派送查看权限 }, '404': { description: 当前客户下派送单不存在 } }
   /api/merchant/v1/last-leg/overseas-procurements:
     post:
       summary: 客户创建海外采购订单
@@ -1246,6 +1335,69 @@ components:
         id: { type: string }
         capacity: { type: integer }
         palletIds: { type: array, items: { type: string } }
+    DispatchUpdate:
+      type: object
+      description: 普通编辑字段；不包含 status 或 departAt。
+      properties:
+        vehiclePlate: { type: string, nullable: true, maxLength: 64 }
+        driverName: { type: string, nullable: true, maxLength: 128 }
+        driverPhone: { type: string, nullable: true, maxLength: 64 }
+        carrierName: { type: string, nullable: true, maxLength: 255 }
+        route: { type: string, nullable: true, maxLength: 255 }
+        fbaAppointmentNo: { type: string, nullable: true, maxLength: 64 }
+        fbaAppointmentStatus: { type: string, nullable: true, maxLength: 32 }
+        vehicleAppointmentStatus: { type: string, nullable: true, maxLength: 32 }
+        estimatedArrivalAt: { type: string, format: date-time, nullable: true }
+    DeliveryTransfer:
+      type: object
+      required: [idempotencyKey, plannedDeliveryAt, deliveryMethod, pickupMethod, loadingType, fees]
+      properties:
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+        plannedDeliveryAt: { type: string, format: date-time }
+        deliveryMethod: { type: string, maxLength: 32 }
+        waybillNo: { type: string, nullable: true, maxLength: 128 }
+        carrierName: { type: string, nullable: true, maxLength: 255 }
+        pickupMethod: { type: string, maxLength: 64 }
+        loadingType: { type: string, maxLength: 64 }
+        vehicleType: { type: string, nullable: true, maxLength: 64 }
+        vehicleSize: { type: string, nullable: true, maxLength: 64 }
+        driverName: { type: string, nullable: true, maxLength: 128 }
+        driverPhone: { type: string, nullable: true, maxLength: 64 }
+        vehiclePlate: { type: string, nullable: true, maxLength: 64 }
+        appointmentAccount: { type: string, nullable: true, maxLength: 128 }
+        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' } }
+    DeliveryFeeInput:
+      type: object
+      required: [feeType, currency, amount]
+      properties:
+        feeType: { type: string, maxLength: 64 }
+        currency: { type: string, maxLength: 8 }
+        amount: { type: number, minimum: 0 }
+        remark: { type: string, nullable: true, maxLength: 500 }
+    OneClickOutboundCreate:
+      type: object
+      required: [recipient, items, idempotencyKey]
+      properties:
+        recipient: { type: string, maxLength: 1000 }
+        remark: { type: string, nullable: true, maxLength: 1000 }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+        items:
+          type: array
+          minItems: 1
+          maxItems: 200
+          items:
+            type: object
+            required: [inventoryPositionId, packages, sku]
+            properties:
+              inventoryPositionId: { type: string, pattern: '^[1-9][0-9]*$' }
+              packages: { type: integer, format: int64, minimum: 1 }
+              sku: { type: string, maxLength: 128 }
+    OutboundCancel:
+      type: object
+      required: [reason]
+      properties: { reason: { type: string, minLength: 1, maxLength: 1000 } }
     DispatchResponse:
       type: object
       properties: