278 lines
16 KiB
YAML
278 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；浏览器不直接调用国内内部接口；非空结果缓存30分钟，空结果不缓存；国内合作仓变更后可使用refresh=true强制刷新'
|
||
parameters:
|
||
- name: refresh
|
||
in: query
|
||
required: false
|
||
description: 是否绕过仍有效的非空缓存并重新读取国内海外合作仓
|
||
schema: { type: boolean, default: false }
|
||
responses:
|
||
'200':
|
||
description: 业务响应，data为海外合作仓候选数组
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
code: { type: string, example: '200' }
|
||
data:
|
||
type: array
|
||
items: { $ref: '#/components/schemas/PartnerWarehouseOption' }
|
||
/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/{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' } }
|
||
- { name: dispatchNo, in: query, description: 排车维护候选，分页前排除其他车次实际占用，保留本车资源, schema: { type: string, maxLength: 64 } }
|
||
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/{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] }
|
||
PartnerWarehouseOption:
|
||
type: object
|
||
required: [warehouseId, warehouseCode, warehouseName, countryCode]
|
||
properties:
|
||
warehouseId: { type: string, description: 平台公共海外合作仓雪花ID字符串 }
|
||
warehouseCode: { type: string, description: 仓库编码 }
|
||
warehouseName: { type: string, description: 仓库名称 }
|
||
countryCode: { type: string, pattern: '^[A-Z]{2}$', description: ISO国家二字码 }
|
||
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
|
||
description: 托位/载重/容积同时填写正数，或全部留空表示容量尚未确认；未知容量不可用于正式配载，不按车型名称推算。
|
||
required: [plateNumber, model, fuelConsumptionPer100Km, mileageKm, region, ownership, status]
|
||
properties:
|
||
plateNumber: { type: string, maxLength: 64 }
|
||
model: { type: string, maxLength: 128 }
|
||
maxPalletSpaces: { type: integer, minimum: 1, maximum: 10000, nullable: true }
|
||
maxLoadKg: { type: number, minimum: 0, exclusiveMinimum: true, nullable: true }
|
||
maxVolumeCbm: { type: number, minimum: 0, exclusiveMinimum: true, nullable: true }
|
||
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
|
||
description: 托位/载重/容积同时填写正数，或全部留空；不能部分设置容量。
|
||
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 }
|
||
maxPalletSpaces: { type: integer, minimum: 1, maximum: 10000, nullable: true }
|
||
maxLoadKg: { type: number, minimum: 0, exclusiveMinimum: true, nullable: true }
|
||
maxVolumeCbm: { type: number, minimum: 0, exclusiveMinimum: true, nullable: true }
|
||
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 }
|