# Nestjs多终端架构设计_RBAC

**Repository Path**: muaiyuese/nestjs-server-framework

## Basic Information

- **Project Name**: Nestjs多终端架构设计_RBAC
- **Description**: 多终端架构设计：
admin应用：完整后台管理系统，基于RBAC权限控制
web应用：面向终端用户的前端系统
核心库封装：
common库：封装认证、权限、日志等公共能力
db库：统一数据库访问和实体管理
统一技术规范：
全局拦截器/过滤器统一API输入输出
标准化状态码和错误处理
统一的Winston日志和监控体系
基于角色的访问控制(RBAC)
内含mysql workbench数据库建模文件
- **Primary Language**: NodeJS
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2024-07-30
- **Last Updated**: 2025-12-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NestJS项目文档

## 项目概述与技术栈

该项目是一个基于 NestJS 的企业级权限管理系统，采用模块化架构设计，主要技术栈：

| 技术 | 版本 | 用途 |
|------|------|------|
| NestJS | ^10.0.0 | 核心框架 |
| TypeORM | ^0.3.20 | 数据库ORM |
| MySQL | 8.0+ | 主数据库 |
| Redis | 6.0+ | 会话与验证码存储，提升系统性能与跨域一致性 |
| JWT | ^10.2.0 | 认证机制 |
| Winston | ^3.17.0 | 日志系统 |

核心功能：
- **多终端架构设计**：
  - `admin`应用：完整后台管理系统，基于RBAC权限控制
  - `web`应用：面向终端用户的前端系统
  - 共享`libs`核心库，确保功能一致性
- **核心库封装**：
  - `common`库：封装认证、权限、日志等公共能力
  - `db`库：统一数据库访问和实体管理
  - 严格的模块边界和接口定义
- **统一技术规范**：
  - 全局拦截器/过滤器统一API输入输出
  - 标准化状态码和错误处理
  - 统一的Winston日志和监控体系
- **完整权限体系**：
  - 基于角色的访问控制(RBAC)
  - 多终端权限隔离
  - 细粒度的资源权限管理
- **数据库设计**：
  - 使用MySQL Workbench专业建模
  - 用户、角色、资源等核心实体
  - 测试管理和用户测试记录

## 统一响应与异常处理

### 1. 成功响应规范
通过全局拦截器(`libs/common/src/interceptor/response.interceptor.ts`)统一格式：

```typescript
{
  code: number,       // 状态码
  message: string,    // 提示信息
  data: any,          // 返回数据
  timestamp: number   // 响应时间戳
}
```

### 2. 异常处理规范
通过全局过滤器(`libs/common/src/filters/all-exceptions.filter.ts`)处理：

```typescript
{
  code: number,       // 错误码
  message: string,    // 错误信息
  timestamp: number,  // 时间戳
  path: string,       // 请求路径
  details?: any       // 错误详情(开发环境可见)
}
```

### 3. 状态码规范
| 状态码 | 类型 | 说明 |
|--------|------|------|
| 200 | 成功 | 请求成功处理 |
| 400 | 客户端错误 | 请求参数校验失败 |
| 401 | 未授权 | 缺少有效认证凭证 |
| 403 | 禁止访问 | 权限不足 |
| 404 | 未找到 | 资源不存在 |
| 500 | 服务器错误 | 服务器内部错误 |


## 核心模块说明

### 1. 认证模块 (auth)
- JWT认证流程
- 密码加密中间件
- 多终端权限控制
- 相关文件：
  - `libs/common/src/auth/`
  - `libs/common/src/middleware/hash-password.middleware.ts`

### 2. 用户模块 (user)
- 用户CRUD操作
- 用户名唯一性校验
- 密码加密存储
- 软删除功能
- 相关文件：
  - `libs/common/src/permission/user/`
  - `libs/db/src/entities/User.ts`

### 3. 权限模块 (permission)
- 角色管理
- 资源管理
- 权限分配
- 相关文件：
  - `libs/common/src/permission/role/`
  - `libs/common/src/permission/resource/`
  - `libs/db/src/entities/Role.ts`
  - `libs/db/src/entities/Resource.ts`

### 4. 测试模块 (test)
- 测试内容管理
- 用户测试记录
- 测试结果统计
- 相关文件：
  - `libs/db/src/entities/TestContent.ts`
  - `libs/db/src/entities/UserTestingCompleted.ts`

## API文档

项目集成了Swagger UI，启动服务后访问：

```
http://localhost:3000/api
```

包含以下API分组：
1. 认证API
2. 用户管理API
3. 角色权限API
4. 测试管理API

## 环境配置与初始化

### 1. 数据库准备
1. 使用MySQL Workbench打开`fxinlixue建模.mwb`文件
2. 导出SQL脚本并执行创建数据库和表结构
3. 生成TypeORM实体：

```bash
yarn db:generate
```

### 2. 环境变量配置
复制环境模板文件并根据实际配置修改：

```bash
# 开发环境
cp .env.example .env.development

# 生产环境 
cp .env.example .env.production
```

关键配置项说明：
```ini
# 数据库配置
DB_HOST=127.0.0.1       # 数据库主机
DB_PORT=3306           # 数据库端口
DB_USER=fxuser         # 数据库用户名
DB_PASS=fxpassword     # 数据库密码
DB_NAME=fxinlixue      # 数据库名称

# 应用配置
PORT=3000              # 应用端口
JWT_SECRET=your_strong_jwt_secret_here  # JWT密钥
LOG_LEVEL=debug        # 日志级别(debug|info|warn|error)
```

### 3. 依赖安装与初始化
```bash
# 安装依赖
yarn install

# 生成数据库实体(根据现有数据库生成TypeORM实体)
yarn db
```

## Redis 用法说明

### 1. 使用场景
- **验证码存储**：`getCaptcha` 接口生成唯一 `captchaToken`，通过 `X-Captcha-Token` 响应头传递给前端，后端使用 `RedisService` 存储验证码。
- **会话管理**：替代 `session` 存储，提升跨域一致性。
- **缓存机制**：可扩展用于其他缓存场景。

### 2. 配置与连接
- 服务端地址：`localhost:6379`
- 无密码（默认配置）
- 客户端使用 `ioredis` 库
- 连接参数：
  ```ts
  new Redis({
    host: 'localhost',
    port: 6379,
    maxRetriesPerRequest: 3,
    retryStrategy(times) {
      const delay = Math.min(times * 50, 2000);
      return delay;
    },
  });
  ```

### 3. 代码示例
```ts
// 生成验证码并存储
const captchaToken = crypto.randomUUID();
await this.redisService.set(`captcha:${captchaToken}`, captcha.text, 120);

// 验证验证码
const storedCaptcha = await this.redisService.get(`captcha:${captchaToken}`);
if (body.captcha.toLowerCase() !== storedCaptcha.toLowerCase()) {
  throw new UnauthorizedException('验证码错误');
}
// 删除验证码
await this.redisService.del(`captcha:${captchaToken}`);
```

## 部署建议
1. 启动 Redis 服务：`redis-server --daemonize yes`
2. 使用 Docker 部署（推荐）：
   ```bash
   docker run -d --name redis-server -p 6379:6379 redis:latest
   ```
3. 确保 `redis-service.ts` 配置正确，连接 `localhost:6379`

## 启动与测试

### 开发模式

```bash
# 启动开发服务器(带热重载)
yarn start:dev

# 带调试模式
yarn start:debug
```

### 生产模式

```bash
# 构建项目
yarn build

# 启动生产服务器
yarn start:prod
```

### 测试

```bash
# 运行单元测试
yarn test

# 运行e2e测试
yarn test:e2e

# 生成测试覆盖率报告
yarn test:cov

# 测试覆盖率查看
open coverage/lcov-report/index.html
```

## 代码规范

### 1. 代码风格

```bash
# 代码格式化
yarn format

# 代码检查
yarn lint
```

## 监控与日志

### 1. 日志配置
日志文件存储在`logs/`目录下，按天分割：

```
logs/
├── application-2023-01-01.log
├── error-2023-01-01.log
└── debug-2023-01-01.log
```


## 核心依赖

项目主要依赖以下技术栈，完整列表请参考`package.json`：

### 框架与基础设施
- [NestJS](https://nestjs.com/) - 渐进式Node.js框架
- [TypeORM](https://typeorm.io/) - 数据库ORM
- [MySQL 8.0+](https://www.mysql.com/) - 主数据库
- [Redis](https://redis.io/) - 缓存服务(可选)

### 关键模块
- `@nestjs/jwt` - JWT认证
- `@nestjs/swagger` - API文档生成
- `winston` + `winston-daily-rotate-file` - 日志系统
- `class-validator` + `class-transformer` - 数据验证与转换
- `bcryptjs` - 密码加密

## 项目目录结构

```
.
├── apps/                  # 应用模块(多端入口)
│   ├── admin/             # 后台管理系统
│   │   ├── src/           # 源代码
│   │   │   ├── modules/   # 业务模块
│   │   │   ├── main.ts    # 入口文件
│   │   ├── test/          # 测试代码
│   └── web/               # 前端应用
│       ├── src/           # 源代码
│       ├── test/          # 测试代码
├── libs/                  # 共享库
│   ├── common/            # 公共模块
│   │   ├── src/           # 核心实现
│   │   │   ├── auth/      # 认证(JWT/权限)
│   │   │   ├── config/    # 配置管理
│   │   │   ├── filters/   # 异常过滤器
│   │   │   ├── interceptor/ # 响应拦截器
│   │   │   ├── logger/    # 日志系统
│   │   │   ├── middleware/ # 中间件
│   │   │   ├── permission/ # RBAC权限系统
│   │   │   ├── utils/     # 工具函数
│   ├── db/                # 数据库模块
│   │   ├── src/           # 数据库相关
│   │   │   ├── entities/  # 数据库实体
│   │   │   ├── migrations/ # 数据库迁移
├── logs/                  # 日志目录
├── test/                  # 全局测试配置
├── .env.development       # 开发环境配置
├── .env.production        # 生产环境配置
├── nest-cli.json          # NestJS配置
├── package.json           # 项目依赖
├── README.md              # 项目文档
```

## 开发工作流

### 1. 功能开发流程
1. 在`libs/common`中开发公共模块
2. 在`apps/[app-name]/src/modules`中开发业务模块
3. 编写单元测试和e2e测试
4. 提交Pull Request进行代码审查

### 2. 代码提交规范
- feat: 新功能
- fix: bug修复
- docs: 文档更新
- style: 代码格式
- refactor: 代码重构
- test: 测试相关
- chore: 构建或依赖更新

### 3. CI/CD流程
1. 代码提交触发自动化测试
2. 测试通过后自动部署到测试环境
3. 手动审批后部署到生产环境