274 lines
16 KiB
YAML
274 lines
16 KiB
YAML
|
openapi: 3.0.3
|
|||
|
|
info:
|
|||
|
|
title: Lastleg Overseas Master Data API
|
|||
|
|
version: 1.0.0
|
|||
|
|
description: 海外仓报价、月度汇率与车辆主数据；车辆契约不包含派送履约历史。
|
|||
|
|
paths:
|
|||
|
|
/api/platform/v1/last-leg/master-data/overseas-quotes:
|
|||
|
|
get:
|
|||
|
|
summary: 分页查询海外仓报价
|
|||
|
|
description: '权限：platform:overseas-master-data:quote:list'
|
|||
|
|
parameters:
|
|||
|
|
- $ref: '#/components/parameters/Page'
|
|||
|
|
- $ref: '#/components/parameters/Size'
|
|||
|
|
- { name: keyword, in: query, schema: { type: string } }
|
|||
|
|
- { name: warehouseId, in: query, schema: { type: string } }
|
|||
|
|
- { name: providerName, in: query, schema: { type: string } }
|
|||
|
|
- { name: currency, in: query, schema: { type: string } }
|
|||
|
|
- { name: status, in: query, schema: { $ref: '#/components/schemas/ActiveStatus' } }
|
|||
|
|
responses: { '200': { description: 业务响应，data为PageResult<QuoteSummary> } }
|
|||
|
|
post:
|
|||
|
|
summary: 创建海外仓报价
|
|||
|
|
description: '权限：platform:overseas-master-data:quote:create；服务端读取国内overseas-partners并缓存合作仓目录30分钟'
|
|||
|
|
requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/QuoteCreate' } } } }
|
|||
|
|
responses: { '200': { description: 业务响应，data为报价详情 } }
|
|||
|
|
/api/platform/v1/last-leg/master-data/overseas-quotes/warehouse-options:
|
|||
|
|
get:
|
|||
|
|
summary: 查询缓存的有效海外合作仓选项
|
|||
|
|
description: '权限：platform:overseas-master-data:quote:list；浏览器不直接调用国内内部接口'
|
|||
|
|
responses: { '200': { description: 业务响应 } }
|
|||
|
|
/api/platform/v1/last-leg/master-data/overseas-quotes/export:
|
|||
|
|
get:
|
|||
|
|
summary: 导出海外仓报价
|
|||
|
|
description: '权限：platform:overseas-master-data:quote:export；UTF-8 BOM CSV'
|
|||
|
|
parameters:
|
|||
|
|
- { name: keyword, in: query, schema: { type: string } }
|
|||
|
|
- { name: warehouseId, in: query, schema: { type: string } }
|
|||
|
|
- { name: providerName, in: query, schema: { type: string } }
|
|||
|
|
- { name: currency, in: query, schema: { type: string } }
|
|||
|
|
- { name: status, in: query, schema: { $ref: '#/components/schemas/ActiveStatus' } }
|
|||
|
|
responses: { '200': { description: CSV, content: { text/csv: { schema: { type: string, format: binary } } } } }
|
|||
|
|
/api/platform/v1/last-leg/master-data/overseas-quotes/{id}:
|
|||
|
|
parameters:
|
|||
|
|
- { name: id, in: path, required: true, schema: { type: integer, format: int64 } }
|
|||
|
|
get:
|
|||
|
|
summary: 查询海外仓报价详情
|
|||
|
|
description: '权限：platform:overseas-master-data:quote:list'
|
|||
|
|
responses: { '200': { description: 业务响应 } }
|
|||
|
|
put:
|
|||
|
|
summary: 编辑未生效的海外仓报价
|
|||
|
|
description: '权限：platform:overseas-master-data:quote:edit；recordVersion乐观锁'
|
|||
|
|
requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/QuoteUpdate' } } } }
|
|||
|
|
responses: { '200': { description: 业务响应 } }
|
|||
|
|
/api/platform/v1/last-leg/master-data/overseas-quotes/{id}/status:
|
|||
|
|
patch:
|
|||
|
|
summary: 启停海外仓报价
|
|||
|
|
description: '权限：platform:overseas-master-data:quote:status'
|
|||
|
|
parameters:
|
|||
|
|
- { name: id, in: path, required: true, schema: { type: integer, format: int64 } }
|
|||
|
|
requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/QuoteStatusChange' } } } }
|
|||
|
|
responses: { '200': { description: 业务响应 } }
|
|||
|
|
/api/platform/v1/last-leg/master-data/exchange-rates:
|
|||
|
|
get:
|
|||
|
|
summary: 分页查询月度汇率
|
|||
|
|
description: '权限：platform:overseas-master-data:exchange-rate:list'
|
|||
|
|
parameters:
|
|||
|
|
- $ref: '#/components/parameters/Page'
|
|||
|
|
- $ref: '#/components/parameters/Size'
|
|||
|
|
- { name: monthFrom, in: query, schema: { type: string, pattern: '^\d{4}-(0[1-9]|1[0-2])$' } }
|
|||
|
|
- { name: monthTo, in: query, schema: { type: string, pattern: '^\d{4}-(0[1-9]|1[0-2])$' } }
|
|||
|
|
- { name: status, in: query, schema: { $ref: '#/components/schemas/ActiveStatus' } }
|
|||
|
|
responses: { '200': { description: 业务响应，data为PageResult<MonthlyExchangeRate> } }
|
|||
|
|
post:
|
|||
|
|
summary: 创建月度汇率
|
|||
|
|
description: '权限：platform:overseas-master-data:exchange-rate:create；月份唯一，初始状态ACTIVE'
|
|||
|
|
requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ExchangeRateCreate' } } } }
|
|||
|
|
responses: { '200': { description: 业务响应，data为MonthlyExchangeRate } }
|
|||
|
|
/api/platform/v1/last-leg/master-data/exchange-rates/summary:
|
|||
|
|
get:
|
|||
|
|
summary: 查询最新有效月度汇率摘要
|
|||
|
|
description: '权限：platform:overseas-master-data:exchange-rate:list'
|
|||
|
|
responses: { '200': { description: 业务响应，data含latestMonth/latestUsdToCnyAverage/updatedBy/updatedAt } }
|
|||
|
|
/api/platform/v1/last-leg/master-data/exchange-rates/export:
|
|||
|
|
get:
|
|||
|
|
summary: 导出筛选后的全部月度汇率
|
|||
|
|
description: '权限：platform:overseas-master-data:exchange-rate:export；UTF-8 BOM CSV'
|
|||
|
|
parameters:
|
|||
|
|
- { name: monthFrom, in: query, schema: { type: string } }
|
|||
|
|
- { name: monthTo, in: query, schema: { type: string } }
|
|||
|
|
- { name: status, in: query, schema: { $ref: '#/components/schemas/ActiveStatus' } }
|
|||
|
|
responses: { '200': { description: CSV, content: { text/csv: { schema: { type: string, format: binary } } } } }
|
|||
|
|
/api/platform/v1/last-leg/master-data/exchange-rates/{month}:
|
|||
|
|
parameters:
|
|||
|
|
- { name: month, in: path, required: true, schema: { type: string, pattern: '^\d{4}-(0[1-9]|1[0-2])$' } }
|
|||
|
|
get:
|
|||
|
|
summary: 查询月度汇率详情
|
|||
|
|
description: '权限：platform:overseas-master-data:exchange-rate:list'
|
|||
|
|
responses: { '200': { description: 业务响应，data为MonthlyExchangeRate } }
|
|||
|
|
put:
|
|||
|
|
summary: 编辑月度汇率
|
|||
|
|
description: '权限：platform:overseas-master-data:exchange-rate:edit；recordVersion冲突返回业务错误'
|
|||
|
|
requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ExchangeRateUpdate' } } } }
|
|||
|
|
responses: { '200': { description: 业务响应 } }
|
|||
|
|
/api/platform/v1/last-leg/master-data/exchange-rates/{month}/status:
|
|||
|
|
patch:
|
|||
|
|
summary: 变更月度汇率状态
|
|||
|
|
description: '权限：platform:overseas-master-data:exchange-rate:status'
|
|||
|
|
parameters:
|
|||
|
|
- { name: month, in: path, required: true, schema: { type: string } }
|
|||
|
|
requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ExchangeRateStatus' } } } }
|
|||
|
|
responses: { '200': { description: 业务响应 } }
|
|||
|
|
/api/platform/v1/last-leg/master-data/vehicles:
|
|||
|
|
get:
|
|||
|
|
summary: 分页查询车辆主数据
|
|||
|
|
description: '权限：platform:overseas-master-data:vehicle:list'
|
|||
|
|
parameters:
|
|||
|
|
- $ref: '#/components/parameters/Page'
|
|||
|
|
- $ref: '#/components/parameters/Size'
|
|||
|
|
- { name: keyword, in: query, description: 车牌/车型/司机或外派单位, schema: { type: string } }
|
|||
|
|
- { name: ownership, in: query, schema: { $ref: '#/components/schemas/VehicleOwnership' } }
|
|||
|
|
- { name: region, in: query, schema: { $ref: '#/components/schemas/VehicleRegion' } }
|
|||
|
|
- { name: status, in: query, schema: { $ref: '#/components/schemas/VehicleStatus' } }
|
|||
|
|
responses: { '200': { description: 业务响应，data为PageResult<Vehicle> } }
|
|||
|
|
post:
|
|||
|
|
summary: 创建车辆主数据
|
|||
|
|
description: '权限：platform:overseas-master-data:vehicle:create；车牌号唯一'
|
|||
|
|
requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/VehicleCreate' } } } }
|
|||
|
|
responses: { '200': { description: 业务响应，data为Vehicle } }
|
|||
|
|
/api/platform/v1/last-leg/master-data/vehicles/export:
|
|||
|
|
get:
|
|||
|
|
summary: 导出筛选后的全部车辆主数据
|
|||
|
|
description: '权限：platform:overseas-master-data:vehicle:export；UTF-8 BOM CSV'
|
|||
|
|
parameters:
|
|||
|
|
- { name: keyword, in: query, schema: { type: string } }
|
|||
|
|
- { name: ownership, in: query, schema: { $ref: '#/components/schemas/VehicleOwnership' } }
|
|||
|
|
- { name: region, in: query, schema: { $ref: '#/components/schemas/VehicleRegion' } }
|
|||
|
|
- { name: status, in: query, schema: { $ref: '#/components/schemas/VehicleStatus' } }
|
|||
|
|
responses: { '200': { description: CSV, content: { text/csv: { schema: { type: string, format: binary } } } } }
|
|||
|
|
/api/platform/v1/last-leg/master-data/vehicles/{id}:
|
|||
|
|
parameters:
|
|||
|
|
- { name: id, in: path, required: true, schema: { type: integer, format: int64 } }
|
|||
|
|
get:
|
|||
|
|
summary: 查询车辆档案详情
|
|||
|
|
description: '权限：platform:overseas-master-data:vehicle:list；不包含派送履约或车辆更换历史'
|
|||
|
|
responses: { '200': { description: 业务响应，data为Vehicle } }
|
|||
|
|
put:
|
|||
|
|
summary: 编辑车辆主数据
|
|||
|
|
description: '权限：platform:overseas-master-data:vehicle:edit；状态由独立接口变更'
|
|||
|
|
requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/VehicleUpdate' } } } }
|
|||
|
|
responses: { '200': { description: 业务响应 } }
|
|||
|
|
/api/platform/v1/last-leg/master-data/vehicles/{id}/status:
|
|||
|
|
patch:
|
|||
|
|
summary: 变更车辆状态
|
|||
|
|
description: '权限：platform:overseas-master-data:vehicle:status；使用recordVersion乐观锁'
|
|||
|
|
parameters:
|
|||
|
|
- { name: id, in: path, required: true, schema: { type: integer, format: int64 } }
|
|||
|
|
requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/VehicleStatusChange' } } } }
|
|||
|
|
responses: { '200': { description: 业务响应 } }
|
|||
|
|
components:
|
|||
|
|
parameters:
|
|||
|
|
Page: { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
|
|||
|
|
Size: { name: size, in: query, schema: { type: integer, minimum: 1, maximum: 200, default: 20 } }
|
|||
|
|
schemas:
|
|||
|
|
ActiveStatus: { type: string, enum: [ACTIVE, INACTIVE] }
|
|||
|
|
QuoteFee:
|
|||
|
|
type: object
|
|||
|
|
required: [item, billingUnit, unitPrice]
|
|||
|
|
properties:
|
|||
|
|
item: { type: string, maxLength: 128 }
|
|||
|
|
billingUnit: { type: string, maxLength: 64 }
|
|||
|
|
unitPrice: { type: number, minimum: 0 }
|
|||
|
|
minimumCharge: { type: number, minimum: 0, nullable: true }
|
|||
|
|
remark: { type: string, maxLength: 500, nullable: true }
|
|||
|
|
QuoteTransitPrice:
|
|||
|
|
type: object
|
|||
|
|
required: [fbaWarehouseCode, deliveryMethod, price]
|
|||
|
|
properties:
|
|||
|
|
fbaWarehouseCode: { type: string, maxLength: 64 }
|
|||
|
|
deliveryMethod: { type: string, maxLength: 64 }
|
|||
|
|
estimatedMiles: { type: number, minimum: 0, nullable: true }
|
|||
|
|
price: { type: number, minimum: 0 }
|
|||
|
|
minimumCharge: { type: number, minimum: 0, nullable: true }
|
|||
|
|
remark: { type: string, maxLength: 500, nullable: true }
|
|||
|
|
QuoteCreate:
|
|||
|
|
type: object
|
|||
|
|
required: [name, warehouseId, providerName, currency, effectiveStart, effectiveEnd, versionCode, warehouseFees]
|
|||
|
|
properties:
|
|||
|
|
name: { type: string, maxLength: 128 }
|
|||
|
|
warehouseId: { type: string, description: 国内平台海外合作仓ID }
|
|||
|
|
providerName: { type: string, maxLength: 128 }
|
|||
|
|
currency: { type: string, minLength: 3, maxLength: 3 }
|
|||
|
|
effectiveStart: { type: string, format: date }
|
|||
|
|
effectiveEnd: { type: string, format: date }
|
|||
|
|
versionCode: { type: string, maxLength: 64 }
|
|||
|
|
warehouseFees: { type: array, minItems: 1, items: { $ref: '#/components/schemas/QuoteFee' } }
|
|||
|
|
transitPrices: { type: array, items: { $ref: '#/components/schemas/QuoteTransitPrice' } }
|
|||
|
|
remark: { type: string, maxLength: 1000, nullable: true }
|
|||
|
|
QuoteUpdate:
|
|||
|
|
type: object
|
|||
|
|
required: [recordVersion, name, providerName, currency, effectiveStart, effectiveEnd, warehouseFees]
|
|||
|
|
properties:
|
|||
|
|
recordVersion: { type: integer, format: int64, minimum: 0 }
|
|||
|
|
name: { type: string, maxLength: 128 }
|
|||
|
|
providerName: { type: string, maxLength: 128 }
|
|||
|
|
currency: { type: string, minLength: 3, maxLength: 3 }
|
|||
|
|
effectiveStart: { type: string, format: date }
|
|||
|
|
effectiveEnd: { type: string, format: date }
|
|||
|
|
warehouseFees: { type: array, minItems: 1, items: { $ref: '#/components/schemas/QuoteFee' } }
|
|||
|
|
transitPrices: { type: array, items: { $ref: '#/components/schemas/QuoteTransitPrice' } }
|
|||
|
|
remark: { type: string, maxLength: 1000, nullable: true }
|
|||
|
|
QuoteStatusChange:
|
|||
|
|
type: object
|
|||
|
|
required: [status, recordVersion]
|
|||
|
|
properties:
|
|||
|
|
status: { $ref: '#/components/schemas/ActiveStatus' }
|
|||
|
|
recordVersion: { type: integer, format: int64, minimum: 0 }
|
|||
|
|
ExchangeRateCreate:
|
|||
|
|
type: object
|
|||
|
|
required: [month, usdToCnyAverage]
|
|||
|
|
properties:
|
|||
|
|
month: { type: string, example: '2026-08' }
|
|||
|
|
usdToCnyAverage: { type: number, exclusiveMinimum: true, minimum: 0, example: 7.18540000 }
|
|||
|
|
remark: { type: string, maxLength: 1000, nullable: true }
|
|||
|
|
ExchangeRateUpdate:
|
|||
|
|
type: object
|
|||
|
|
required: [recordVersion, usdToCnyAverage]
|
|||
|
|
properties:
|
|||
|
|
recordVersion: { type: integer, format: int64, minimum: 0 }
|
|||
|
|
usdToCnyAverage: { type: number, exclusiveMinimum: true, minimum: 0 }
|
|||
|
|
remark: { type: string, maxLength: 1000, nullable: true }
|
|||
|
|
ExchangeRateStatus:
|
|||
|
|
type: object
|
|||
|
|
required: [status, recordVersion]
|
|||
|
|
properties:
|
|||
|
|
status: { $ref: '#/components/schemas/ActiveStatus' }
|
|||
|
|
recordVersion: { type: integer, format: int64, minimum: 0 }
|
|||
|
|
remark: { type: string, maxLength: 500, nullable: true }
|
|||
|
|
VehicleOwnership: { type: string, enum: [OWNED, DISPATCHED] }
|
|||
|
|
VehicleRegion: { type: string, enum: [DOMESTIC, OVERSEAS] }
|
|||
|
|
VehicleStatus: { type: string, enum: [IN_SERVICE, DISPATCHED, MAINTENANCE, INACTIVE, RETURNED] }
|
|||
|
|
VehicleCreate:
|
|||
|
|
type: object
|
|||
|
|
required: [plateNumber, model, fuelConsumptionPer100Km, mileageKm, region, ownership, status]
|
|||
|
|
properties:
|
|||
|
|
plateNumber: { type: string, maxLength: 64 }
|
|||
|
|
model: { type: string, maxLength: 128 }
|
|||
|
|
fuelConsumptionPer100Km: { type: number, exclusiveMinimum: true, minimum: 0 }
|
|||
|
|
mileageKm: { type: integer, format: int64, minimum: 0 }
|
|||
|
|
driverOrDispatchCompany: { type: string, maxLength: 128, nullable: true }
|
|||
|
|
phone: { type: string, maxLength: 64, nullable: true }
|
|||
|
|
region: { $ref: '#/components/schemas/VehicleRegion' }
|
|||
|
|
ownership: { $ref: '#/components/schemas/VehicleOwnership' }
|
|||
|
|
status: { $ref: '#/components/schemas/VehicleStatus' }
|
|||
|
|
remark: { type: string, maxLength: 1000, nullable: true }
|
|||
|
|
VehicleUpdate:
|
|||
|
|
type: object
|
|||
|
|
required: [recordVersion, plateNumber, model, fuelConsumptionPer100Km, mileageKm, region, ownership]
|
|||
|
|
properties:
|
|||
|
|
recordVersion: { type: integer, format: int64, minimum: 0 }
|
|||
|
|
plateNumber: { type: string, maxLength: 64 }
|
|||
|
|
model: { type: string, maxLength: 128 }
|
|||
|
|
fuelConsumptionPer100Km: { type: number, exclusiveMinimum: true, minimum: 0 }
|
|||
|
|
mileageKm: { type: integer, format: int64, minimum: 0, description: 不得小于已有公里码 }
|
|||
|
|
driverOrDispatchCompany: { type: string, maxLength: 128, nullable: true }
|
|||
|
|
phone: { type: string, maxLength: 64, nullable: true }
|
|||
|
|
region: { $ref: '#/components/schemas/VehicleRegion' }
|
|||
|
|
ownership: { $ref: '#/components/schemas/VehicleOwnership' }
|
|||
|
|
remark: { type: string, maxLength: 1000, nullable: true }
|
|||
|
|
VehicleStatusChange:
|
|||
|
|
type: object
|
|||
|
|
required: [status, recordVersion]
|
|||
|
|
properties:
|
|||
|
|
status: { $ref: '#/components/schemas/VehicleStatus' }
|
|||
|
|
recordVersion: { type: integer, format: int64, minimum: 0 }
|