rustjr-account-management/docs/integration/frontend-backend.md

前后端对接清单

一、对接状态总览

1.1 后端 API 统计

领域	端点总数	已对接	未对接
Account	11	11	0
Transaction	5	3	2
Ledger	3	0	3
Reconciliation	8	4	4
Points	5	0	5
总计	32	18	14

1.2 前端多余 API

前端定义了以下 API 但后端尚未实现：

前端方法	预期端点	状态
submitToBank	POST /transactions/:id/submit	待补充
cancelTransaction	POST /transactions/:id/cancel	待补充
retryTransaction	POST /transactions/:id/retry	待补充
getTransactionStatus	GET /transactions/:id/status	待补充
getBankStatements	GET /bank-statements	待补充
getTransactionStats	GET /transactions/stats	待补充
executeBatch	POST /reconciliation/batch	待补充
getAdjustments	GET /reconciliation/adjustments	待补充
getStats	GET /reconciliation/stats	待补充
exportReport	GET /reconciliation/export	待补充

二、详细对接清单

2.1 账户 API 对接

后端端点	前端方法	状态	说明
POST /physical-accounts	AccountAPI.createPhysicalAccount	✅ 已对接
GET /physical-accounts	AccountAPI.getPhysicalAccounts	✅ 已对接
GET /physical-accounts/:id	AccountAPI.getPhysicalAccount	✅ 已对接
POST /physical-accounts/:id/freeze	AccountAPI.freezeAccount	✅ 已对接
POST /physical-accounts/:id/unfreeze	AccountAPI.unfreezeAccount	✅ 已对接
POST /sub-accounts	AccountAPI.createSubAccount	✅ 已对接
GET /sub-accounts/:id	AccountAPI.getSubAccount	✅ 已对接
GET /sub-accounts/:id/balance	AccountAPI.getSubAccountBalance	✅ 已对接
POST /sub-accounts/:id/freeze	AccountAPI.freezeSubAccount	✅ 已对接
POST /sub-accounts/:id/unfreeze	AccountAPI.unfreezeSubAccount	✅ 已对接
POST /sub-accounts/:id/close	AccountAPI.closeSubAccount	✅ 已对接

前端文件: src/api/account.ts

2.2 交易 API 对接

后端端点	前端方法	状态	说明
POST /transactions/transfer	TransactionAPI.createTransfer	✅ 已对接
POST /transactions/deposit	-	❌ 未对接	需添加 createDeposit
POST /transactions/withdraw	-	❌ 未对接	需添加 createWithdraw
GET /transactions/:id	TransactionAPI.getTransaction	✅ 已对接
GET /transactions	TransactionAPI.getTransactions	✅ 已对接

前端文件: src/api/transaction.ts

需要补充的前端方法：

// 充值
static async createDeposit(data: DepositRequest): Promise<Transaction> {
  return apiClient.post('/transactions/deposit', data)
}

// 提现
static async createWithdraw(data: WithdrawRequest): Promise<Transaction> {
  return apiClient.post('/transactions/withdraw', data)
}

2.3 账务 API 对接

后端端点	前端方法	状态	说明
GET /ledger/subjects	-	❌ 未对接	需创建 ledger.ts
GET /ledger/entries/:id	-	❌ 未对接	需创建 ledger.ts
GET /ledger/accounts/:id/entries	-	❌ 未对接	需创建 ledger.ts

需要创建的前端文件: src/api/ledger.ts

2.4 对账 API 对接

后端端点	前端方法	状态	说明
POST /reconciliation/run	ReconciliationAPI.runReconciliation	✅ 已对接
GET /reconciliation/batches/:id	ReconciliationAPI.getBatch	✅ 已对接
GET /reconciliation/batches/:id/items	ReconciliationAPI.getBatchItems	✅ 已对接
GET /reconciliation/three-account/:id	ReconciliationAPI.verifyThreeAccounts	✅ 已对接
POST /reconciliation/adjustments	ReconciliationAPI.createAdjustment	✅ 已对接
POST /reconciliation/adjustments/:id/approve	-	❌ 未对接	需添加 approveAdjustment
POST /reconciliation/adjustments/:id/reject	-	❌ 未对接	需添加 rejectAdjustment
GET /reconciliation/adjustments/pending	-	❌ 未对接	需添加 getPendingAdjustments

前端文件: src/api/reconciliation.ts

需要补充的前端方法：

// 审批补录
static async approveAdjustment(id: number, approver: string): Promise<void> {
  return apiClient.post(`/reconciliation/adjustments/${id}/approve`, { approver })
}

// 拒绝补录
static async rejectAdjustment(id: number, approver: string, reason: string): Promise<void> {
  return apiClient.post(`/reconciliation/adjustments/${id}/reject`, { approver, reason })
}

// 获取待审批补录
static async getPendingAdjustments(): Promise<ManualAdjustment[]> {
  return apiClient.get('/reconciliation/adjustments/pending')
}

2.5 积分 API 对接

后端端点	前端方法	状态	说明
GET /points/accounts/:id	-	❌ 未对接	需创建 points.ts
POST /points/earn	-	❌ 未对接	需创建 points.ts
POST /points/spend	-	❌ 未对接	需创建 points.ts
POST /points/transfer	-	❌ 未对接	需创建 points.ts
GET /points/transactions	-	❌ 未对接	需创建 points.ts

