# RustJR 前端 - 账户管理系统
基于 Vue 3 + TypeScript + Element Plus 的现代化前端应用，对接 Rust 后端 API。
## ✨ 技术栈
### 核心框架
- **Vue 3** - 渐进式前端框架，使用 Composition API
- **TypeScript** - 类型安全的 JavaScript 超集
- **Pinia** - Vue 官方状态管理库
- **Vue Router 4** - 官方路由管理器
### UI 组件库
- **Element Plus** - 基于 Vue 3 的组件库
- **@element-plus/icons-vue** - Element Plus 图标库
### HTTP 客户端
- **Axios** - HTTP 请求库，支持请求/响应拦截器
- **@tanstack/vue-query** - 数据获取和缓存 (可选)
### 构建工具
- **Vite** - 下一代前端构建工具
- **ESLint** - 代码质量检查
- **Prettier** - 代码格式化
### 开发工具
- **TypeScript** - 类型检查
- **Vue DevTools** - Vue 开发调试工具
## 🏗️ 项目结构
```
src/
├── api/ # API 服务层
│ ├── client.ts # 统一 HTTP 客户端
│ ├── account.ts # 账户相关 API
│ ├── transaction.ts # 交易相关 API
│ └── reconciliation.ts # 对账相关 API
├── components/ # 可复用组件
│ ├── common/ # 通用组件
│ ├── forms/ # 表单组件
│ └── tables/ # 表格组件
├── composables/ # Vue Composition 函数
│ ├── useAuth.ts # 认证相关
│ ├── useApi.ts # API 调用
│ └── useValidation.ts # 表单验证
├── layouts/ # 布局组件
├── pages/ # 页面组件
│ ├── Dashboard.vue # 仪表板
│ ├── Accounts.vue # 账户管理
│ ├── Transactions.vue # 交易管理
│ └── Reconciliation.vue # 对账管理
├── router/ # 路由配置
├── stores/ # Pinia 状态管理
│ ├── auth.ts # 认证状态
│ ├── account.ts # 账户状态
│ └── transaction.ts # 交易状态
├── types/ # TypeScript 类型定义
│ ├── account.ts # 账户类型
│ ├── transaction.ts # 交易类型
│ └── api.ts # API 类型
├── utils/ # 工具函数
│ ├── format.ts # 格式化工具
│ ├── validation.ts # 验证工具
│ └── constants.ts # 常量定义
└── styles/ # 样式文件
└── main.css # 全局样式
```
## 🚀 快速开始
### 1. 环境要求
- Node.js 16+
- npm 或 yarn 或 pnpm
### 2. 安装依赖
```bash
# 安装项目依赖
npm install
# 或使用 yarn
yarn install
# 或使用 pnpm
pnpm install
```
### 3. 环境配置
复制环境配置文件：
```bash
cp .env.example .env.local
```
编辑 `.env.local`：
```env
# API 基础地址 (对应后端地址)
VITE_API_BASE_URL=http://localhost:8080/api
# 应用配置
VITE_APP_NAME=账户管理系统
VITE_APP_VERSION=1.0.0
```
### 4. 启动开发服务器
```bash
# 使用 npm
npm run dev
# 或使用 yarn
yarn dev
# 或使用 pnpm
pnpm dev
```
应用将在 `http://localhost:3001` 启动。
### 5. 构建生产版本
```bash
# 构建生产版本
npm run build
# 预览生产版本
npm run preview
```
## 🔧 前后端联调
### API 接口对接
项目使用了统一的 API 客户端 (`src/api/client.ts`)，具有以下特性：
#### 请求拦截器
- 自动添加认证 token
- 添加请求ID用于追踪
- 统一的错误处理
#### 响应拦截器
- 统一的状态码处理
- 自动 token 过期处理
- 业务错误统一处理
#### 使用示例
```typescript
import { AccountAPI } from '@/api'
// 获取账户列表
const accounts = await AccountAPI.getAccountList({
page: 1,
pageSize: 20
})
// 创建交易
const transaction = await TransactionAPI.createTransaction({
txnType: TransactionType.TRANSFER,
fromAccountId: 1,
toAccountId: 2,
amount: 1000.00,
remark: '转账备注'
})
```
### 类型安全
项目使用 TypeScript 确保类型安全：
- 所有 API 请求/响应都有完整的类型定义
- 状态管理使用类型化的 store
- 组件 props 有严格的类型检查
### 状态管理
使用 Pinia 进行状态管理：
```typescript
import { useAccountStore } from '@/stores'
// 在组件中使用
const accountStore = useAccountStore()
// 获取数据
await accountStore.fetchAccounts()
// 监听状态变化
watch(() => accountStore.accounts, (newAccounts) => {
console.log('账户列表更新:', newAccounts)
})
```
## 📱 页面功能
### 1. 仪表板 (Dashboard)
- 账户余额汇总
- 今日交易统计
- 系统状态概览
- 快捷操作入口
### 2. 账户管理 (Accounts)
- 账户列表查看
- 账户余额详情
- 冻结/解冻操作
- 账户创建/编辑
### 3. 交易管理 (Transactions)
- 交易记录查询
- 交易详情查看
- 交易状态跟踪
- 交易操作 (重试/取消)
### 4. 对账管理 (Reconciliation)
- 对账批次管理
- 三账校验结果
- 差异处理
- 对账报告导出
## 🎨 样式和主题
项目使用 Element Plus 的默认主题，可以通过以下方式自定义：
### 全局样式
```css
/* src/styles/main.css */
:root {
--el-color-primary: #409eff;
--el-color-success: #67c23a;
--el-color-warning: #e6a23c;
--el-color-danger: #f56c6c;
}
```
### 组件样式覆盖
```vue
自定义按钮
```
## 🔒 认证和权限
### JWT 认证
项目使用 JWT 进行身份认证：
- 登录后 token 自动保存到 localStorage
- 请求拦截器自动添加 Authorization 头
- token 过期自动跳转登录页面
### 权限控制
基于角色的权限控制：
```typescript
import { useAuthStore } from '@/stores'
const authStore = useAuthStore()
// 检查权限
if (authStore.hasPermission('account.create')) {
// 显示创建账户按钮
}
```
## 🧪 测试
```bash
# 运行单元测试
npm run test
# 运行 E2E 测试 (需要额外配置)
npm run test:e2e
```
## 📦 部署
### 构建配置
```typescript
// vite.config.ts
export default defineConfig({
build: {
outDir: 'dist',
sourcemap: false,
minify: 'terser',
},
server: {
proxy: {
'/api': {
target: 'http://your-backend-url',
changeOrigin: true,
},
},
},
})
```
### Nginx 配置
```nginx
server {
listen 80;
server_name your-domain.com;
location / {
root /path/to/dist;
try_files $uri $uri/ /index.html;
}
location /api {
proxy_pass http://localhost:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
```
## 🤝 开发规范
### 代码风格
- 使用 ESLint + Prettier 保持代码风格一致
- 遵循 Vue 3 Composition API 最佳实践
- 组件使用 `