cz-hjjc-ht/TECH_STACK.md

# 技术栈文档

## 项目概述

**项目名称**：内控管理系统（cz-hjjc-ht）  
**项目版本**：4.4.0  
**基础模板**：vue-admin-template  
**开发端口**：9530

## 核心技术栈

### 前端框架
- **Vue.js**: `2.6.10`
  - 渐进式 JavaScript 框架
  - 使用 Options API
  - 支持 Composition API（通过 @vue/composition-api）

### UI 组件库
- **Element UI**: `2.13.2`
  - 基于 Vue 2.0 的桌面端组件库
  - 主要 UI 组件来源
  - 提供完整的组件生态

- **View Design (iView)**: `4.7.0`
  - 企业级 UI 组件库
  - 作为 Element UI 的补充组件

### 状态管理
- **Vuex**: `3.1.0`
  - 集中式状态管理
  - 支持模块化 store 结构
  - 主要模块：app、permission、settings、user

- **vuex-persistedstate**: `^4.1.0`
  - Vuex 状态持久化插件
  - 将状态保存到 localStorage

### 路由管理
- **Vue Router**: `3.0.6`
  - 官方路由管理器
  - 支持动态路由、权限控制
  - 路由懒加载优化

### HTTP 客户端
- **Axios**: `0.18.1`
  - 基于 Promise 的 HTTP 库
  - 支持请求/响应拦截器
  - 统一错误处理和加载状态管理
  - Bearer Token 认证

### 构建工具
- **Vue CLI**: `4.4.4`
  - 官方脚手架工具
  - 基于 Webpack 的构建配置
  - 开发服务器、热更新支持

### CSS 预处理器
- **Less**: `^3.13.1`
  - CSS 预处理器
  - less-loader `^5.0.0`

- **Sass/SCSS**: `1.26.8`
  - CSS 预处理器
  - sass-loader `8.0.2`

### 图表与可视化
- **ECharts**: `^5.0.0`
  - 数据可视化图表库
  - 用于仪表盘和报表展示
  - 支持多种图表类型

### 文档处理
- **@vue-office/docx**: `^1.6.2`
  - Word 文档预览组件

- **@vue-office/excel**: `^1.7.11`
  - Excel 文档预览组件

- **@vue-office/pdf**: `^2.0.2`
  - PDF 文档预览组件

- **docx-preview**: `^0.3.2`
  - Word 文档预览库

### 富文本编辑器
- **wangeditor**: `^4.7.12`
  - 轻量级富文本编辑器
  - 支持 Markdown

### 工具库
- **moment**: `^2.29.4`
  - 日期时间处理库
  - 通过 `Vue.prototype.$moment` 全局使用

- **js-cookie**: `2.2.0`
  - Cookie 操作工具
  - 用于 Token 存储

- **path-to-regexp**: `2.4.0`
  - 路径匹配工具
  - 路由匹配支持

- **nprogress**: `0.2.0`
  - 页面加载进度条
  - 提升用户体验

- **normalize.css**: `7.0.0`
  - CSS 重置样式
  - 统一浏览器默认样式

### 其他功能库
- **vue-grid-layout**: `^2.4.0`
  - 网格布局组件
  - 支持拖拽和调整大小
  - 用于仪表盘布局

- **html2canvas**: `^1.4.1`
  - HTML 转 Canvas 工具
  - 用于截图功能

- **print-js**: `^1.6.0`
  - 打印功能库
  - 支持 HTML、PDF、图片打印

- **element-resize-detector**: `^1.2.4`
  - 元素尺寸监听工具
  - 用于响应式布局

- **@vue/composition-api**: `^1.7.2`
  - Composition API 支持（Vue 2）
  - 为 Vue 3 迁移做准备

- **vue-demi**: `^0.14.6`
  - 兼容 Vue 2/3 的工具库

### 微前端支持
- **Wujie（无界）**
  - 支持微前端架构
  - 可在 iframe 中运行
  - 支持生命周期管理（MOUNT/UNMOUNT）
  - 支持独立运行模式和嵌入模式

### 核心依赖
- **core-js**: `3.6.5`
  - JavaScript 标准库 polyfill
  - 提供 ES6+ 特性支持

## 开发工具

### 代码规范
- **ESLint**: `6.7.2`
  - 代码质量检查工具
  - 支持 Vue 文件检查（eslint-plugin-vue 6.2.2）
  - 使用 babel-eslint `^8.2.2` 作为解析器

### 测试框架
- **Jest**: 通过 `@vue/cli-plugin-unit-jest`
  - 单元测试框架
  - 使用 @vue/test-utils `1.0.0-beta.29`
  - babel-jest `23.6.0` 用于转译

### 编译工具
- **Babel**
  - @vue/cli-plugin-babel `4.4.4`
  - babel-plugin-dynamic-import-node `2.3.3`
  - 开发环境动态导入优化

### 构建优化
- **SVG 处理**
  - svg-sprite-loader `4.1.3` - SVG 图标精灵图
  - svgo `1.2.2` - SVG 优化工具

- **代码分割**
  - chunk-libs: 第三方库分离
  - chunk-elementUI: Element UI 单独打包
  - chunk-commons: 公共组件分离（最小引用 3 次）
  - runtime chunk: 运行时代码分离

- **构建优化插件**
  - script-ext-html-webpack-plugin `2.1.3` - 内联运行时脚本

### Mock 数据
- **mockjs**: `1.0.1-beta3`
  - 生成随机数据
  - 拦截 Ajax 请求
  - 用于开发环境数据模拟

