declare namespace Api {
  /** 账单管理类型 */
  namespace Billing {
    // ==================== 枚举定义 ====================

    /** 账单状态枚举 */
    enum TenantBillingStatus {
      /** 待支付 */
      /** 已支付 */
      Pending = 0,
      /** 已支付 */
      Paid = 1,
      /** 已逾期 */
      Overdue = 2,
      /** 已取消 */
      Cancelled = 3
    }

    /** 账单类型枚举 */
    enum BillingType {
      /** 订阅账单 */
      Subscription = 0,
      /** 配额包购买 */
      QuotaPurchase = 1,
      /** 手动创建 */
      Manual = 2,
      /** 续费账单 */
      Renewal = 3
    }

    /** 租户账单支付方式枚举（后端已从 PaymentMethod 重命名为 TenantPaymentMethod，以解决 Swagger schemaId 冲突） */
    enum TenantPaymentMethod {
      /** 在线支付 */
      Online = 0,
      /** 银行转账 */
      BankTransfer = 1,
      /** 其他方式 */
      Other = 2
    }

    /** 租户账单支付状态枚举（后端已从 PaymentStatus 重命名为 TenantPaymentStatus，以解决 Swagger schemaId 冲突） */
    enum TenantPaymentStatus {
      /** 待处理 */
      Pending = 0,
      /** 成功 */
      Success = 1,
      /** 失败 */
      Failed = 2,
      /** 已退款 */
      Refunded = 3
    }

    /** 导出格式枚举 */
    enum ExportFormat {
      /** Excel 格式 */
      Excel = 0,
      /** PDF 格式 */
      Pdf = 1,
      /** CSV 格式 */
      Csv = 2
    }

    // ==================== DTOs 定义 ====================

    /** 账单列表项 DTO */
    interface BillingListDto {
      id: string
      tenantId: string
      tenantName?: string
      statementNo: string
      /** 账单类型（部分接口可能不返回） */
      billingType?: BillingType
      periodStart: string
      periodEnd: string
      amountDue: number
      amountPaid: number
      discountAmount?: number
      taxAmount?: number
      currency?: string
      status: TenantBillingStatus
      dueDate: string
      overdueNotifiedAt?: string
      createdAt: string
      updatedAt?: string
    }

    /** 账单详情 DTO */
    interface BillingDetailDto extends BillingListDto {
      /** 账单明细 JSON（后端可能直接返回字符串） */
      lineItemsJson?: string
      /** 账单明细列表（后端可能直接返回数组，或由前端从 lineItemsJson 解析） */
      lineItems?: BillingLineItemDto[]
      /** 支付记录列表 */
      payments: PaymentRecordDto[]
      notes?: string
      reminderSentAt?: string
      cancelledAt?: string
      cancelReason?: string
    }

    /** 账单明细项 DTO */
    interface BillingLineItemDto {
      itemType: string
      description: string
      quantity: number
      unitPrice: number
      amount: number
      discountRate?: number
    }

    /** 支付记录 DTO */
    interface PaymentRecordDto {
      id: string
      /** 账单 ID（兼容不同接口字段命名） */
      billingStatementId?: string
      /** 账单 ID（兼容不同接口字段命名） */
      billingId?: string
      amount: number
      method: TenantPaymentMethod
      status: TenantPaymentStatus
      transactionNo?: string
      proofUrl?: string
      paidAt?: string
      notes?: string
      /** 兼容部分后端返回的支付方式文本字段 */
      paymentMethod?: string
      /** 兼容部分后端返回的审核状态字段 */
      verificationStatus?: string
      verifiedBy?: string
      verifiedAt?: string
      refundReason?: string
      refundedAt?: string
      createdAt: string
    }

    /** 账单统计数据 DTO */
    interface BillingStatisticsDto {
      // 兼容“基础统计”返回（当前后端实现）
      totalCount?: number
      pendingCount?: number
      paidCount?: number
      overdueCount?: number
      cancelledCount?: number
      totalAmountDue?: number
      totalAmountPaid?: number
      totalAmountUnpaid?: number
      totalOverdueAmount?: number
      averageAmount?: number
      paymentSuccessRate?: number
      dailyStats?: Array<{
        date: string
        count: number
        totalAmount: number
        paidAmount: number
      }>

      // 兼容“增强统计”返回（用于仪表盘展示）
      /** 总收入 */
      totalRevenue?: number
      /** 本月收入 */
      monthlyRevenue?: number
      /** 待收款金额 */
      pendingAmount?: number
      /** 逾期金额 */
      overdueAmount?: number
      /** 已支付账单数 */
      paidBillCount?: number
      /** 待支付账单数 */
      pendingBillCount?: number
      /** 已逾期账单数 */
      overdueBillCount?: number
      /** 按状态分布 */
      statusDistribution?: Array<{
        status: TenantBillingStatus
        count: number
        amount: number
      }>
      /** 收入趋势（按日期） */
      revenueTrend?: Array<{
        date: string
        amount: number
        count: number
      }>
      /** 支付方式占比 */
      paymentMethodDistribution?: Array<{
        method: TenantPaymentMethod
        count: number
        amount: number
      }>
      /** 租户欠款排行（Top 10） */
      topDebtors?: Array<{
        tenantId: string
        tenantName: string
        overdueAmount: number
        overdueDays: number
      }>
    }

