# admin-starter

**Repository Path**: lang9076/admin-starter

## Basic Information

- **Project Name**: admin-starter
- **Description**: 后台起步模板
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-02
- **Last Updated**: 2026-06-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Vue 3 + TypeScript + Vite 后台管理系统

一个基于 Vue 3 + TypeScript + Vite 的前后端分离后台管理系统，包含完整的 RBAC 权限管理功能。

## ✨ 功能特性

- 🔐 **RBAC 权限管理** - 用户、角色、部门、菜单的完整权限控制
- 🎨 **现代化 UI** - 基于 Ant Design Vue 的精美界面
- 🌙 **暗黑模式** - 支持亮色/暗色主题切换
- 🌍 **国际化** - 中英文双语切换（i18n）
- 📐 **拼图滑块验证** - 登录安全验证
- ⚡ **高性能** - Vite 构建，快速冷启动和热更新
- 📱 **响应式设计** - 适配各种屏幕尺寸
- 🔧 **TypeScript** - 完整的类型支持
- 🚀 **服务管理** - 一键启停前后端服务

## 🛠️ 技术栈

### 前端

| 技术 | 版本 | 说明 |
|------|------|------|
| Vue | 3.5.34 | 渐进式 JavaScript 框架 |
| TypeScript | ~6.0.2 | 类型安全的 JavaScript 超集 |
| Vite | 8.0.12 | 下一代前端构建工具 |
| Vue Router | 5.0.7 | 官方路由管理器 |
| Pinia | 3.0.4 | 状态管理库 |
| Ant Design Vue | 4.2.6 | UI 组件库 |
| Axios | 1.16.1 | HTTP 客户端 |
| Vue I18n | - | 国际化方案 |
| Tailwind CSS | 3.4.19 | 原子化 CSS 框架 |
| Dayjs | 1.11.20 | 日期处理库 |
| Less | - | CSS 预处理器 |

### 后端

| 技术 | 版本 | 说明 |
|------|------|------|
| Koa2 | 2.15.0 | Node.js Web 框架 |
| TypeScript | ^5.4.5 | 类型系统 |
| Sequelize | 6.37.3 | ORM 框架 |
| MySQL2 | 3.9.7 | MySQL 驱动 |
| JWT | 9.0.2 | 身份认证 |
| Bcryptjs | 2.4.3 | 密码加密 |

## 📁 项目结构

```
vue3-ts-vite/
├── 📁 public/                  # 静态资源
├── 📁 service/                 # 后端服务
│   ├── db/init.sql             # 数据库初始化脚本
│   ├── src/
│   │   ├── config/             # 配置文件
│   │   ├── controllers/        # 控制器层
│   │   ├── models/             # 数据模型层
│   │   ├── routes/             # 路由配置
│   │   └── services/           # 业务逻辑层
│   └── package.json
├── 📁 scripts/                 # 脚本工具
│   └── manage-services.js      # 服务管理脚本
├── 📁 src/                     # 前端源码
│   ├── api/                    # API 接口封装
│   ├── components/             # 公共组件
│   ├── plugins/                # 插件注册
│   ├── router/                 # 路由配置
│   ├── store/                  # 状态管理
│   ├── style/                  # 样式文件
│   └── views/                  # 页面视图
├── .env                        # 环境变量
├── package.json
├── vite.config.ts
└── README.md
```

## 🚀 快速开始

### 环境要求

- Node.js >= 18.0.0
- pnpm >= 8.0.0
- MySQL >= 8.0

### 安装依赖

```bash
# 安装前端依赖
pnpm install

# 安装后端依赖
cd service && pnpm install
```

### 数据库配置

1. 创建数据库
```bash
mysql -u root -p < service/db/init.sql
```

2. 配置数据库连接
编辑 `service/src/config/db.ts`，修改数据库连接信息：
```typescript
const sequelize = new Sequelize('system_db', 'root', 'your_password', {
  host: 'localhost',
  dialect: 'mysql',
  // ...
})
```

### 启动服务

```bash
# 查看服务状态
pnpm status

# 启动前后端服务
pnpm start

# 停止服务
pnpm stop

# 重启服务
pnpm restart
```

