优化

lastleg-service/src/main/resources/openapi/delivery-documents-v1.yaml

@@ -5,7 +5,7 @@ info:
   description: |
     所有入口只允许平台，customerId 必须为真实派送所属客户；不得按 BOL 文本查找或复用其他客户/派送单文件。
     GET /delivery-orders 及 GET /delivery-orders/{deliveryNo} 的 order 行新增 bolNo 和 documentSummary，version/allowedActions 保持原契约。
-    状态 PUT /delivery-orders/{deliveryNo}/status 请求保持 {status,expectedVersion,remark}，expectedVersion 必传。
+    RECEIPT 签收文件只有在 PUT 保存进入权威资料快照后才自动完成当前派送单；仅上传未保存不会完成。allowedActions 不再返回人工 COMPLETE_DELIVERY。
     START_DELIVERY=DELIVERING（派送中）；COMPLETE_DELIVERY=DELIVERED（完成并记录签收时间、生成待回访）。同状态重放不重复副作用。
     资料不设必传门禁，不以三类齐全作为派送完成条件。业务失败使用统一 ApiResponse（A0422参数、A0409冲突），通常HTTP200。
 security: [{ bearerAuth: [] }]

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

@@ -620,11 +620,11 @@ paths:
   /api/platform/v1/last-leg/dispatches/{dispatchNo}/transfer-delivery:
     post:
       summary: 排车转出库与派送单
-      description: 权限 platform:overseas-warehouse:dispatch:transfer-delivery；只按全局唯一 dispatchNo 锁定记录并从记录解析客户范围，不接收 customerId；同一幂等键或已转换排车重复调用返回既有单据。
+      description: 权限 platform:overseas-warehouse:dispatch:transfer-delivery；只按全局唯一 dispatchNo 锁定记录并从记录解析客户范围，不接收 customerId；一个排车仍生成一张出库单，并按目的FBA仓分别生成派送单，返回 deliveries 数组；同一幂等键或已转换排车重复调用返回全部既有单据。派送费用只发布一次，避免按拆分派送单重复计费。
       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: 状态、托盘或幂等冲突 } }
+      responses: { '200': { description: 一张出库单与按目的FBA仓拆分的派送单转换结果 }, '404': { description: 排车单不存在 }, '409': { description: 状态、托盘、目的FBA仓或幂等冲突 } }
   /api/platform/v1/last-leg/outbound-orders:
     get:
       summary: 分页查询出库单
@@ -664,7 +664,7 @@ paths:
       description: 权限 platform:overseas-warehouse:outbound:list；只按全局唯一 outboundNo 定位并从记录解析客户范围，不接收 customerId。
       security: [{ bearerAuth: [] }]
       parameters: [{ name: outboundNo, in: path, required: true, schema: { type: string } }]
-      responses: { '200': { description: '出库单、出库托盘及关联派送单详情；一件代发等独立出库无派送单时 delivery 为 null，排车转派送必须存在派送单；pallets[].palletNo 为 Warehouse 权威实物托盘码' }, '404': { description: 出库单不存在 } }
+      responses: { '200': { description: '出库单、出库托盘及关联 deliveries 派送单数组；一件代发等独立出库时数组为空，排车转派送按目的FBA仓返回一项或多项；pallets[].palletNo 为 Warehouse 权威实物托盘码' }, '404': { description: 出库单不存在 } }
   /api/platform/v1/last-leg/outbound-orders/{outboundNo}/cancel:
     post:
       summary: 取消未执行出库单
@@ -676,7 +676,7 @@ paths:
   /api/platform/v1/last-leg/delivery-orders:
     get:
       summary: 分页查询平台派送单
-      description: 权限 platform:overseas-warehouse:delivery:list；customerId 仅为可选平台筛选条件。每行返回服务端计算的 allowedActions，页面不得自行推导状态门禁。
+      description: 权限 platform:overseas-warehouse:delivery:list；customerId 仅为可选平台筛选条件。同一排车按目的FBA仓显示为不同派送单，每行返回目的仓快照和服务端计算的 allowedActions，页面不得自行推导状态门禁；完成动作不再由人工触发。
       security: [{ bearerAuth: [] }]
       responses: { '200': { description: 派送单分页 } }
   /api/platform/v1/last-leg/delivery-orders/{deliveryNo}:
@@ -685,7 +685,7 @@ paths:
       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: 派送单不存在 } }
+      responses: { '200': { description: 派送单详情，SKU与BOL打印数据只包含当前派送单目的FBA仓 }, '404': { description: 派送单不存在 } }
   /api/platform/v1/last-leg/exception-orders:
     get:
       summary: 分页查询异常订单
@@ -762,18 +762,10 @@ paths:
       parameters: [{ name: deliveryNo, in: path, required: true, schema: { type: string } }]
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/DeliveryMarkReturn' } } } }
       responses: { '200': { description: 已创建退回异常单 } }
-  /api/platform/v1/last-leg/delivery-orders/{deliveryNo}/complete:
-    post:
-      summary: 标记派送完成并生成回访记录
-      description: 权限 platform:overseas-warehouse:delivery:status。仅 WAIT_DELIVERY/DELIVERING 可完成；DELIVERED 同状态重放成功，其他终态或倒退返回 409。
-      security: [{ bearerAuth: [] }]
-      parameters: [{ name: deliveryNo, in: path, required: true, schema: { type: string } }]
-      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/DeliveryStatusChange' } } } }
-      responses: { '200': { description: 派送状态与回访记录 }, '409': { description: 版本或状态冲突 } }
   /api/platform/v1/last-leg/delivery-orders/{deliveryNo}/status:
     put:
       summary: 更新派送状态
-      description: 权限 platform:overseas-warehouse:delivery:status。只允许 WAIT_DELIVERY→DELIVERING/DELIVERED/REJECTED/CANCELLED、DELIVERING→DELIVERED/REJECTED；同状态幂等，终态不可倒退。
+      description: 权限 platform:overseas-warehouse:delivery:status。人工只允许 WAIT_DELIVERY→DELIVERING/REJECTED/CANCELLED、DELIVERING→REJECTED；DELIVERED 仅由签收资料保存成功自动触发，同状态幂等，终态不可倒退。
       security: [{ bearerAuth: [] }]
       parameters: [{ name: deliveryNo, in: path, required: true, schema: { type: string } }]
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/DeliveryStatusChange' } } } }
@@ -2179,13 +2171,13 @@ components:
       type: object
       required: [status, expectedVersion]
       properties:
-        status: { type: string, enum: [WAIT_DELIVERY, DELIVERING, DELIVERED, REJECTED, CANCELLED] }
+        status: { type: string, enum: [WAIT_DELIVERY, DELIVERING, REJECTED, CANCELLED] }
         expectedVersion: { type: integer, format: int64, minimum: 0 }
         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 接口。
+      enum: [START_DELIVERY, REJECT_DELIVERY, CANCEL_DELIVERY, MARK_RETURN]
+      description: START/REJECT/CANCEL 使用通用 status 接口；MARK_RETURN 使用 mark-return 接口；派送完成由签收资料保存成功自动触发。
     DeliveryMarkReturn:
       type: object
       required: [inboundOrderId, reason, returnDirection, items, idempotencyKey]