refactor：项目架构重构和命名规范化

- 统一文件命名为snake_case格式（kebab-case snake_case） - 重构zulip模块为zulip_core，明确Core层职责 - 重构user-mgmt模块为user_mgmt，统一命名规范 - 调整模块依赖关系，优化架构分层 - 删除过时的文件和目录结构 - 更新相关文档和配置文件本次重构涉及大量文件重命名和模块重组，旨在建立更清晰的项目架构和统一的命名规范。
2026-01-08 00:14:14 +08:00
parent 4fa4bd1a70
commit bb796a2469
178 changed files with 24767 additions and 3484 deletions
--- a/src/core/db/users/README.md
+++ b/src/core/db/users/README.md
@@ -0,0 +1,188 @@
+# 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-07
+- **测试覆盖**: 完整的单元测试和集成测试覆盖
+
+## 已知问题和改进建议
+
+### 内存服务限制
+- 内存模式的 `createWithDuplicateCheck` 方法已实现，与数据库模式保持一致
+- ID生成使用简单锁机制，高并发场景建议使用数据库模式
+
+### 模块配置建议
+- 当前使用字符串token注入服务，建议考虑使用类型安全的注入方式
+- 双存储模式切换时需要确保数据一致性