feat: 完善 Transaction 和 Reconciliation API 客户端

Transaction API:
- 新增 deposit() 充值方法
- 新增 withdraw() 提现方法
- 修正 transfer() 端点路径为 /transactions/transfer
- 添加 DepositRequest 和 WithdrawRequest 类型
- 标记需要后端扩展的方法

Reconciliation API:
- 新增 approveAdjustment() 审批补录方法
- 新增 rejectAdjustment() 拒绝补录方法
- 新增 getPendingAdjustments() 获取待审批列表
- 修正 runReconciliation() 端点路径为 /reconciliation/run
- 完善类型定义 (ReconciliationBatch, ManualAdjustment 等)
- 添加状态标签映射

现在前端 API 覆盖率:
- Transaction: 100% (5/5 端点)
- Reconciliation: 100% (8/8 端点)

src/api/reconciliation.ts

@@ -1,131 +1,312 @@
-// 对账相关API服务
+/**
+ * 对账 API 客户端
+ * 提供对账批次管理、三账校验、手工补录等功能
+ */
 import { apiClient } from './client'
+import type { PageResponse } from '@/types/api'
 
+/**
+ * 对账批次
+ */
 export interface ReconciliationBatch {
   id: number
-  batchNo: string
+  batch_no: string
-  reconDate: string
+  physical_account_id: number
-  status: string
+  recon_date: string
-  totalTransactions: number
+  total_count: number
-  matchedCount: number
+  matched_count: number
-  mismatchedCount: number
+  mismatch_count: number
-  bankTotal: number
+  status: ReconciliationStatus
-  ledgerTotal: number
+  bank_total?: string
-  inTransitNet: number
+  transit_net?: string
-  threeAccountBalanced: boolean
+  ledger_total?: string
-  difference: number
+  three_account_balanced?: boolean
-  createdAt: string
+  created_at: string
-  completedAt?: string
+  completed_at?: string
 }
 
+/**
+ * 对账批次状态
+ */
+export type ReconciliationStatus = 'processing' | 'completed' | 'need_review'
+
+/**
+ * 对账明细项
+ */
 export interface ReconciliationItem {
   id: number
-  batchId: number
+  batch_id: number
-  transactionId?: number
+  system_txn_no?: string
-  bankRefNo?: string
+  bank_ref_no?: string
-  txnType: string
+  system_amount?: string
-  amount: number
+  bank_amount?: string
-  bankAmount?: number
+  diff_amount: string
-  ledgerAmount?: number
+  status: ReconciliationItemStatus
-  matchStatus: 'matched' | 'mismatched' | 'bank_only' | 'ledger_only'
+  remark?: string
-  matchTime?: string
+  created_at: string
-  remarks?: string
 }
 
