cz-hjjc-budget/技术栈说明.md

# 前端技术栈说明文档

本文档详细说明了 `czemc-budget-execution-frontend` 项目使用的技术栈。

## 📦 核心依赖

### 1. 核心框架

#### Vue 3.4.21
- **类型**: 核心框架
- **版本**: ^3.4.21
- **用途**: 渐进式 JavaScript 框架，项目的基础框架
- **特性**: 
  - 使用 Composition API（组合式 API）
  - 支持 TypeScript（项目中使用 JavaScript）
  - 响应式数据绑定
  - 组件化开发

#### Vue Router 4.3.0
- **类型**: 路由管理
- **版本**: ^4.3.0
- **用途**: Vue.js 官方路由管理器
- **功能**:
  - 单页面应用路由配置
  - 路由守卫（登录验证）
  - 动态路由加载

### 2. 状态管理

#### Pinia 2.1.7
- **类型**: 状态管理库
- **版本**: ^2.1.7
- **用途**: Vue 3 官方推荐的状态管理库（替代 Vuex）
- **使用场景**:
  - 用户信息管理（`src/store/user.js`）
  - 登录状态管理
  - Token 管理
- **特性**:
  - TypeScript 支持
  - DevTools 支持
  - 模块化设计

### 3. UI 组件库

#### Element Plus 2.6.3
- **类型**: UI 组件库
- **版本**: ^2.6.3
- **用途**: 基于 Vue 3 的企业级 UI 组件库
- **配置**:
  - 使用中文语言包（`zh-cn`）
  - 全局注册所有图标组件
- **主要组件**:
  - 表格、表单、对话框
  - 菜单、导航、布局
  - 按钮、输入框等基础组件

#### Element Plus Icons Vue 2.3.1
- **类型**: 图标库
- **版本**: ^2.3.1
- **用途**: Element Plus 官方图标库
- **使用**: 全局注册所有图标，可在组件中直接使用

### 4. 构建工具

#### Vite 5.1.6
- **类型**: 构建工具
- **版本**: ^5.1.6
- **用途**: 下一代前端构建工具
- **特性**:
  - 快速的开发服务器启动
  - 热模块替换（HMR）
  - 优化的生产构建
  - 原生 ES 模块支持

#### @vitejs/plugin-vue 5.0.4
- **类型**: Vite 插件
- **版本**: ^5.0.4
- **用途**: Vue 3 单文件组件（SFC）支持插件

### 5. 工具库

#### js-cookie 3.0.5
- **类型**: Cookie 操作库
- **版本**: ^3.0.5
- **用途**: 用于管理浏览器 Cookie
- **使用场景**: Token 存储和管理（`src/utils/auth.js`）

#### mermaid 11.12.2
- **类型**: 流程图/图表库
- **版本**: ^11.12.2
- **用途**: 用于渲染流程图和思维导图
- **使用场景**:
  - 支付类别可视化（`src/views/payment/CreatePayment.vue`）
  - 间接支付流程展示（`src/views/payment/IndirectPayment.vue`）
- **功能**: 
  - 将树形数据转换为 Mermaid 语法
  - 渲染为 SVG 图表
  - 支持节点交互和选择

#### vuedraggable 4.1.0
- **类型**: 拖拽组件库
- **版本**: ^4.1.0
- **用途**: 基于 Sortable.js 的 Vue 3 拖拽组件
- **使用场景**: 支付类别排序（`src/views/settings/PaymentCategory.vue`）

## 🛠️ 开发工具和配置

### 环境变量管理
- 支持多环境配置（development、staging、production）
- 使用 `.env` 文件进行环境变量配置
- 所有环境变量必须以 `VITE_` 开头

### 代理配置
- 开发环境使用 Vite 代理转发 API 请求
- 支持配置代理目标和 Host 头
- 自动处理跨域问题

### 构建配置
- 支持多环境构建（`build:dev`、`build:staging`、`build:prod`）
- 不同环境输出到不同目录
- 支持 Source Map 配置

## 📁 项目架构

