# AI-RBAC-ADMIN

**Repository Path**: geeksdidi/ai-rbac-admin

## Basic Information

- **Project Name**: AI-RBAC-ADMIN
- **Description**: 一个基于vue3+NestJS以AICoding开发可运行的多租户 RBAC 权限管理系统（前后端分离），包含租户/用户/角色/权限点/菜单/审计日志等能力，并提供管理后台用于配置与验证权限。代码均由AI生成
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-03-19
- **Last Updated**: 2026-03-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI-RBAC（多租户 RBAC 权限管理系统）

一个可运行的多租户 RBAC 权限管理系统（前后端分离），包含租户/用户/角色/权限点/菜单/审计日志等能力，并提供管理后台用于配置与验证权限。

> 说明：本项目代码由 AI 全量生成，并在迭代过程中持续由 AI 辅助完善与加固（含功能实现、权限策略收口、测试补齐、文档整理等）。

## 功能概览

- 多租户（Tenant）：按租户隔离用户、角色、权限分配与数据访问
- RBAC（Role-Based Access Control）
  - 权限点（Permission）：以 `module.action` 风格编码（例如 `user.read`）
  - 角色（Role）：绑定权限点
  - 用户（User）：绑定角色（多角色）
- 菜单（Menu）与权限联动：菜单条目可绑定 `permissionCode`，无权限不显示
- 全局鉴权与授权
  - JWT 鉴权（全局守卫）
  - 权限守卫（全局守卫），接口通过装饰器声明所需权限
- 审计日志：记录关键访问允许/拒绝等行为
- 管理后台
  - 用户管理、角色管理、权限点管理、租户管理、菜单管理、审计日志
  - 403/404 错误页、全局 Loading、请求超时处理

## 技术栈

- 后端：NestJS + TypeORM + MySQL + JWT + Swagger
- 前端：Vue 3 + Vite + TypeScript + Element Plus + Pinia + Axios

## 项目结构

```
AI-RBAC/
  backend/              # NestJS 后端（API + 鉴权/授权 + 数据库）
  frontend/             # Vue3 管理后台
  docker-compose.yml    # 本地 MySQL（含初始化 SQL）
```

## 快速开始（推荐：Docker 启 MySQL + 本地跑前后端）

### 1) 启动 MySQL

在项目根目录执行：

```bash
docker compose up -d
```

默认会启动一个 MySQL 容器并初始化数据库：

- Host：127.0.0.1
- Port：3306
- DB：rbac
- User：rbac
- Password：rbac_dev_password

### 2) 启动后端（API）

```bash
cd backend
npm install
```

配置环境变量（任选其一）：

- 复制 `.env.example` 为 `.env` 并按需修改
- 或直接使用仓库内已有的 `.env`

启动开发模式：

```bash
npm run start:dev
```

可访问：

- API：`http://localhost:3000`
- Swagger：`http://localhost:3000/docs`

### 3) 初始化数据（非常重要）

首次运行（或你清空/误删了租户等数据）需要执行：

```bash
cd backend
npm run seed
```

该脚本会写入系统基础数据（权限点、默认租户、默认账号、菜单等），核心逻辑在 `backend/src/seed-rbac.ts`。

### 4) 启动前端（管理后台）

```bash
cd frontend
npm install
npm run dev
```

默认前端会请求 `http://localhost:3000` 的后端 API（见 `frontend/.env.example`）。

访问：

- 管理后台：`http://localhost:5173`

## 默认账号

初始化数据后，默认会创建：

- 租户代码：`acme`
- 管理员账号：`admin@acme.io`
- 密码：`P@ssw0rd123`

并会额外创建一批测试用户（例如 `user1@acme.io` ~ `user50@acme.io`，密码同上）。

## 系统用法（管理员操作指南）

### 1) 权限模型怎么运作

