# Leaderboard Service 架构设计文档 ## 1. 概述 Leaderboard Service（龙虎榜服务）是一个基于 NestJS 框架的微服务，负责管理和展示用户的团队认种排名。服务采用 **领域驱动设计（DDD）** 结合 **六边形架构（Hexagonal Architecture）** 的设计模式。 ### 1.1 核心功能 - **日榜/周榜/月榜管理**: 支持多种时间周期的排行榜 - **排名计算**: 基于团队认种数据计算龙虎榜分值 - **虚拟排名**: 支持系统虚拟账户占位显示 - **实时更新**: 定时刷新排名数据 - **缓存优化**: Redis 缓存热点数据 ### 1.2 技术栈 | 组件 | 技术 | 版本 | |------|------|------| | 框架 | NestJS | 10.x | | 语言 | TypeScript | 5.x | | 数据库 | PostgreSQL | 15.x | | ORM | Prisma | 5.x | | 缓存 | Redis (ioredis) | 7.x | | 消息队列 | Kafka (kafkajs) | 2.x | | 认证 | JWT + Passport | - | | API 文档 | Swagger | 7.x | ## 2. 架构设计 ### 2.1 六边形架构（端口与适配器） ``` ┌─────────────────────────────────────────┐ │ API Layer │ │ (Controllers, DTOs, Guards, Swagger) │ └─────────────────┬───────────────────────┘ │ ┌─────────────────▼───────────────────────┐ │ Application Layer │ │ (Application Services, Schedulers) │ └─────────────────┬───────────────────────┘ │ ┌─────────────────────────────┼─────────────────────────────┐ │ │ │ │ ┌────────────────▼────────────────┐ │ │ │ Domain Layer │ │ │ │ (Aggregates, Entities, VOs, │ │ │ │ Domain Services, Events) │ │ │ └────────────────┬────────────────┘ │ │ │ │ └─────────────────────────────┼─────────────────────────────┘ │ ┌─────────────────▼───────────────────────┐ │ Infrastructure Layer │ │ (Repositories, External Services, │ │ Cache, Messaging, Database) │ └─────────────────────────────────────────┘ ``` ### 2.2 目录结构 ``` src/ ├── api/ # API 层（入站适配器） │ ├── controllers/ # HTTP 控制器 │ │ ├── health.controller.ts │ │ ├── leaderboard.controller.ts │ │ ├── leaderboard-config.controller.ts │ │ └── virtual-account.controller.ts │ ├── dto/ # 数据传输对象 │ │ ├── leaderboard.dto.ts │ │ ├── leaderboard-config.dto.ts │ │ └── virtual-account.dto.ts │ ├── guards/ # 认证守卫 │ │ ├── jwt-auth.guard.ts │ │ └── admin.guard.ts │ ├── decorators/ # 自定义装饰器 │ │ ├── public.decorator.ts │ │ └── current-user.decorator.ts │ └── strategies/ # Passport 策略 │ └── jwt.strategy.ts │ ├── application/ # 应用层 │ ├── services/ # 应用服务 │ │ └── leaderboard-application.service.ts │ └── schedulers/ # 定时任务 │ └── leaderboard-refresh.scheduler.ts │ ├── domain/ # 领域层（核心业务逻辑） │ ├── aggregates/ # 聚合根 │ │ ├── leaderboard-ranking/ │ │ │ └── leaderboard-ranking.aggregate.ts │ │ └── leaderboard-config/ │ │ └── leaderboard-config.aggregate.ts │ ├── entities/ # 实体 │ │ └── virtual-account.entity.ts │ ├── value-objects/ # 值对象 │ │ ├── leaderboard-type.enum.ts │ │ ├── leaderboard-period.vo.ts │ │ ├── ranking-score.vo.ts │ │ ├── rank-position.vo.ts │ │ ├── user-snapshot.vo.ts │ │ └── virtual-account-type.enum.ts │ ├── events/ # 领域事件 │ │ ├── domain-event.base.ts │ │ ├── leaderboard-refreshed.event.ts │ │ ├── config-updated.event.ts │ │ └── ranking-changed.event.ts │ ├── repositories/ # 仓储接口（端口） │ │ ├── leaderboard-ranking.repository.interface.ts │ │ ├── leaderboard-config.repository.interface.ts │ │ └── virtual-account.repository.interface.ts │ └── services/ # 领域服务 │ ├── leaderboard-calculation.service.ts │ ├── virtual-ranking-generator.service.ts │ └── ranking-merger.service.ts │ ├── infrastructure/ # 基础设施层（出站适配器） │ ├── database/ # 数据库 │ │ └── prisma.service.ts │ ├── repositories/ # 仓储实现 │ │ ├── leaderboard-ranking.repository.impl.ts │ │ ├── leaderboard-config.repository.impl.ts │ │ └── virtual-account.repository.impl.ts │ ├── cache/ # 缓存服务 │ │ ├── redis.service.ts │ │ └── leaderboard-cache.service.ts │ ├── messaging/ # 消息队列 │ │ ├── kafka.service.ts │ │ ├── event-publisher.service.ts │ │ └── event-consumer.service.ts │ └── external/ # 外部服务客户端 │ ├── referral-service.client.ts │ └── identity-service.client.ts │ ├── modules/ # NestJS 模块定义 │ ├── domain.module.ts │ ├── infrastructure.module.ts │ ├── application.module.ts │ └── api.module.ts │ ├── app.module.ts # 应用根模块 └── main.ts # 应用入口 ``` ## 3. 领域模型设计 ### 3.1 聚合根 #### LeaderboardRanking（排名聚合） ```typescript class LeaderboardRanking { // 标识 id: bigint; // 榜单信息 leaderboardType: LeaderboardType; // DAILY | WEEKLY | MONTHLY period: LeaderboardPeriod; // 用户信息 userId: bigint; isVirtual: boolean; // 排名信息 rankPosition: RankPosition; // 实际排名 displayPosition: RankPosition; // 显示排名 previousRank: RankPosition | null; // 分值信息 score: RankingScore; // 用户快照 userSnapshot: UserSnapshot; } ``` #### LeaderboardConfig（配置聚合） ```typescript class LeaderboardConfig { // 标识 id: bigint; configKey: string; // 榜单开关 dailyEnabled: boolean; weeklyEnabled: boolean; monthlyEnabled: boolean; // 虚拟排名设置 virtualRankingEnabled: boolean; virtualAccountCount: number; // 显示设置 displayLimit: number; refreshIntervalMinutes: number; } ``` ### 3.2 值对象 #### RankingScore（排名分值） ```typescript // 龙虎榜分值计算公式： // effectiveScore = totalTeamPlanting - maxDirectTeamPlanting class RankingScore { totalTeamPlanting: number; // 团队总认种 maxDirectTeamPlanting: number; // 最大单个直推团队认种 effectiveScore: number; // 有效分值（龙虎榜分值） static calculate(total: number, maxDirect: number): RankingScore { const effective = Math.max(0, total - maxDirect); return new RankingScore(total, maxDirect, effective); } } ``` #### LeaderboardPeriod（周期） ```typescript class LeaderboardPeriod { key: string; // 2024-01-15 | 2024-W03 | 2024-01 startAt: Date; endAt: Date; static currentDaily(): LeaderboardPeriod; static currentWeekly(): LeaderboardPeriod; static currentMonthly(): LeaderboardPeriod; } ``` ### 3.3 领域事件 | 事件 | 触发时机 | 数据 | |------|----------|------| | LeaderboardRefreshedEvent | 榜单刷新完成 | type, period, rankings | | ConfigUpdatedEvent | 配置变更 | configKey, changes | | RankingChangedEvent | 用户排名变化 | userId, oldRank, newRank | ## 4. 数据模型 ### 4.1 数据库表设计 ``` ┌─────────────────────────────────────────────────────────────────┐ │ leaderboard_rankings │ ├─────────────────────────────────────────────────────────────────┤ │ ranking_id (PK) │ 排名ID │ │ leaderboard_type │ 榜单类型 (DAILY/WEEKLY/MONTHLY) │ │ period_key │ 周期标识 │ │ user_id │ 用户ID │ │ is_virtual │ 是否虚拟账户 │ │ rank_position │ 实际排名 │ │ display_position │ 显示排名 │ │ previous_rank │ 上次排名 │ │ total_team_planting │ 团队总认种 │ │ max_direct_team_planting│ 最大直推团队认种 │ │ effective_score │ 有效分值 │ │ user_snapshot │ 用户快照 (JSON) │ │ period_start_at │ 周期开始时间 │ │ period_end_at │ 周期结束时间 │ │ calculated_at │ 计算时间 │ │ created_at │ 创建时间 │ ├─────────────────────────────────────────────────────────────────┤ │ UK: (leaderboard_type, period_key, user_id) │ │ IDX: (leaderboard_type, period_key, display_position) │ │ IDX: (leaderboard_type, period_key, effective_score DESC) │ └─────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────┐ │ leaderboard_configs │ ├─────────────────────────────────────────────────────────────────┤ │ config_id (PK) │ 配置ID │ │ config_key (UK) │ 配置键 (GLOBAL) │ │ daily_enabled │ 日榜开关 │ │ weekly_enabled │ 周榜开关 │ │ monthly_enabled │ 月榜开关 │ │ virtual_ranking_enabled │ 虚拟排名开关 │ │ virtual_account_count │ 虚拟账户数量 │ │ display_limit │ 显示数量限制 │ │ refresh_interval_minutes│ 刷新间隔（分钟） │ │ created_at │ 创建时间 │ │ updated_at │ 更新时间 │ └─────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────┐ │ virtual_accounts │ ├─────────────────────────────────────────────────────────────────┤ │ virtual_account_id (PK) │ 虚拟账户ID │ │ account_type │ 账户类型 │ │ display_name │ 显示名称 │ │ avatar │ 头像URL │ │ province_code │ 省份代码 │ │ city_code │ 城市代码 │ │ min_score │ 最小分值 │ │ max_score │ 最大分值 │ │ current_score │ 当前分值 │ │ usdt_balance │ USDT余额 │ │ hashpower_balance │ 算力余额 │ │ is_active │ 是否激活 │ │ created_at │ 创建时间 │ │ updated_at │ 更新时间 │ └─────────────────────────────────────────────────────────────────┘ ``` ### 4.2 缓存设计 ``` Redis Key 设计: leaderboard:{type}:{period}:rankings # 排名列表 (ZSET) leaderboard:{type}:{period}:user:{id} # 用户排名详情 (HASH) leaderboard:config # 全局配置 (HASH) leaderboard:virtual:accounts # 虚拟账户列表 (LIST) TTL: - 日榜: 10 分钟 - 周榜: 30 分钟 - 月榜: 1 小时 - 配置: 5 分钟 ``` ## 5. 核心业务流程 ### 5.1 排名刷新流程 ``` ┌─────────────┐ ┌──────────────┐ ┌─────────────────┐ │ Scheduler │────▶│ Application │────▶│ ReferralService │ │ (Cron) │ │ Service │ │ (External) │ └─────────────┘ └──────┬───────┘ └────────┬────────┘ │ │ │ 获取团队数据 │ │◀──────────────────────┘ │ ▼ ┌───────────────────────┐ │ LeaderboardCalculation│ │ Service │ │ - 计算有效分值 │ │ - 排序 │ │ - 生成排名 │ └───────────┬───────────┘ │ ▼ ┌───────────────────────┐ │ VirtualRanking │ │ Generator │ │ - 生成虚拟排名 │ └───────────┬───────────┘ │ ▼ ┌───────────────────────┐ │ RankingMerger │ │ - 合并真实/虚拟排名 │ │ - 调整显示位置 │ └───────────┬───────────┘ │ ┌─────────────────┼─────────────────┐ │ │ │ ▼ ▼ ▼ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ Database │ │ Cache │ │ Kafka │ │ (Persist) │ │ (Update) │ │ (Publish) │ └───────────────┘ └───────────────┘ └───────────────┘ ``` ### 5.2 排名查询流程 ``` ┌─────────┐ ┌────────────┐ ┌─────────┐ │ Client │────▶│ Controller │────▶│ Cache │ └─────────┘ └─────┬──────┘ └────┬────┘ │ │ │ Cache Hit? │ │◀────────────────┘ │ ┌───────┴───────┐ │ Yes No│ ▼ ▼ ┌──────────┐ ┌──────────┐ │ Return │ │ Database │ │ Cached │ │ Query │ └──────────┘ └────┬─────┘ │ ▼ ┌──────────┐ │ Update │ │ Cache │ └────┬─────┘ │ ▼ ┌──────────┐ │ Return │ └──────────┘ ``` ## 6. 安全设计 ### 6.1 认证与授权 | 端点 | 认证要求 | 权限要求 | |------|----------|----------| | GET /leaderboard/* | 无 (公开) | - | | GET /leaderboard/my-rank | JWT | 用户 | | GET /leaderboard/config | JWT | 管理员 | | POST /leaderboard/config/* | JWT | 管理员 | | * /virtual-accounts/* | JWT | 管理员 | ### 6.2 数据安全 - 用户敏感信息脱敏 - BigInt ID 防止遍历 - 输入验证与清洗 - SQL 注入防护 (Prisma) ## 7. 性能优化 ### 7.1 缓存策略 - **L1**: 应用内存缓存（热点数据） - **L2**: Redis 分布式缓存 - **缓存预热**: 服务启动时加载 ### 7.2 数据库优化 - 合理索引设计 - 分页查询 - 批量操作 - 读写分离（可选） ### 7.3 异步处理 - 排名计算异步执行 - 事件驱动更新 - 消息队列削峰 ## 8. 可观测性 ### 8.1 日志 ```typescript // 结构化日志 { level: 'info', timestamp: '2024-01-15T10:30:00Z', service: 'leaderboard-service', traceId: 'abc123', message: 'Leaderboard refreshed', context: { type: 'DAILY', period: '2024-01-15', totalRankings: 100 } } ``` ### 8.2 健康检查 - `/health` - 服务存活检查 - `/health/ready` - 服务就绪检查（含依赖） ### 8.3 指标 (Metrics) - 请求延迟 - 缓存命中率 - 排名计算耗时 - 数据库连接池状态 ## 9. 扩展性考虑 ### 9.1 水平扩展 - 无状态服务设计 - Redis 集群支持 - Kafka 分区消费 ### 9.2 垂直扩展 - 异步任务队列 - 数据库分片（未来） - 冷热数据分离