whale-town-end/src/core/db/users/README.md

Users 用户数据管理模块

模块概述

Users 是应用的核心用户数据管理模块，位于Core层，专注于提供技术实现而不包含业务逻辑。该模块提供完整的用户数据存储、查询、更新和删除功能，支持数据库和内存两种存储模式，具备统一的异常处理、日志记录和性能监控能力。

作为Core层模块，Users模块为Business层提供可靠的数据访问服务，确保数据持久化和技术实现的稳定性。

对外接口

服务接口

由于这是Core层模块，不直接提供HTTP API接口，而是通过服务接口为其他模块提供功能：

UsersService / UsersMemoryService

用户数据管理服务，提供完整的CRUD操作和高级查询功能。

主要方法接口

• create(createUserDto) - 创建新用户记录，支持数据验证和唯一性检查
• createWithDuplicateCheck(createUserDto) - 创建用户前进行完整的重复性检查
• findAll(limit?, offset?, includeDeleted?) - 分页查询所有用户，支持排序和软删除过滤
• findOne(id, includeDeleted?) - 根据用户ID查询单个用户
• findByUsername(username) - 根据用户名查询用户，支持精确匹配查找
• findByEmail(email) - 根据邮箱地址查询用户，用于登录验证和账户找回
• findByGithubId(githubId) - 根据GitHub ID查询用户，支持第三方OAuth登录
• update(id, updateData) - 更新用户信息，包含唯一性约束检查和数据验证
• remove(id) - 物理删除用户记录，数据将从存储中永久移除
• softRemove(id) - 软删除用户，设置删除时间戳但保留数据记录
• search(keyword, limit?) - 根据关键词在用户名和昵称中进行模糊搜索
• findByRole(role, includeDeleted?) - 根据用户角色查询用户列表
• createBatch(createUserDtos) - 批量创建用户，支持事务回滚和错误处理
• count(conditions?) - 统计用户数量，支持条件查询和数据分析
• exists(id) - 检查用户是否存在，用于快速验证和业务逻辑判断

内部依赖

项目内部依赖

• UserStatus (本模块) - 用户状态枚举，定义用户的激活、禁用、待验证等状态值
• CreateUserDto (本模块) - 用户创建数据传输对象，提供完整的数据验证规则和类型定义
• Users (本模块) - 用户实体类，映射数据库表结构和字段约束
• BaseUsersService (本模块) - 用户服务基类，提供统一的异常处理、日志记录和数据脱敏功能

外部技术依赖

• @nestjs/common - NestJS核心装饰器和异常类
• @nestjs/typeorm - TypeORM集成模块
• typeorm - ORM框架，用于数据库操作
• class-validator - 数据验证库
• class-transformer - 数据转换库
• mysql2 - MySQL数据库驱动（数据库模式）

核心特性

技术特性

双存储模式支持

• 数据库模式：使用TypeORM连接MySQL，适用于生产环境，提供完整的ACID事务支持
• 内存模式：使用Map存储，适用于开发测试和故障降级，提供极高的查询性能
• 动态模块配置：通过UsersModule.forDatabase()和forMemory()灵活切换存储模式

完整的CRUD操作

• 支持用户的创建、查询、更新、删除全生命周期管理
• 提供批量操作和高级查询功能，支持复杂业务场景
• 软删除机制保护重要数据，避免误删除操作

数据完整性保障

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

功能特性

统一异常处理

• 继承BaseUsersService的统一异常处理机制
• 详细的错误分类和用户友好的错误信息
• 完整的日志记录和性能监控，支持问题追踪和性能优化

安全性设计

• 敏感信息脱敏：邮箱、手机号、密码哈希在日志中自动脱敏处理
• 软删除保护：重要数据支持软删除而非物理删除，支持数据恢复
• 并发安全：内存模式支持线程安全的ID生成机制

高性能优化

• 分页查询：支持limit和offset参数控制查询数量，避免大数据量查询
• 索引优化：数据库模式支持索引加速查询，提高查询效率
• 内存缓存：内存模式提供极高的查询性能，适用于高频访问场景

质量特性

可维护性

• 清晰的代码结构和完整的注释文档
• 统一的错误处理和日志记录机制
• 完整的单元测试和集成测试覆盖

可扩展性

• 支持双存储模式的灵活切换
• 模块化设计，易于功能扩展和维护
• 标准化的服务接口，便于其他模块集成

潜在风险

技术风险

内存模式数据丢失

• 风险描述：内存存储在应用重启后数据会丢失
• 影响范围：开发测试环境的数据持久化
• 缓解措施：仅在开发测试环境使用，生产环境必须使用数据库模式

并发操作风险

• 风险描述：内存模式的ID生成锁机制相对简单，高并发场景可能存在性能瓶颈
• 影响范围：高并发用户创建场景
• 缓解措施：生产环境使用数据库模式，利用数据库的并发控制机制

业务风险

数据一致性问题

• 风险描述：双存储模式可能导致开发和生产环境数据不一致
• 影响范围：数据迁移和环境切换
• 缓解措施：确保存储模式的正确选择和配置，建立数据同步机制

唯一性约束冲突

• 风险描述：用户名、邮箱等字段的唯一性约束可能导致创建失败
• 影响范围：用户注册和数据导入
• 缓解措施：提供友好的冲突解决方案和预检查机制

运维风险

软删除数据累积

• 风险描述：软删除的用户数据会持续累积，影响查询性能和存储空间
• 影响范围：长期运行的生产环境
• 缓解措施：定期清理过期的软删除数据，建立数据归档机制

存储模式配置错误

• 风险描述：错误的存储模式配置可能导致数据丢失或性能问题
• 影响范围：应用启动和运行
• 缓解措施：完善的配置验证和环境检查机制

安全风险

敏感信息泄露

• 风险描述：用户邮箱、手机号等敏感信息可能在日志中泄露
• 影响范围：日志系统和监控系统
• 缓解措施：完善的敏感信息脱敏机制和日志安全策略

使用示例

// 创建用户
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' }
]);

模块配置

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

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

版本信息

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

修改记录

• 2026-01-09: 文档优化 - 按照AI代码检查规范更新README文档结构，完善模块概述、对外接口、内部依赖、核心特性和潜在风险描述 (修改者: kiro)
• 2026-01-08: 代码风格优化 - 修复测试文件中的require语句转换为import语句并修复Mock问题 (修改者: moyin)
• 2026-01-07: 架构分层修正 - 修正Core层导入Business层的问题，确保依赖方向正确 (修改者: moyin)
• 2026-01-07: 代码质量提升 - 重构users_memory.service.ts的create方法，提取私有方法减少代码重复 (修改者: moyin)