openapi: 3.0.3
info:
  title: Finance F1 Manual AR API
  version: 1.3.0
  description: >-
    F1 人工账单、收款和成本目标契约。仅 CNY；平台财务可写；客户只读且仅可见
    ISSUED、PARTIALLY_PAID、PAID 账单。整柜成本由 Finance 根据 containerId 调用
    Firstleg 真实快照，浏览器不提交订单体积。固定 DTO、完整追踪字段和 File fail-closed
    校验仍属于放行目标；当前实现差异见契约门禁文档。
servers:
  - url: /api
paths:
  /platform/finance/v1/customers/{tenantId}/terms:
    get:
      summary: 查询客户账期
      x-permission: platform:finance:customer-terms:view
      security:
        - platformFinance: []
      parameters:
        - $ref: '#/components/parameters/TenantId'
      responses:
        '200':
          $ref: '#/components/responses/CustomerTermsResponse'
        '403':
          $ref: '#/components/responses/BusinessError'
    put:
      summary: 保存客户账期
      x-permission: platform:finance:customer-terms:update
      security:
        - platformFinance: []
      parameters:
        - $ref: '#/components/parameters/TenantId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerTermsRequest'
      responses:
        '200':
          $ref: '#/components/responses/CustomerTermsResponse'
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
  /platform/finance/v1/bills:
    get:
      summary: 查询平台账单
      x-permission: platform:finance:customer-statement:list
      security:
        - platformFinance: []
      parameters:
        - $ref: '#/components/parameters/RequiredCustomerId'
      responses:
        '200':
          $ref: '#/components/responses/BillListResponse'
    post:
      summary: 创建账单草稿
      x-permission: platform:finance:bill:create
      security:
        - platformFinance: []
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBillRequest'
      responses:
        '200':
          $ref: '#/components/responses/BillDetailResponse'
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
  /platform/finance/v1/bills/{billId}:
    get:
      summary: 查询平台账单详情
      x-permission: platform:finance:customer-statement:list
      security:
        - platformFinance: []
      parameters:
        - $ref: '#/components/parameters/BillId'
      responses:
        '200':
          $ref: '#/components/responses/BillDetailResponse'
    put:
      summary: 更新账单草稿
      x-permission: platform:finance:bill:update
      security:
        - platformFinance: []
      parameters:
        - $ref: '#/components/parameters/BillId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBillRequest'
      responses:
        '200':
          $ref: '#/components/responses/BillDetailResponse'
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
  /platform/finance/v1/bills/{billId}/issue:
    post:
      summary: 出账并冻结账单
      x-permission: platform:finance:bill:issue
      security:
        - platformFinance: []
      parameters:
        - $ref: '#/components/parameters/BillId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VersionRequest'
      responses:
        '200':
          $ref: '#/components/responses/BillDetailResponse'
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
  /platform/finance/v1/bills/{billId}/revisions:
    get:
      summary: 查询账单修订历史
      description: 只返回指定客户所属账单的调整前快照，跨客户或不存在账单统一拒绝。
      x-permission: platform:finance:customer-statement:list
      security:
        - platformFinance: []
      parameters:
        - $ref: '#/components/parameters/BillId'
        - $ref: '#/components/parameters/RequiredCustomerId'
      responses:
        '200':
          $ref: '#/components/responses/BillRevisionListResponse'
        '404':
          $ref: '#/components/responses/BusinessError'
  /platform/finance/v1/bills/{billId}/adjust:
    post:
      summary: 调整已出账账单并保留修订历史
      x-permission: platform:finance:bill:adjust
      security:
        - platformFinance: []
      parameters:
        - $ref: '#/components/parameters/BillId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdjustBillRequest'
      responses:
        '200':
          $ref: '#/components/responses/BillDetailResponse'
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
  /platform/finance/v1/bills/{billId}/void:
    post:
      summary: 作废未收款账单
      x-permission: platform:finance:bill:void
      security:
        - platformFinance: []
      parameters:
        - $ref: '#/components/parameters/BillId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReasonRequest'
      responses:
        '200':
          $ref: '#/components/responses/BillDetailResponse'
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
  /platform/finance/v1/receipts:
    get:
      summary: 查询收款记录
      x-permission: platform:finance:receipt:view
      security:
        - platformFinance: []
      parameters:
        - $ref: '#/components/parameters/OptionalCustomerId'
      responses:
        '200':
          $ref: '#/components/responses/ReceiptListResponse'
    post:
      summary: 人工登记收款并分配账单
      description: voucherFileIds 必须先通过 File 财务凭证上传接口取得，并通过客户、用途和状态校验。
      x-permission: platform:finance:receipt:create
      security:
        - platformFinance: []
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReceiptRequest'
      responses:
        '200':
          $ref: '#/components/responses/ReceiptResponse'
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
  /platform/finance/v1/cost-entries:
    get:
      summary: 查询成本记录
      x-permission: platform:finance:cost:view
      security:
        - platformFinance: []
      parameters:
        - $ref: '#/components/parameters/OptionalCustomerId'
      responses:
        '200':
          $ref: '#/components/responses/CostListResponse'
    post:
      summary: 人工登记单票或整柜成本
      description: >-
        SINGLE_ORDER 直接归属经服务端验证的同客户订单；CONTAINER_SHARED 只提交 containerId，
        Finance 从 Firstleg 取得属于该客户的柜内有效订单体积快照。快照为空或总体积无效时拒绝，
        首期不支持浏览器提交体积或人工分摊。
      x-permission: platform:finance:cost:create
      security:
        - platformFinance: []
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCostRequest'
      responses:
        '200':
          $ref: '#/components/responses/CostResponse'
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
  /platform/finance/v1/container-settlement-details:
    get:
      summary: 按客户和柜次查询已结算柜费及成本分摊
      description: >-
        为装柜清单柜费页提供固定请求量聚合。服务端校验柜次在 Finance 快照中的客户归属，
        以集合查询一次返回已进入 PAID 正式结算或 FIRSTLEG_DIRECT_PAID 已确认成本的
        CONTAINER_FEE 来源 ID，以及该客户在该柜下的全部成本及不可变分摊明细。
        不返回整张结算单、其他客户数据或平台凭证。
      x-permissions-all-of:
        - platform:finance:cost:view
        - platform:finance:settlement-ar:list
        - platform:finance:settlement-ap:list
      x-query-count: 3 fixed set-based SQL statements
      x-customer-isolation: customerId 与 containerBookingId 必须在 Finance 费用来源或成本快照中存在真实归属关系。
      security:
        - platformFinance: []
      parameters:
        - $ref: '#/components/parameters/RequiredCustomerId'
        - $ref: '#/components/parameters/ContainerBookingId'
      responses:
        '200':
          $ref: '#/components/responses/ContainerSettlementDetailsResponse'
        '403':
          $ref: '#/components/responses/BusinessError'
        '404':
          $ref: '#/components/responses/BusinessError'
  /platform/finance/v1/vouchers:
    post:
      summary: 上传财务凭证图片
      description: >-
        当前 Finance Controller 的真实入口，query 参数为 customerId，multipart 字段为 file。
        收款与成本创建均按客户、FINANCE_VOUCHER 业务类型和图片 MIME 校验元数据；
        File 客户端缺失时仍须改为 fail-closed，详见门禁文档。
      x-permission-any-of:
        - platform:finance:receipt:create
        - platform:finance:cost:create
        - platform:finance:fee-source:edit
      security:
        - platformFinance: []
      parameters:
        - $ref: '#/components/parameters/RequiredCustomerId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/FinanceVoucherUploadRequest'
      responses:
        '200':
          $ref: '#/components/responses/VoucherUploadResponse'
  /platform/finance/v1/vouchers/{fileId}:
    get:
      summary: 读取付款凭证名称及类型
      description: 按 customerId 校验 File 的客户、FINANCE_VOUCHER 类型和业务归属；下载响应禁止缓存并使用 attachment。
      x-permission: platform:finance:customer-arap:list
      security:
        - platformFinance: []
      parameters:
        - $ref: '#/components/parameters/RequiredCustomerId'
        - name: fileId
          in: path
          required: true
          schema: {type: string, pattern: '^[1-9][0-9]*$'}
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    required: [fileId, fileName, contentType, sizeBytes]
                    properties:
                      fileId: {type: string}
                      fileName: {type: string}
                      contentType: {type: string}
                      sizeBytes: {type: integer, format: int64}
        '400':
          $ref: '#/components/responses/BusinessError'
        '403':
          $ref: '#/components/responses/BusinessError'
  /platform/finance/v1/vouchers/{fileId}/content:
    get:
      summary: 下载付款凭证
      description: 按 customerId 校验 File 的客户、FINANCE_VOUCHER 类型和业务归属；下载响应禁止缓存并使用 attachment。
      x-permission: platform:finance:customer-arap:list
      security:
        - platformFinance: []
      parameters:
        - $ref: '#/components/parameters/RequiredCustomerId'
        - name: fileId
          in: path
          required: true
          schema: {type: string, pattern: '^[1-9][0-9]*$'}
      responses:
        '200':
          description: 成功
          content:
            application/octet-stream:
              schema: {type: string, format: binary}
        '400':
          $ref: '#/components/responses/BusinessError'
        '403':
          $ref: '#/components/responses/BusinessError'
  /client/finance/v1/bills:
    get:
      summary: 客户只读查询可见账单
      description: 服务端只返回当前客户且状态为 ISSUED、PARTIALLY_PAID、PAID 的账单。
      x-permission: merchant:finance:statement:list
      security:
        - customerFinanceRead: []
      responses:
        '200':
          $ref: '#/components/responses/ClientBillListResponse'
        '403':
          $ref: '#/components/responses/BusinessError'
  /client/finance/v1/bills/{billId}:
    get:
      summary: 客户只读查看可见账单详情
      description: DRAFT、VOIDED、跨客户或不存在的账单统一返回 FIN-AR-001，不泄露资源是否存在。
      x-permission: merchant:finance:statement:view
      security:
        - customerFinanceRead: []
      parameters:
        - $ref: '#/components/parameters/BillId'
      responses:
        '200':
          $ref: '#/components/responses/ClientBillDetailResponse'
        '404':
          $ref: '#/components/responses/BusinessError'
  /client/finance/v1/receipts:
    get:
      summary: 客户只读查询收款记录
      description: 仅返回分配到当前客户可见账单的收款信息，不返回平台凭证 fileId 和内部备注。
      x-permission: merchant:finance:statement:view
      security:
        - customerFinanceRead: []
      responses:
        '200':
          $ref: '#/components/responses/ClientReceiptListResponse'
        '403':
          $ref: '#/components/responses/BusinessError'
