forked from datawhale/whale-town-end
docs：重构文档结构
- 创建模块化文档系统 - 添加用户认证系统详细文档 - 添加日志系统专门文档 - 简化主README，通过链接引用子系统文档 - 提高文档的可维护性和可读性
This commit is contained in:
moyin
80
docs/systems/logger/README.md
Normal file
80
docs/systems/logger/README.md
Normal file
@@ -0,0 +1,80 @@
|
||||
# 日志系统
|
||||
|
||||
## 概述
|
||||
|
||||
项目集成了完整的日志系统，基于 Pino 高性能日志库，提供结构化日志记录、自动敏感信息过滤和多级别日志控制。
|
||||
|
||||
## 功能特性
|
||||
|
||||
- 🚀 高性能日志记录
|
||||
- 🔒 自动敏感信息过滤
|
||||
- 🎯 多级别日志控制
|
||||
- 🔍 请求上下文绑定
|
||||
- 📊 结构化日志输出
|
||||
|
||||
## 使用示例
|
||||
|
||||
### 基础用法
|
||||
|
||||
```typescript
|
||||
import { AppLoggerService } from './core/utils/logger/logger.service';
|
||||
|
||||
@Injectable()
|
||||
export class UserService {
|
||||
constructor(private readonly logger: AppLoggerService) {}
|
||||
|
||||
async createUser(userData: CreateUserDto) {
|
||||
this.logger.info('开始创建用户', {
|
||||
operation: 'createUser',
|
||||
email: userData.email,
|
||||
timestamp: new Date().toISOString()
|
||||
});
|
||||
|
||||
try {
|
||||
const user = await this.userRepository.save(userData);
|
||||
|
||||
this.logger.info('用户创建成功', {
|
||||
operation: 'createUser',
|
||||
userId: user.id,
|
||||
email: userData.email
|
||||
});
|
||||
|
||||
return user;
|
||||
} catch (error) {
|
||||
this.logger.error('用户创建失败', {
|
||||
operation: 'createUser',
|
||||
email: userData.email,
|
||||
error: error.message
|
||||
}, error.stack);
|
||||
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 日志级别
|
||||
|
||||
- `error`: 错误信息
|
||||
- `warn`: 警告信息
|
||||
- `info`: 一般信息
|
||||
- `debug`: 调试信息
|
||||
|
||||
## 配置
|
||||
|
||||
日志配置位于 `src/core/utils/logger/logger.config.ts`，支持：
|
||||
|
||||
- 日志级别设置
|
||||
- 输出格式配置
|
||||
- 敏感信息过滤规则
|
||||
- 文件输出配置
|
||||
|
||||
## 敏感信息过滤
|
||||
|
||||
系统自动过滤以下敏感信息：
|
||||
- 密码字段
|
||||
- 令牌信息
|
||||
- 个人身份信息
|
||||
- 支付相关信息
|
||||
|
||||
详细使用方法请参考：[后端开发规范指南 - 日志系统使用指南](../../backend_development_guide.md#四日志系统使用指南)
|
||||
334
docs/systems/user-auth/README.md
Normal file
334
docs/systems/user-auth/README.md
Normal file
@@ -0,0 +1,334 @@
|
||||
# 用户认证系统
|
||||
|
||||
## 概述
|
||||
|
||||
用户认证系统提供完整的用户注册、登录、密码管理功能，支持传统用户名密码登录和第三方OAuth登录。
|
||||
|
||||
## 功能特性
|
||||
|
||||
- 🔐 多种登录方式：用户名/邮箱/手机号登录
|
||||
- 📝 用户注册和信息管理
|
||||
- 🐙 GitHub OAuth 第三方登录
|
||||
- 🔄 密码重置和修改
|
||||
- 🛡️ bcrypt 密码加密
|
||||
- 🎯 基于角色的权限控制
|
||||
|
||||
## 架构设计
|
||||
|
||||
### 分层结构
|
||||
|
||||
```
|
||||
src/
|
||||
├── business/login/ # 业务逻辑层
|
||||
│ ├── login.controller.ts # HTTP 控制器
|
||||
│ ├── login.service.ts # 业务服务
|
||||
│ ├── login.dto.ts # 数据传输对象
|
||||
│ ├── login.service.spec.ts # 业务服务测试
|
||||
│ └── login.module.ts # 业务模块
|
||||
├── core/
|
||||
│ ├── login_core/ # 核心功能层
|
||||
│ │ ├── login_core.service.ts # 核心认证逻辑
|
||||
│ │ ├── login_core.service.spec.ts # 核心服务测试
|
||||
│ │ └── login_core.module.ts # 核心模块
|
||||
│ └── db/users/ # 数据访问层
|
||||
│ ├── users.entity.ts # 用户实体
|
||||
│ ├── users.service.ts # 用户数据服务
|
||||
│ └── users.dto.ts # 用户 DTO
|
||||
```
|
||||
|
||||
### 职责分离
|
||||
|
||||
#### 1. 业务逻辑层 (Business Layer)
|
||||
- **位置**: `src/business/login/`
|
||||
- **职责**:
|
||||
- 处理HTTP请求和响应
|
||||
- 数据格式化和验证
|
||||
- 业务流程控制
|
||||
- 错误处理和日志记录
|
||||
|
||||
#### 2. 核心功能层 (Core Layer)
|
||||
- **位置**: `src/core/login_core/`
|
||||
- **职责**:
|
||||
- 认证核心算法实现
|
||||
- 密码加密和验证
|
||||
- 用户查找和匹配
|
||||
- 令牌生成和验证
|
||||
|
||||
#### 3. 数据访问层 (Data Access Layer)
|
||||
- **位置**: `src/core/db/users/`
|
||||
- **职责**:
|
||||
- 数据库操作封装
|
||||
- 实体关系映射
|
||||
- 数据完整性保证
|
||||
- 查询优化
|
||||
|
||||
## API 接口
|
||||
|
||||
### 用户注册
|
||||
|
||||
```bash
|
||||
POST /auth/register
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"username": "testuser",
|
||||
"password": "password123",
|
||||
"nickname": "测试用户",
|
||||
"email": "test@example.com",
|
||||
"phone": "+8613800138000"
|
||||
}
|
||||
```
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"user": {
|
||||
"id": "1",
|
||||
"username": "testuser",
|
||||
"nickname": "测试用户",
|
||||
"email": "test@example.com",
|
||||
"phone": "+8613800138000",
|
||||
"avatar_url": null,
|
||||
"role": 1,
|
||||
"created_at": "2025-12-17T10:00:00.000Z"
|
||||
},
|
||||
"access_token": "eyJ1c2VySWQiOiIxIiwidXNlcm5hbWUiOiJ0ZXN0dXNlciJ9...",
|
||||
"is_new_user": true,
|
||||
"message": "注册成功"
|
||||
},
|
||||
"message": "注册成功"
|
||||
}
|
||||
```
|
||||
|
||||
### 用户登录
|
||||
|
||||
```bash
|
||||
POST /auth/login
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"identifier": "testuser", # 支持用户名/邮箱/手机号
|
||||
"password": "password123"
|
||||
}
|
||||
```
|
||||
|
||||
### GitHub OAuth登录
|
||||
|
||||
```bash
|
||||
POST /auth/github
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"github_id": "12345678",
|
||||
"username": "githubuser",
|
||||
"nickname": "GitHub用户",
|
||||
"email": "github@example.com",
|
||||
"avatar_url": "https://avatars.githubusercontent.com/u/12345678"
|
||||
}
|
||||
```
|
||||
|
||||
### 密码重置
|
||||
|
||||
```bash
|
||||
# 1. 发送验证码
|
||||
POST /auth/forgot-password
|
||||
{
|
||||
"identifier": "test@example.com"
|
||||
}
|
||||
|
||||
# 2. 重置密码
|
||||
POST /auth/reset-password
|
||||
{
|
||||
"identifier": "test@example.com",
|
||||
"verification_code": "123456",
|
||||
"new_password": "newpassword123"
|
||||
}
|
||||
```
|
||||
|
||||
### 修改密码
|
||||
|
||||
```bash
|
||||
PUT /auth/change-password
|
||||
{
|
||||
"user_id": "1",
|
||||
"old_password": "password123",
|
||||
"new_password": "newpassword123"
|
||||
}
|
||||
```
|
||||
|
||||
## 数据模型
|
||||
|
||||
### 用户实体 (Users Entity)
|
||||
|
||||
```typescript
|
||||
{
|
||||
id: bigint, // 主键ID
|
||||
username: string, // 用户名（唯一）
|
||||
email?: string, // 邮箱（唯一，可选）
|
||||
phone?: string, // 手机号（唯一，可选）
|
||||
password_hash?: string, // 密码哈希（OAuth用户为空）
|
||||
nickname: string, // 显示昵称
|
||||
github_id?: string, // GitHub ID（唯一，可选）
|
||||
avatar_url?: string, // 头像URL
|
||||
role: number, // 用户角色（1-普通，9-管理员）
|
||||
created_at: Date, // 创建时间
|
||||
updated_at: Date // 更新时间
|
||||
}
|
||||
```
|
||||
|
||||
### 数据库设计特点
|
||||
|
||||
1. **唯一性约束**: username, email, phone, github_id
|
||||
2. **索引优化**: 主键、唯一索引、角色索引
|
||||
3. **字符集支持**: utf8mb4，支持emoji
|
||||
4. **数据类型**: BIGINT主键，VARCHAR字段，DATETIME时间戳
|
||||
|
||||
## 安全机制
|
||||
|
||||
### 1. 密码安全
|
||||
- **加密算法**: bcrypt (saltRounds=12)
|
||||
- **强度验证**: 最少8位，包含字母和数字
|
||||
- **存储安全**: 只存储哈希值，不存储明文
|
||||
|
||||
### 2. 数据验证
|
||||
- **输入验证**: class-validator装饰器
|
||||
- **SQL注入防护**: TypeORM参数化查询
|
||||
- **XSS防护**: 数据转义和验证
|
||||
|
||||
### 3. 访问控制
|
||||
- **令牌机制**: 基于用户信息的访问令牌
|
||||
- **角色权限**: 基于角色的访问控制（RBAC）
|
||||
- **会话管理**: 令牌生成和验证
|
||||
|
||||
### 4. 错误处理
|
||||
- **统一异常**: NestJS异常过滤器
|
||||
- **日志记录**: 操作日志和错误日志
|
||||
- **信息脱敏**: 敏感信息自动脱敏
|
||||
|
||||
## 测试覆盖
|
||||
|
||||
### 单元测试
|
||||
- 核心服务测试：`src/core/login_core/login_core.service.spec.ts`
|
||||
- 业务服务测试：`src/business/login/login.service.spec.ts`
|
||||
|
||||
### 集成测试
|
||||
- 端到端测试：`test/business/login.e2e-spec.ts`
|
||||
|
||||
### 测试用例
|
||||
- 用户注册和登录流程
|
||||
- GitHub OAuth认证
|
||||
- 密码重置和修改
|
||||
- 数据验证和错误处理
|
||||
- 安全性测试
|
||||
|
||||
## 使用示例
|
||||
|
||||
### JavaScript/TypeScript
|
||||
|
||||
```javascript
|
||||
// 用户注册
|
||||
const registerResponse = await fetch('/auth/register', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
},
|
||||
body: JSON.stringify({
|
||||
username: 'testuser',
|
||||
password: 'password123',
|
||||
nickname: '测试用户',
|
||||
email: 'test@example.com'
|
||||
})
|
||||
});
|
||||
|
||||
const registerData = await registerResponse.json();
|
||||
console.log(registerData);
|
||||
|
||||
// 用户登录
|
||||
const loginResponse = await fetch('/auth/login', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
},
|
||||
body: JSON.stringify({
|
||||
identifier: 'testuser',
|
||||
password: 'password123'
|
||||
})
|
||||
});
|
||||
|
||||
const loginData = await loginResponse.json();
|
||||
console.log(loginData);
|
||||
```
|
||||
|
||||
### curl 命令
|
||||
|
||||
```bash
|
||||
# 用户注册
|
||||
curl -X POST http://localhost:3000/auth/register \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"username": "testuser",
|
||||
"password": "password123",
|
||||
"nickname": "测试用户",
|
||||
"email": "test@example.com"
|
||||
}'
|
||||
|
||||
# 用户登录
|
||||
curl -X POST http://localhost:3000/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"identifier": "testuser",
|
||||
"password": "password123"
|
||||
}'
|
||||
```
|
||||
|
||||
## 错误处理
|
||||
|
||||
### 常见错误代码
|
||||
|
||||
- `LOGIN_FAILED`: 登录失败
|
||||
- `REGISTER_FAILED`: 注册失败
|
||||
- `GITHUB_OAUTH_FAILED`: GitHub登录失败
|
||||
- `SEND_CODE_FAILED`: 发送验证码失败
|
||||
- `RESET_PASSWORD_FAILED`: 密码重置失败
|
||||
- `CHANGE_PASSWORD_FAILED`: 密码修改失败
|
||||
|
||||
### 错误响应格式
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "错误描述",
|
||||
"error_code": "ERROR_CODE"
|
||||
}
|
||||
```
|
||||
|
||||
## 扩展功能
|
||||
|
||||
### 计划中的功能
|
||||
|
||||
1. **JWT令牌管理**
|
||||
- 访问令牌和刷新令牌
|
||||
- 令牌黑名单机制
|
||||
- 自动刷新功能
|
||||
|
||||
2. **多因子认证**
|
||||
- 短信验证码
|
||||
- 邮箱验证码
|
||||
- TOTP应用支持
|
||||
|
||||
3. **社交登录扩展**
|
||||
- 微信登录
|
||||
- QQ登录
|
||||
- 微博登录
|
||||
|
||||
4. **安全增强**
|
||||
- 登录失败次数限制
|
||||
- IP白名单/黑名单
|
||||
- 设备指纹识别
|
||||
|
||||
5. **用户管理**
|
||||
- 用户状态管理（激活/禁用）
|
||||
- 用户角色权限细化
|
||||
- 用户行为日志记录
|
||||
Reference in New Issue
Block a user