# webTemplate

**Repository Path**: whenTheMorningDark/web-template

## Basic Information

- **Project Name**: webTemplate
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-23
- **Last Updated**: 2026-02-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# web-template

基于 Vue 3 + NestJS 的全栈后台管理系统

## 项目简介

web-template 是一个现代化的全栈后台管理系统前端模板，采用了业界主流的技术栈进行构建。前端基于 Vue 3、Vite、Ant Design Vue，后端基于 NestJS、TypeORM，支持 RESTful API 和 WebSocket 通信，具备完整的权限认证、RBAC 角色权限、数据分页、任务调度等功能。

## 技术栈

### 前端 (web-admin)
- **框架**: Vue 3 + Composition API
- **构建工具**: Vite 5.x
- **UI 组件库**: Ant Design Vue 4.x
- **状态管理**: Pinia
- **路由**: Vue Router 4
- **国际化**: vue-i18n
- **样式方案**: Less + CSS Modules
- **代码规范**: ESLint + Prettier
- **提交规范**: Commitlint + Husky

### 后端 (web-api)
- **框架**: NestJS 10.x
- **数据库**: TypeORM + MySQL
- **缓存**: Redis
- **任务调度**: Bull + Redis
- **API 文档**: Swagger/OpenAPI
- **WebSocket**: Socket.io
- **消息推送**: SSE (Server-Sent Events)

## 功能特性

### 前端功能
- 🏗️ **完善的目录结构**: 基础组件、业务组件、核心组件分层组织
- 🎨 **深色主题支持**: 内置主题切换功能
- 🌐 **国际化支持**: 中英文切换，开箱即用
- 🔐 **权限控制**: 基于角色的访问控制 (RBAC)
- 📱 **响应式布局**: 适配多种屏幕尺寸
- 📊 **动态表格**: 强大的数据表格组件，支持排序、筛选、导出
- 📝 **动态表单**: 灵活的表单配置，支持异步数据获取
- 🖼️ **文件预览**: 支持多种文件格式在线预览
- 📋 **标签页管理**: 多标签页切换与状态保持
- 🔔 **锁屏功能**: 多种锁屏样式可选

### 后端功能
- 🔐 **JWT 认证**: 支持 Access Token 和 Refresh Token 双令牌机制
- 👥 **用户管理**: 完整的用户 CRUD 操作
- 🏢 **部门管理**: 组织架构管理
- 🔑 **角色管理**: 角色权限分配
- 📋 **菜单管理**: 动态路由菜单生成
- 📧 **邮件服务**: 邮件发送与模板支持
- 💾 **文件存储**: 本地存储和 OSS 对象存储支持
- 📤 **文件上传**: 大文件分片上传
- 📊 **系统监控**: 在线用户、服务状态监控
- 📝 **操作日志**: 登录日志、任务日志记录
- ⏰ **任务调度**: 定时任务管理
- 🔄 **数据缓存**: Redis 缓存支持
- 🔁 **幂等控制**: 请求幂等性保证
- 📡 **WebSocket**: 实时通信支持
- 📩 **SSE 推送**: 服务端事件推送

## 项目结构

```
web-template/
├── web-admin/                 # 前端项目
│   ├── public/               # 静态资源
│   ├── src/
│   │   ├── api/             # API 接口定义
│   │   ├── assets/          # 资源文件
│   │   ├── components/      # 组件
│   │   │   ├── basic/       # 基础组件
│   │   │   ├── business/    # 业务组件
│   │   │   └── core/        # 核心组件
│   │   ├── constants/       # 常量定义
│   │   ├── enums/           # 枚举类型
│   │   ├── hooks/           # 组合式函数
│   │   ├── layouts/         # 布局组件
│   │   ├── locales/         # 国际化资源
│   │   ├── plugins/         # 插件配置
│   │   ├── router/          # 路由配置
│   │   ├── store/           # Pinia 状态管理
│   │   ├── styles/          # 样式文件
│   │   ├── utils/           # 工具函数
│   │   └── views/           # 页面视图
│   ├── packages/            # 自定义包
│   │   ├── vite-plugin-http2-proxy/
│   │   ├── vite-plugin-msw/
│   │   └── vite-plugin-tinymce-resource/
│   └── types/               # TypeScript 类型定义
│
└── web-api/                  # 后端项目
    ├── src/
    │   ├── common/          # 公共模块
    │   │   ├── adapters/    # 适配器
    │   │   ├── decorators/  # 自定义装饰器
    │   │   ├── dto/         # 数据传输对象
    │   │   ├── entities/    # 实体类
    │   │   ├── exceptions/  # 异常处理
    │   │   ├── filters/     # 过滤器
    │   │   ├── interceptors/# 拦截器
    │   │   ├── model/       # 数据模型
    │   │   └── pipes/       # 管道
    │   ├── config/          # 配置文件
    │   ├── constants/       # 常量定义
    │   ├── global/          # 全局配置
    │   ├── helper/          # 辅助函数
    │   ├── migrations/      # 数据库迁移
    │   ├── modules/         # 功能模块
    │   │   ├── auth/        # 认证模块
    │   │   ├── health/      # 健康检查
    │   │   ├── netdisk/     # 网盘管理
    │   │   ├── sse/         # SSE 推送
    │   │   ├── system/      # 系统管理
    │   │   ├── tasks/       # 任务调度
    │   │   ├── todo/        # 待办事项
    │   │   ├── tools/       # 工具模块
    │   │   └── user/        # 用户模块
    │   ├── shared/          # 共享模块
    │   │   ├── database/    # 数据库
    │   │   ├── helper/      # 辅助服务
    │   │   ├── logger/      # 日志服务
    │   │   ├── mailer/      # 邮件服务
    │   │   └── redis/       # Redis 服务
    │   ├── socket/          # WebSocket
    │   └── utils/           # 工具函数
    ├── deploy/              # 部署配置
    └── scripts/             # 脚本文件
```

