311 lines
15 KiB
YAML
311 lines
15 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: 平台车辆管理司机档案
|
|
version: 1.0.0
|
|
description: >-
|
|
平台司机主数据，列表权限包含详情、资格预览、历史和已关联证照读取。
|
|
写操作独立鉴权且要求当前recordVersion；创建版本0，后续每次成功写入递增。
|
|
证照或身份关键字段变化、替换附件后重新待审；电话和备注更正不撤销既有审核。
|
|
驾驶证是当前资格最低要求，其他资质不隐式必填。日期按licenseZone计算，
|
|
30天内到期但仍有效允许并提醒，任务结束达到有效截止日次日当地零点或更晚则禁止。
|
|
缺少预计结束时间时资格返回MISSING_TRIP_END；资格预览不预留司机，不代替发车事务复核。
|
|
新档案允许缺证照保存为PENDING，通过审核必须补齐编号、类型、有效期和真实附件。
|
|
所有业务错误遵循HTTP200加code，认证或基础设施错误可返回401/403/503。
|
|
security:
|
|
- bearerAuth: []
|
|
paths:
|
|
/api/platform/v1/last-leg/fleet/drivers:
|
|
get:
|
|
summary: 分页查询司机及资格
|
|
description: '权限：platform:overseas-master-data:driver:list；无逐行文件请求。'
|
|
parameters:
|
|
- {name: page, in: query, schema: {type: integer, minimum: 1, default: 1}}
|
|
- {name: size, in: query, schema: {type: integer, minimum: 1, maximum: 200, default: 20}}
|
|
- {name: keyword, in: query, schema: {type: string, maxLength: 128}}
|
|
- {name: active, in: query, schema: {type: boolean}}
|
|
- {name: reviewStatus, in: query, schema: {type: string, enum: [PENDING, APPROVED, REJECTED]}}
|
|
- {name: ownership, in: query, schema: {type: string, enum: [OWNED, DISPATCHED]}}
|
|
- {name: region, in: query, schema: {type: string, enum: [DOMESTIC, OVERSEAS]}}
|
|
- {name: licenseState, in: query, schema: {type: string, enum: [MISSING, VALID, EXPIRING, EXPIRED]}, description: 仅驾驶证日期状态，与审核和附件状态分别展示}
|
|
- {name: expectedEnd, in: query, schema: {type: string, format: date-time}}
|
|
responses:
|
|
'200':
|
|
description: 业务响应，分页数据
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- {$ref: '#/components/schemas/Envelope'}
|
|
- properties:
|
|
data:
|
|
type: object
|
|
properties:
|
|
records: {type: array, items: {$ref: '#/components/schemas/Driver'}}
|
|
page: {type: integer}
|
|
size: {type: integer}
|
|
total: {type: integer}
|
|
pages: {type: integer}
|
|
summary: {$ref: '#/components/schemas/Summary'}
|
|
post:
|
|
summary: 创建待审司机档案
|
|
description: '权限：platform:overseas-master-data:driver:create'
|
|
requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/Draft'}}}}
|
|
responses: {'200': {$ref: '#/components/responses/Driver'}}
|
|
/api/platform/v1/last-leg/fleet/drivers/warehouse-options:
|
|
get:
|
|
summary: 获取当前区域可关联的公共仓库
|
|
description: '权限：platform:overseas-master-data:driver:list；复用Warehouse内部有效目录，国内DOMESTIC，海外OVERSEAS/OVERSEAS_PARTNER，排除FBA目的仓；保存时再次校验。'
|
|
parameters:
|
|
- {name: region, in: query, required: true, schema: {type: string, enum: [DOMESTIC, OVERSEAS]}}
|
|
responses:
|
|
'200':
|
|
description: 业务响应，data为仓库候选
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- {$ref: '#/components/schemas/Envelope'}
|
|
- properties:
|
|
data: {type: array, items: {$ref: '#/components/schemas/WarehouseOption'}}
|
|
/api/platform/v1/last-leg/fleet/drivers/{id}:
|
|
parameters: [{$ref: '#/components/parameters/Id'}]
|
|
get:
|
|
summary: 司机详情
|
|
description: '权限：platform:overseas-master-data:driver:list'
|
|
parameters:
|
|
- {name: expectedEnd, in: query, schema: {type: string, format: date-time}}
|
|
responses: {'200': {$ref: '#/components/responses/Driver'}}
|
|
put:
|
|
summary: 编辑档案，关键字段变化后重新待审
|
|
description: '权限：platform:overseas-master-data:driver:edit'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [recordVersion, details]
|
|
properties:
|
|
recordVersion: {type: integer, format: int64, minimum: 0}
|
|
details: {$ref: '#/components/schemas/Draft'}
|
|
responses: {'200': {$ref: '#/components/responses/Driver'}}
|
|
/api/platform/v1/last-leg/fleet/drivers/{id}/status:
|
|
parameters: [{$ref: '#/components/parameters/Id'}]
|
|
patch:
|
|
summary: 启停司机并记录原因
|
|
description: '权限：platform:overseas-master-data:driver:status；停用后不可派车，历史保留。'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [recordVersion, active, reason]
|
|
properties:
|
|
recordVersion: {type: integer, format: int64, minimum: 0}
|
|
active: {type: boolean}
|
|
reason: {type: string, minLength: 1, maxLength: 1000}
|
|
responses: {'200': {$ref: '#/components/responses/Driver'}}
|
|
/api/platform/v1/last-leg/fleet/drivers/{id}/review:
|
|
parameters: [{$ref: '#/components/parameters/Id'}]
|
|
post:
|
|
summary: 通过或打回司机证照
|
|
description: '权限：platform:overseas-master-data:driver:review；仅PENDING允许审核；打回原因必填；通过前校验真实附件归属与证照有效性。'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [recordVersion, decision]
|
|
properties:
|
|
recordVersion: {type: integer, format: int64, minimum: 0}
|
|
decision: {type: string, enum: [APPROVED, REJECTED]}
|
|
reason: {type: string, maxLength: 1000}
|
|
responses: {'200': {$ref: '#/components/responses/Driver'}}
|
|
/api/platform/v1/last-leg/fleet/drivers/{id}/submit:
|
|
parameters: [{$ref: '#/components/parameters/Id'}]
|
|
post:
|
|
summary: 已打回档案重新提交
|
|
description: '权限：platform:overseas-master-data:driver:edit；仅REJECTED；先校验证照完整及文件归属。'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [recordVersion]
|
|
properties:
|
|
recordVersion: {type: integer, format: int64, minimum: 0}
|
|
responses: {'200': {$ref: '#/components/responses/Driver'}}
|
|
/api/platform/v1/last-leg/fleet/drivers/{id}/qualification:
|
|
parameters: [{$ref: '#/components/parameters/Id'}]
|
|
get:
|
|
summary: 按预计任务结束时间预览派车资格
|
|
description: '权限：platform:overseas-master-data:driver:list；预计结束应覆盖本司机承担的返程或转场。'
|
|
parameters:
|
|
- {name: expectedEnd, in: query, required: true, schema: {type: string, format: date-time}}
|
|
responses:
|
|
'200':
|
|
description: 资格结果，canDispatch与expiringSoon独立
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- {$ref: '#/components/schemas/Envelope'}
|
|
- properties:
|
|
data: {$ref: '#/components/schemas/Qualification'}
|
|
/api/platform/v1/last-leg/fleet/drivers/{id}/history:
|
|
parameters: [{$ref: '#/components/parameters/Id'}]
|
|
get:
|
|
summary: 分页读取司机操作与审核历史
|
|
description: '权限：platform:overseas-master-data:driver:list；按版本降序，snapshot是历史当时的档案及资格，不能用作当前派车门禁。'
|
|
parameters:
|
|
- {name: page, in: query, schema: {type: integer, minimum: 1, default: 1}}
|
|
- {name: size, in: query, schema: {type: integer, minimum: 1, maximum: 200, default: 20}}
|
|
responses:
|
|
'200':
|
|
description: 业务响应，data为含records/page/size/total/pages的分页
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- {$ref: '#/components/schemas/Envelope'}
|
|
- properties:
|
|
data:
|
|
type: object
|
|
properties:
|
|
records: {type: array, items: {$ref: '#/components/schemas/History'}}
|
|
page: {type: integer}
|
|
size: {type: integer}
|
|
total: {type: integer}
|
|
pages: {type: integer}
|
|
/api/platform/v1/last-leg/fleet/drivers/{id}/license:
|
|
parameters: [{$ref: '#/components/parameters/Id'}]
|
|
post:
|
|
summary: 上传并绑定驾驶证，重置为待审
|
|
description: '权限：platform:overseas-master-data:driver:upload；复合归属固定平台0、FLEET_DRIVER_LICENSE、当前司机；非空PDF/JPG/PNG不超过10MiB，校验MIME和签名，旧版本附件保留在历史中。'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: object
|
|
required: [recordVersion, file]
|
|
properties:
|
|
recordVersion: {type: integer, format: int64, minimum: 0}
|
|
file: {type: string, format: binary}
|
|
responses: {'200': {$ref: '#/components/responses/Driver'}}
|
|
/api/platform/v1/last-leg/fleet/drivers/{id}/license/{fileId}:
|
|
parameters:
|
|
- {$ref: '#/components/parameters/Id'}
|
|
- {name: fileId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
|
|
get:
|
|
summary: 下载当前或历史已关联驾驶证
|
|
description: '权限：platform:overseas-master-data:driver:list；校验关联和File复合归属，attachment下载，Cache-Control no-store，拒绝未绑定文件。'
|
|
responses:
|
|
'200':
|
|
description: 文件内容；业务错误仍需识别JSON响应
|
|
content:
|
|
application/pdf: {schema: {type: string, format: binary}}
|
|
image/jpeg: {schema: {type: string, format: binary}}
|
|
image/png: {schema: {type: string, format: binary}}
|
|
components:
|
|
securitySchemes:
|
|
bearerAuth: {type: http, scheme: bearer, bearerFormat: JWT}
|
|
parameters:
|
|
Id: {name: id, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
|
|
responses:
|
|
Driver:
|
|
description: 业务响应，data为司机详情
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- {$ref: '#/components/schemas/Envelope'}
|
|
- properties:
|
|
data: {$ref: '#/components/schemas/Driver'}
|
|
schemas:
|
|
Envelope:
|
|
type: object
|
|
properties:
|
|
code: {type: string}
|
|
message: {type: string, nullable: true}
|
|
data: {type: object, nullable: true}
|
|
Draft:
|
|
type: object
|
|
required: [name, phone, ownership, region, licenseZone]
|
|
properties:
|
|
name: {type: string, minLength: 1, maxLength: 128}
|
|
phone: {type: string, minLength: 1, maxLength: 64}
|
|
ownership: {type: string, enum: [OWNED, DISPATCHED]}
|
|
region: {type: string, enum: [DOMESTIC, OVERSEAS]}
|
|
licenseNumber: {type: string, nullable: true, maxLength: 128}
|
|
licenseType: {type: string, nullable: true, maxLength: 64}
|
|
licenseIssuedOn: {type: string, format: date, nullable: true}
|
|
licenseExpiresOn: {type: string, format: date, nullable: true}
|
|
licenseZone: {type: string, maxLength: 64, description: IANA时区，如America/Los_Angeles}
|
|
remark: {type: string, nullable: true, maxLength: 1000}
|
|
profile: {$ref: '#/components/schemas/Profile'}
|
|
Profile:
|
|
type: object
|
|
nullable: true
|
|
description: 可选补充资料；当前其他资质日期不自动作为派车必需条件
|
|
properties:
|
|
warehouseId: {type: string, nullable: true, pattern: '^[1-9][0-9]*$'}
|
|
vehicleModels: {type: string, nullable: true, maxLength: 128}
|
|
languagesAndArea: {type: string, nullable: true, maxLength: 256}
|
|
medicalExpiresOn: {type: string, format: date, nullable: true}
|
|
trainingExpiresOn: {type: string, format: date, nullable: true}
|
|
insuranceExpiresOn: {type: string, format: date, nullable: true}
|
|
WarehouseOption:
|
|
type: object
|
|
properties:
|
|
id: {type: string}
|
|
code: {type: string}
|
|
name: {type: string}
|
|
region: {type: string, enum: [DOMESTIC, OVERSEAS]}
|
|
Summary:
|
|
type: object
|
|
description: 与列表共用筛选范围，按各证照时区计算30天（含）提醒，不以浏览器时区计算
|
|
properties:
|
|
total: {type: integer, format: int64}
|
|
owned: {type: integer, format: int64}
|
|
dispatched: {type: integer, format: int64}
|
|
expiringSoon: {type: integer, format: int64}
|
|
expired: {type: integer, format: int64}
|
|
Driver:
|
|
type: object
|
|
properties:
|
|
id: {type: string}
|
|
driverNo: {type: string, description: 独立生成的业务编号}
|
|
details: {$ref: '#/components/schemas/Draft'}
|
|
active: {type: boolean}
|
|
reviewStatus: {type: string, enum: [PENDING, APPROVED, REJECTED]}
|
|
licenseFileId: {type: string, nullable: true}
|
|
recordVersion: {type: integer, format: int64}
|
|
updatedBy: {type: string}
|
|
updatedAt: {type: string, description: UTC本地日期时间}
|
|
qualification: {$ref: '#/components/schemas/Qualification'}
|
|
licenseState: {type: string, enum: [MISSING, VALID, EXPIRING, EXPIRED]}
|
|
warehouseCode: {type: string, nullable: true}
|
|
warehouseName: {type: string, nullable: true}
|
|
Qualification:
|
|
type: object
|
|
properties:
|
|
canDispatch: {type: boolean}
|
|
expiringSoon: {type: boolean}
|
|
reason:
|
|
type: string
|
|
enum: [ELIGIBLE, INACTIVE, MISSING_LICENSE, MISSING_EXPIRY, PENDING_REVIEW, REJECTED, EXPIRED, MISSING_TRIP_END, INVALID_TRIP_END, EXPIRES_DURING_TRIP]
|
|
licenseExpiresOn: {type: string, format: date, nullable: true}
|
|
History:
|
|
type: object
|
|
properties:
|
|
recordVersion: {type: integer, format: int64}
|
|
action: {type: string, enum: [CREATE, UPDATE, ACTIVATE, DEACTIVATE, UPLOAD_LICENSE, APPROVED, REJECTED, RESUBMIT]}
|
|
reason: {type: string, nullable: true}
|
|
operatorId: {type: string}
|
|
occurredAt: {type: string, description: UTC本地日期时间}
|
|
snapshot: {$ref: '#/components/schemas/Driver'}
|