提交

2026-11-02 17:14:02 +08:00
parent 035e7e06af
commit 21a9ce7d27
98 changed files with 2558 additions and 104 deletions
@@ -1,9 +1,51 @@
 openapi: 3.0.3
 info:
  title: Lastleg Overseas Business API
-  description: 派送资料完整契约见同目录 delivery-documents-v1.yaml；派送列表/详情行返回 bolNo、documentSummary（三类状态与x/3），状态仍使用 version 和 allowedActions。
+  description: 派送资料完整契约见同目录 delivery-documents-v1.yaml；散板取货和送达照片履约见 dispatch-looseboard-execution-v1.yaml。派送列表/详情行返回 bolNo、documentSummary（三类状态与x/3），状态仍使用 version 和 allowedActions。
  version: 1.0.0
 paths:
+  /api/platform/v1/last-leg/dispatches/capacity-demands/{dispatchNo}/cargo:
+    parameters:
+      - { name: dispatchNo, in: path, required: true, schema: { type: string } }
+    get:
+      summary: 读取同仓已审核散板的申报与实收候选
+      description: 需capacity-offer:list或manage以及dispatch:list权限；仅已发布且未发车的有效派送排车，候选展示真实本土散板原单号，本土散板无入仓码和集装箱号时均返回空，不以履约单号代填。审核后申报货物可先排车，无需以PDA打托为前置；不生成实收库存，实际到仓后核对实托和货量，按仓库及真实客户来源隔离。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
+        - { name: size, in: query, schema: { type: integer, minimum: 1, maximum: 50, default: 20 } }
+      responses: { '200': { description: 统一ApiResponse；data为正式排车CandidateList，含候选来源版本、目的地及资格原因 } }
+    post:
+      summary: 将已收货散板加入需求排车
+      description: 需capacity-offer:cargo-add或manage以及dispatch:edit、dispatch:list权限；复用正式AddCargo命令，校验版本、幂等、同仓及整托占用，自动刷新目的站和货量并失效审核，不执行出库拣货。
+      security: [{ bearerAuth: [] }]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/DispatchAddCargo' }
+      responses: { '200': { description: 统一ApiResponse；data为正式排车CommandResult，冲突返回业务码A0409 } }
+  /api/platform/v1/last-leg/local-looseboard-orders/{orderNo}/review:
+    post:
+      summary: 审核散板并创建唯一入仓履约单
+      description: 权限platform:overseas-business:looseboard:status；通过后送货到仓进入PDA收货，仓库上门取货进入取货排车；审核后即可从散板需求添加申报货物；上门取货沿取货排车上传取货与到仓凭证，实收到仓后原单进入PENDING_DISPATCH并交接原排车货量。客户及幂等键严格校验。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: orderNo, 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: [version, decision, idempotencyKey]
+              properties:
+                version: { type: integer, minimum: 0 }
+                decision: { type: string, enum: [APPROVE, REJECT] }
+                idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+                remark: { type: string, maxLength: 1000 }
+      responses: { '200': { description: 统一ApiResponse包装的散板详情，summary.transferNo关联转运履约 } }
  /api/platform/v1/last-leg/dispatches/capacity-demands:
    get:
      summary: 读取有效派送排车的内部散板余位需求
@@ -4817,6 +4859,15 @@ components:
      description: 散板商业主单摘要；池来源附带同客户fleetArrangement，独立订单该字段为null。池来源不创建第二张占位尾程来源。
      required: [id, customerId, orderNo, origin, destination, estimatedPalletCount, packageCount, totalWeightKg, totalVolumeCbm, status, version, createdAt, updatedAt]
      properties:
