提交

2026-10-20 21:47:51 +08:00
parent 34b90f311a
commit 137efc6809
54 changed files with 1434 additions and 63 deletions
@@ -0,0 +1,99 @@
+openapi: 3.0.3
+info:
+  title: 现有排车运输任务
+  version: 1.0.0
+  description: >-
+    平台主体（tenantId=0）在现有排车列表内安排到仓取货、本土卡车，使用真实PC排车号。
+    请求经统一Gateway与Bearer认证；JSON响应HTTP200，业务code=200成功，A0400参数错误、A0403权限不足、A0404不存在、A0409版本或状态冲突。
+    list读取、create安排、edit分配/执行/释放、depart发车、cancel取消权限前缀均为platform:overseas-warehouse:dispatch:。
+    创建及执行使用稳定idempotencyKey；重试保留完整原载荷。取消仅限未发车；完成后分别释放司机、车辆。
+    到仓取货逐原单确认实提和送仓，送仓只开放仓库收货门禁；本土卡车同步原单运输状态，完成须本任务凭证。
+servers:
+  - url: /api/platform/v1/last-leg/dispatches/transport-tasks
+security:
+  - bearerAuth: []
+paths:
+  /pickup-candidates:
+    get:
+      summary: 同仓上门取货候选（list，page/size/keyword/warehouseId）
+      responses: &response
+        '200':
+          description: 业务响应信封；data为对应详情、候选或操作结果
+  /truck-candidates:
+    get:
+      summary: 待派车且未被运输或拼车占用的本土卡车候选（list）
+      responses: *response
+  /pickup:
+    post:
+      summary: 同一海外仓多客户取货安排（create）
+      description: sources为customerId/transferNo数组，plannedDepartureAt和expectedDriverEndAt为ISO时刻；idempotencyKey必填，remark可选。返回Detail。
+      responses: *response
+  /truck:
+    post:
+      summary: 本土卡车原单接入排车（create）
+      description: customerId、orderNo、warehouseId、plannedDepartureAt、expectedDriverEndAt、idempotencyKey必填；原单须PENDING_DISPATCH且未被占用。返回Detail。
+      responses: *response
+  /{number}:
+    parameters: &number
+      - { name: number, in: path, required: true, schema: { type: string }, description: 真实PC排车业务号 }
+    get:
+      summary: 排车运输详情（list）
+      description: data包含dispatchNo、taskType（PICKUP/LOCAL_TRUCK）、execution（现有资源与执行详情）、customerId、orderNo、pickups、completionEvidence（已确认凭证）。
+      responses: *response
+  /{number}/{action}:
+    parameters:
+      - { name: number, in: path, required: true, schema: { type: string } }
+      - { name: action, in: path, required: true, schema: { type: string, enum: [assign, cancel, resource-occupancy, release] } }
+    post:
+      summary: 分配、取消、资源可用性查询与实际任务释放
+      description: >-
+        assign(edit)：recordVersion、vehicleId、driverId、reason；cancel(cancel)：recordVersion、reason。
+        resource-occupancy(list)：kind=VEHICLE/DRIVER、resourceIds数组。
+        release(edit)：recordVersion、resourceKind、actualEndAt、endLocation、vehicleStatus（车辆必填）、idempotencyKey、reason。
+      responses: *response
+  /{number}/{kind}/{action}:
+    parameters:
+      - { name: number, in: path, required: true, schema: { type: string } }
+      - { name: kind, in: path, required: true, schema: { type: string, enum: [pickup, truck] } }
+      - { name: action, in: path, required: true, schema: { type: string, enum: [depart, complete] } }
+    post:
+      summary: 运输发车（depart）或完成（edit）
+      description: recordVersion、idempotencyKey、reason必填。本土卡车complete还须至少一份evidenceFileIds，文件归属本任务。取货complete要求所有原单已送仓。
+      responses: *response
+  /{number}/pickup/{customer}/{source}/{action}:
+    parameters:
+      - { name: number, in: path, required: true, schema: { type: string } }
+      - { name: customer, in: path, required: true, schema: { type: string } }
+      - { name: source, in: path, required: true, schema: { type: string }, description: 仓储转运单号 }
+      - { name: action, in: path, required: true, schema: { type: string, enum: [picked, arrive, files] } }
+    post:
+      summary: 按原单上传凭证、确认实提或送仓（edit）
+      description: files使用multipart字段file；picked使用recordVersion、idempotencyKey、actualPackages、evidenceFileIds、remark；arrive使用recordVersion、idempotencyKey、reason。凭证不能跨客户原单使用。
+      responses: *response
+  /{number}/truck/files:
+    parameters: *number
+    post:
+      summary: 本土卡车凭证上传（edit）
+      description: multipart字段file，非空且不超过10MB，只能在计划或运输中上传。上传不等于完成，须通过complete命令确认文件引用。
+      responses: *response
+  /{number}/truck/files/{fileId}:
+    parameters:
+      - { name: number, in: path, required: true, schema: { type: string } }
+      - { name: fileId, in: path, required: true, schema: { type: integer, format: int64 } }
+    get:
+      summary: 已确认本土卡车完成凭证鉴权下载（list）
+      responses:
+        '200': { description: application/octet-stream文件；失败返回业务响应信封 }
+  /{number}/pickup/{customer}/{source}/files/{fileId}:
+    parameters:
+      - { name: number, in: path, required: true, schema: { type: string } }
+      - { name: customer, in: path, required: true, schema: { type: string } }
+      - { name: source, in: path, required: true, schema: { type: string } }
+      - { name: fileId, in: path, required: true, schema: { type: integer, format: int64 } }
+    get:
+      summary: 当前排车原单已确认取货凭证鉴权下载（list）
+      responses:
+        '200': { description: application/octet-stream文件；当前排车及原单归属不符时拒绝 }
+components:
+  securitySchemes:
+    bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT }