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/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] }
    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
      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 }