components:
  securitySchemes:
    platformFinance:
      type: http
      scheme: bearer
    customerFinanceRead:
      type: http
      scheme: bearer
  parameters:
    BillId:
      name: billId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Id'
    TenantId:
      name: tenantId
      in: path
      required: true
      description: 后端兼容字段，对应产品中的客户 ID。
      schema:
        $ref: '#/components/schemas/Id'
    RequiredCustomerId:
      name: customerId
      in: query
      required: true
      schema:
        $ref: '#/components/schemas/Id'
    OptionalCustomerId:
      name: customerId
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/Id'
    ContainerBookingId:
      name: containerBookingId
      in: query
      required: true
      description: Firstleg 真实货柜 containerBookingId，不是装柜计划 loadingPlanId。
      schema:
        $ref: '#/components/schemas/Id'
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: >-
        服务端以 HTTP method、规范化 path、客户范围和完整规范化 JSON body 计算请求哈希。
        同键同参重放原结果；同键异参冲突；PROCESSING 返回 409 和 Retry-After。
      schema:
        type: string
        minLength: 1
        maxLength: 128
  schemas:
    Id:
      type: string
      pattern: '^[1-9][0-9]*$'
    Money:
      type: string
      pattern: '^(0|[1-9][0-9]*)(\.[0-9]{1,6})?$'
      example: '300.000000'
    ResponseMeta:
      type: object
      required:
        - requestId
        - traceId
        - timestamp
      properties:
        requestId:
          type: string
          minLength: 1
        traceId:
          type: string
          minLength: 1
        timestamp:
          type: string
          format: date-time
          description: UTC ISO-8601 时间。
    CustomerTermsRequest:
      type: object
      required:
        - creditDays
      properties:
        customerName:
          type: string
          maxLength: 200
        creditDays:
          type: integer
          minimum: 0
          maximum: 3650
          default: 30
    CreateBillRequest:
      type: object
      required:
        - customerId
        - billDate
        - lines
      properties:
        customerId:
          $ref: '#/components/schemas/Id'
        billDate:
          type: string
          format: date
        lines:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/BillLineInput'
    UpdateBillRequest:
      type: object
      required:
        - customerId
        - billDate
        - expectedVersion
        - lines
      properties:
        customerId:
          $ref: '#/components/schemas/Id'
        billDate:
          type: string
          format: date
        expectedVersion:
          type: integer
          minimum: 0
        lines:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/BillLineInput'
    BillLineInput:
      type: object
      required:
        - sourceFeeId
        - sourceFeeVersion
        - feeItemName
        - amount
      properties:
        sourceFeeId:
          $ref: '#/components/schemas/Id'
        sourceFeeVersion:
          type: integer
          minimum: 1
        orderId:
          $ref: '#/components/schemas/Id'
        inboundId:
          $ref: '#/components/schemas/Id'
        feeItemName:
          type: string
          minLength: 1
          maxLength: 100
        amount:
          $ref: '#/components/schemas/Money'
    VersionRequest:
      type: object
      required:
        - expectedVersion
      properties:
        expectedVersion:
          type: integer
          minimum: 0
    ReasonRequest:
      type: object
      required:
        - expectedVersion
        - reason
      properties:
        expectedVersion:
          type: integer
          minimum: 0
        reason:
          type: string
          minLength: 1
          maxLength: 500
    AdjustBillRequest:
      allOf:
        - $ref: '#/components/schemas/ReasonRequest'
        - type: object
          required:
            - lines
          properties:
            lines:
              type: array
              minItems: 1
              items:
                $ref: '#/components/schemas/BillLineInput'
    CreateReceiptRequest:
      type: object
      required:
        - customerId
        - receivedDate
        - amount
        - paymentMethod
        - voucherFileIds
        - allocations
      properties:
        customerId:
          $ref: '#/components/schemas/Id'
        receivedDate:
          type: string
          format: date
        amount:
          $ref: '#/components/schemas/Money'
        currency:
          type: string
          enum:
            - CNY
          default: CNY
        paymentMethod:
          type: string
          enum:
            - BANK_TRANSFER
            - CASH
            - OTHER
        voucherFileIds:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            $ref: '#/components/schemas/Id'
        remark:
          type: string
          maxLength: 500
        allocations:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ReceiptAllocationInput'
      example:
        customerId: '10001'
        receivedDate: '2026-08-11'
        amount: '300.000000'
        currency: CNY
        paymentMethod: BANK_TRANSFER
        voucherFileIds:
          - '90001'
        allocations:
          - billId: '81001'
            amount: '100.000000'
          - billId: '81002'
            amount: '100.000000'
          - billId: '81003'
            amount: '100.000000'
    ReceiptAllocationInput:
      type: object
      required:
        - billId
        - amount
      properties:
        billId:
          $ref: '#/components/schemas/Id'
        amount:
          $ref: '#/components/schemas/Money'
    CreateCostRequest:
      oneOf:
        - $ref: '#/components/schemas/CreateSingleOrderCostRequest'
        - $ref: '#/components/schemas/CreateContainerCostRequest'
      discriminator:
        propertyName: costType
        mapping:
          SINGLE_ORDER: '#/components/schemas/CreateSingleOrderCostRequest'
          CONTAINER_SHARED: '#/components/schemas/CreateContainerCostRequest'
    CostRequestBase:
      type: object
      required:
        - customerId
        - amount
        - expenseName
        - voucherFileIds
      properties:
        customerId:
          $ref: '#/components/schemas/Id'
        expenseName:
          type: string
          minLength: 1
          maxLength: 100
        amount:
          $ref: '#/components/schemas/Money'
        currency:
          type: string
          enum:
            - CNY
          default: CNY
        voucherFileIds:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            $ref: '#/components/schemas/Id'
        remark:
          type: string
          maxLength: 500
    CreateSingleOrderCostRequest:
      allOf:
        - $ref: '#/components/schemas/CostRequestBase'
        - type: object
          required:
            - costType
            - orderId
          properties:
            costType:
              type: string
              enum:
                - SINGLE_ORDER
            orderId:
              $ref: '#/components/schemas/Id'
    CreateContainerCostRequest:
      allOf:
        - $ref: '#/components/schemas/CostRequestBase'
        - type: object
          required:
            - costType
            - containerId
          properties:
            costType:
              type: string
              enum:
                - CONTAINER_SHARED
            containerId:
              $ref: '#/components/schemas/Id'
    FinanceVoucherUploadRequest:
      type: object
      required:
        - file
      properties:
        file:
          type: string
          format: binary
    BillStatus:
      type: string
      enum:
        - DRAFT
        - ISSUED
        - PARTIALLY_PAID
        - PAID
        - VOIDED
    ClientBillStatus:
      type: string
      enum:
        - ISSUED
        - PARTIALLY_PAID
        - PAID
    Bill:
      type: object
      required:
        - billId
        - billNo
        - customerId
        - customerName
        - billDate
        - dueDate
        - currency
        - totalAmount
        - receivedAmount
        - outstandingAmount
        - status
        - version
      properties:
        billId:
          $ref: '#/components/schemas/Id'
        billNo:
          type: string
        customerId:
          $ref: '#/components/schemas/Id'
        customerName:
          type: string
        billDate:
          type: string
          format: date
        dueDate:
          type: string
          format: date
        currency:
          type: string
          enum:
            - CNY
        totalAmount:
          $ref: '#/components/schemas/Money'
        receivedAmount:
          $ref: '#/components/schemas/Money'
        outstandingAmount:
          $ref: '#/components/schemas/Money'
        status:
          $ref: '#/components/schemas/BillStatus'
        version:
          type: integer
          minimum: 0
    ClientBill:
      allOf:
        - $ref: '#/components/schemas/Bill'
        - type: object
          properties:
            status:
              $ref: '#/components/schemas/ClientBillStatus'
    BillLine:
      type: object
      required:
        - lineId
        - sourceFeeId
        - sourceFeeVersion
        - feeItemName
        - amount
      properties:
        lineId:
          $ref: '#/components/schemas/Id'
        sourceFeeId:
          $ref: '#/components/schemas/Id'
        sourceFeeVersion:
          type: integer
          minimum: 1
        orderId:
          $ref: '#/components/schemas/Id'
        inboundId:
          $ref: '#/components/schemas/Id'
        feeItemName:
          type: string
        amount:
          $ref: '#/components/schemas/Money'
    BillDetail:
      allOf:
        - $ref: '#/components/schemas/Bill'
        - type: object
          required:
            - lines
          properties:
            lines:
              type: array
              items:
                $ref: '#/components/schemas/BillLine'
    BillRevision:
      type: object
      required:
        - revisionId
        - billId
        - version
        - reason
        - billSnapshot
        - lineSnapshot
        - createdBy
        - createdAt
      properties:
        revisionId:
          $ref: '#/components/schemas/Id'
        billId:
          $ref: '#/components/schemas/Id'
        version:
          type: integer
          minimum: 0
        reason:
          type: string
        billSnapshot:
          type: object
          additionalProperties: true
        lineSnapshot:
          type: array
          items:
            type: object
            additionalProperties: true
        createdBy:
          $ref: '#/components/schemas/Id'
        createdAt:
          type: string
          format: date-time
    ClientBillDetail:
      allOf:
        - $ref: '#/components/schemas/ClientBill'
        - type: object
          required:
            - lines
          properties:
            lines:
              type: array
              items:
                $ref: '#/components/schemas/BillLine'
    ReceiptAllocation:
      type: object
      required:
        - billId
        - allocatedAmount
      properties:
        billId:
          $ref: '#/components/schemas/Id'
        allocatedAmount:
          $ref: '#/components/schemas/Money'
    Receipt:
      type: object
      required:
        - receiptId
        - receiptNo
        - customerId
        - receivedDate
        - amount
        - currency
        - paymentMethod
        - voucherFileIds
        - allocations
        - createdAt
      properties:
        receiptId:
          $ref: '#/components/schemas/Id'
        receiptNo:
          type: string
        customerId:
          $ref: '#/components/schemas/Id'
        receivedDate:
          type: string
          format: date
        amount:
          $ref: '#/components/schemas/Money'
        currency:
          type: string
          enum:
            - CNY
        paymentMethod:
          type: string
          enum:
            - BANK_TRANSFER
            - CASH
            - OTHER
        voucherFileIds:
          type: array
          items:
            $ref: '#/components/schemas/Id'
        remark:
          type: string
        allocations:
          type: array
          items:
            $ref: '#/components/schemas/ReceiptAllocation'
        createdAt:
          type: string
          format: date-time
    ClientReceipt:
      type: object
      required:
        - receiptId
        - receiptNo
        - receivedDate
        - amount
        - currency
        - paymentMethod
        - allocations
      properties:
        receiptId:
          $ref: '#/components/schemas/Id'
        receiptNo:
          type: string
        receivedDate:
          type: string
          format: date
        amount:
          $ref: '#/components/schemas/Money'
        currency:
          type: string
          enum:
            - CNY
        paymentMethod:
          type: string
        allocations:
          type: array
          items:
            $ref: '#/components/schemas/ReceiptAllocation'
    CostAllocation:
      type: object
      required:
        - orderId
        - volumeCbm
        - totalVolumeCbm
        - ratio
        - allocatedAmount
        - roundingAdjustment
      properties:
        orderId:
          $ref: '#/components/schemas/Id'
        volumeCbm:
          $ref: '#/components/schemas/Money'
        totalVolumeCbm:
          $ref: '#/components/schemas/Money'
        ratio:
          type: string
          pattern: '^(0|1|0\.[0-9]{1,12})$'
        allocatedAmount:
          $ref: '#/components/schemas/Money'
        roundingAdjustment:
          type: boolean
          description: 仅实际尾差非零时为 true。
    Cost:
      type: object
      required:
        - costId
        - costNo
        - customerId
        - costType
        - expenseName
        - amount
        - currency
        - voucherFileIds
        - allocations
        - createdAt
      properties:
        costId:
          $ref: '#/components/schemas/Id'
        costNo:
          type: string
        customerId:
          $ref: '#/components/schemas/Id'
        costType:
          type: string
          enum:
            - SINGLE_ORDER
            - CONTAINER_SHARED
        orderId:
          $ref: '#/components/schemas/Id'
        containerId:
          $ref: '#/components/schemas/Id'
        allocationMode:
          type: string
          enum:
            - DIRECT
            - AUTO_VOLUME
        expenseName:
          type: string
        amount:
          $ref: '#/components/schemas/Money'
        currency:
          type: string
          enum:
            - CNY
        voucherFileIds:
          type: array
          items:
            $ref: '#/components/schemas/Id'
        allocations:
          type: array
          items:
            $ref: '#/components/schemas/CostAllocation'
        createdAt:
          type: string
          format: date-time
    ContainerSettlementDetails:
      type: object
      required: [customerId, containerBookingId, settledSourceFeeIds, costs]
      properties:
        customerId: {$ref: '#/components/schemas/Id'}
        containerBookingId: {$ref: '#/components/schemas/Id'}
        settledSourceFeeIds:
          type: array
          uniqueItems: true
          items: {$ref: '#/components/schemas/Id'}
        costs:
          type: array
          items: {$ref: '#/components/schemas/ContainerSettlementCost'}
    ContainerSettlementCost:
      type: object
      required: [costId, costNo, costType, costOrigin, containerBookingId, feeItemName, amount, currency, status, allocations]
      properties:
        costId: {$ref: '#/components/schemas/Id'}
        costNo: {type: string}
        costType: {type: string, enum: [SINGLE_ORDER, CONTAINER_SHARED, SOURCE_DIRECT_PAID]}
        costOrigin: {type: string, enum: [MANUAL, FIRSTLEG_DIRECT_PAID, BUSINESS_DIRECT_PAID]}
        sourceFeeId: {$ref: '#/components/schemas/Id'}
        sourceFeeVersion: {type: integer, minimum: 1}
        containerBookingId: {$ref: '#/components/schemas/Id'}
        supplierName: {type: string}
        feeItemName: {type: string}
        amount: {$ref: '#/components/schemas/Money'}
        currency: {type: string, enum: [CNY]}
        status: {type: string, enum: [DRAFT, CONFIRMED, VOIDED]}
        allocations:
          type: array
          items: {$ref: '#/components/schemas/ContainerSettlementCostAllocation'}
    ContainerSettlementCostAllocation:
      type: object
      required: [allocationId, orderId, volumeCbm, totalVolumeCbm, allocationRate, allocatedAmount, roundingAdjustment]
      properties:
        allocationId: {$ref: '#/components/schemas/Id'}
        orderId: {$ref: '#/components/schemas/Id'}
        inboundId: {$ref: '#/components/schemas/Id'}
        volumeCbm: {$ref: '#/components/schemas/Money'}
        totalVolumeCbm: {$ref: '#/components/schemas/Money'}
        allocationRate: {type: string, pattern: '^(0|1|0\.[0-9]{1,10})$'}
        allocatedAmount: {$ref: '#/components/schemas/Money'}
        roundingAdjustment: {type: boolean}
    CustomerTerms:
      type: object
      required:
        - customerId
        - creditDays
        - status
        - version
      properties:
        customerId:
          $ref: '#/components/schemas/Id'
        customerName:
          type: string
        creditDays:
          type: integer
          minimum: 0
          maximum: 3650
        status:
          type: string
          enum:
            - ACTIVE
        version:
          type: integer
          minimum: 0
    VoucherFile:
      type: object
      required:
        - fileId
        - customerId
        - fileName
        - contentType
        - sizeBytes
      properties:
        fileId:
          $ref: '#/components/schemas/Id'
        customerId:
          $ref: '#/components/schemas/Id'
        fileName:
          type: string
        contentType:
          type: string
          enum:
            - image/jpeg
            - image/png
            - image/webp
        sizeBytes:
          type: integer
          format: int64
          minimum: 1
          maximum: 10485760
    ErrorDetail:
      type: object
      required:
        - field
        - reason
      properties:
        field:
          type: string
        reason:
          type: string
    ErrorEnvelope:
      type: object
      required:
        - code
        - message
        - requestId
        - traceId
        - timestamp
      properties:
        code:
          type: string
          example: FIN-AR-002
          description: >-
            稳定业务码。体积快照/归属使用 FIN-COST-VOLUME-SNAPSHOT-REQUIRED、
            FIN-COST-VOLUME-SNAPSHOT-INVALID、FIN-COST-CUSTOMER-MISMATCH、
            FIN-COST-ORDER-NOT-IN-CONTAINER；凭证使用 FIN-FILE-VALIDATION-UNAVAILABLE、
            FIN-FILE-CUSTOMER-MISMATCH、FIN-FILE-TYPE-INVALID；幂等使用
            FIN-IDEMPOTENCY-CONFLICT、FIN-IDEMPOTENCY-PROCESSING。
        message:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
        requestId:
          type: string
        traceId:
          type: string
        timestamp:
          type: string
          format: date-time
    BillListEnvelope:
      allOf:
        - $ref: '#/components/schemas/ResponseMeta'
        - type: object
          required: [code, message, data]
          properties:
            code: {type: string, example: '200'}
            message: {type: string}
            data:
              type: array
              items: {$ref: '#/components/schemas/Bill'}
    ClientBillListEnvelope:
      allOf:
        - $ref: '#/components/schemas/ResponseMeta'
        - type: object
          required: [code, message, data]
          properties:
            code: {type: string, example: '200'}
            message: {type: string}
            data:
              type: array
              items: {$ref: '#/components/schemas/ClientBill'}
    BillDetailEnvelope:
      allOf:
        - $ref: '#/components/schemas/ResponseMeta'
        - type: object
          required: [code, message, data]
          properties:
            code: {type: string, example: '200'}
            message: {type: string}
            data: {$ref: '#/components/schemas/BillDetail'}
    BillRevisionListEnvelope:
      allOf:
        - $ref: '#/components/schemas/ResponseMeta'
        - type: object
          required: [code, message, data]
          properties:
            code: {type: string, example: '200'}
            message: {type: string}
            data:
              type: array
              items: {$ref: '#/components/schemas/BillRevision'}
    ClientBillDetailEnvelope:
      allOf:
        - $ref: '#/components/schemas/ResponseMeta'
        - type: object
          required: [code, message, data]
          properties:
            code: {type: string, example: '200'}
            message: {type: string}
            data: {$ref: '#/components/schemas/ClientBillDetail'}
    ReceiptEnvelope:
      allOf:
        - $ref: '#/components/schemas/ResponseMeta'
        - type: object
          required: [code, message, data]
          properties:
            code: {type: string, example: '200'}
            message: {type: string}
            data: {$ref: '#/components/schemas/Receipt'}
    ReceiptListEnvelope:
      allOf:
        - $ref: '#/components/schemas/ResponseMeta'
        - type: object
          required: [code, message, data]
          properties:
            code: {type: string, example: '200'}
            message: {type: string}
            data:
              type: array
              items: {$ref: '#/components/schemas/Receipt'}
    ClientReceiptListEnvelope:
      allOf:
        - $ref: '#/components/schemas/ResponseMeta'
        - type: object
          required: [code, message, data]
          properties:
            code: {type: string, example: '200'}
            message: {type: string}
            data:
              type: array
              items: {$ref: '#/components/schemas/ClientReceipt'}
    CostEnvelope:
      allOf:
        - $ref: '#/components/schemas/ResponseMeta'
        - type: object
          required: [code, message, data]
          properties:
            code: {type: string, example: '200'}
            message: {type: string}
            data: {$ref: '#/components/schemas/Cost'}
    CostListEnvelope:
      allOf:
        - $ref: '#/components/schemas/ResponseMeta'
        - type: object
          required: [code, message, data]
          properties:
            code: {type: string, example: '200'}
            message: {type: string}
            data:
              type: array
              items: {$ref: '#/components/schemas/Cost'}
    ContainerSettlementDetailsEnvelope:
      allOf:
        - $ref: '#/components/schemas/ResponseMeta'
        - type: object
          required: [code, message, data]
          properties:
            code: {type: string, example: '200'}
            message: {type: string}
            data: {$ref: '#/components/schemas/ContainerSettlementDetails'}
    CustomerTermsEnvelope:
      allOf:
        - $ref: '#/components/schemas/ResponseMeta'
        - type: object
          required: [code, message, data]
          properties:
            code: {type: string, example: '200'}
            message: {type: string}
            data: {$ref: '#/components/schemas/CustomerTerms'}
    VoucherUploadEnvelope:
      allOf:
        - $ref: '#/components/schemas/ResponseMeta'
        - type: object
          required: [code, message, data]
          properties:
            code: {type: string, example: '200'}
            message: {type: string}
            data: {$ref: '#/components/schemas/VoucherFile'}
  responses:
    BillListResponse:
      description: 平台账单列表。
      content:
        application/json:
          schema: {$ref: '#/components/schemas/BillListEnvelope'}
    ClientBillListResponse:
      description: 客户可见账单列表。
      content:
        application/json:
          schema: {$ref: '#/components/schemas/ClientBillListEnvelope'}
    BillDetailResponse:
      description: 平台账单详情。
      content:
        application/json:
          schema: {$ref: '#/components/schemas/BillDetailEnvelope'}
    BillRevisionListResponse:
      description: 账单修订历史列表。
      content:
        application/json:
          schema: {$ref: '#/components/schemas/BillRevisionListEnvelope'}
    ClientBillDetailResponse:
      description: 客户可见账单详情。
      content:
        application/json:
          schema: {$ref: '#/components/schemas/ClientBillDetailEnvelope'}
    ReceiptResponse:
      description: 收款结果。
      content:
        application/json:
          schema: {$ref: '#/components/schemas/ReceiptEnvelope'}
    ReceiptListResponse:
      description: 平台收款列表。
      content:
        application/json:
          schema: {$ref: '#/components/schemas/ReceiptListEnvelope'}
    ClientReceiptListResponse:
      description: 客户可见收款列表。
      content:
        application/json:
          schema: {$ref: '#/components/schemas/ClientReceiptListEnvelope'}
    CostResponse:
      description: 成本结果。
      content:
        application/json:
          schema: {$ref: '#/components/schemas/CostEnvelope'}
    CostListResponse:
      description: 成本列表。
      content:
        application/json:
          schema: {$ref: '#/components/schemas/CostListEnvelope'}
    ContainerSettlementDetailsResponse:
      description: 柜级已结算来源与成本分摊聚合结果。
      content:
        application/json:
          schema: {$ref: '#/components/schemas/ContainerSettlementDetailsEnvelope'}
    CustomerTermsResponse:
      description: 客户账期结果。
      content:
        application/json:
          schema: {$ref: '#/components/schemas/CustomerTermsEnvelope'}
    VoucherUploadResponse:
      description: 临时财务凭证元数据。
      content:
        application/json:
          schema: {$ref: '#/components/schemas/VoucherUploadEnvelope'}
    BusinessError:
      description: 业务错误。
      content:
        application/json:
          schema: {$ref: '#/components/schemas/ErrorEnvelope'}
    IdempotencyConflict:
      description: >-
        幂等冲突。同键异参返回 FIN-IDEMPOTENCY-CONFLICT；同键同参且原请求仍为 PROCESSING
        返回 FIN-IDEMPOTENCY-PROCESSING，并携带 Retry-After: 2。
      headers:
        Retry-After:
          schema:
            type: integer
            minimum: 1
          description: 仅 PROCESSING 时返回，单位秒。
      content:
        application/json:
          schema: {$ref: '#/components/schemas/ErrorEnvelope'}