+/**
+ * 对账项状态
+ */
+export type ReconciliationItemStatus = 
+  | 'matched'          // 已匹配
+  | 'system_unreached' // 系统未达
+  | 'bank_unreached'   // 银行未达
+  | 'amount_mismatch'  // 金额不匹配
+  | 'adjusted'         // 已调整
+
+/**
+ * 三账校验结果
+ */
 export interface ThreeAccountResult {
-  bankBalance: number
+  physical_account_id: number
-  transitNet: number
+  bank_balance: string
-  ledgerTotal: number
+  transit_net: string
-  isBalanced: boolean
+  ledger_total: string
-  difference: number
+  expected_total: string
+  difference: string
+  is_balanced: boolean
+  verified_at: string
+}
+
+/**
+ * 手工补录
+ */
+export interface ManualAdjustment {
+  id: number
+  adjustment_no: string
+  related_txn_no?: string
+  reconciliation_item_id?: number
+  adjustment_type: AdjustmentType
+  account_id: number
+  amount: string
+  reason: string
+  operator: string
+  approver?: string
+  status: AdjustmentStatus
+  created_at: string
+  approved_at?: string
+}
+
+/**
+ * 补录类型
+ */
+export type AdjustmentType = 'add' | 'reverse' | 'modify'
+
+/**
+ * 补录状态
+ */
+export type AdjustmentStatus = 'pending' | 'approved' | 'rejected'
+
+/**
+ * 创建对账请求
+ */
+export interface CreateReconciliationRequest {
+  physical_account_id: number
+  recon_date: string
+}
+
+/**
+ * 创建补录请求
+ */
+export interface CreateAdjustmentRequest {
+  related_txn_no?: string
+  reconciliation_item_id?: number
+  adjustment_type: AdjustmentType
+  account_id: number
+  amount: string
+  reason: string
 }
 
 export class ReconciliationAPI {
-  // 获取对账批次列表
+  // ==================== 核心对账功能 (已对接后端) ====================
-  static async getBatches(params?: {
+
-    status?: string
+  /**
-    startDate?: string
+   * 执行对账
-    endDate?: string
+   * 对应后端: POST /api/v1/reconciliation/run
-    page?: number
+   */
-    pageSize?: number
+  static async runReconciliation(data: CreateReconciliationRequest): Promise<ReconciliationBatch> {
-  }): Promise<{
+    return apiClient.post('/reconciliation/run', data)
-    items: ReconciliationBatch[]
-    total: number
-  }> {
-    return apiClient.get('/reconciliation/batches', params)
   }
-  
+
-  // 获取对账批次详情
+  /**
+   * 获取对账批次详情
+   * 对应后端: GET /api/v1/reconciliation/batches/:id
+   */
   static async getBatch(id: number): Promise<ReconciliationBatch> {
     return apiClient.get(`/reconciliation/batches/${id}`)
   }
   
-  // 创建对账批次
+  /**
-  static async createBatch(data: {
+   * 获取对账明细
-    reconDate: string
+   * 对应后端: GET /api/v1/reconciliation/batches/:id/items
-    accountIds?: number[]
+   */
-  }): Promise<ReconciliationBatch> {
-    return apiClient.post('/reconciliation/batches', data)
-  }
-  
-  // 执行对账
-  static async executeBatch(id: number): Promise<ReconciliationBatch> {
-    return apiClient.post(`/reconciliation/batches/${id}/execute`)
-  }
-  
-  // 获取对账明细
   static async getBatchItems(batchId: number, params?: {
-    matchStatus?: string
+    status?: ReconciliationItemStatus
     page?: number
-    pageSize?: number
+    page_size?: number
-  }): Promise<{
+  }): Promise<PageResponse<ReconciliationItem>> {
-    items: ReconciliationItem[]
+    return apiClient.get(`/reconciliation/batches/${batchId}/items`, { params })
-    total: number
-  }> {
-    return apiClient.get(`/reconciliation/batches/${batchId}/items`, params)
   }
   
-  // 三账校验
+  /**
+   * 三账校验
+   * 对应后端: GET /api/v1/reconciliation/three-account/:account_id
+   */
   static async verifyThreeAccounts(accountId: number): Promise<ThreeAccountResult> {
     return apiClient.get(`/reconciliation/three-account/${accountId}`)
   }
   
-  // 手工调整
+  /**
-  static async createAdjustment(data: {
+   * 创建手工补录
-    batchId: number
+   * 对应后端: POST /api/v1/reconciliation/adjustments
-    transactionId?: number
+   */
-    adjustmentType: string
+  static async createAdjustment(data: CreateAdjustmentRequest): Promise<ManualAdjustment> {
-    amount: number
-    reason: string
-    operator: string
-  }): Promise<ReconciliationItem> {
     return apiClient.post('/reconciliation/adjustments', data)
   }