    /** 账单导出数据 DTO */
    interface BillingExportDto {
      statementNo: string
      tenantName: string
      billingType: string
      periodStart: string
      periodEnd: string
      amountDue: number
      amountPaid: number
      status: string
      dueDate: string
      createdAt: string
    }

    // ==================== 查询参数 ====================

    /** 账单列表查询参数 */
    interface BillingListParams {
      /** 页码（从 1 开始） */
      PageNumber?: number
      /** 页大小 */
      PageSize?: number
      /** 租户 ID */
      TenantId?: string
      /** 账单状态 */
      Status?: TenantBillingStatus
      /** 账单类型 */
      BillingType?: BillingType
      /** 开始日期（账单创建时间或到期日） */
      StartDate?: string
      /** 结束日期 */
      EndDate?: string
      /** 最小金额 */
      MinAmount?: number
      /** 最大金额 */
      MaxAmount?: number
      /** 搜索关键词（账单号、租户名） */
      Keyword?: string
      /** 排序字段（CreatedAt, DueDate, AmountDue） */
      SortBy?: string
      /** 是否降序 */
      SortDesc?: boolean
    }

    /** 账单统计查询参数 */
    interface BillingStatisticsParams {
      /** 租户 ID（可选，不传则统计全部） */
      TenantId?: string
      /** 开始日期 */
      StartDate: string
      /** 结束日期 */
      EndDate: string
      /** 分组方式（Day, Week, Month） */
      GroupBy?: 'Day' | 'Week' | 'Month'
    }

    /** 导出参数 */
    interface ExportParams {
      /** 导出格式 */
      Format: ExportFormat
      /** 账单 ID 列表（可选：按选中导出） */
      BillingIds?: string[]
      /** 租户 ID（可选：按筛选条件导出） */
      TenantId?: string
      /** 状态（可选） */
      Status?: TenantBillingStatus
      /** 开始日期（可选） */
      StartDate?: string
      /** 结束日期（可选） */
      EndDate?: string
      /** 关键词（可选） */
      Keyword?: string
    }

    // ==================== 命令参数 ====================

    /** 创建账单命令 */
    interface CreateBillingCommand {
      /** 租户 ID */
      tenantId: string
      /** 账单类型 */
      billingType: BillingType
      /** 应付金额 */
      amountDue: number
      /** 到期日期 */
      dueDate: string
      /** 账单明细 */
      lineItems: Array<{
        itemType: string
        description: string
        quantity: number
        unitPrice: number
        amount: number
        discountRate?: number
      }>
      /** 备注 */
      notes?: string
    }

    /** 更新账单状态命令 */
    interface UpdateStatusCommand {
      /** 新状态 */
      status: TenantBillingStatus
      /** 备注 */
      notes?: string
    }

    /** 记录支付命令 */
    interface RecordPaymentCommand {
      /** 支付金额 */
      amount: number
      /** 支付方式 */
      method: TenantPaymentMethod
      /** 交易号 */
      transactionNo?: string
      /** 支付凭证 URL */
      proofUrl?: string
      /** 备注 */
      notes?: string
    }

    /** 审核支付命令 */
    interface VerifyPaymentCommand {
      /** 审核通过 */
      approved: boolean
      /** 审核备注 */
      notes?: string
    }

    /** 取消账单命令 */
    interface CancelBillingCommand {
      /** 取消原因 */
      reason: string
    }

    /** 批量更新状态命令 */
    interface BatchUpdateStatusCommand {
      /** 账单 ID 列表 */
      billingIds: string[]
      /** 新状态 */
      newStatus: TenantBillingStatus
      /** 备注 */
      notes?: string
    }

    // ==================== 响应类型 ====================

    /** 账单列表响应 */
    type BillingListResponse = Common.PageResult<BillingListDto>

    /** 支付记录列表响应 */
    type PaymentRecordListResponse = PaymentRecordDto[]

    // ==================== 兼容别名（适配现有页面/历史命名） ====================

    /** 账单列表项（兼容旧命名） */
    type BillDto = BillingListDto
    /** 账单详情（兼容旧命名） */
    type BillDetailDto = BillingDetailDto
    /** 账单列表查询参数（兼容旧命名） */
    type BillListParams = BillingListParams
    /** 账单列表响应（兼容旧命名） */
    type BillListResponse = BillingListResponse
    /** 支付记录（兼容旧命名） */
    type PaymentDto = PaymentRecordDto
    /** 创建账单命令（兼容旧命名） */
    type CreateBillCommand = CreateBillingCommand
    /** 更新账单状态命令（兼容旧命名） */
    type UpdateBillStatusCommand = UpdateStatusCommand
  }
}
