# Users 用户数据管理模块

Users 是应用的核心用户数据管理模块，提供完整的用户数据存储、查询、更新和删除功能，支持数据库和内存两种存储模式，具备统一的异常处理、日志记录和性能监控能力。

## 用户数据操作

### create()
创建新用户记录，支持数据验证和唯一性检查。

### createWithDuplicateCheck()
创建用户前进行完整的重复性检查，确保用户名、邮箱、手机号、GitHub ID的唯一性。

### findAll()
分页查询所有用户，支持排序和软删除过滤。

### findOne()
根据用户ID查询单个用户，支持包含已删除用户的查询。

### findByUsername()
根据用户名查询用户，支持精确匹配查找。

### findByEmail()
根据邮箱地址查询用户，用于登录验证和账户找回。

### findByGithubId()
根据GitHub ID查询用户，支持第三方OAuth登录。

### update()
更新用户信息，包含唯一性约束检查和数据验证。

### remove()
物理删除用户记录，数据将从存储中永久移除。

### softRemove()
软删除用户，设置删除时间戳但保留数据记录。

## 高级查询功能

### search()
根据关键词在用户名和昵称中进行模糊搜索，支持大小写不敏感匹配。

### findByRole()
根据用户角色查询用户列表，支持权限管理和用户分类。

### createBatch()
批量创建用户，支持事务回滚和错误处理。

### count()
统计用户数量，支持条件查询和数据分析。

### exists()
检查用户是否存在，用于快速验证和业务逻辑判断。

## 使用的项目内部依赖

### UserStatus (来自 business/user-mgmt/enums/user-status.enum)
用户状态枚举，定义用户的激活、禁用、待验证等状态值。

### CreateUserDto (本模块)
用户创建数据传输对象，提供完整的数据验证规则和类型定义。

### Users (本模块)
用户实体类，映射数据库表结构和字段约束。

### BaseUsersService (本模块)
用户服务基类，提供统一的异常处理、日志记录和数据脱敏功能。

## 核心特性

### 双存储模式支持
- 数据库模式：使用TypeORM连接MySQL，适用于生产环境
- 内存模式：使用Map存储，适用于开发测试和故障降级
- 动态模块配置：通过UsersModule.forDatabase()和forMemory()灵活切换

### 完整的CRUD操作
- 支持用户的创建、查询、更新、删除全生命周期管理
- 提供批量操作和高级查询功能
- 软删除机制保护重要数据

### 数据完整性保障
- 唯一性约束检查：用户名、邮箱、手机号、GitHub ID
- 数据验证：使用class-validator进行输入验证
- 事务支持：批量操作支持回滚机制

### 统一异常处理
- 继承BaseUsersService的统一异常处理机制
- 详细的错误分类和用户友好的错误信息
- 完整的日志记录和性能监控

### 安全性设计
- 敏感信息脱敏：邮箱、手机号、密码哈希自动脱敏
- 软删除保护：重要数据支持软删除而非物理删除
- 并发安全：内存模式支持线程安全的ID生成

### 高性能优化
- 分页查询：支持limit和offset参数控制查询数量
- 索引优化：数据库模式支持索引加速查询
- 内存缓存：内存模式提供极高的查询性能

## 潜在风险

### 内存模式数据丢失
- 内存存储在应用重启后数据会丢失
- 不适用于生产环境的持久化需求
- 建议仅在开发测试环境使用

### 并发操作风险
- 内存模式的ID生成锁机制相对简单
- 高并发场景可能存在性能瓶颈
- 建议在生产环境使用数据库模式

### 数据一致性问题
- 双存储模式可能导致数据不一致
- 需要确保存储模式的正确选择和配置
- 建议在同一环境中保持存储模式一致

### 软删除数据累积
- 软删除的用户数据会持续累积
- 可能影响查询性能和存储空间
- 建议定期清理过期的软删除数据

### 唯一性约束冲突
- 用户名、邮箱等字段的唯一性约束可能导致创建失败
- 需要前端进行预检查和用户提示
- 建议提供友好的冲突解决方案

## 使用示例

```typescript
// 创建用户
const newUser = await usersService.create({
  username: 'testuser',
  email: 'test@example.com',
  nickname: '测试用户',
  password_hash: 'hashed_password'
});

// 查询用户
const user = await usersService.findByEmail('test@example.com');

// 更新用户信息
const updatedUser = await usersService.update(user.id, {
  nickname: '新昵称'
});

// 搜索用户
const searchResults = await usersService.search('测试', 10);

// 批量创建用户
const batchUsers = await usersService.createBatch([
  { username: 'user1', nickname: '用户1' },
  { username: 'user2', nickname: '用户2' }
]);
```

## 模块配置

```typescript
// 数据库模式
@Module({
  imports: [UsersModule.forDatabase()],
})
export class AppModule {}

// 内存模式
@Module({
  imports: [UsersModule.forMemory()],
})
export class TestModule {}
```

## 版本信息

- **版本**: 1.0.1
- **主要作者**: moyin, angjustinl
- **创建时间**: 2025-12-17
- **最后修改**: 2026-01-08
- **测试覆盖**: 完整的单元测试和集成测试覆盖

## 修改记录

- 2026-01-08: 代码风格优化 - 修复测试文件中的require语句转换为import语句并修复Mock问题 (修改者: moyin)
- 2026-01-07: 架构分层修正 - 修正Core层导入Business层的问题，确保依赖方向正确 (修改者: moyin)
- 2026-01-07: 代码质量提升 - 重构users_memory.service.ts的create方法，提取私有方法减少代码重复 (修改者: moyin)

## 已知问题和改进建议

### 内存服务限制
- 内存模式的 `createWithDuplicateCheck` 方法已实现，与数据库模式保持一致
- ID生成使用简单锁机制，高并发场景建议使用数据库模式

### 模块配置建议
- 当前使用字符串token注入服务，建议考虑使用类型安全的注入方式
- 双存储模式切换时需要确保数据一致性