+
+  /**
+   * 审批补录
+   * 对应后端: POST /api/v1/reconciliation/adjustments/:id/approve
+   */
+  static async approveAdjustment(id: number, approver: string): Promise<ManualAdjustment> {
+    return apiClient.post(`/reconciliation/adjustments/${id}/approve`, { approver })
+  }
+
+  /**
+   * 拒绝补录
+   * 对应后端: POST /api/v1/reconciliation/adjustments/:id/reject
+   */
+  static async rejectAdjustment(id: number, approver: string, reason: string): Promise<ManualAdjustment> {
+    return apiClient.post(`/reconciliation/adjustments/${id}/reject`, { approver, reason })
+  }
+
+  /**
+   * 获取待审批补录列表
+   * 对应后端: GET /api/v1/reconciliation/adjustments/pending
+   */
+  static async getPendingAdjustments(): Promise<ManualAdjustment[]> {
+    return apiClient.get('/reconciliation/adjustments/pending')
+  }
+
+  // ==================== 扩展功能 (需要后端支持) ====================
+
+  /**
+   * 获取对账批次列表 (需要后端扩展)
+   * @todo 后端需要添加列表查询端点
+   */
+  static async getBatches(params?: {
+    status?: ReconciliationStatus
+    physical_account_id?: number
+    start_date?: string
+    end_date?: string
+    page?: number
+    page_size?: number
+  }): Promise<PageResponse<ReconciliationBatch>> {
+    return apiClient.get('/reconciliation/batches', { params })
+  }
   
-  // 获取调整记录
+  /**
-  static async getAdjustments(batchId: number): Promise<ReconciliationItem[]> {
+   * 获取批次的调整记录 (需要后端扩展)
+   * @todo 后端需要添加此端点
+   */
+  static async getAdjustments(batchId: number): Promise<ManualAdjustment[]> {
     return apiClient.get(`/reconciliation/batches/${batchId}/adjustments`)
   }
   
-  // 对账统计
+  /**
+   * 对账统计 (需要后端扩展)
+   * @todo 后端需要添加此端点
+   */
   static async getStats(params: {
-    startDate?: string
+    start_date?: string
-    endDate?: string
+    end_date?: string
-    accountId?: number
+    physical_account_id?: number
   }): Promise<{
-    totalBatches: number
+    total_batches: number
-    successRate: number
+    success_rate: number
-    totalDiscrepancy: number
+    total_discrepancy: string
-    largestDiscrepancy: number
+    largest_discrepancy: string
   }> {
-    return apiClient.get('/reconciliation/stats', params)
+    return apiClient.get('/reconciliation/stats', { params })
   }
   
-  // 导出对账报告
+  /**
+   * 导出对账报告 (需要后端扩展)
+   * @todo 后端需要添加此端点
+   */
   static async exportReport(batchId: number, format: 'excel' | 'pdf' = 'excel'): Promise<Blob> {
-    return apiClient.get(`/reconciliation/batches/${batchId}/export`, 
+    return apiClient.get(`/reconciliation/batches/${batchId}/export`, { 
-      { format }, 
+      params: { format },
-      { responseType: 'blob' }
+      responseType: 'blob' 
-    )
+    })
+  }
+
+  // ==================== 兼容旧方法 ====================
+
+  /**
+   * @deprecated 使用 runReconciliation 替代
+   */
+  static async createBatch(data: {
+    reconDate: string
+    accountIds?: number[]
+  }): Promise<ReconciliationBatch> {
+    return this.runReconciliation({
+      physical_account_id: data.accountIds?.[0] || 0,
+      recon_date: data.reconDate,
+    })
+  }
+
+  /**
+   * @deprecated 使用 runReconciliation 替代
+   */
+  static async executeBatch(id: number): Promise<ReconciliationBatch> {
+    // 获取批次信息后重新执行对账
+    const batch = await this.getBatch(id)
+    return this.runReconciliation({
+      physical_account_id: batch.physical_account_id,
+      recon_date: batch.recon_date,
+    })
   }
 }
+
+/**
+ * 对账状态显示名称映射
+ */
+export const ReconciliationStatusLabels: Record<ReconciliationStatus, string> = {
+  processing: '处理中',
+  completed: '已完成',
+  need_review: '需要审核',
+}
+
+/**
+ * 对账项状态显示名称映射
+ */
+export const ReconciliationItemStatusLabels: Record<ReconciliationItemStatus, string> = {
+  matched: '已匹配',
+  system_unreached: '系统未达',
+  bank_unreached: '银行未达',
+  amount_mismatch: '金额不匹配',
+  adjusted: '已调整',
+}
+
+/**
+ * 补录类型显示名称映射
+ */
+export const AdjustmentTypeLabels: Record<AdjustmentType, string> = {
+  add: '补录',
+  reverse: '冲销',
+  modify: '修改',
+}
+
+/**
+ * 补录状态显示名称映射
+ */
+export const AdjustmentStatusLabels: Record<AdjustmentStatus, string> = {
+  pending: '待审批',
+  approved: '已审批',
+  rejected: '已拒绝',
+}
+
+export default ReconciliationAPI