### 目录结构
```
src/
├── config/              # 配置管理
│   ├── index.js        # 统一配置管理模块
│   └── settings.js     # 配置设置
├── layout/             # 布局组件
│   └── MainLayout.vue  # 主布局组件
├── router/             # 路由配置
│   └── index.js        # 路由定义
├── store/              # 状态管理
│   └── user.js         # 用户状态管理
├── utils/              # 工具类
│   ├── api.js          # API 接口定义
│   ├── auth.js         # 认证工具（Token 管理）
│   └── request.js      # HTTP 请求封装
├── views/              # 页面组件
│   ├── Login.vue       # 登录页面
│   ├── Dashboard.vue   # 工作台
│   ├── BudgetList.vue  # 预算列表
│   ├── ExecutionList.vue # 执行列表
│   ├── Report.vue      # 报表统计
│   ├── funds/          # 资金管理模块
│   ├── payment/        # 支付管理模块
│   ├── pre-approval/   # 预审批模块
│   └── settings/       # 设置模块
├── mock/               # Mock 数据
│   └── index.js
├── App.vue             # 根组件
└── main.js             # 入口文件
```

## 🔧 技术特点

### 1. API 请求封装
- 使用原生 `fetch` API 封装请求工具
- 统一的错误处理机制
- 自动添加 Token 认证
- 支持请求/响应拦截
- 业务状态码检查（code !== 0 时抛出错误）

### 2. 认证机制
- 使用 Bearer Token 认证
- Token 存储在 Cookie 中
- 路由守卫进行登录验证
- Pinia Store 管理用户状态

### 3. 国际化
- Element Plus 使用中文语言包
- Day.js 使用中文语言环境

### 4. 响应式设计
- 使用 Element Plus 的响应式组件
- 支持桌面端和移动端

## 📊 技术栈总结

| 类别 | 技术 | 版本 | 用途 |
|------|------|------|------|
| **核心框架** | Vue | 3.4.21 | 基础框架 |
| **路由** | Vue Router | 4.3.0 | 路由管理 |
| **状态管理** | Pinia | 2.1.7 | 状态管理 |
| **UI 组件** | Element Plus | 2.6.3 | UI 组件库 |
| **图标** | Element Plus Icons | 2.3.1 | 图标库 |
| **构建工具** | Vite | 5.1.6 | 构建工具 |
| **图表** | Mermaid | 11.12.2 | 流程图/图表 |
| **拖拽** | vuedraggable | 4.1.0 | 拖拽功能 |
| **工具** | js-cookie | 3.0.5 | Cookie 操作 |

## 🎯 技术选型说明

### 为什么选择 Vue 3？
- 更好的性能（Composition API）
- 更小的包体积
- 更好的 TypeScript 支持
- 活跃的社区和生态

### 为什么选择 Pinia 而不是 Vuex？
- Vue 3 官方推荐
- 更简洁的 API
- 更好的 TypeScript 支持
- 支持 Vue DevTools

### 为什么选择 Element Plus？
- 与 Vue 3 完美集成
- 丰富的组件库
- 良好的文档和社区支持
- 适合企业级应用

### 为什么选择 Vite？
- 极快的开发服务器启动速度
- 快速的热更新
- 优化的生产构建
- 原生 ES 模块支持

## 📝 开发规范

### 代码风格
- 使用 Composition API（组合式 API）
- 单文件组件（SFC）格式
- 使用 `<script setup>` 语法糖

### 命名规范
- 组件使用 PascalCase
- 文件使用 PascalCase（组件）或 camelCase（工具类）
- 变量和函数使用 camelCase

### 导入规范
- 使用 `@/` 别名代替相对路径
- 按类别组织导入（Vue、组件、工具、样式）

## 🔄 更新和维护

### 依赖更新
定期检查并更新依赖版本：
```bash
npm outdated
npm update
```

### 版本锁定
项目使用 `package-lock.json` 锁定依赖版本，确保团队环境一致性。

## 📚 相关文档

- [Vue 3 官方文档](https://cn.vuejs.org/)
- [Element Plus 官方文档](https://element-plus.org/zh-CN/)
- [Vite 官方文档](https://cn.vitejs.dev/)
- [Pinia 官方文档](https://pinia.vuejs.org/zh/)
- [Vue Router 官方文档](https://router.vuejs.org/zh/)

---

**最后更新时间**: 2024年
**维护者**: 开发团队