# VeloAdmin

**Repository Path**: sudong1989/comfreamwork

## Basic Information

- **Project Name**: VeloAdmin
- **Description**: 基于vue + nestJs的通用框架
- **Primary Language**: NodeJS
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-27
- **Last Updated**: 2026-05-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# VeloAdmin 通用框架

## 项目简介

VeloAdmin 是一个基于 **Vue3 + NestJS** 的通用后台管理框架，采用前后端分离架构设计。框架集成了业界主流的技术栈和最佳实践，旨在为开发者提供一个功能完善、易于扩展的企业级后台管理解决方案。

项目采用 MIT 开源许可证，可免费用于个人和商业项目。

## 技术栈概览

### 前端技术栈

| 技术 | 说明 | 版本 |
|------|------|------|
| Vue | 渐进式JavaScript框架 | 3.5+ |
| TypeScript | JavaScript超集，提供类型检查 | 5.8+ |
| Vite | 下一代前端构建工具 | 7.0+ |
| Pinia | Vue3 官方推荐状态管理方案 | 3.0+ |
| Vue Router | Vue官方路由管理器 | 4.5+ |
| Element Plus | 基于Vue3的组件库 | 2.10+ |
| UnoCSS | 原子化CSS引擎 | 66.4+ |
| Axios | HTTP请求库 | 1.10+ |

### 后端技术栈

| 技术 | 说明 | 版本 |
|------|------|------|
| NestJS | 基于TypeScript的企业级Node.js框架 | 11+ |
| TypeORM | 强大的TypeScript ORM | 0.3+ |
| MySQL | 关系型数据库 | 8.0+ |
| JWT | JSON Web Token 身份认证 | 11+ |
| Passport | Node.js身份认证中间件 | 0.7+ |
| Swagger | API文档生成工具 | 11+ |
| bcrypt | 密码加密库 | 6.0+ |

## 项目结构

```
freamwork/
├── database/                 # 数据库脚本和SQL文件
│   └── freamwork.sql        # 完整数据库结构定义
├── doc/                     # 项目文档目录
├── server/                  # 后端项目（NestJS）
│   ├── src/
│   │   ├── common/          # 公共模块（装饰器、过滤器、守卫、拦截器）
│   │   ├── config/          # 配置文件（多环境配置）
│   │   ├── modules/         # 业务模块
│   │   │   ├── auth/        # 认证模块
│   │   │   ├── user/        # 用户模块
│   │   │   ├── rbac/        # 权限模块（角色、权限）
│   │   │   ├── dept/        # 部门模块
│   │   │   ├── post/        # 岗位模块
│   │   │   ├── dict/        # 字典模块
│   │   │   ├── config/      # 系统配置模块
│   │   │   └── file/        # 文件管理模块
│   │   ├── shared/          # 共享工具和类型
│   │   ├── app.module.ts   # 根模块
│   │   └── main.ts          # 应用入口
│   ├── test/                # 测试文件
│   ├── uploads/             # 文件上传目录
│   └── package.json
└── web/                     # 前端项目（Vue3）
    ├── src/
    │   ├── api/             # API接口封装
    │   ├── assets/          # 静态资源
    │   ├── components/      # 通用组件
    │   │   ├── crud-manager/       # CRUD管理器
    │   │   ├── dict-select/        # 字典选择器
    │   │   ├── dict-tag/          # 字典标签
    │   │   ├── dynamic-form/       # 动态表单
    │   │   ├── dynamic-table/      # 动态表格
    │   │   ├── filter-form/       # 筛选表单
    │   │   └── theme-switch/       # 主题切换
    │   ├── layouts/         # 布局组件
    │   ├── router/          # 路由配置
    │   ├── stores/          # Pinia状态管理
    │   ├── types/           # TypeScript类型定义
    │   ├── utils/          # 工具函数
    │   ├── views/          # 页面视图
    │   ├── App.vue         # 根组件
    │   └── main.ts         # 应用入口
    └── package.json
```

## 核心功能特性

### 1. 认证授权系统

- **JWT双令牌机制**：访问令牌（Access Token）+ 刷新令牌（Refresh Token）
- **登录失败锁定**：连续多次登录失败后自动锁定账户
- **单设备登录支持**：通过缓存管理刷新令牌实现
- **细粒度权限控制**：基于RBAC模型，支持菜单权限和API权限

### 2. RBAC权限管理

- **角色管理**：创建、编辑、删除、分配权限
- **权限管理**：树形权限结构，支持菜单、API、按钮三种权限类型
- **用户角色分配**：支持多角色分配
- **动态路由生成**：根据用户权限动态生成菜单和路由

### 3. 通用组件库

#### DynamicTable 动态表格

