openapi: 3.0.3
info:
  title: Finance F1 Manual AR API
  version: 1.0.0
  description: 首期人工账单、收款和成本接口；仅 CNY，平台财务可写，客户只读。
servers:
  - url: /api
paths:
  /platform/finance/v1/bills:
    get:
      summary: 查询平台账单
      security: [{platformFinance: []}]
      parameters:
        - {$ref: '#/components/parameters/CustomerId'}
        - {name: status, in: query, schema: {$ref: '#/components/schemas/BillStatus'}}
        - {name: page, in: query, schema: {type: integer, minimum: 1, default: 1}}
        - {name: pageSize, in: query, schema: {type: integer, minimum: 1, maximum: 100, default: 20}}
      responses: {'200': {$ref: '#/components/responses/SuccessPage'}}
    post:
      summary: 创建账单草稿
      security: [{platformFinance: []}]
      parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/CreateBillRequest'}}}}
      responses: {'200': {$ref: '#/components/responses/SuccessBill'}, '403': {$ref: '#/components/responses/BusinessError'}}
  /platform/finance/v1/bills/{billId}:
    get:
      summary: 查询平台账单详情
      security: [{platformFinance: []}]
      parameters: [{$ref: '#/components/parameters/BillId'}]
      responses: {'200': {$ref: '#/components/responses/SuccessBill'}}
    put:
      summary: 更新账单草稿
      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/SuccessBill'}}
  /platform/finance/v1/bills/{billId}/issue:
    post:
      summary: 出账并冻结账单
      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/SuccessBill'}}
  /platform/finance/v1/bills/{billId}/adjust:
    post:
      summary: 出账后调整并生成新版本
      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/SuccessBill'}}
  /platform/finance/v1/bills/{billId}/void:
    post:
      summary: 作废账单
      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/SuccessBill'}}
  /platform/finance/v1/receipts:
    post:
      summary: 人工登记收款并分配账单
      security: [{platformFinance: []}]
      parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/CreateReceiptRequest'}}}}
      responses: {'200': {$ref: '#/components/responses/SuccessReceipt'}}
    get:
      summary: 查询收款记录
      security: [{platformFinance: []}]
      responses: {'200': {$ref: '#/components/responses/SuccessPage'}}
  /platform/finance/v1/cost-entries:
    post:
      summary: 人工登记单票或整柜成本
      security: [{platformFinance: []}]
      parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/CreateCostRequest'}}}}
      responses: {'200': {$ref: '#/components/responses/SuccessCost'}}
    get:
      summary: 查询成本记录
      security: [{platformFinance: []}]
      responses: {'200': {$ref: '#/components/responses/SuccessPage'}}
  /client/finance/v1/bills:
    get:
      summary: 客户只读查询账单
      security: [{customerFinanceRead: []}]
      responses: {'200': {$ref: '#/components/responses/SuccessPage'}, '403': {$ref: '#/components/responses/BusinessError'}}
  /client/finance/v1/bills/{billId}:
    get:
      summary: 客户只读查看账单详情
      security: [{customerFinanceRead: []}]
      parameters: [{$ref: '#/components/parameters/BillId'}]
      responses: {'200': {$ref: '#/components/responses/SuccessBill'}, '403': {$ref: '#/components/responses/BusinessError'}}
  /client/finance/v1/receipts:
    get:
      summary: 客户只读查询收款记录
      security: [{customerFinanceRead: []}]
      responses: {'200': {$ref: '#/components/responses/SuccessPage'}, '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: {type: string, pattern: '^[1-9][0-9]*$'}}
    CustomerId: {name: customerId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
    IdempotencyKey: {name: Idempotency-Key, in: header, required: true, schema: {type: string, maxLength: 128}}
  schemas:
    CreateBillRequest:
      type: object
      required: [customerId, billDate, lines]
      properties:
        customerId: {type: string}
        billDate: {type: string, format: date}
        lines: {type: array, minItems: 1, items: {$ref: '#/components/schemas/BillLineInput'}}
    UpdateBillRequest:
      allOf:
        - {$ref: '#/components/schemas/CreateBillRequest'}
        - type: object
          required: [expectedVersion]
          properties: {expectedVersion: {type: integer, minimum: 0}}
    BillLineInput:
      type: object
      required: [sourceFeeId, sourceFeeVersion, amount]
      properties:
        sourceFeeId: {type: string}
        sourceFeeVersion: {type: integer, minimum: 1}
        orderId: {type: string}
        inboundId: {type: string}
        feeItemName: {type: string}
        amount: {type: number, format: double, minimum: 0}
    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: {type: string}
        receivedDate: {type: string, format: date}
        amount: {type: number, format: double, minimum: 0, exclusiveMinimum: true}
        currency: {type: string, enum: [CNY], default: CNY}
        paymentMethod: {type: string, enum: [BANK_TRANSFER, CASH, OTHER]}
        voucherFileIds: {type: array, minItems: 1, items: {type: string}}
        remark: {type: string, maxLength: 500}
        allocations: {type: array, minItems: 1, items: {$ref: '#/components/schemas/ReceiptAllocationInput'}}
      example:
        customerId: '10001'
        receivedDate: '2026-08-11'
        amount: 300
        currency: CNY
        paymentMethod: BANK_TRANSFER
        voucherFileIds: ['90001']
        allocations:
          - {billId: '81001', amount: 100}
          - {billId: '81002', amount: 100}
          - {billId: '81003', amount: 100}
    ReceiptAllocationInput:
      type: object
      required: [billId, amount]
      properties:
        billId: {type: string}
        amount: {type: number, format: double, minimum: 0, exclusiveMinimum: true}
    CreateCostRequest:
      type: object
      required: [costType, amount, expenseName, voucherFileIds]
      properties:
        costType: {type: string, enum: [SINGLE_ORDER, CONTAINER_SHARED]}
        orderId: {type: string}
        containerId: {type: string}
        expenseName: {type: string, minLength: 1, maxLength: 100}
        amount: {type: number, format: double, minimum: 0, exclusiveMinimum: true}
        currency: {type: string, enum: [CNY], default: CNY}
        voucherFileIds: {type: array, minItems: 1, items: {type: string}}
        remark: {type: string, maxLength: 500}
    BillStatus: {type: string, enum: [DRAFT, ISSUED, PARTIALLY_PAID, PAID, VOIDED]}
    ApiEnvelope:
      type: object
      required: [code, message, data]
      properties:
        code: {type: string, example: '200'}
        message: {type: string}
        data: {type: object, additionalProperties: true}
        requestId: {type: string}
    ErrorEnvelope:
      type: object
      required: [code, message]
      properties: {code: {type: string}, message: {type: string}, requestId: {type: string}}
  responses:
    SuccessBill: {description: Bill result, content: {application/json: {schema: {$ref: '#/components/schemas/ApiEnvelope'}}}}
    SuccessReceipt: {description: Receipt result, content: {application/json: {schema: {$ref: '#/components/schemas/ApiEnvelope'}}}}
    SuccessCost: {description: Cost result, content: {application/json: {schema: {$ref: '#/components/schemas/ApiEnvelope'}}}}
    SuccessPage: {description: Paged result, content: {application/json: {schema: {$ref: '#/components/schemas/ApiEnvelope'}}}}
    BusinessError: {description: Business error, content: {application/json: {schema: {$ref: '#/components/schemas/ErrorEnvelope'}}}}