提交

lastleg-service/src/main/resources/openapi/exception-return-inbound-v1.yaml

@@ -0,0 +1,95 @@
+openapi: 3.0.3
+info:
+  title: 派送异常退回入库
+  version: 1.0.0
+  description: 排车异常冻结原出库货物，异常单生成退回尾程单后进入PDA退货入库列表。现场展示异常单号、车牌和待收箱数，点击开始作业，不需要回单号或扫码找单。建单不增加库存，分批实收调用原来源RETURN_STOCK_IN或原箱恢复，异常和退回尾程单收齐后完成。
+paths:
+  /api/platform/v1/last-leg/dispatches/{dispatchNo}/exception-return-options:
+    get:
+      summary: 当前排车的原派送货物候选
+      description: 权限platform:overseas-warehouse:dispatch:edit；仅派送中的仓库派送排车。客户归属、尾程单和真实原拣货来源由服务端决定。
+      parameters:
+        - { name: dispatchNo, in: path, required: true, schema: { type: string } }
+      responses:
+        '200': { description: ApiResponse，data为customerId/customerName/deliveryNo/lastMileOrderId/lastMileOrderNo/sources数组；sources包含原出库项、互斥库存仓位或退货原箱、SKU及maxReturnPackages。 }
+  /api/platform/v1/last-leg/exception-orders/{exceptionNo}/generate-return-inbound:
+    post:
+      summary: 生成关联原尾程单的退回入库单
+      description: 权限platform:overseas-warehouse:exception-order:process。customerId显式选择；异常须为退回海外仓且待处理或处理中，版本匹配。以客户和异常ID作为唯一来源，已有结果直接恢复；不创建普通接柜计划、不重复入账或占用原入仓码。data返回orderNo/status/sourceOrderNo。异常详情额外返回returnOrderNo。
+      parameters:
+        - { name: exceptionNo, in: path, required: true, schema: { type: string } }
+        - { name: customerId, in: query, required: true, schema: { type: string } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [expectedVersion, idempotencyKey]
+              properties:
+                expectedVersion: { type: integer, minimum: 0 }
+                idempotencyKey: { type: string, maxLength: 255 }
+      responses:
+        '200': { description: ApiResponse；data为退回尾程单摘要。 }
+  /api/pda/v1/last-leg/return-receipts/exceptions:
+    get:
+      summary: 当前绑定仓的异常退货入库任务列表
+      description: 仅ROLE_OVERSEAS_WAREHOUSE_PDA_OPERATOR及lastleg:pda:operate；服务端冻结仓隔离，不接受客户或仓库参数。只展示已生成退回尾程单的PROCESSING异常，按异常时间排序，最多200条。
+      responses:
+        '200': { description: ApiResponse；data数组含exceptionNo、vehiclePlate、customerName、status、packageCount、receivedPackages和returnOrderNo。 }
+  /api/pda/v1/last-leg/return-receipts/exceptions/{number}/start:
+    post:
+      summary: 点击开始作业，读取异常冻结货物与当前版本
+      parameters:
+        - { name: number, in: path, required: true, schema: { type: string } }
+      responses:
+        '200': { description: ApiResponse；data为异常Detail，含order.version、returnSources剩余来源、returnReceipts实收历史和returnOrderNo。跨仓或非待验收任务拒绝。 }
+  /api/pda/v1/last-leg/return-receipts/exceptions/{number}/evidence:
+    post:
+      summary: 上传本次实收证据
+      parameters:
+        - { name: number, in: path, required: true, schema: { type: string } }
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              required: [file]
+              properties:
+                file: { type: string, format: binary }
+      responses:
+        '200': { description: ApiResponse；data为绑定异常客户和异常ID的fileId/fileName/contentType/sizeBytes。 }
+  /api/pda/v1/last-leg/return-receipts/exceptions/{number}/receive:
+    post:
+      summary: 确认本批实收并恢复原来源库存
+      description: 资格与开始作业一致；当前版本及幂等键必填，原库存仓位与退货原箱恰有一个。本批累计不能超过批准量，原箱须整箱；目标托盘和库位须在冻结仓实际绑定。至少一份本异常证据。原键重放不重复入账，分批使用新键及最新版本；收齐后异常COMPLETED，退回尾程INBOUND_COMPLETED，原单已签收事实保留。
+      parameters:
+        - { name: number, in: path, required: true, schema: { type: string } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [expectedVersion, idempotencyKey, palletCode, locationCode, items, evidenceFileIds]
+              properties:
+                expectedVersion: { type: integer, minimum: 0 }
+                idempotencyKey: { type: string, maxLength: 128 }
+                palletCode: { type: string }
+                locationCode: { type: string }
+                evidenceFileIds: { type: array, minItems: 1, maxItems: 20, items: { type: string } }
+                items:
+                  type: array
+                  minItems: 1
+                  maxItems: 200
+                  items:
+                    type: object
+                    required: [outboundPalletItemId, packages]
+                    properties:
+                      outboundPalletItemId: { type: string }
+                      inventoryPositionId: { type: string, nullable: true }
+                      returnCartonId: { type: string, nullable: true }
+                      packages: { type: integer, minimum: 1 }
+      responses:
+        '200': { description: ApiResponse；data为异常CommandResult，含status/version/restoredPackages/replayed。业务失败仍须读取code。 }

lastleg-service/src/main/resources/openapi/order-budgets-v1.yaml

@@ -2,7 +2,7 @@ openapi: 3.0.3
 info:
   title: 海外客户下单预估资金校验
   version: 1.0.0
-  description: Finance异步冻结成功后才能创建客户采购/本土卡车订单。余额优先、授信补足及不足判断由Finance原子执行；本服务不自行修改钱包。创建订单须使用相同幂等键、金额及币种。未绑定预占15分钟过期；订单终态释放，释放失败重试。预占独立于最终人工费用结算。
+  description: 客户订单先原子落库并进入资金处理中，资金冻结通过Outbox异步执行。冻结成功后进入待审核，失败进入资金失败并可在原订单上重试；平台仅可审核待审核订单。余额优先、授信补足及不足判断由Finance原子执行；本服务不自行修改钱包。预算预占、订单和冻结指令在同一事务内写入，订单终态释放。
 security:
   - bearerAuth: []
 paths:
@@ -11,7 +11,7 @@ paths:
       - {name: kind, in: path, required: true, schema: {type: string, enum: [procurement, trucking]}}
       - {name: key, in: path, required: true, schema: {type: string, minLength: 1, maxLength: 128}}
     post:
-      summary: 发起冻结或读取原请求，失败后可用原键重试
+      summary: 兼容接口：发起或读取预算冻结请求
       description: 客户身份仅来自认证。procurement需要merchant:cross-border:procurement:create，trucking需要merchant:cross-border:domestic-trucking:create；权限不能交叉使用。采购金额是预算单价乘采购数量，免费样品零金额不发资金指令；卡车金额必须大于0。重试禁止更改金额或币种。
       requestBody:
         required: true
@@ -28,10 +28,29 @@ paths:
         '403': {description: 身份或业务创建权限不足}
     get:
       summary: 读取当前客户本次下单的权威资金回执
-      description: 与POST相同创建权限；只有usable=true才允许继续下单。FREEZE_PENDING处理期间应轮询，超时保留原键重试；失败显示Finance返回原因。
+      description: 与POST相同创建权限；该接口保留用于旧客户端兼容。新客户端应直接创建订单，并通过订单资金状态接口读取异步结果。
       responses:
         '200': {$ref: '#/components/responses/Result'}
         '403': {description: 身份或业务创建权限不足}
+  /api/merchant/v1/last-leg/order-budgets/{kind}/orders/{orderNo}:
+    parameters:
+      - {name: kind, in: path, required: true, schema: {type: string, enum: [procurement, trucking]}}
+      - {name: orderNo, in: path, required: true, schema: {type: string, minLength: 1, maxLength: 128}}
+    get:
+      summary: 读取订单资金状态
+      description: 仅当前客户可读。FUNDING_PENDING期间客户端可短暂轮询；FUNDING_FAILED展示失败原因并允许重试。只有PENDING_REVIEW允许平台审核。
+      responses:
+        '200': {$ref: '#/components/responses/Result'}
+  /api/merchant/v1/last-leg/order-budgets/{kind}/orders/{orderNo}/retry:
+    parameters:
+      - {name: kind, in: path, required: true, schema: {type: string, enum: [procurement, trucking]}}
+      - {name: orderNo, in: path, required: true, schema: {type: string, minLength: 1, maxLength: 128}}
+    post:
+      summary: 重试订单资金冻结
+      description: 仅当前客户可重试FUNDING_FAILED订单，沿用原金额和币种；重复请求幂等。
+      responses:
+        '200': {$ref: '#/components/responses/Result'}
+
 components:
   securitySchemes:
     bearerAuth: {type: http, scheme: bearer, bearerFormat: JWT}

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

@@ -1741,7 +1741,7 @@ paths:
   /api/platform/v1/last-leg/dispatches/{dispatchNo}/exceptions:
     post:
       summary: 登记派送异常
-      description: 权限 platform:overseas-warehouse:dispatch:edit；仅有效仓库派送单DELIVERING可登记，保存后阶段不变，不产生退货、签收或库存变化。原键重试恢复原结果。
+      description: 权限 platform:overseas-warehouse:dispatch:edit；仅有效仓库派送单DELIVERING可登记，保存后阶段不变，同事务生成异常工单；选择退回海外仓时必须提交原出库来源和退回数量，冻结退回范围但不增加库存。原键重试恢复原结果。退回尾程建单与PDA列表验收契约见exception-return-inbound-v1.yaml。
       security:
       - bearerAuth: []
       responses:
@@ -2639,7 +2639,7 @@ paths:
   /api/merchant/v1/last-leg/overseas-procurements:
     post:
       summary: 客户创建海外采购订单
-      description: 权限 merchant:cross-border:procurement:create；客户 ID 只取认证身份且不接收 customerId；新单固定进入 PENDING_REVIEW。同幂等键同请求返回既有订单，异请求返回 A0409。
+      description: 权限 merchant:cross-border:procurement:create；客户 ID 只取认证身份且不接收 customerId；新单先进入 FUNDING_PENDING，异步冻结成功进入 PENDING_REVIEW，失败进入 FUNDING_FAILED 并可原单重试；零金额直接待审核。同幂等键同请求返回既有订单，异请求返回 A0409。
       security: [{ bearerAuth: [] }]
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ProcurementCreate' } } } }
       responses: { '200': { description: 采购订单详情, content: { application/json: { schema: { $ref: 'procurement-fulfillment-v1.yaml#/components/schemas/ProcurementCustomerResponse' } } } }, '409': { description: 幂等冲突 } }
@@ -2682,7 +2682,7 @@ paths:
       responses: { '200': { description: 当前客户本土卡订单分页, content: { application/json: { schema: { $ref: '#/components/schemas/TruckPageResponse' } } } } }
     post:
       summary: 客户创建美国本土卡订单
-      description: 权限 merchant:cross-border:domestic-trucking:create；新单固定进入 PENDING_REVIEW，客户不能调用平台审核或状态推进端点。
+      description: 权限 merchant:cross-border:domestic-trucking:create；新单先进入 FUNDING_PENDING，异步冻结成功进入 PENDING_REVIEW，失败进入 FUNDING_FAILED 并可原单重试；客户不能调用平台审核或状态推进端点。
       security: [{ bearerAuth: [] }]
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/TruckCreate' } } } }
       responses: { '200': { description: 本土卡订单详情, content: { application/json: { schema: { $ref: '#/components/schemas/TruckDetailResponse' } } } }, '409': { description: 幂等冲突 } }
@@ -5077,7 +5077,7 @@ components:
         actualVolumeCbm: { type: number, nullable: true }
         status: { type: string }
         version: { type: integer }
-    ProcurementStatus: { type: string, enum: [PENDING_REVIEW, RECEIVING, WAIT_CUSTOMER_CONFIRM, CONFIRMED, IN_TRANSIT, DELIVERING, COMPLETED, REJECTED, CANCELLED, EXCEPTION_CLOSED, WAIT_PURCHASE, WAIT_OVERSEAS_RECEIPT, OVERSEAS_RECEIVING, WAIT_PACKING, WAIT_LABELS, WAIT_OVERSEAS_DISPATCH, WAIT_OVERSEAS_SHIPMENT, INTERNATIONAL_TRANSIT, DOMESTIC_RECEIVING, WAIT_CHARGES, WAIT_CUSTOMER_DISPATCH, WAIT_CUSTOMER_SHIPMENT, SHIPPED_TO_CUSTOMER] }
+    ProcurementStatus: { type: string, enum: [FUNDING_PENDING, FUNDING_FAILED, PENDING_REVIEW, RECEIVING, WAIT_CUSTOMER_CONFIRM, CONFIRMED, IN_TRANSIT, DELIVERING, COMPLETED, REJECTED, CANCELLED, EXCEPTION_CLOSED, WAIT_PURCHASE, WAIT_OVERSEAS_RECEIPT, OVERSEAS_RECEIVING, WAIT_PACKING, WAIT_LABELS, WAIT_OVERSEAS_DISPATCH, WAIT_OVERSEAS_SHIPMENT, INTERNATIONAL_TRANSIT, DOMESTIC_RECEIVING, WAIT_CHARGES, WAIT_CUSTOMER_DISPATCH, WAIT_CUSTOMER_SHIPMENT, SHIPPED_TO_CUSTOMER] }
     ProcurementReview:
       type: object
       required: [version, decision, idempotencyKey]
@@ -5126,7 +5126,7 @@ components:
       properties:
         code: { type: string, enum: ['200'] }
         data: { type: array, items: { type: object, properties: { warehouseId: { type: string }, warehouseCode: { type: string }, warehouseName: { type: string }, countryCode: { type: string } } } }
-    TruckStatus: { type: string, enum: [PENDING_REVIEW, WAITING_INBOUND, RECEIVING, WAITING_CONSOLIDATION, PALLET_OVERAGE_REVIEW, PARTIALLY_ALLOCATED, ALLOCATED, PENDING_DISPATCH, DISPATCHED, IN_TRANSIT, COMPLETED, REJECTED, CANCELLED] }
+    TruckStatus: { type: string, enum: [FUNDING_PENDING, FUNDING_FAILED, PENDING_REVIEW, WAITING_INBOUND, RECEIVING, WAITING_CONSOLIDATION, PALLET_OVERAGE_REVIEW, PARTIALLY_ALLOCATED, ALLOCATED, PENDING_DISPATCH, DISPATCHED, IN_TRANSIT, COMPLETED, REJECTED, CANCELLED] }
     TruckReview:
       type: object
       required: [version, decision, idempotencyKey]
@@ -8378,7 +8378,7 @@ components:
     DispatchReturnDirection:
       type: string
       enum: [OVERSEAS_WAREHOUSE, OTHER]
-      description: 退回海外仓、其他；仅登记去向，不自动退货入库。
+      description: 退回海外仓、其他；退回海外仓须选择原出库货物生成异常单，建单不自动增加库存。
     DispatchMarkException:
       type: object
       x-java-record: DispatchCommands.MarkException
@@ -8409,6 +8409,27 @@ components:
           items:
             type: string
             pattern: ^[1-9][0-9]*$
+        returnSelections:
+          type: array
+          description: 退回海外仓必填。来源必须属于本车派送，箱数不超过原拣货及未签收余量。
+          items:
+            type: object
+            required: [deliveryNo, lastMileOrderId, items]
+            properties:
+              deliveryNo: { type: string }
+              lastMileOrderId: { type: string }
+              items:
+                type: array
+                minItems: 1
+                maxItems: 200
+                items:
+                  type: object
+                  required: [outboundPalletItemId, packageCount]
+                  properties:
+                    outboundPalletItemId: { type: string }
+                    inventoryPositionId: { type: string, nullable: true }
+                    returnCartonId: { type: string, nullable: true }
+                    packageCount: { type: integer, minimum: 1 }
     DispatchExceptionRecord:
       type: object
       x-java-record: DispatchViews.ExceptionRecord

lastleg-service/src/main/resources/openapi/procurement-workflow-v1.yaml

@@ -2,7 +2,7 @@ openapi: 3.0.3
 info:
   title: 简化海外采购批次流程 API
   version: 1.0.0
-  description: 创建采购单后为待审核；审核通过进入收货中。实收可分批登记，客户确认后按采购库存分批出库。库存仅在本批次签收完成时扣减，创建出库单先占用可用库存。
+  description: 客户创建采购单后为资金处理中；冻结成功进入待审核，失败保留原单重试；审核通过进入收货中。实收可分批登记，客户确认后按采购库存分批出库。库存仅在本批次签收完成时扣减，创建出库单先占用可用库存。
 security:
   - bearerAuth: []
 paths:
@@ -276,7 +276,7 @@ components:
       description: Long 主键在 JSON 中按字符串传输，避免前端精度损失
     Status:
       type: string
-      enum: [PENDING_REVIEW, RECEIVING, WAIT_CUSTOMER_CONFIRM, CONFIRMED, IN_TRANSIT, DELIVERING, COMPLETED]
+      enum: [FUNDING_PENDING, FUNDING_FAILED, PENDING_REVIEW, RECEIVING, WAIT_CUSTOMER_CONFIRM, CONFIRMED, IN_TRANSIT, DELIVERING, COMPLETED]
       description: 依次为待审核、收货中、待客户确认、已确认、运输中、派送中、签收完成
     Command:
       type: object