docs/财务管理/openapi/finance-f1-manual-v1.yaml

openapi: 3.0.3
info:
  title: Finance F1 Manual AR API
  version: 1.2.0
  description: >-
    F1 人工账单、收款和成本目标契约。仅 CNY；平台财务可写；客户只读且仅可见
    ISSUED、PARTIALLY_PAID、PAID 账单。固定 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:bill:view
      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:bill:view
      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}/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 当前请求包含
        containerOrders 过渡字段，但放行前必须改由服务端从 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/vouchers:
    post:
      summary: 上传财务凭证图片
      description: >-
        当前 Finance Controller 的真实入口，query 参数为 customerId，multipart 字段为 file。
        当前 File 仅校验图片 MIME，尚无用途区分和关联状态；收款/成本落库前的 fail-closed
        校验仍是门禁阻断。
      x-permission-any-of:
        - platform:finance:receipt:create
        - platform:finance:cost:create
      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'
  /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'
    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'
    SignedMoney:
      type: string
      pattern: '^-?(0|[1-9][0-9]*)(\.[0-9]{1,6})?$'
      example: '-0.000001'
    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
            - containerOrders
          properties:
            costType:
              type: string
              enum:
                - CONTAINER_SHARED
            containerId:
              $ref: '#/components/schemas/Id'
            containerOrders:
              type: array
              minItems: 1
              items:
                $ref: '#/components/schemas/ContainerOrderVolumeInput'
              description: >-
                当前 Java 过渡请求字段。调用方不得把人工填写体积视为可信快照；放行前应由
                Finance 根据 containerId 从 Firstleg 获取并校验，届时公开请求应移除此字段。
    ContainerOrderVolumeInput:
      type: object
      required:
        - orderId
        - inboundId
        - containerId
        - volumeCbm
      properties:
        orderId:
          $ref: '#/components/schemas/Id'
        inboundId:
          $ref: '#/components/schemas/Id'
        containerId:
          $ref: '#/components/schemas/Id'
        volumeCbm:
          $ref: '#/components/schemas/Money'
    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'
    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
        - roundingDelta
      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。
        roundingDelta:
          $ref: '#/components/schemas/SignedMoney'
    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
    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'}
    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'}
    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'}
    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'}
    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'}