rustjr-account-management-frontend/README.md

# 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
<template>
  <el-button class="custom-button">自定义按钮</el-button>
</template>

<style scoped>
.custom-button {
  background-color: #custom-color;
}
</style>
```

## 🔒 认证和权限

### 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 最佳实践
- 组件使用 `<script setup>` 语法糖

### Git 提交规范

```bash
feat: 新功能
fix: 修复bug
docs: 文档更新
style: 代码格式化
refactor: 代码重构
test: 测试相关
chore: 构建过程或工具配置
```

### 命名约定

- **组件**: PascalCase (`AccountList.vue`)
- **方法**: camelCase (`fetchAccounts()`)
- **常量**: UPPER_SNAKE_CASE (`API_BASE_URL`)
- **文件**: kebab-case (`account-list.vue`)

## 🔗 相关链接

- [Vue 3 官方文档](https://v3.vuejs.org/)
- [Element Plus 文档](https://element-plus.org/)
- [Pinia 文档](https://pinia.vuejs.org/)
- [TypeScript 文档](https://www.typescriptlang.org/)

## 📄 许可证

MIT License