# admin-starter

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

## Basic Information

- **Project Name**: admin-starter
- **Description**: 通用后台管理系统基础模板。剥离业务逻辑，保留核心架构，新项目可直接 clone 此仓库快速起步。
- **Primary Language**: Python
- **License**: MPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-06
- **Last Updated**: 2026-08-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# admin-starter

> 通用后台管理系统基础模板 · FastAPI + Vue 3

剥离具体业务逻辑，保留核心架构（认证授权、RBAC 权限、用户/角色/菜单/日志管理、动态路由），新项目可直接 clone 本仓库快速起步。

## 功能特性

### 后端（api/）

- **认证授权**：JWT 登录认证、注册、修改密码、退出登录，RBAC 角色权限控制（管理员 / 普通用户）；
- **密码安全**：前端 RSA 公钥加密密码传输，后端 BCrypt 哈希存储；
- **用户管理**：分页列表、新增/修改/删除/批量删除、启停用、重置密码、分配角色、个人资料与布局偏好；
- **角色管理**：分页列表、新增/修改/删除/批量删除、启停用、菜单权限分配；
- **菜单管理**：菜单树、新增/修改/删除/批量删除、启停用，菜单数据驱动前端动态路由与导航；
- **日志管理**：分页查询、详情、删除、按日期清空；
- **规范统一**：统一响应 `{ code, message, data }`、全局异常处理、参数校验统一返回 `validate_error`、接口仅使用 GET/POST；
- **测试**：Pytest + TestClient 测试框架（见 `test/`）。

### 前端（web/）

- **登录页**：RSA 加密密码传输；
- **动态路由**：登录后根据后端菜单数据动态生成路由与导航，无菜单权限自动回退登录页；
- **多布局模式**：侧边栏 / 顶部导航 / 混合 / 双栏侧边栏，支持折叠、宽度调节、标签页吸顶等个性化配置并持久化；
- **页面**：仪表盘、账号设置、用户管理、角色管理、菜单管理、图标管理、日志管理；
- **组件体系**：Element Plus + Tailwind CSS，ECharts 图表、CodeMirror 代码编辑、iconfont 图标库。

## 技术栈

| 端 | 技术 |
| --- | --- |
| 前端 web/ | Vue 3 · TypeScript · Vite · Pinia · Vue Router · Element Plus · Tailwind CSS · ECharts |
| 后端 api/ | FastAPI · Uvicorn · SQLAlchemy 2.0 · PyMySQL · Pydantic v2 |
| 安全 | PyJWT · bcrypt · cryptography（RSA） |
| 数据库 | MySQL 8.0（`utf8mb4`） |

## 目录结构

```
admin-starter
├── web/                      # 前端（Vue 3 + TypeScript + Vite）
│   └── src/
│       ├── components/       # 通用组件（表格、弹窗、树、分页等）
│       ├── config/           # 全局配置（API 地址等）
│       ├── hooks/            # 组合式函数
│       ├── router/           # 路由（含基于菜单的动态路由生成）
│       ├── services/         # 页面业务逻辑与接口请求（按页面拆分）
│       ├── stores/           # Pinia 状态管理
│       ├── utils/            # 通用工具（request / auth / storage 等）
│       └── views/
│           ├── layouts/      # 布局组件（多布局模式）
│           └── pages/        # 业务页面
├── api/                      # 后端（FastAPI）
│   ├── app/                  # 应用组装入口
│   ├── config/               # 应用配置（环境变量优先，默认值兜底）
│   ├── internal/
│   │   ├── core/             # 加解密、JWT、密码等核心工具
│   │   ├── exception/        # 自定义异常体系
│   │   ├── extension/        # 数据库扩展（engine / session）
│   │   ├── handler/          # 路由处理器（业务处理层）
│   │   ├── middleware/       # 认证依赖（JWT 校验、管理员校验）
│   │   ├── model/            # 数据库模型
│   │   ├── router/           # 路由注册
│   │   ├── schema/           # 请求 / 响应结构体（Pydantic）
│   │   ├── server/           # 应用构建引擎（create_app 工厂）
│   │   └── service/          # 服务层（业务逻辑、事务管理）
│   ├── pkg/response/         # 统一接口响应封装
│   ├── sql/                  # 数据库建表脚本与初始化数据
│   ├── storage/              # 本地存储
│   └── test/                 # 测试目录（镜像源码结构）
├── README.md
├── README.en.md
└── LICENSE                   # MPL-2.0
```

## 快速开始

### 环境要求

- Node.js >= 16
- Python >= 3.10
- MySQL >= 8.0

### 1. 初始化数据库

```sql
CREATE DATABASE admin_starter DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;
```

依次执行 `api/sql/` 下的建表脚本（`users` → `roles` → `user_roles` → `menus` → `role_menus` → `logs`）。脚本中预置管理员账号 `admin`、角色及菜单初始化数据。

### 2. 启动后端（api/）

```bash
cd api

# 创建并激活虚拟环境
python -m venv .venv
.venv\Scripts\activate          # Windows（macOS/Linux: source .venv/bin/activate）

# 安装依赖
pip install -r requirements.txt

# 配置环境变量（按需修改数据库、JWT 等配置）
copy .env.example .env          # Windows（macOS/Linux: cp .env.example .env）

# 启动服务
python main.py                  # 默认 http://127.0.0.1:5002（Swagger 文档 /docs）
```

### 3. 启动前端（web/）

```bash
cd web

# 安装依赖
npm install

# 配置环境变量（指定后端 API 地址）
copy .env.example .env          # Windows（macOS/Linux: cp .env.example .env）

# 启动开发服务器
npm run dev                     # 默认 http://localhost:3010
```

### 生产构建

```bash
cd web
npm run build                   # 构建产物输出到 web/dist
```

## 接口规范

- 所有接口仅使用 `GET` / `POST`，接口路径不重复；
- 统一响应结构：`{ code, message, data }`，`code` 取值见 `api/pkg/response/http_code.py`；
- 未登录 / 权限不足返回 `unauthorized` / `forbidden`，参数校验失败返回 `validate_error`；
- 分页接口统一使用 `PagedResult` 包装（`list` / `total` / `page_index` / `page_size`）。

## 测试

```bash
cd api
.venv\Scripts\activate
pytest                          # 运行 api/test/ 下全部用例
```

## 开发规范

项目开发遵循 `.trae/rules/` 下的规范文档：

- 前端：`frontend-vue-rules.md`
- 后端：`python-backend-rules.md`、`python-test-rules.md`

## 参与贡献

1. Fork 本仓库
2. 新建 `Feat_xxx` 分支
3. 提交代码
4. 新建 Pull Request

## 开源协议

[MPL-2.0](LICENSE)