src/api/transaction.ts

@@ -1,4 +1,7 @@
-// 交易相关API服务
+/**
+ * 交易 API 客户端
+ * 提供转账、充值、提现等交易功能
+ */
 import { apiClient } from './client'
 import type { 
   SystemTransaction, 
@@ -9,54 +12,166 @@ import type {
   TransferRequest,
   TransferResponse 
 } from '@/types/transaction'
+import type { PageResponse } from '@/types/api'
+
+/**
+ * 充值请求
+ */
+export interface DepositRequest {
+  account_id: number
+  amount: string
+  source_key?: string
+  remark?: string
+}
+
+/**
+ * 提现请求
+ */
+export interface WithdrawRequest {
+  account_id: number
+  amount: string
+  remark?: string
+}
 
 export class TransactionAPI {
-  // 获取交易详情
+  // ==================== 核心交易操作 ====================
+  
+  /**
+   * 发起转账
+   * 对应后端: POST /api/v1/transactions/transfer
+   */
+  static async transfer(data: TransferRequest): Promise<SystemTransaction> {
+    return apiClient.post('/transactions/transfer', data)
+  }
+
+  /**
+   * 发起充值 (入金)
+   * 对应后端: POST /api/v1/transactions/deposit
+   */
+  static async deposit(data: DepositRequest): Promise<SystemTransaction> {
+    return apiClient.post('/transactions/deposit', data)
+  }
+
+  /**
+   * 发起提现 (出金)
+   * 对应后端: POST /api/v1/transactions/withdraw
+   */
+  static async withdraw(data: WithdrawRequest): Promise<SystemTransaction> {
+    return apiClient.post('/transactions/withdraw', data)
+  }
+
+  // ==================== 交易查询 ====================
+
+  /**
+   * 获取交易详情
+   * 对应后端: GET /api/v1/transactions/:id
+   */
   static async getTransaction(id: number): Promise<SystemTransaction> {
     return apiClient.get(`/transactions/${id}`)
   }
   
-  // 根据交易号获取交易
+  /**
-  static async getTransactionByNo(txnNo: string): Promise<SystemTransaction> {
+   * 获取交易列表
-    return apiClient.get(`/transactions/by-no/${txnNo}`)
+   * 对应后端: GET /api/v1/transactions
+   */
+  static async getTransactions(query: TransactionQuery = {}): Promise<PageResponse<SystemTransaction>> {
+    return apiClient.get('/transactions', { params: query })
   }
-  
+
-  // 获取交易列表
+  // ==================== 兼容旧方法 (保持向后兼容) ====================
+
+  /**
+   * @deprecated 使用 getTransactions 替代
+   */
   static async getTransactionList(query: TransactionQuery = {}): Promise<TransactionListResponse> {
-    return apiClient.get('/transactions', query)
+    return apiClient.get('/transactions', { params: query })
   }
   
-  // 创建交易
+  /**
+   * 根据交易号获取交易 (需要后端支持)
+   * 注意: 当前后端未提供此端点，需要使用 getTransactions + filter
+   */
+  static async getTransactionByNo(txnNo: string): Promise<SystemTransaction> {
+    const result = await this.getTransactions({ txn_no: txnNo })
+    if (result.data && result.data.length > 0) {
+      return result.data[0]
+    }
+    throw new Error('交易不存在')
+  }
+
+  // ==================== 扩展功能 (需要后端支持) ====================
+
+  /**
+   * 创建交易 (通用)
+   * 注意: 建议使用具体的 transfer/deposit/withdraw 方法
+   */
   static async createTransaction(data: CreateTransactionRequest): Promise<SystemTransaction> {
-    return apiClient.post('/transactions', data)
+    // 根据交易类型调用对应的方法
+    switch (data.txn_type) {
+      case 'transfer':
+        return this.transfer({
+          from_account_id: data.from_account_id!,
+          to_account_id: data.to_account_id!,
+          amount: data.amount,
+          remark: data.remark,
+        })
+      case 'deposit':
+        return this.deposit({
+          account_id: data.to_account_id!,
+          amount: data.amount,
+          remark: data.remark,
+        })
+      case 'withdrawal':
+        return this.withdraw({
+          account_id: data.from_account_id!,
+          amount: data.amount,
+          remark: data.remark,
+        })
+      default:
+        throw new Error(`不支持的交易类型: ${data.txn_type}`)
+    }
   }
   
-  // 提交交易到银行
+  /**
+   * 提交交易到银行 (需要后端扩展)
+   * @todo 后端需要添加此端点
+   */
   static async submitToBank(id: number): Promise<{ bankRefNo: string }> {
     return apiClient.post(`/transactions/${id}/submit`)
   }
   
-  // 取消交易
+  /**
+   * 取消交易 (需要后端扩展)
+   * @todo 后端需要添加此端点
+   */
   static async cancelTransaction(id: number): Promise<void> {
     return apiClient.post(`/transactions/${id}/cancel`)
   }
   
-  // 重试交易
+  /**
+   * 重试交易 (需要后端扩展)
+   * @todo 后端需要添加此端点
+   */
   static async retryTransaction(id: number): Promise<SystemTransaction> {
     return apiClient.post(`/transactions/${id}/retry`)
   }
   
-  // 获取交易状态
+  /**
+   * 获取交易状态 (需要后端扩展)
+   * 注意: 可以通过 getTransaction 获取完整信息
+   */
   static async getTransactionStatus(id: number): Promise<{ status: string, bankRefNo?: string }> {
-    return apiClient.get(`/transactions/${id}/status`)
+    const txn = await this.getTransaction(id)
+    return {
+      status: txn.status,
+      bankRefNo: txn.bank_ref_no,
+    }
   }
   
-  // 转账操作
+  /**
-  static async transfer(data: TransferRequest): Promise<TransferResponse> {
+   * 查询银行流水 (需要后端扩展)
-    return apiClient.post('/transfer', data)
+   * @todo 后端需要添加此端点
-  }
+   */
-  
-  // 查询银行流水
   static async getBankStatements(params: {
     accountNo: string
     startDate: string
@@ -67,10 +182,13 @@ export class TransactionAPI {
     items: BankTransaction[]
     total: number
   }> {
-    return apiClient.get('/bank/statements', params)
+    return apiClient.get('/bank/statements', { params })
   }
   
-  // 查询交易统计
+  /**
+   * 查询交易统计 (需要后端扩展)
+   * @todo 后端需要添加此端点
+   */
   static async getTransactionStats(params: {
     accountId?: number
     startDate?: string
@@ -82,22 +200,28 @@ export class TransactionAPI {
     failedCount: number
     pendingCount: number
   }> {
-    return apiClient.get('/transactions/stats', params)
+    return apiClient.get('/transactions/stats', { params })
   }
   
-  // 获取交易历史（分页）
+  /**
+   * 获取账户交易历史（分页）
+   * 使用 getTransactions + from_account_id 筛选
+   */
   static async getTransactionHistory(params: {
     accountId: number
     page?: number
     pageSize?: number
     startDate?: string
     endDate?: string
-  }): Promise<{
+  }): Promise<PageResponse<SystemTransaction>> {
-    items: SystemTransaction[]
+    return this.getTransactions({
-    total: number
+      from_account_id: params.accountId,
-    page: number
+      page: params.page,
-    pageSize: number
+      page_size: params.pageSize,
-  }> {
+      start_date: params.startDate,
-    return apiClient.get(`/accounts/${params.accountId}/transactions`, params)
+      end_date: params.endDate,
+    })
   }
 }
+
+export default TransactionAPI