302 lines
14 KiB
YAML
302 lines
14 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: 车辆在途交接
|
|
version: 1.0.0
|
|
description: 从不可变DEPART及真实派送终态核对剩余货物。交接不重新出库或收费，不重写原始发车。旧车辆和司机分别确认实际任务结束后释放。
|
|
security:
|
|
- bearerAuth: []
|
|
paths:
|
|
/api/pda/v1/last-leg/dispatches/{dispatchNo}/handover-status:
|
|
get:
|
|
description: lastleg:pda:operate及ROLE_OVERSEAS_WAREHOUSE_PDA_OPERATOR；只读，仓库来自Token。只返回所选排车的原发车资源、逐派送当前资源及涉及该排车的最近交接，不返回其他客户货物或内部ID。不提供PDA交接确认写接口。
|
|
parameters:
|
|
- { name: dispatchNo, in: path, required: true, schema: { type: string } }
|
|
responses:
|
|
'200':
|
|
description: 当前排车运输及交接状态
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Envelope'
|
|
- type: object
|
|
properties:
|
|
data:
|
|
type: object
|
|
properties:
|
|
dispatchNo: { type: string }
|
|
tripNo: { type: string }
|
|
tripStatus: { type: string, enum: [IN_TRANSIT, COMPLETED] }
|
|
tripRecordVersion: { type: string }
|
|
originalDeparture: { $ref: '#/components/schemas/Transport' }
|
|
deliveries:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
deliveryNo: { type: string }
|
|
status: { type: string }
|
|
packages: { type: integer }
|
|
remainingPackages: { type: integer, minimum: 0, description: 原运输尚未签收且尚未实际退回的箱数 }
|
|
terminalAt: { type: string, format: date-time, nullable: true }
|
|
transport: { $ref: '#/components/schemas/Transport' }
|
|
latestHandover:
|
|
type: object
|
|
nullable: true
|
|
properties:
|
|
handoverNo: { type: string }
|
|
handedOverAt: { type: string, format: date-time }
|
|
location: { type: string }
|
|
previous: { $ref: '#/components/schemas/Transport' }
|
|
replacement: { $ref: '#/components/schemas/Transport' }
|
|
/api/platform/v1/last-leg/fleet/trips/{tripNo}/handovers:
|
|
parameters:
|
|
- $ref: '#/components/parameters/TripNo'
|
|
get:
|
|
description: platform:fleet:trip:list；按车次分页读取交接及原资源任务结束记录。
|
|
parameters:
|
|
- { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
|
|
- { name: size, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 20 } }
|
|
responses:
|
|
'200':
|
|
description: 业务响应
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Envelope'
|
|
- type: object
|
|
properties:
|
|
data:
|
|
type: object
|
|
required: [records, page, size, total, pages]
|
|
properties:
|
|
records: { type: array, items: { $ref: '#/components/schemas/Handover' } }
|
|
page: { type: integer }
|
|
size: { type: integer }
|
|
total: { type: integer, format: int64 }
|
|
pages: { type: integer }
|
|
post:
|
|
description: platform:fleet:trip:handover；同车次请求键唯一，异内容拒绝；先锁车次及新资源，再锁原客户执行单复核。原资源仍占用，车次保持IN_TRANSIT，仅未完成派送更新资源。失败整体回滚。
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [selection, cargoHash, location, idempotencyKey]
|
|
properties:
|
|
selection: { $ref: '#/components/schemas/Selection' }
|
|
cargoHash: { type: string, pattern: '^[0-9a-f]{64}$' }
|
|
location: { type: string, minLength: 1, maxLength: 500 }
|
|
reason: { type: string, maxLength: 1000 }
|
|
idempotencyKey: { type: string, minLength: 8, maxLength: 128 }
|
|
responses:
|
|
'200': { $ref: '#/components/responses/Handover' }
|
|
/api/platform/v1/last-leg/fleet/trips/{tripNo}/handovers/preview:
|
|
parameters:
|
|
- $ref: '#/components/parameters/TripNo'
|
|
post:
|
|
description: platform:fleet:trip:list；只核对不写入。资格、容量、占用和派送事实变化使cargoHash失效。已签收后另退货使用原签收事实，未签收退回必须有RETURN_COMPLETED证据。部分同托仍用原整托实测，不按箱数比例猜重量体积。
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema: { $ref: '#/components/schemas/Selection' }
|
|
responses:
|
|
'200':
|
|
description: 交接预览
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Envelope'
|
|
- type: object
|
|
properties:
|
|
data:
|
|
type: object
|
|
required: [tripNo, recordVersion, cargoHash, previous, replacement, capacity, cargo, driverQualification]
|
|
properties:
|
|
tripNo: { type: string }
|
|
recordVersion: { type: integer, format: int64 }
|
|
cargoHash: { type: string }
|
|
previous: { $ref: '#/components/schemas/Resource' }
|
|
replacement: { $ref: '#/components/schemas/Resource' }
|
|
capacity: { $ref: '#/components/schemas/Load' }
|
|
cargo: { $ref: '#/components/schemas/Inspection' }
|
|
driverQualification:
|
|
type: object
|
|
properties:
|
|
canDispatch: { type: boolean }
|
|
expiringSoon: { type: boolean }
|
|
reason: { type: string }
|
|
licenseExpiresOn: { type: string, format: date, nullable: true }
|
|
/api/platform/v1/last-leg/fleet/trips/{tripNo}/handovers/{handoverNo}/resources/release:
|
|
parameters:
|
|
- $ref: '#/components/parameters/TripNo'
|
|
- { name: handoverNo, in: path, required: true, schema: { type: string } }
|
|
post:
|
|
description: platform:fleet:trip:release；分别结束被接替车辆或司机任务，可早于整车货物结案。未变化资源仍由原车次结案后释放。原请求重放不操作后续占用，车辆状态与结束记录同事务提交。
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [recordVersion, resourceKind, actualEndAt, location, idempotencyKey]
|
|
properties:
|
|
recordVersion: { type: integer, format: int64, minimum: 0, description: 交接记录版本 }
|
|
resourceKind: { type: string, enum: [VEHICLE, DRIVER] }
|
|
actualEndAt: { type: string, format: date-time }
|
|
location: { type: string, minLength: 1, maxLength: 500 }
|
|
vehicleStatus: { type: string, nullable: true, enum: [IN_SERVICE, MAINTENANCE, INACTIVE, RETURNED], description: 结束原车辆必填；司机不得提交 }
|
|
idempotencyKey: { type: string, minLength: 8, maxLength: 128 }
|
|
responses:
|
|
'200': { $ref: '#/components/responses/Handover' }
|
|
components:
|
|
securitySchemes:
|
|
bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT }
|
|
parameters:
|
|
TripNo: { name: tripNo, in: path, required: true, schema: { type: string } }
|
|
responses:
|
|
Handover:
|
|
description: 已保存的交接事实及资源结束状态
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Envelope'
|
|
- type: object
|
|
properties:
|
|
data: { $ref: '#/components/schemas/Handover' }
|
|
schemas:
|
|
Transport:
|
|
type: object
|
|
properties:
|
|
vehiclePlate: { type: string, nullable: true }
|
|
driverName: { type: string, nullable: true }
|
|
driverPhone: { type: string, nullable: true }
|
|
Envelope:
|
|
type: object
|
|
required: [code]
|
|
properties:
|
|
code: { type: string, example: '200' }
|
|
message: { type: string }
|
|
Selection:
|
|
type: object
|
|
required: [recordVersion, vehicleId, driverId, expectedDriverEndAt, handedOverAt]
|
|
properties:
|
|
recordVersion: { type: integer, format: int64, minimum: 0 }
|
|
vehicleId: { type: string, pattern: '^[1-9][0-9]*$' }
|
|
driverId: { type: string, pattern: '^[1-9][0-9]*$' }
|
|
expectedDriverEndAt: { type: string, format: date-time }
|
|
handedOverAt: { type: string, format: date-time }
|
|
Resource:
|
|
type: object
|
|
properties:
|
|
vehicleId: { type: string }
|
|
vehiclePlate: { type: string, nullable: true }
|
|
driverId: { type: string }
|
|
driverName: { type: string, nullable: true }
|
|
driverPhone: { type: string, nullable: true }
|
|
Load:
|
|
type: object
|
|
properties:
|
|
palletSpaces: { type: integer }
|
|
weightKg: { type: number }
|
|
volumeCbm: { type: number }
|
|
Cargo:
|
|
type: object
|
|
properties:
|
|
customerId: { type: string, description: 隔离键，不作客户名称展示 }
|
|
dispatchNo: { type: string }
|
|
itemId: { type: string, description: 内部核对键，不作业务编号展示 }
|
|
palletId: { type: string, description: 内部核对键，不作托盘码展示 }
|
|
destinationKey: { type: string, description: 匹配键，私人地址摘要不可作地址展示 }
|
|
packages: { type: integer }
|
|
Delivery:
|
|
type: object
|
|
properties:
|
|
customerId: { type: string }
|
|
dispatchNo: { type: string }
|
|
deliveryNo: { type: string }
|
|
destinationKey: { type: string }
|
|
packages: { type: integer }
|
|
terminalAt: { type: string, format: date-time, nullable: true }
|
|
returnedCargo:
|
|
type: array
|
|
description: 由实际退回入账流水映射到原发运明细；部分退回按此扣减箱数，未清空实托保留原测量载荷。
|
|
items:
|
|
type: object
|
|
properties:
|
|
itemId: { type: string }
|
|
palletId: { type: string }
|
|
packages: { type: integer, minimum: 1 }
|
|
receivedAt: { type: string, format: date-time }
|
|
Inspection:
|
|
type: object
|
|
properties:
|
|
remainingCargo: { type: array, items: { $ref: '#/components/schemas/Cargo' } }
|
|
completedDeliveries: { type: array, items: { $ref: '#/components/schemas/Delivery' } }
|
|
remainingPalletIds: { type: array, uniqueItems: true, items: { type: string } }
|
|
occupied: { $ref: '#/components/schemas/Load' }
|
|
Snapshot:
|
|
type: object
|
|
properties:
|
|
previous: { $ref: '#/components/schemas/Resource' }
|
|
replacement: { $ref: '#/components/schemas/Resource' }
|
|
handedOverAt: { type: string, format: date-time }
|
|
location: { type: string }
|
|
reason: { type: string }
|
|
expectedDriverEndAt: { type: string, format: date-time }
|
|
capacity: { $ref: '#/components/schemas/Load' }
|
|
cargo: { $ref: '#/components/schemas/Inspection' }
|
|
executionEvidence:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
dispatchNo: { type: string }
|
|
customerId: { type: string }
|
|
warehouseId: { type: string }
|
|
shippedPackages: { type: integer }
|
|
deliveries:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
cargo: { $ref: '#/components/schemas/Delivery' }
|
|
status: { type: string }
|
|
recordVersion: { type: integer, format: int64 }
|
|
transport: { $ref: '#/components/schemas/Transport' }
|
|
operatorId: { type: string, description: 审计身份，不作姓名展示 }
|
|
carriedDeliveries:
|
|
type: array
|
|
description: 当次实际交接的未完成派送身份，用于车辆运输区段查询
|
|
items:
|
|
type: object
|
|
properties:
|
|
customerId: { type: string }
|
|
deliveryNo: { type: string }
|
|
recordedAt: { type: string, format: date-time }
|
|
Released:
|
|
type: object
|
|
nullable: true
|
|
properties:
|
|
idempotencyKey: { type: string }
|
|
requestHash: { type: string }
|
|
actualEndAt: { type: string, format: date-time }
|
|
location: { type: string }
|
|
vehicleStatus: { type: string, nullable: true }
|
|
operatorId: { type: string }
|
|
recordedAt: { type: string, format: date-time }
|
|
Handover:
|
|
type: object
|
|
properties:
|
|
handoverNo: { type: string }
|
|
tripNo: { type: string }
|
|
recordVersion: { type: integer, format: int64 }
|
|
snapshot: { $ref: '#/components/schemas/Snapshot' }
|
|
vehicleRelease: { $ref: '#/components/schemas/Released' }
|
|
driverRelease: { $ref: '#/components/schemas/Released' }
|