功能强大的数据表格组件，支持：

- 列配置化：类型、宽度、对齐方式、排序等
- 行内编辑：支持多种编辑器类型
- 格式化渲染：支持枚举、布尔值、JSON等格式化
- 自定义模板：支持自定义列渲染
- 分页控制：内置分页组件
- 工具栏配置：可自定义工具栏按钮

#### DynamicForm 动态表单

灵活的表单生成组件，支持：

- 多种字段类型：输入框、选择器、日期、文件上传等
- 联动字段：字段之间可以设置联动关系
- 动态选项：支持从API或函数获取选项
- 表单验证：内置常用验证规则，支持自定义验证
- 自定义模板：支持插入自定义组件

#### FilterForm 筛选表单

高级筛选表单组件，支持：

- 条件组合：AND/OR 条件组合
- 多种操作符：等于、不等于、模糊匹配、范围查询等
- 动态字段：可根据配置动态生成筛选条件

#### DictSelect / DictTag 字典组件

字典数据专用组件：

- DictSelect：字典下拉选择器
- DictTag：字典标签展示，自动匹配颜色

### 4. 状态管理

使用 Pinia 进行状态管理，包含以下核心Store：

- **useUserStore**：用户状态、Token、登录登出
- **useMenuStore**：动态菜单、标签页管理
- **useConfigStore**：系统配置缓存
- **useThemeStore**：主题配置

### 5. 请求封装

基于 Axios 封装的请求模块，提供：

- 自动Token注入
- 统一错误处理
- Token自动刷新
- 请求重试机制
- 登录过期自动跳转

### 6. 系统模块

| 模块 | 功能说明 |
|------|----------|
| 用户管理 | 用户CRUD、状态管理、角色分配 |
| 角色管理 | 角色CRUD、权限分配 |
| 权限管理 | 菜单权限、API权限、按钮权限 |
| 部门管理 | 树形部门结构管理 |
| 岗位管理 | 岗位CRUD |
| 字典管理 | 字典类型和字典数据管理 |
| 系统配置 | 键值对配置管理 |
| 文件管理 | 文件上传、下载、管理 |

## 数据库设计

框架采用标准的RBAC数据库设计，包含以下核心表：

| 表名 | 说明 |
|------|------|
| sys_user | 用户表 |
| sys_role | 角色表 |
| sys_permission | 权限表 |
| sys_user_role | 用户角色关联表 |
| sys_role_permission | 角色权限关联表 |
| sys_dept | 部门表 |
| sys_post | 岗位表 |
| sys_dict_type | 字典类型表 |
| sys_dict_data | 字典数据表 |
| sys_config | 系统配置表 |
| sys_files | 文件表 |
| sys_audit_logs | 审计日志表 |

## 环境配置

### 前端环境变量

```env
VITE_API_BASE_URL=http://localhost:3000/api
```

### 后端环境变量

```env
NODE_ENV=development
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=freamwork
DB_PASSWORD=123456
DB_DATABASE=freamwork
JWT_SECRET=your_jwt_secret
```

## 快速开始

### 环境要求

- Node.js >= 18
- MySQL >= 8.0
- pnpm / npm / yarn

### 安装步骤

```bash
# 克隆项目
git clone <repository-url>
cd freamwork

# 安装后端依赖
cd server
pnpm install

# 安装前端依赖
cd ../web
pnpm install
```

### 启动服务

```bash
# 启动后端（开发模式）
cd server
pnpm run start:dev

# 启动前端（开发模式）
cd web
pnpm run dev
```

### 访问应用

- 前端地址：http://localhost:5173
- 后端API地址：http://localhost:3000/api
- Swagger文档：http://localhost:3000/api-docs

## 开发指南

详细开发指南请参考各模块文档：

- [前端开发指南](./doc/guides/frontend.md)
- [后端开发指南](./doc/guides/backend.md)
- [组件使用文档](./doc/guides/components.md)
- [API接口文档](./doc/guides/api.md)

## 技术亮点

1. **TypeScript类型安全**：全项目TypeScript编写，提供完整的类型定义
2. **动态权限系统**：基于数据库的动态权限和路由，权限变更无需重启
3. **通用CRUD封装**：通过动态表格和动态表单，大幅提升开发效率
4. **响应式主题**：支持亮色/暗色主题切换
5. **多环境配置**：开发、测试、生产环境配置分离
6. **安全防护**：登录锁定、密码加密、JWT安全策略
7. **API文档**：集成Swagger，自动生成API文档

## 开源协议

MIT License - 详见 LICENSE 文件

## 贡献指南

欢迎提交Issue和Pull Request帮助改进项目。

## 联系方式

如有问题，请通过GitHub Issues提交。