需要创建的前端文件: src/api/points.ts

三、类型定义对照

3.1 账户相关类型

后端类型	前端类型	位置
PhysicalAccount	PhysicalAccount	types/account.ts
VirtualSubAccount	SubAccount	types/account.ts
AccountStatus	AccountStatus	types/account.ts
ConsistencyMode	ConsistencyMode	types/account.ts
OutboundControl	OutboundControl	types/account.ts

3.2 交易相关类型

后端类型	前端类型	位置
SystemTransaction	Transaction	types/transaction.ts
TransactionStatus	TransactionStatus	types/transaction.ts
TransactionType	TransactionType	types/transaction.ts
TransactionDirection	TransactionDirection	types/transaction.ts

3.3 对账相关类型

后端类型	前端类型	位置
ReconciliationBatch	ReconciliationBatch	types/reconciliation.ts
ReconciliationItem	ReconciliationItem	types/reconciliation.ts
ManualAdjustment	ManualAdjustment	types/reconciliation.ts
ThreeAccountResult	ThreeAccountResult	types/reconciliation.ts

3.4 积分相关类型 (需添加)

// types/points.ts

export interface PointsAccount {
  id: number
  sub_account_id: number
  points_type: PointsType
  balance: string
  total_earned: string
  total_spent: string
  total_expired: string
  created_at: string
  updated_at: string
}

export interface PointsTransaction {
  id: number
  txn_no: string
  points_account_id: number
  txn_type: PointsTransactionType
  amount: string
  balance_before: string
  balance_after: string
  related_business_id?: string
  remark?: string
  created_at: string
}

export type PointsType = 'production' | 'management' | 'other'
export type PointsTransactionType = 'earn' | 'spend' | 'transfer' | 'expire' | 'adjust'

3.5 账务相关类型 (需添加)

// types/ledger.ts

export interface AccountingSubject {
  code: string
  name: string
  category: SubjectCategory
  direction_default: number
  parent_code?: string
  level: number
}

export interface LedgerEntry {
  id: number
  entry_no: string
  txn_no: string
  post_date: string
  post_time: string
  description?: string
  status: EntryStatus
  created_at: string
  lines: LedgerLine[]
}

export interface LedgerLine {
  id: number
  entry_id: number
  account_id: number
  account_type: string
  subject_code: string
  direction: Direction
  amount: string
}

export type SubjectCategory = 'asset' | 'liability' | 'income' | 'expense'
export type Direction = 'debit' | 'credit'
export type EntryStatus = 'pending' | 'posted' | 'reversed'

四、待办事项

4.1 高优先级

1. ✅ 创建 src/api/points.ts - 积分 API 客户端
2. ✅ 创建 src/api/ledger.ts - 账务 API 客户端
3. 补充 src/api/transaction.ts 中的 deposit 和 withdraw 方法
4. 补充 src/api/reconciliation.ts 中的审批相关方法

4.2 中优先级

1. 添加 src/types/points.ts - 积分类型定义
2. 添加 src/types/ledger.ts - 账务类型定义
3. 更新前端界面支持新的 API

4.3 低优先级

1. 后端补充前端多余 API 的实现
2. 添加 API 版本管理
3. 添加 API 文档自动生成（OpenAPI/Swagger）

五、接口规范

5.1 请求规范

// 统一请求配置
const apiClient = axios.create({
  baseURL: '/api/v1',
  timeout: 30000,
  headers: {
    'Content-Type': 'application/json',
  },
})

5.2 响应处理

// 响应拦截器
apiClient.interceptors.response.use(
  (response) => response.data.data,
  (error) => {
    const message = error.response?.data?.message || '请求失败'
    ElMessage.error(message)
    return Promise.reject(error)
  }
)

5.3 错误处理

// 统一错误处理
interface ApiError {
  code: number
  message: string
  error?: string
}

// 使用示例
try {
  await AccountAPI.createPhysicalAccount(data)
} catch (error) {
  if (axios.isAxiosError(error)) {
    const apiError = error.response?.data as ApiError
    console.error('API错误:', apiError.message)
  }
}

六、Mock 数据

开发环境使用 MSW (Mock Service Worker) 进行 API 模拟：

配置文件: src/mocks/handlers.ts

// MSW handlers 示例
export const handlers = [
  rest.get('/api/v1/physical-accounts', (req, res, ctx) => {
    return res(ctx.json({
      code: 200,
      message: 'success',
      data: mockPhysicalAccounts
    }))
  }),
  // ... 其他 handlers
]

七、环境配置

7.1 开发环境 (.env.development)

VITE_API_BASE_URL=/api/v1
VITE_USE_MOCK=true

7.2 生产环境 (.env.production)

VITE_API_BASE_URL=https://api.example.com/api/v1
VITE_USE_MOCK=false

八、对接检查清单

在进行前后端对接时，请确认以下事项：

• 接口路径是否正确
• 请求方法是否匹配 (GET/POST/PUT/DELETE)
• 请求参数格式是否正确 (Query/Body/Path)
• 响应数据结构是否匹配
• 错误码处理是否完整
• 类型定义是否同步
• Mock 数据是否更新