- 你在“权限点管理”中维护系统权限点（例如 `user.read` / `role.update`）
- 在“角色管理”中给角色勾选权限点
- 在“用户管理”中给用户分配角色
- 用户登录后：
  - 后端会校验 token 并在每次请求时从数据库计算该用户最新权限
  - 前端会根据后端返回的菜单树显示侧边栏，并用 `v-permission` 控制按钮可见性

### 2) 菜单与权限

菜单项支持 `permissionCode`：

- 菜单没有 `permissionCode`：公共可见
- 菜单有 `permissionCode`：用户必须拥有该权限点才会显示

### 3) 典型权限点示例

- `user.read`：查看租户下用户列表
- `user.create`：创建用户
- `role.read`：查看角色列表
- `role.update`：编辑角色与权限分配（也作为“权限点管理”的管理权限）
- `tenant.read`：查看租户
- `menu.manage`：菜单管理
- `audit.read`：审计日志查看

## 开发说明（后端）

### 核心约定：权限装饰器

后端采用“默认拒绝”的授权策略：

- 公开接口：使用 `@Public()`
- 仅需登录但不绑定权限点：使用 `@NoPermissionRequired()`
- 其余业务接口：必须使用 `@RequirePermissions('xxx')`

否则会被权限守卫拒绝（避免未来新增接口忘记标注而导致越权）。

### 权限即时生效

系统实现为“权限变更即时生效”：

- JWT token 仅承载身份信息
- 每次请求在 JWT 守卫内从数据库读取用户的最新权限集

因此：给用户调整角色/权限后，无需重新登录，下一次请求即按新权限生效。

### 常用命令

在 `backend/` 目录：

```bash
npm run start:dev   # 开发模式
npm run seed        # 初始化/补齐基础数据
npm test            # 单元测试
npm run test:e2e    # 集成测试
npm run typecheck   # TypeScript 类型检查
npm run lint        # ESLint
```

## 开发说明（前端）

### API 与鉴权

- Axios 封装：`frontend/src/utils/request.ts`
- Token 存储：`localStorage.accessToken`
- 401 会清理 token 并跳转登录页
- 403 会跳转 `/403` 页面（用于快速提示“无权限”）

### 权限相关

- 菜单数据来自 `/auth/me` 返回的 `menus`
- 按钮级权限由 `v-permission` 指令控制
- 某些页面为了避免“菜单能看到但页面因额外接口 403 而跳转”，会做降级处理（例如没有 `role.read` 时不请求角色列表）

### 常用命令

在 `frontend/` 目录：

```bash
npm run dev     # 启动开发服务
npm run build   # 构建
npm run preview # 预览构建产物
```

## 常见问题（Troubleshooting）

### 1) 登录提示 Tenant not found

表示你登录时输入的租户代码在数据库中不存在。

解决：

1. 确保登录页租户代码为 `acme`
2. 重新执行一次 `backend` 的 `npm run seed` 以重建默认租户与账号
3. 检查前端 `VITE_API_BASE_URL` 是否指向正确后端（避免请求到另一个后端/另一个数据库）

### 2) 菜单能看到，但点进去是 403

菜单可见只代表满足菜单的 `permissionCode`。

页面内部可能还会请求其他接口（例如用户管理页会请求角色列表），这些接口需要额外权限。解决方式：

- 赋予缺失的权限点（例如 `role.read`）
- 或在前端做降级处理（项目中部分页面已处理）

### 3) 分页 pageSize must not be greater than 200

后端分页 DTO 限制 `pageSize <= 200`。

如果前端请求带了过大的 `pageSize` 会触发验证错误，请将前端请求的 `pageSize` 调整到 200 以内。

## 注意事项

- 建议在生产环境替换 `backend/.env` 中的 `JWT_SECRET`
- 租户与用户启用状态会影响鉴权结果（禁用后会导致 token 失效/被拒绝）
- `seed-rbac.ts` 是用于初始化/填充数据的脚本，重复执行会补齐缺失数据，但请注意它也会重置/重建部分菜单数据