326 lines
9.6 KiB
Markdown
326 lines
9.6 KiB
Markdown
# 前后端对接清单
|
||
|
||
## 一、对接状态总览
|
||
|
||
### 1.1 后端 API 统计
|
||
|
||
| 领域 | 端点总数 | 已对接 | 未对接 | 覆盖率 |
|
||
|------|----------|--------|--------|--------|
|
||
| Account | 11 | 11 | 0 | ✅ 100% |
|
||
| Transaction | 5 | 5 | 0 | ✅ 100% |
|
||
| Ledger | 3 | 3 | 0 | ✅ 100% |
|
||
| Reconciliation | 8 | 8 | 0 | ✅ 100% |
|
||
| Points | 5 | 5 | 0 | ✅ 100% |
|
||
| **总计** | **32** | **32** | **0** | **✅ 100%** |
|
||
|
||
### 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.transfer | ✅ 已对接 | |
|
||
| POST /transactions/deposit | TransactionAPI.deposit | ✅ 已对接 | |
|
||
| POST /transactions/withdraw | TransactionAPI.withdraw | ✅ 已对接 | |
|
||
| GET /transactions/:id | TransactionAPI.getTransaction | ✅ 已对接 | |
|
||
| GET /transactions | TransactionAPI.getTransactions | ✅ 已对接 | |
|
||
|
||
**前端文件**: `src/api/transaction.ts`
|
||
|
||
### 2.3 账务 API 对接
|
||
|
||
| 后端端点 | 前端方法 | 状态 | 说明 |
|
||
|----------|----------|------|------|
|
||
| GET /ledger/subjects | LedgerAPI.getSubjects | ✅ 已对接 | |
|
||
| GET /ledger/entries/:id | LedgerAPI.getEntry | ✅ 已对接 | |
|
||
| GET /ledger/accounts/:id/entries | LedgerAPI.getAccountEntries | ✅ 已对接 | |
|
||
|
||
**前端文件**: `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 | ReconciliationAPI.approveAdjustment | ✅ 已对接 | |
|
||
| POST /reconciliation/adjustments/:id/reject | ReconciliationAPI.rejectAdjustment | ✅ 已对接 | |
|
||
| GET /reconciliation/adjustments/pending | ReconciliationAPI.getPendingAdjustments | ✅ 已对接 | |
|
||
|
||
**前端文件**: `src/api/reconciliation.ts`
|
||
|
||
### 2.5 积分 API 对接
|
||
|
||
| 后端端点 | 前端方法 | 状态 | 说明 |
|
||
|----------|----------|------|------|
|
||
| GET /points/accounts/:id | PointsAPI.getAccounts | ✅ 已对接 | |
|
||
| POST /points/earn | PointsAPI.earnPoints | ✅ 已对接 | |
|
||
| POST /points/spend | PointsAPI.spendPoints | ✅ 已对接 | |
|
||
| POST /points/transfer | PointsAPI.transferPoints | ✅ 已对接 | |
|
||
| GET /points/transactions | PointsAPI.getTransactions | ✅ 已对接 | |
|
||
|
||
**前端文件**: `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 API 客户端 (全部完成)
|
||
|
||
- ✅ 创建 `src/api/points.ts` - 积分 API 客户端
|
||
- ✅ 创建 `src/api/ledger.ts` - 账务 API 客户端
|
||
- ✅ 补充 `src/api/transaction.ts` 中的 deposit 和 withdraw 方法
|
||
- ✅ 补充 `src/api/reconciliation.ts` 中的审批相关方法
|
||
|
||
### 4.2 类型定义 (全部完成)
|
||
|
||
- ✅ 添加 `src/types/points.ts` - 积分类型定义
|
||
- ✅ 添加 `src/types/ledger.ts` - 账务类型定义
|
||
|
||
### 4.3 后续优化建议
|
||
|
||
1. 更新前端界面以支持新的 API
|
||
2. 添加 API 版本管理
|
||
3. 添加 API 文档自动生成（OpenAPI/Swagger）
|
||
4. 后端补充扩展 API（如交易统计、银行流水查询等）
|
||
|
||
## 五、接口规范
|
||
|
||
### 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 数据是否更新
|
||
|