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`

**需要补充的前端方法**：
```typescript
// 充值
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`

**需要补充的前端方法**：
```typescript
// 审批补录
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 积分相关类型 (需添加)

```typescript
// 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 账务相关类型 (需添加)

```typescript
// 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 请求规范

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

### 5.2 响应处理

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

### 5.3 错误处理

```typescript
// 统一错误处理
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`

```typescript
// 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)

```env
VITE_API_BASE_URL=/api/v1
VITE_USE_MOCK=true
```

### 7.2 生产环境 (.env.production)

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

## 八、对接检查清单

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

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