openapi: 3.0.3
info:
  title: 客户资金账户、授信与充值 API
  version: 1.2.0
  description: |
    CNY 资金账户支持静态收款码、付款截图申请、平台审核、手工充扣、限时授信及业务冻结/结算/释放。
    授信到期日当天仍有效，次日不再计入可用余额。消费直接扣减实际余额并允许形成负数；实际余额为负时禁止提交新订单。
    充值直接增加实际余额。新账户授信额度由
    `baiyue.finance.wallet.default-credit-limit` 初始化，默认 `0.00`，平台可按客户调整。
paths:
  /api/client/finance/v1/account:
    get:
      summary: 查询当前客户资金账户
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/WalletAccountEnvelope' }
  /api/client/finance/v1/account/ledger:
    get:
      summary: 查询当前客户账户流水
      parameters:
        - { name: page, in: query, schema: { type: integer, default: 1 } }
        - { name: size, in: query, schema: { type: integer, default: 20 } }
      responses:
        '200': { description: 成功 }
  /api/client/finance/v1/recharge-channel:
    get:
      summary: 查询平台统一静态收款码配置
      responses:
        '200': { description: 成功 }
  /api/client/finance/v1/recharge-requests:
    get:
      summary: 查询当前客户充值申请，待审核优先
      responses:
        '200': { description: 成功 }
    post:
      summary: 上传付款截图并提交充值申请
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [amount, file]
              properties:
                amount: { type: number, format: decimal, minimum: 0.01 }
                file: { type: string, format: binary, description: JPG 或 PNG }
      responses:
        '200': { description: 提交成功 }
  /api/client/finance/v1/recharge-requests/{requestId}/voucher:
    get:
      summary: 预览当前客户充值凭证
      parameters:
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200': { description: 图片内容 }
  /api/platform/finance/v1/accounts/{customerId}/recharge-requests:
    get:
      summary: 查询客户充值申请，待审核优先
      parameters:
        - $ref: '#/components/parameters/CustomerId'
      responses:
        '200': { description: 成功 }
  /api/platform/finance/v1/recharge-requests/{requestId}/review:
    post:
      summary: 审核或驳回充值申请
      parameters:
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RechargeReviewRequest' }
      responses:
        '200': { description: 成功 }
  /api/platform/finance/v1/recharge-requests/{requestId}/voucher:
    get:
      summary: 平台预览充值凭证
      parameters:
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200': { description: 图片内容 }
  /api/platform/finance/v1/accounts/{customerId}/adjustments:
    post:
      summary: 平台手工充值或扣款
      parameters:
        - $ref: '#/components/parameters/CustomerId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/AccountAdjustmentRequest' }
      responses:
        '200': { description: 成功 }
  /api/platform/finance/v1/accounts/{customerId}/credit-limit:
    put:
      summary: 设置客户授信额度
      parameters:
        - $ref: '#/components/parameters/CustomerId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreditLimitRequest' }
      responses:
        '200': { description: 成功并生成授信调整流水 }
  /internal/finance/v1/wallet/accounts/{customerId}:
    get:
      summary: 业务模块查询客户资金账户
      parameters:
        - $ref: '#/components/parameters/InternalServiceToken'
        - $ref: '#/components/parameters/CustomerId'
      responses:
        '200': { description: 成功 }
  /internal/finance/v1/wallet/accounts/{customerId}/holds:
    post:
      summary: 按业务单冻结资金，先冻结实际资金再冻结授信
      parameters:
        - $ref: '#/components/parameters/InternalServiceToken'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/CustomerId'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/WalletFreezeRequest' }
      responses:
        '200': { description: 成功；同一客户、业务类型和业务单号只允许一条冻结记录 }
  /internal/finance/v1/wallet/accounts/{customerId}/holds/{businessType}/{businessNo}/settle:
    post:
      summary: 结算已冻结资金
      parameters:
        - $ref: '#/components/parameters/InternalServiceToken'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/CustomerId'
        - $ref: '#/components/parameters/BusinessType'
        - $ref: '#/components/parameters/BusinessNo'
      requestBody:
        content:
          application/json:
            schema: { $ref: '#/components/schemas/WalletHoldActionRequest' }
      responses:
        '200': { description: 成功；实际冻结转为实际扣减，授信冻结转为已用授信 }
  /internal/finance/v1/wallet/accounts/{customerId}/holds/{businessType}/{businessNo}/release:
    post:
      summary: 释放已冻结资金
      parameters:
        - $ref: '#/components/parameters/InternalServiceToken'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/CustomerId'
        - $ref: '#/components/parameters/BusinessType'
        - $ref: '#/components/parameters/BusinessNo'
      requestBody:
        content:
          application/json:
            schema: { $ref: '#/components/schemas/WalletHoldActionRequest' }
      responses:
        '200': { description: 成功；实际资金和授信恢复为可用 }
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema: { type: string, maxLength: 128 }
    InternalServiceToken:
      name: X-Internal-Service-Token
      in: header
      required: true
      schema: { type: string, writeOnly: true }
    CustomerId:
      name: customerId
      in: path
      required: true
      schema: { type: string, pattern: '^[1-9][0-9]*$' }
    RequestId:
      name: requestId
      in: path
      required: true
      schema: { type: string, pattern: '^[1-9][0-9]*$' }
    BusinessType:
      name: businessType
      in: path
      required: true
      schema: { type: string, pattern: '^[A-Z][A-Z0-9_]{1,31}$' }
    BusinessNo:
      name: businessNo
      in: path
      required: true
      schema: { type: string, minLength: 1, maxLength: 128 }
  schemas:
    WalletAccountEnvelope:
      type: object
      properties:
        data: { $ref: '#/components/schemas/WalletAccount' }
    WalletAccount:
      type: object
      required: [currencyCode, actualBalance, frozenBalance, availableBalance, creditLimit, creditUsed, creditFrozen, availableCredit, creditActive, version]
      properties:
        currencyCode: { type: string, enum: [CNY] }
        actualBalance: { type: number, format: decimal, description: 实际余额；授信到期后已用额度并入此余额，可为负数 }
        frozenBalance: { type: number, format: decimal, minimum: 0, description: 实际资金冻结与授信冻结合计 }
        availableBalance: { type: number, format: decimal, description: 当前可用余额，可在授信失效后为负数 }
        creditLimit: { type: number, format: decimal, minimum: 0 }
        creditUsed: { type: number, format: decimal, minimum: 0 }
        creditFrozen: { type: number, format: decimal, minimum: 0 }
        availableCredit: { type: number, format: decimal, minimum: 0 }
        creditExpiresOn: { type: string, format: date, nullable: true, description: 授信到期日，当天仍有效 }
        creditActive: { type: boolean, description: 授信当前是否有效 }
        version: { type: integer, minimum: 0 }
        updatedAt: { type: string, format: date-time, nullable: true }
    RechargeReviewRequest:
      type: object
      required: [decision, expectedVersion]
      properties:
        decision: { type: string, enum: [APPROVE, REJECT] }
        remark: { type: string, maxLength: 500, description: 驳回时必填 }
        expectedVersion: { type: integer, minimum: 0 }
    AccountAdjustmentRequest:
      type: object
      required: [type, amount, occurredDate, remark, expectedAccountVersion]
      properties:
        type: { type: string, enum: [RECHARGE, DEDUCTION] }
        amount: { type: number, format: decimal, minimum: 0.01 }
        occurredDate: { type: string, format: date }
        paymentMethod: { type: string, maxLength: 32 }
        referenceNo: { type: string, maxLength: 128 }
        remark: { type: string, maxLength: 500 }
        expectedAccountVersion: { type: integer, minimum: 0 }
    CreditLimitRequest:
      type: object
      required: [creditLimit, creditExpiresOn, expectedAccountVersion]
      properties:
        creditLimit: { type: number, format: decimal, minimum: 0 }
        creditExpiresOn: { type: string, format: date, description: 必须晚于服务端当前日期，不限制最远日期 }
        remark: { type: string, maxLength: 500 }
        expectedAccountVersion: { type: integer, minimum: 0 }
    WalletFreezeRequest:
      type: object
      required: [amount, businessType, businessNo]
      properties:
        amount: { type: number, format: decimal, minimum: 0.01 }
        businessType: { type: string, minLength: 1, maxLength: 64 }
        businessNo: { type: string, minLength: 1, maxLength: 128 }
        remark: { type: string, maxLength: 500 }
    WalletHoldActionRequest:
      type: object
      properties:
        remark: { type: string, maxLength: 500 }