forked from datawhale/whale-town-end
refactor：项目架构重构和命名规范化
- 统一文件命名为snake_case格式（kebab-case snake_case） - 重构zulip模块为zulip_core，明确Core层职责 - 重构user-mgmt模块为user_mgmt，统一命名规范 - 调整模块依赖关系，优化架构分层 - 删除过时的文件和目录结构 - 更新相关文档和配置文件 本次重构涉及大量文件重命名和模块重组， 旨在建立更清晰的项目架构和统一的命名规范。
This commit is contained in:
moyin
209
src/core/db/zulip_accounts/README.md
Normal file
209
src/core/db/zulip_accounts/README.md
Normal file
@@ -0,0 +1,209 @@
|
||||
# ZulipAccounts Zulip账号关联管理模块
|
||||
|
||||
ZulipAccounts 是应用的核心Zulip账号关联管理模块，提供游戏用户与Zulip账号的完整关联功能，支持数据库和内存两种存储模式，具备完善的数据验证、状态管理、批量操作和统计分析能力。
|
||||
|
||||
## 账号数据操作
|
||||
|
||||
### create()
|
||||
创建新的Zulip账号关联记录，支持数据验证和唯一性检查。
|
||||
|
||||
### findByGameUserId()
|
||||
根据游戏用户ID查询账号关联，用于用户登录验证。
|
||||
|
||||
### findByZulipUserId()
|
||||
根据Zulip用户ID查询账号关联，用于Zulip集成。
|
||||
|
||||
### findByZulipEmail()
|
||||
根据Zulip邮箱查询账号关联，用于邮箱验证。
|
||||
|
||||
### findById()
|
||||
根据主键ID查询特定账号关联记录。
|
||||
|
||||
### update()
|
||||
更新账号关联信息，支持部分字段更新。
|
||||
|
||||
### updateByGameUserId()
|
||||
根据游戏用户ID更新账号信息。
|
||||
|
||||
### delete()
|
||||
删除指定的账号关联记录。
|
||||
|
||||
### deleteByGameUserId()
|
||||
根据游戏用户ID删除账号关联。
|
||||
|
||||
## 高级查询功能
|
||||
|
||||
### findMany()
|
||||
批量查询账号关联，支持分页和条件筛选。
|
||||
|
||||
### findAccountsNeedingVerification()
|
||||
查找需要重新验证的账号列表。
|
||||
|
||||
### findErrorAccounts()
|
||||
查找处于错误状态的账号列表。
|
||||
|
||||
### existsByEmail()
|
||||
检查指定邮箱是否已存在关联。
|
||||
|
||||
### existsByZulipUserId()
|
||||
检查指定Zulip用户ID是否已存在关联。
|
||||
|
||||
## 批量操作和统计
|
||||
|
||||
### batchUpdateStatus()
|
||||
批量更新多个账号的状态。
|
||||
|
||||
### getStatusStatistics()
|
||||
获取各状态账号的统计信息。
|
||||
|
||||
### verifyAccount()
|
||||
验证账号的有效性和状态。
|
||||
|
||||
## 使用的项目内部依赖
|
||||
|
||||
### ZulipAccounts (本模块)
|
||||
核心实体类，定义数据库表结构和业务方法。
|
||||
|
||||
### ZulipAccountsRepository (本模块)
|
||||
数据访问层，封装数据库操作逻辑。
|
||||
|
||||
### ZulipAccountsMemoryRepository (本模块)
|
||||
内存存储实现，用于测试和开发环境。
|
||||
|
||||
### CreateZulipAccountDto (本模块)
|
||||
创建账号的数据传输对象。
|
||||
|
||||
### UpdateZulipAccountDto (本模块)
|
||||
更新账号的数据传输对象。
|
||||
|
||||
### ZulipAccountResponseDto (本模块)
|
||||
响应数据传输对象。
|
||||
|
||||
### ZULIP_ACCOUNTS_CONSTANTS (本模块)
|
||||
模块常量定义，包含默认值和配置。
|
||||
|
||||
### Users (来自 ../users/users.entity)
|
||||
用户实体，建立一对一关联关系。
|
||||
|
||||
### @nestjs/common (来自 NestJS框架)
|
||||
提供依赖注入、异常处理等核心功能。
|
||||
|
||||
### @nestjs/typeorm (来自 TypeORM集成)
|
||||
提供数据库ORM功能和Repository模式。
|
||||
|
||||
### typeorm (来自 TypeORM)
|
||||
提供数据库连接、实体定义、查询构建器等功能。
|
||||
|
||||
### class-validator (来自 验证库)
|
||||
提供DTO数据验证和约束检查。
|
||||
|
||||
### class-transformer (来自 转换库)
|
||||
提供数据转换和序列化功能。
|
||||
|
||||
## 核心特性
|
||||
|
||||
### 双存储模式支持
|
||||
- 数据库模式：使用TypeORM连接MySQL，适用于生产环境
|
||||
- 内存模式：使用Map存储，适用于开发测试和故障降级
|
||||
- 动态模块配置：通过ZulipAccountsModule.forDatabase()和forMemory()灵活切换
|
||||
- 环境自适应：根据数据库配置自动选择合适的存储模式
|
||||
|
||||
### 数据完整性保障
|
||||
- 唯一性约束检查：游戏用户ID、Zulip用户ID、邮箱地址的唯一性
|
||||
- 数据验证：使用class-validator进行输入验证和格式检查
|
||||
- 事务支持：批量操作支持回滚机制，确保数据一致性
|
||||
- 关联关系管理：与Users表建立一对一关系，维护数据完整性
|
||||
|
||||
### 业务逻辑完备性
|
||||
- 状态管理：支持active、inactive、suspended、error四种状态
|
||||
- 验证机制：提供账号验证、重试机制、错误处理等功能
|
||||
- 统计分析：提供状态统计、错误账号查询等分析功能
|
||||
- 批量操作：支持批量状态更新、批量查询等高效操作
|
||||
|
||||
### 错误处理和监控
|
||||
- 统一异常处理：ConflictException、NotFoundException等标准异常
|
||||
- 日志记录：详细的操作日志和错误信息记录
|
||||
- 性能监控：操作耗时统计和性能指标收集
|
||||
- 重试机制：失败操作的自动重试和计数管理
|
||||
|
||||
## 潜在风险
|
||||
|
||||
### 数据一致性风险
|
||||
- 内存模式数据在应用重启后会丢失，不适用于生产环境的持久化需求
|
||||
- 建议仅在开发测试环境使用内存模式，生产环境必须使用数据库模式
|
||||
- 需要定期备份重要的账号关联数据，防止数据丢失
|
||||
|
||||
### 并发操作风险
|
||||
- 内存模式的ID生成和唯一性检查在高并发场景可能存在竞态条件
|
||||
- 数据库模式依赖数据库的事务机制，但仍需注意死锁问题
|
||||
- 建议在高并发场景下使用数据库模式，并合理设计事务边界
|
||||
|
||||
### 性能瓶颈风险
|
||||
- 批量操作在数据量大时可能影响数据库性能
|
||||
- 统计查询可能在大数据量时响应缓慢
|
||||
- 建议添加适当的数据库索引，并考虑分页查询和缓存机制
|
||||
|
||||
### 安全风险
|
||||
- Zulip API Key以加密形式存储，但加密密钥的管理需要特别注意
|
||||
- 账号关联信息涉及用户隐私，需要严格的访问控制
|
||||
- 建议定期轮换加密密钥，并审计敏感操作的访问日志
|
||||
|
||||
## 使用示例
|
||||
|
||||
### 基本使用
|
||||
```typescript
|
||||
// 创建账号关联
|
||||
const createDto: CreateZulipAccountDto = {
|
||||
gameUserId: '12345',
|
||||
zulipUserId: 67890,
|
||||
zulipEmail: 'user@example.com',
|
||||
zulipFullName: '张三',
|
||||
zulipApiKeyEncrypted: 'encrypted_key',
|
||||
status: 'active'
|
||||
};
|
||||
const account = await zulipAccountsService.create(createDto);
|
||||
|
||||
// 查询账号关联
|
||||
const found = await zulipAccountsService.findByGameUserId('12345');
|
||||
|
||||
// 批量更新状态
|
||||
const result = await zulipAccountsService.batchUpdateStatus([1, 2, 3], 'inactive');
|
||||
```
|
||||
|
||||
### 模块配置
|
||||
```typescript
|
||||
// 数据库模式
|
||||
@Module({
|
||||
imports: [ZulipAccountsModule.forDatabase()],
|
||||
})
|
||||
export class AppModule {}
|
||||
|
||||
// 内存模式
|
||||
@Module({
|
||||
imports: [ZulipAccountsModule.forMemory()],
|
||||
})
|
||||
export class TestModule {}
|
||||
|
||||
// 自动模式选择
|
||||
@Module({
|
||||
imports: [ZulipAccountsModule.forRoot()],
|
||||
})
|
||||
export class AutoModule {}
|
||||
```
|
||||
|
||||
## 版本信息
|
||||
- **版本**: 1.1.1
|
||||
- **作者**: angjustinl
|
||||
- **创建时间**: 2025-01-05
|
||||
- **最后修改**: 2026-01-07
|
||||
|
||||
## 已知问题和改进建议
|
||||
- 考虑添加Redis缓存层提升查询性能
|
||||
- 优化批量操作的事务处理机制
|
||||
- 增强内存模式的并发安全性
|
||||
- 完善监控指标和告警机制
|
||||
|
||||
## 最近修改记录
|
||||
- 2026-01-07: 代码规范优化 - 功能文档生成，补充使用示例和版本信息更新 (修改者: moyin)
|
||||
- 2026-01-07: 代码规范优化 - 创建缺失的测试文件，完善测试覆盖 (修改者: moyin)
|
||||
- 2026-01-05: 功能开发 - 初始版本创建，实现基础功能 (修改者: angjustinl)
|
||||
Reference in New Issue
Block a user