openapi: 3.0.3
info: { title: Overseas Business Fee Source API, version: 1.0.0 }
paths:
  /api/platform/v1/last-leg/finance-fee-sources:
    get:
      summary: 查询海外业务费用来源当前版本
      security: [{ bearerAuth: [] }]
      parameters:
        - { in: query, name: customerId, schema: { type: string } }
        - { in: query, name: businessType, schema: { $ref: '#/components/schemas/BusinessType' } }
        - { in: query, name: businessNo, schema: { type: string } }
        - { in: query, name: containerBookingId, description: 精确查询真实来源柜下全部客户的费用；可再传customerId收窄到单个客户, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
      responses: { '200': { description: 当前版本列表 } }
    post:
      summary: 创建海外业务费用来源草稿
      description: 客户和业务编号必填；入仓ID、入仓码均按业务事实选填，不得为补字段伪造。海外货柜费用必须以相同的businessId和containerBookingId引用真实来源柜，且businessNo与containerNo均为该柜真实集装箱号。
      security: [{ bearerAuth: [] }]
      parameters: [{ in: header, name: Idempotency-Key, required: true, schema: { type: string, maxLength: 128 } }]
      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/SaveRequest' } } } }
      responses: { '200': { description: 草稿费用来源 }, '400': { description: 业务归属或付款事实无效 } }
  /api/platform/v1/last-leg/finance-fee-sources/container-customers:
    get:
      summary: 查询真实来源柜内客户选项
      description: 单次按真实来源柜聚合全部客户，供柜详情维护费用时选择，不逐票查询。
      security: [{ bearerAuth: [] }]
      parameters:
        - { in: query, name: containerBookingId, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
      responses:
        '200':
          description: 柜内客户选项
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ContainerCustomerListResponse' }
  /api/platform/v1/last-leg/finance-fee-sources/{sourceFeeId}/{action}:
    post:
      summary: 提交、审核、调整或作废海外业务费用来源
      description: 审核通过与作废均事务性写入Outbox，经Event Bridge可靠投递至独立Finance；action为submit、review、adjust、void。
      security: [{ bearerAuth: [] }]
      parameters:
        - { in: path, name: sourceFeeId, required: true, schema: { type: string } }
        - { in: path, name: action, required: true, schema: { type: string, enum: [submit, review, adjust, void] } }
      responses: { '200': { description: 当前费用来源版本 }, '409': { description: 状态、版本或幂等冲突 } }
components:
  schemas:
    BusinessType: { type: string, enum: [OVERSEAS_INBOUND, OVERSEAS_PROCUREMENT, PROCUREMENT_FEE, US_TRUCK, LOCAL_LOOSEBOARD, WAREHOUSE_SERVICE, OVERSEAS_CONTAINER, LASTLEG_ORDER, DELIVERY_ORDER, RELABEL_ORDER] }
    OverseasContainerFeeItem:
      type: string
      description: 海外阶段柜级费用项目：港口费、堆存费、修箱费、吊机费、码头拖车费、其他。
      enum: [PORT_FEE, STORAGE_FEE, CONTAINER_REPAIR_FEE, CRANE_FEE, TERMINAL_DRAYAGE_FEE, OTHER]
    ContainerCustomerOption:
      type: object
      required: [customerId]
      properties:
        customerId: { type: string }
        customerName: { type: string, nullable: true }
    ContainerCustomerListResponse:
      type: object
      required: [data]
      properties:
        code: { type: string }
        message: { type: string }
        data:
          type: array
          items: { $ref: '#/components/schemas/ContainerCustomerOption' }
        requestId: { type: string, nullable: true }
        traceId: { type: string, nullable: true }
        timestamp: { type: string, format: date-time }
    SaveRequest:
      type: object
      required: [customerId, sourceType, businessType, businessNo, feeItemCode, feeItemName, direction, businessDate, currency, amount]
      properties:
        customerId: { type: string }
        sourceType: { type: string, enum: [OVERSEAS_INBOUND_FEE, OVERSEAS_PROCUREMENT_FEE, OVERSEAS_TRUCK_FEE, OVERSEAS_LOOSEBOARD_FEE, OVERSEAS_WAREHOUSE_FEE, OVERSEAS_CONTAINER_FEE, OVERSEAS_ORDER_FEE, OVERSEAS_DELIVERY_FEE, OVERSEAS_RELABEL_FEE] }
        businessType: { $ref: '#/components/schemas/BusinessType' }
        businessId: { type: string, pattern: '^[1-9][0-9]*$', nullable: true }
        businessNo: { type: string, maxLength: 128 }
        containerBookingId: { type: string, pattern: '^[1-9][0-9]*$', nullable: true }
        containerNo: { type: string, maxLength: 64, nullable: true }
        warehouseId: { type: string, nullable: true }
        inboundId: { type: string, nullable: true }
        inboundCode: { type: string, maxLength: 64, nullable: true }
        feeItemCode:
          type: string
          description: OVERSEAS_CONTAINER时必须取OverseasContainerFeeItem枚举；其他业务类型沿用各自费用项目编码。
        feeItemName: { type: string }
        direction: { type: string, enum: [RECEIVABLE, PAYABLE] }
        businessDate: { type: string, format: date }
        currency: { type: string, enum: [CNY, USD], description: 业务原币；USD由服务端按业务月份有效汇率折算为CNY入池 }
        amount: { type: number, format: decimal, minimum: 0, exclusiveMinimum: true, description: 业务原币金额 }
        chargeableQuantity: { type: number, format: decimal, minimum: 0, exclusiveMinimum: true, nullable: true }
        quantityUnit: { type: string, maxLength: 32, nullable: true }
        unitPrice: { type: number, format: decimal, minimum: 0, exclusiveMinimum: true, nullable: true }
        periodStart: { type: string, format: date, nullable: true }
        periodEnd: { type: string, format: date, nullable: true }
  securitySchemes: { bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT } }