openapi: 3.0.3
info:
  title: 平台资金账户关联退款
  version: 1.0.0
  description: 原消费保持不可变；退款记录关联原消费流水号，累计退款不得超过原消费金额，包含业务退款事件已退金额。
paths:
  /api/platform/finance/v1/accounts/{customerId}/ledger/{ledgerId}/refunds:
    post:
      operationId: refundWalletConsumption
      summary: 原消费关联退款
      description: 仅平台 tenantId=0 且具有 platform:finance:customer-account:adjust 权限可操作。账户行锁串行校验累计可退金额，无需前端提交账户版本。优先归还已用授信，再增加实际余额。相同键同请求返回原流水；相同键不同原消费或金额失败。非成功消费、跨客户原流水、超额退款均拒绝。
      security:
        - bearerAuth: []
      parameters:
        - {name: customerId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: ledgerId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: Idempotency-Key, in: header, required: true, schema: {type: string, minLength: 1, maxLength: 128}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [amount, reason]
              properties:
                amount: {type: number, minimum: 0.01, maximum: 999999999999.99, multipleOf: 0.01}
                reason: {type: string, minLength: 1, maxLength: 500, description: 必填退款原因，不得仅空白}
      responses:
        '200':
          description: 统一响应 code=200 成功；业务失败使用 FIN-REQ-400、FIN-WALLET-404、FIN-IDEMPOTENCY-CONFLICT 或 FIN-WALLET-REFUND-EXCEEDED 等业务码。
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: {type: string}
                  data:
                    $ref: '#/components/schemas/RefundLedgerEntry'
        '403': {description: 非平台主体或缺少调账权限}
components:
  securitySchemes:
    bearerAuth: {type: http, scheme: bearer, bearerFormat: JWT}
  schemas:
    RefundLedgerEntry:
      type: object
      description: 完整返回 FinanceWalletDtos.WalletLedgerEntry，资金余额字段沿用账户流水协议。
      properties:
        ledgerId: {type: string}
        businessNo: {type: string, description: 新退款流水正式 AC 单号}
        changeType: {type: string, enum: [REFUND]}
        amount: {type: number, description: 实际退款正金额}
        sourceType: {type: string, enum: [BUSINESS_REFUND]}
        sourceNo: {type: string, description: 客户及幂等键派生的稳定技术退款引用}
        referenceNo: {type: string, description: 原消费流水 businessNo，用于关联及累计可退校验}
        operatorName: {type: string, nullable: true}
        remark: {type: string, description: 退款原因}
        actualBalanceAfter: {type: number}
        frozenBalanceAfter: {type: number}
        availableBalanceAfter: {type: number}
        creditUsedAfter: {type: number}
        availableCreditAfter: {type: number}