feat(finance): manage customer wallet balances

src/modules/finance/api/finance.ts

@@ -1,5 +1,5 @@
 import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
-import type { CreatePayableSettlementPayload, CreateReceivableSettlementPayload, CreateReconciliationPayload, CreateSettlementPaymentPayload, FinanceAccountEntry, FinanceAccountSummary, FinanceBillDetail, FinanceBillLine, FinanceBillResource, FinanceBillRevision, FinanceCostResource, FinanceCustomerAccountReadModel, FinanceCustomerTerms, FinanceFeePoolItem, FinanceFeeSourceDetail, FinanceFeeSourceSummary, FinanceLedgerEntry, FinancePayableSettlement, FinanceReceivableSettlement, FinanceReceiptResource, FinanceReconciliationDetail, FinanceSettlementDetail, FinanceSettlementLine, FinanceStatementReadModel, FinanceVoucherResource, ReceivableStatisticsResult, ReconciliationActionPayload } from '../types'
+import type { CreatePayableSettlementPayload, CreateReceivableSettlementPayload, CreateReconciliationPayload, CreateSettlementPaymentPayload, FinanceAccountAdjustmentPayload, FinanceAccountEntry, FinanceAccountSummary, FinanceBillDetail, FinanceBillLine, FinanceBillResource, FinanceBillRevision, FinanceCostResource, FinanceCustomerAccountReadModel, FinanceCustomerTerms, FinanceFeePoolItem, FinanceFeeSourceDetail, FinanceFeeSourceSummary, FinanceLedgerEntry, FinancePayableSettlement, FinanceRechargeRequest, FinanceRechargeReviewPayload, FinanceReceivableSettlement, FinanceReceiptResource, FinanceReconciliationDetail, FinanceSettlementDetail, FinanceSettlementLine, FinanceStatementReadModel, FinanceVoucherResource, ReceivableStatisticsResult, ReconciliationActionPayload } from '../types'
 
 const basePath = '/platform/finance/v1'
 export interface FinanceCustomerAccountSummaryResource {
@@ -53,6 +53,7 @@ function idempotencyKey(operation: string) { return `finance-${operation}-${Date
 type RawResource = Record<string, unknown>
 function stringValue(value: unknown) { return value == null ? '' : String(value) }
 function numberValue(value: unknown) { return Number(value ?? 0) }
+function nullableStringValue(value: unknown) { return value == null ? null : String(value) }
 function jsonRecord(value: unknown): RawResource {
   if (value && typeof value === 'object' && !Array.isArray(value)) return value as RawResource
   if (typeof value !== 'string' || !value.trim()) return {}
@@ -126,22 +127,77 @@ export async function listFinanceAccounts(params: { page?: number; size?: number
   const query = { page: params.page ?? 1, pageSize: params.size ?? 20, customerId: params.customerId || undefined, status: params.status || undefined }
   const response = await http.get<ApiEnvelope<RawResource[]> & { page?: RawResource }, ApiEnvelope<RawResource[]> & { page?: RawResource }>(`${basePath}/accounts`, { params: query })
   const data = unwrapApiResponse(response)
-  const records: FinanceAccountSummary[] = data.map((item) => ({ customerId: stringValue(item.customerId), customerCode: stringValue(item.customerCode), customerName: stringValue(item.customerName), contactName: stringValue(item.contactName), contactPhone: stringValue(item.contactPhone), outstandingReceivable: numberValue(item.outstandingReceivable), pendingBilling: numberValue(item.pendingBilling), receivedInPeriod: numberValue(item.receivedInPeriod), totalCost: numberValue(item.totalCost), paidCost: numberValue(item.paidCost), outstandingPayable: numberValue(item.outstandingPayable), status: stringValue(item.status), lastChangedAt: stringValue(item.lastChangedAt) }))
+  const records: FinanceAccountSummary[] = data.map(normalizeFinanceAccount)
   const total = numberValue(response.page?.total ?? records.length)
   const pageSize = numberValue(response.page?.pageSize ?? query.pageSize) || query.pageSize
   return { records, total, pages: Math.max(1, Math.ceil(total / pageSize)) }
 }
 
+function normalizeFinanceAccount(item: RawResource): FinanceAccountSummary {
+  return {
+    customerId: stringValue(item.customerId), customerCode: stringValue(item.customerCode), customerName: stringValue(item.customerName),
+    contactName: stringValue(item.contactName), contactPhone: stringValue(item.contactPhone), outstandingReceivable: numberValue(item.outstandingReceivable),
+    pendingBilling: numberValue(item.pendingBilling), receivedInPeriod: numberValue(item.receivedInPeriod), totalCost: numberValue(item.totalCost),
+    paidCost: numberValue(item.paidCost), outstandingPayable: numberValue(item.outstandingPayable), status: stringValue(item.status),
+    lastChangedAt: stringValue(item.lastChangedAt), actualBalance: stringValue(item.actualBalance), frozenBalance: stringValue(item.frozenBalance),
+    availableBalance: stringValue(item.availableBalance), accountVersion: numberValue(item.accountVersion), pendingRechargeCount: numberValue(item.pendingRechargeCount),
+  }
+}
+
 export async function listFinanceAccountLedger(customerId: string, params: { page?: number; size?: number; businessType?: string; startDate?: string; endDate?: string } = {}): Promise<{ records: FinanceLedgerEntry[]; total: number; pages: number }> {
   const query = { page: params.page ?? 1, pageSize: params.size ?? 20, businessType: params.businessType || undefined, startDate: params.startDate || undefined, endDate: params.endDate || undefined }
   const response = await http.get<ApiEnvelope<RawResource[]> & { page?: RawResource }, ApiEnvelope<RawResource[]> & { page?: RawResource }>(`${basePath}/accounts/${customerId}/ledger`, { params: query })
   const data = unwrapApiResponse(response)
-  const records = data.map((item) => ({ ledgerId: stringValue(item.ledgerId), occurredAt: stringValue(item.occurredAt), businessType: stringValue(item.businessType), documentType: stringValue(item.documentType), documentId: stringValue(item.documentId), documentNo: stringValue(item.documentNo), receivableChange: numberValue(item.receivableChange), payableChange: numberValue(item.payableChange), outstandingReceivableAfter: numberValue(item.outstandingReceivableAfter), operatorName: stringValue(item.operatorName), remark: stringValue(item.remark) }))
+  const records: FinanceLedgerEntry[] = data.map((item) => ({
+    ledgerId: stringValue(item.ledgerId), occurredAt: stringValue(item.occurredAt), businessType: stringValue(item.businessType),
+    documentType: stringValue(item.documentType), documentId: stringValue(item.documentId), documentNo: stringValue(item.documentNo),
+    receivableChange: numberValue(item.receivableChange), payableChange: numberValue(item.payableChange),
+    outstandingReceivableAfter: numberValue(item.outstandingReceivableAfter), operatorName: stringValue(item.operatorName), remark: stringValue(item.remark),
+    businessNo: nullableStringValue(item.businessNo), changeType: nullableStringValue(item.changeType), amount: nullableStringValue(item.amount),
+    actualBalanceAfter: nullableStringValue(item.actualBalanceAfter), frozenBalanceAfter: nullableStringValue(item.frozenBalanceAfter),
+    availableBalanceAfter: nullableStringValue(item.availableBalanceAfter), sourceType: nullableStringValue(item.sourceType),
+    sourceNo: nullableStringValue(item.sourceNo), occurredDate: nullableStringValue(item.occurredDate),
+    paymentMethod: nullableStringValue(item.paymentMethod), referenceNo: nullableStringValue(item.referenceNo),
+    createdAt: nullableStringValue(item.createdAt),
+  }))
   const total = numberValue(response.page?.total ?? records.length)
   const pageSize = numberValue(response.page?.pageSize ?? query.pageSize) || query.pageSize
   return { records, total, pages: Math.max(1, Math.ceil(total / pageSize)) }
 }
 
+function normalizeRechargeRequest(item: RawResource): FinanceRechargeRequest {
+  return {
+    requestId: stringValue(item.requestId), requestNo: stringValue(item.requestNo), amount: stringValue(item.amount),
+    paymentMethod: stringValue(item.paymentMethod), voucherFileId: stringValue(item.voucherFileId), voucherFileName: stringValue(item.voucherFileName),
+    status: stringValue(item.status), version: numberValue(item.version), submittedByName: stringValue(item.submittedByName),
+    reviewedByName: stringValue(item.reviewedByName), reviewRemark: stringValue(item.reviewRemark), createdAt: stringValue(item.createdAt),
+    reviewedAt: stringValue(item.reviewedAt),
+  }
+}
+
+export async function listFinanceRechargeRequests(customerId: string, params: { page?: number; size?: number } = {}): Promise<{ records: FinanceRechargeRequest[]; total: number; pages: number }> {
+  const query = { page: params.page ?? 1, pageSize: params.size ?? 200 }
+  const response = await http.get<ApiEnvelope<RawResource[]> & { page?: RawResource }, ApiEnvelope<RawResource[]> & { page?: RawResource }>(`${basePath}/accounts/${customerId}/recharge-requests`, { params: query })
+  const records = unwrapApiResponse(response).map(normalizeRechargeRequest)
+  const total = numberValue(response.page?.total ?? records.length)
+  const pageSize = numberValue(response.page?.pageSize ?? query.pageSize) || query.pageSize
+  return { records, total, pages: Math.max(1, Math.ceil(total / pageSize)) }
+}
+
+export async function reviewFinanceRechargeRequest(requestId: string, payload: FinanceRechargeReviewPayload) {
+  const response = await http.post<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/recharge-requests/${requestId}/review`, payload, mutationHeaders('recharge-review'))
+  return normalizeRechargeRequest(unwrapApiResponse(response))
+}
+
+export function downloadFinanceRechargeVoucher(requestId: string) {
+  return http.get<Blob, Blob>(`${basePath}/recharge-requests/${encodeURIComponent(requestId)}/voucher`, { responseType: 'blob' })
+}
+
+export async function adjustFinanceAccount(customerId: string, payload: FinanceAccountAdjustmentPayload) {
+  const response = await http.post<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/accounts/${customerId}/adjustments`, payload, mutationHeaders('account-adjustment'))
+  return unwrapApiResponse(response)
+}
+
 export async function listFinanceFeeSources(params: {
   page?: number
   size?: number