feat(fleet): integrate costs quotes operations and in-transit handovers
This commit is contained in:
@@ -0,0 +1,290 @@
|
||||
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 }
|
||||
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 }
|
||||
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' }
|
||||
Reference in New Issue
Block a user