### 其他开发工具
- **chalk**: `2.4.2` - 终端颜色输出
- **runjs**: `4.3.2` - 脚本运行工具
- **connect**: `3.6.6` - HTTP 服务器
- **serve-static**: `1.13.2` - 静态文件服务

## 项目配置

### 开发服务器
- **端口**：9530（默认）
- **自动打开浏览器**：是
- **热更新**：支持
- **代理配置**：支持多个 API 代理
  - `/old` -> 旧版系统
  - `/oa` -> OA 系统
  - 主 API -> `VUE_APP_BASE_API`

### 环境变量
- `VUE_APP_MODULE_NAME`: 模块名称（用于路由和构建路径）
- `VUE_APP_BASE_API`: API 基础路径
- `VUE_APP_OUT_URL`: 外部系统 URL
- `VUE_APP_OUT_OLD`: 旧版外部系统 URL

### 路径别名
- `@`: 指向 `src` 目录

### 浏览器兼容性
- 支持所有市场份额 > 1% 的浏览器
- 最后两个版本
- 现代浏览器和 IE 10+

## 项目结构特点

### 权限控制
- **基于角色的权限管理（RBAC）**
- **路由级别权限控制**
- **动态路由生成**
- **按钮级别权限控制**

### 多模式支持
- **独立运行模式**：直接访问应用
- **iframe 嵌入模式**：嵌入到其他系统中
- **微前端（Wujie）模式**：作为微前端子应用

### 错误处理
- **全局错误捕获**：Vue.config.errorHandler
- **iframe 环境错误上报**：向父窗口上报错误
- **Axios 请求错误统一处理**：统一错误提示和处理

### 自定义组件
- **LxHeader**: 自定义头部组件
- **XyTable**: 自定义表格组件
- **XyDialog**: 自定义对话框组件
- **XySelectors**: 自定义选择器组件
- **PlanPicker**: 计划选择器组件
- **Breadcrumb**: 面包屑导航
- **Pagination**: 分页组件

## 主要功能模块

根据项目结构，主要包含以下业务模块：

1. **预算管理** (budget)
   - 预算编制、审核、执行
   - 预算汇总、上报
   - 预算目标管理

2. **合同管理** (contract)
   - 合同列表、详情
   - 合同签订
   - 合同集成

3. **绩效管理** (achievements)
   - 评价管理
   - 积分管理
   - 类型管理

4. **部门进度** (departmentProgress)
   - 部门工作进度跟踪

5. **财务管理** (finance)
   - 收支管理
   - 资金登记

6. **系统管理** (system/sysManage)
   - 用户管理
   - 角色管理
   - 权限管理
   - 菜单管理
   - 字典管理
   - 日志管理

7. **仪表盘** (dashboard)
   - 数据可视化
   - 通知公告

8. **其他功能**
   - 请假管理 (away)
   - 借阅管理 (borrow)
   - 安装部署 (install)
   - 预览功能 (preview)
   - 统计报表 (statisticalReport)

## 运行环境要求

- **Node.js**: >= 8.9
- **npm**: >= 3.0.0

## 常用命令

```bash
# 开发环境
npm run dev

# 生产环境构建
npm run build:prod

# 预发布环境构建
npm run build:stage

# 预览构建结果
npm run preview

# 代码检查
npm run lint

# 单元测试
npm run test:unit

# 代码检查和测试
npm run test:ci

# SVG 优化
npm run svgo
```

## 技术栈版本总结

| 分类 | 技术 | 版本 |
|------|------|------|
| 前端框架 | Vue | 2.6.10 |
| UI 库 | Element UI | 2.13.2 |
| UI 库 | View Design | 4.7.0 |
| 状态管理 | Vuex | 3.1.0 |
| 路由 | Vue Router | 3.0.6 |
| HTTP | Axios | 0.18.1 |
| 构建工具 | Vue CLI | 4.4.4 |
| CSS 预处理器 | Less | ^3.13.1 |
| CSS 预处理器 | Sass | 1.26.8 |
| 图表库 | ECharts | ^5.0.0 |
| 日期处理 | moment | ^2.29.4 |
| 富文本编辑器 | wangeditor | ^4.7.12 |
| 测试框架 | Jest | - |
| 代码规范 | ESLint | 6.7.2 |
| 微前端 | Wujie | - |

## 技术栈特点

### 优势
1. **成熟稳定**：基于 Vue 2 + Element UI 的成熟方案
2. **功能完整**：包含完整的后台管理系统功能
3. **多模式支持**：支持独立运行、iframe、微前端多种部署方式
4. **权限完善**：完整的权限控制系统
5. **文档支持**：支持 Office 文档预览

### 注意事项
1. **Axios 版本较旧**：当前使用 0.18.1，建议升级到最新版本以获得更好的安全性和功能支持
2. **Vue 2 项目**：项目基于 Vue 2.6，如需升级到 Vue 3，需要大量重构工作
3. **微前端兼容**：项目支持多种运行模式，在修改入口文件时需要确保兼容性
4. **生产环境构建**：构建产物输出到 `../cz_hjjc/public/${VUE_APP_MODULE_NAME}`，需要配置相应的环境变量
5. **依赖更新**：部分依赖版本较旧，建议定期更新以获取安全补丁

## 项目构建输出

- **输出目录**：`../cz_hjjc/public/${VUE_APP_MODULE_NAME}`
- **静态资源目录**：`static`
- **源码映射**：生产环境关闭（productionSourceMap: false）

---

*文档生成时间：基于 package.json 和项目结构分析*  
*项目路径：/Users/weizongsong/www/cz-hjjc-ht*