## 环境要求

### 前端
- Node.js 18.x 或更高版本
- pnpm 8.x 或更高版本

### 后端
- Node.js 18.x 或更高版本
- MySQL 8.0 或更高版本
- Redis 6.x 或更高版本
- pnpm 8.x 或更高版本

## 快速开始

### 1. 克隆项目

```bash
git clone https://gitee.com/whenTheMorningDark/web-template.git
cd web-template
```

### 2. 安装依赖

```bash
# 安装前端依赖
cd web-admin
pnpm install

# 安装后端依赖
cd ../web-api
pnpm install
```

### 3. 配置环境变量

```bash
# 前端配置
cd web-admin
cp .env.example .env.development
# 编辑 .env.development 配置开发环境变量

# 后端配置
cd ../web-api
cp .env.example .env.development
# 编辑 .env.development 配置开发环境变量
```

### 4. 初始化数据库

```bash
# 执行数据库迁移
cd web-api
pnpm migration:run

# 或者导入初始化 SQL 文件
# mysql -u root -p < deploy/sql/nest_admin.sql
```

### 5. 启动项目

#### 开发模式

```bash
# 启动前端 (web-admin)
cd web-admin
pnpm dev

# 启动后端 (web-api)
cd web-api
pnpm start:dev
```

#### 生产模式

```bash
# 构建前端
cd web-admin
pnpm build

# 启动后端
cd web-api
pnpm build
pnpm start:prod
```

## Docker 部署

### 使用 Docker Compose

```bash
# 开发环境
docker-compose -f docker-compose.yml up -d

# 生产环境
docker-compose -f docker-compose.prod.yml up -d
```

### 手动构建

```bash
# 构建前端镜像
cd web-admin
docker build -t web-admin:latest .

# 构建后端镜像
cd ../web-api
docker build -t web-api:latest .
```

## API 文档

后端服务启动后，可通过以下地址访问 Swagger API 文档：

```
http://localhost:7001/api
```

## 默认账号

项目初始化后，可使用以下账号登录：

- **管理员账号**: admin / 123456
- **测试账号**: test / 123456

> ⚠️ **安全提示**: 请在生产环境中及时修改默认密码！

## 核心组件说明

### DynamicTable (动态表格)

支持列配置、排序、筛选、分页、导出等功能的强大表格组件。

```vue
<template>
  <DynamicTable :columns="columns" :api="getList" />
</template>

<script setup>
import { DynamicTable } from '@/components/core/dynamic-table';

const columns = [
  { title: '姓名', dataIndex: 'name' },
  { title: '年龄', dataIndex: 'age' },
];

const getList = (params) => api.getUserList(params);
</script>
```

### SchemaForm (动态表单)

基于 JSON Schema 的动态表单组件，支持多种表单项类型。

```vue
<template>
  <SchemaForm :schema="schema" @submit="handleSubmit" />
</template>

<script setup>
import { SchemaForm } from '@/components/core/schema-form';

const schema = [
  {
    field: 'username',
    label: '用户名',
    component: 'Input',
  },
  {
    field: 'password',
    label: '密码',
    component: 'InputPassword',
  },
];
</script>
```

## 提交规范

本项目使用 Commitlint 规范提交信息：

```
feat: 新功能
fix: 修复 Bug
docs: 文档更新
style: 代码格式调整
refactor: 重构代码
perf: 性能优化
test: 单元测试
chore: 构建配置更新
```

## 浏览器支持

| 浏览器 | 支持版本 |
|--------|----------|
| Chrome | >= 90 |
| Firefox | >= 88 |
| Safari | >= 14 |
| Edge | >= 90 |

## 许可证

本项目基于 MIT 协议开源。

## 贡献指南

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

## 相关资源

- [Vue 3 文档](https://vuejs.org/)
- [Ant Design Vue](https://antdv.com/)
- [NestJS 文档](https://nestjs.com/)
- [TypeORM 文档](https://typeorm.io/)

## 致谢

感谢以下开源项目：

- [Vue](https://vuejs.org/)
- [Ant Design Vue](https://antdv.com/)
- [NestJS](https://nestjs.com/)
- [Vite](https://vitejs.dev/)
- [TypeORM](https://typeorm.io/)
- [Pinia](https://pinia.vuejs.org/)
- [ulog](https://github.com/unawesome/ulog)