服务启动后：
- 前端: http://localhost:5173
- 后端: http://localhost:3000

### 默认账号

- **用户名**: `admin`
- **密码**: `123456`

## 📋 可用命令

### 根目录命令

| 命令 | 说明 |
|------|------|
| `pnpm start` | 启动前后端服务 |
| `pnpm stop` | 停止前后端服务 |
| `pnpm restart` | 重启前后端服务 |
| `pnpm status` | 查看服务状态 |
| `pnpm dev` | 仅启动前端开发服务器 |
| `pnpm dev:all` | 同时启动前后端（并发模式） |
| `pnpm dev:service` | 仅启动后端服务 |
| `pnpm build` | 构建前端生产包 |
| `pnpm build:service` | 构建后端服务 |
| `pnpm lint` | 运行 ESLint 检查 |
| `pnpm lint:fix` | 自动修复 ESLint 错误 |
| `pnpm format` | 格式化代码 |

### 后端目录命令 (service/)

| 命令 | 说明 |
|------|------|
| `pnpm dev` | 开发模式启动（热重载） |
| `pnpm build` | 编译 TypeScript |
| `pnpm start` | 生产模式启动 |

## 🔧 配置说明

### 环境变量 (.env)

```env
# 是否启动后端服务 (true/false)
VITE_START_BACKEND=true

# API 基础地址
VITE_APP_BASE_API=http://localhost:3000/api
```

### Vite 配置

路径别名：
- `@` → `./src`
- `@service` → `./service/src`

自动导入：
- Vue 相关 API（ref、reactive、onMounted 等）
- Vue Router API
- Pinia API
- `src/components` 下的自定义组件

## 📦 功能模块

### 1. 登录认证
- 拼图滑块验证码
- 登录加载动画（字符跳动效果）
- 记住密码功能（跟随主题色）
- JWT Token 认证

### 2. 用户管理
- 用户的增删改查
- 用户状态管理（启用/禁用）
- 密码重置
- 用户头像支持

### 3. 角色管理
- 角色的增删改查
- 角色权限分配
- 角色状态管理

### 4. 部门管理
- 部门的增删改查
- 树形结构展示
- 部门负责人设置

### 5. 菜单管理
- 菜单的增删改查
- 权限标识配置
- 菜单类型（目录/菜单/按钮）
- 图标选择

### 6. 操作日志
- 系统操作记录
- 日志查询和导出

### 7. 个人中心
- 个人信息查看与编辑
- 密码修改
- 用户下拉菜单快捷入口

### 8. 异常页面
- 404 页面（渐变数字 + 轨道动画）
- 500 页面（科技感网格 + 脉冲动画）

### 9. 系统功能
- 亮色/暗色主题切换
- 中英文国际化切换
- 面包屑导航
- 侧边栏折叠

## 🔐 权限系统

系统采用 RBAC（基于角色的访问控制）模型：

- **用户** - 系统使用者
- **角色** - 权限的集合
- **部门** - 组织架构
- **菜单** - 功能权限的载体

权限标识格式：`模块:功能:操作`

示例：
- `system:user:list` - 查看用户列表
- `system:user:create` - 创建用户
- `system:user:update` - 更新用户
- `system:user:delete` - 删除用户

## 📝 开发规范

### 代码风格

- 使用 ESLint + Prettier 进行代码检查和格式化
- 遵循 Vue 3 组合式 API 规范
- 使用 TypeScript 严格模式

### 提交规范

```
feat: 新功能
fix: 修复问题
docs: 文档更新
style: 代码格式调整
refactor: 代码重构
test: 测试相关
chore: 构建/工具相关
```

## 🐛 常见问题

### 1. 端口被占用

```bash
# 查看端口占用情况
pnpm status

# 停止占用端口的服务
pnpm stop
```

### 2. 数据库连接失败

- 检查 MySQL 服务是否启动
- 检查数据库配置是否正确
- 检查数据库用户权限

### 3. 依赖安装失败

```bash
# 清除缓存后重新安装
pnpm store prune
pnpm install
```

## 📄 许可证

[MIT](LICENSE)

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

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

---

**Happy Coding!** 🎉