+        deliveryMode: { type: string, enum: [DELIVERY_TO_WAREHOUSE, WAREHOUSE_PICKUP], description: 送货到仓或仓库上门取货 }
+        operatingWarehouseId: { type: string, description: 实际收货海外仓ID }
+        destinationType: { type: string, enum: [FBA, PRIVATE] }
+        destinationPostalCode: { type: string, maxLength: 32, nullable: true }
+        deliveryContactName: { type: string, maxLength: 128, nullable: true, description: 送货到仓必填 }
+        deliveryContactPhone: { type: string, maxLength: 64, nullable: true, description: 送货到仓必填 }
+        estimatedArrivalAt: { type: string, format: date-time, nullable: true, description: 送货到仓必填 }
+        trackingNo: { type: string, maxLength: 255, nullable: true, description: 可选物流跟踪号 }
+        transferNo: { type: string, nullable: true, description: 审核后生成的仓储转运履约单号 }
        id: { type: string, pattern: '^[0-9]+$' }
        customerId: { type: string }
        orderNo: { type: string }
@@ -5242,8 +5293,16 @@ components:
        remark: { type: string, nullable: true, maxLength: 1000 }
    LooseboardCreate:
      type: object
-      required: [originContactName, originContactPhone, destinationContactName, destinationContactPhone, pickupAt, deliveryAt, origin, destination, estimatedPalletCount, packageCount, totalWeightKg, totalVolumeCbm, idempotencyKey]
+      required: [operatingWarehouseId, deliveryMode, destinationContactName, destinationContactPhone, pickupAt, deliveryAt, destination, estimatedPalletCount, packageCount, totalWeightKg, totalVolumeCbm, idempotencyKey]
      properties:
+        deliveryMode: { type: string, enum: [DELIVERY_TO_WAREHOUSE, WAREHOUSE_PICKUP], description: 送货到仓或仓库上门取货 }
+        operatingWarehouseId: { type: string, description: 实际收货海外仓ID }
+        destinationType: { type: string, enum: [FBA, PRIVATE] }
+        destinationPostalCode: { type: string, maxLength: 32, nullable: true }
+        deliveryContactName: { type: string, maxLength: 128, nullable: true, description: 送货到仓必填 }
+        deliveryContactPhone: { type: string, maxLength: 64, nullable: true, description: 送货到仓必填 }
+        estimatedArrivalAt: { type: string, format: date-time, nullable: true, description: 送货到仓必填 }
+        trackingNo: { type: string, maxLength: 255, nullable: true, description: 可选物流跟踪号 }
        origin: { type: string, maxLength: 255 }
        originAddress: { type: string, nullable: true, maxLength: 500 }
        destination: { type: string, maxLength: 255 }
@@ -5265,8 +5324,16 @@ components:
        idempotencyKey: { type: string, maxLength: 255 }
    LooseboardUpdate:
      type: object
-      required: [originContactName, originContactPhone, destinationContactName, destinationContactPhone, pickupAt, deliveryAt, version, origin, destination, estimatedPalletCount, packageCount, totalWeightKg, totalVolumeCbm]
+      required: [operatingWarehouseId, deliveryMode, destinationContactName, destinationContactPhone, pickupAt, deliveryAt, version, destination, estimatedPalletCount, packageCount, totalWeightKg, totalVolumeCbm]
      properties:
+        deliveryMode: { type: string, enum: [DELIVERY_TO_WAREHOUSE, WAREHOUSE_PICKUP], description: 送货到仓或仓库上门取货 }
+        operatingWarehouseId: { type: string, description: 实际收货海外仓ID }
+        destinationType: { type: string, enum: [FBA, PRIVATE] }
+        destinationPostalCode: { type: string, maxLength: 32, nullable: true }
+        deliveryContactName: { type: string, maxLength: 128, nullable: true, description: 送货到仓必填 }
+        deliveryContactPhone: { type: string, maxLength: 64, nullable: true, description: 送货到仓必填 }
+        estimatedArrivalAt: { type: string, format: date-time, nullable: true, description: 送货到仓必填 }
+        trackingNo: { type: string, maxLength: 255, nullable: true, description: 可选物流跟踪号 }
        version: { type: integer, format: int64, minimum: 0 }
        origin: { type: string, maxLength: 255 }
        originAddress: { type: string, nullable: true, maxLength: 500 }