feat: implement comprehensive badge system with categories (#574)

src/app.module.ts

@@ -21,6 +21,7 @@ import { DataPipelineModule } from './data-pipeline/data-pipeline.module';
 import { CanaryModule } from './canary/canary.module';
 import { IncidentManagementModule } from './incident-management/incident-management.module';
 import { MonitoringModule } from './monitoring/monitoring.module';
+import { GamificationModule } from './gamification/gamification.module';
 import { I18nModule as AppI18nModule } from './i18n/i18n.module';
 import { AchievementsModule } from './achievements/achievements.module';
 
@@ -68,6 +69,7 @@ const featureFlags = loadFeatureFlags();
     CanaryModule,
     IncidentManagementModule,
     MonitoringModule,
+    GamificationModule,
     ShardingModule,
     IdempotencyModule,
     DeepLinkModule,

src/gamification/badges/badge-definitions.ts

@@ -0,0 +1,98 @@
+import { BadgeCategory } from '../enums/badge-category.enum';
+import { BadgeCriteriaType } from '../enums/badge-criteria-type.enum';
+
+export const DEFAULT_BADGES = [
+  // --- LEARNING ---
+  {
+    name: 'First Step',
+    description: 'Complete your first course',
+    category: BadgeCategory.LEARNING,
+    criteriaType: BadgeCriteriaType.COURSES_COMPLETED,
+    criteriaValue: { threshold: 1 },
+    points: 50,
+  },
+  {
+    name: 'Course Collector',
+    description: 'Complete 5 courses',
+    category: BadgeCategory.LEARNING,
+    criteriaType: BadgeCriteriaType.COURSES_COMPLETED,
+    criteriaValue: { threshold: 5 },
+    points: 200,
+  },
+  {
+    name: 'Scholar',
+    description: 'Complete 20 courses',
+    category: BadgeCategory.LEARNING,
+    criteriaType: BadgeCriteriaType.COURSES_COMPLETED,
+    criteriaValue: { threshold: 20 },
+    points: 500,
+  },
+  {
+    name: 'Week Warrior',
+    description: 'Maintain a 7-day learning streak',
+    category: BadgeCategory.LEARNING,
+    criteriaType: BadgeCriteriaType.LEARNING_STREAK_DAYS,
+    criteriaValue: { threshold: 7 },
+    points: 150,
+  },
+  // --- ASSESSMENT ---
+  {
+    name: 'Perfectionist',
+    description: 'Score 100% on an assessment',
+    category: BadgeCategory.ASSESSMENT,
+    criteriaType: BadgeCriteriaType.ASSESSMENT_PERFECT_SCORE,
+    criteriaValue: { threshold: 1 },
+    points: 100,
+  },
+  {
+    name: 'Test Ace',
+    description: 'Pass 10 assessments',
+    category: BadgeCategory.ASSESSMENT,
+    criteriaType: BadgeCriteriaType.ASSESSMENTS_PASSED,
+    criteriaValue: { threshold: 10 },
+    points: 300,
+  },
+  // --- ACHIEVEMENT ---
+  {
+    name: 'Point Collector',
+    description: 'Earn 1,000 points',
+    category: BadgeCategory.ACHIEVEMENT,
+    criteriaType: BadgeCriteriaType.POINTS_REACHED,
+    criteriaValue: { threshold: 1000 },
+    points: 100,
+  },
+  {
+    name: 'High Achiever',
+    description: 'Reach Level 5',
+    category: BadgeCategory.ACHIEVEMENT,
+    criteriaType: BadgeCriteriaType.LEVEL_REACHED,
+    criteriaValue: { threshold: 5 },
+    points: 250,
+  },
+  // --- SOCIAL ---
+  {
+    name: 'Critic',
+    description: 'Write your first course review',
+    category: BadgeCategory.SOCIAL,
+    criteriaType: BadgeCriteriaType.REVIEWS_WRITTEN,
+    criteriaValue: { threshold: 1 },
+    points: 50,
+  },
+  {
+    name: 'Reviewer',
+    description: 'Write 10 course reviews',
+    category: BadgeCategory.SOCIAL,
+    criteriaType: BadgeCriteriaType.REVIEWS_WRITTEN,
+    criteriaValue: { threshold: 10 },
+    points: 150,
+  },
+  // --- CONTRIBUTION ---
+  {
+    name: 'Creator',
+    description: 'Publish your first course',
+    category: BadgeCategory.CONTRIBUTION,
+    criteriaType: BadgeCriteriaType.COURSES_CREATED,
+    criteriaValue: { threshold: 1 },
+    points: 200,
+  },
+];

src/gamification/badges/badges.controller.ts

@@ -0,0 +1,129 @@
+import {
+  Controller,
+  Get,
+  Post,
+  Param,
+  Body,
+  Query,
+  UseGuards,
+  ParseUUIDPipe,
+} from '@nestjs/common';
+import { ApiTags, ApiOperation, ApiBearerAuth } from '@nestjs/swagger';
+import { BadgesService } from './badges.service';
+import { LeaderboardService } from '../leaderboards/leaderboards.service';
+import { CreateBadgeDto, BadgeFilterDto, LeaderboardQueryDto } from '../dto/badge.dto';
+import { JwtAuthGuard } from '../../auth/guards/jwt-auth.guard';
+import { CurrentUser } from '../../auth/decorators/current-user.decorator';
+import { BadgeCategory } from '../enums/badge-category.enum';
+
+@ApiTags('Gamification - Badges')
+@ApiBearerAuth()
+@UseGuards(JwtAuthGuard)
+@Controller('gamification')
+export class BadgesController {
+  constructor(
+    private readonly badgesService: BadgesService,
+    private readonly leaderboardService: LeaderboardService,
+  ) {}
+
+  // ─── Badges ───────────────────────────────────────────────────────────────
+
+  @Get('badges')
+  @ApiOperation({ summary: 'Get all badges, optionally filtered by category' })
+  getAllBadges(@Query() filter: BadgeFilterDto) {
+    return this.badgesService.getAllBadges(filter);
+  }
+
+  @Get('badges/categories')
+  @ApiOperation({ summary: 'Get all badge categories' })
+  getCategories() {
+    return Object.values(BadgeCategory);
+  }
+
+  @Get('badges/category/:category')
+  @ApiOperation({ summary: 'Get badges by category' })
+  getBadgesByCategory(@Param('category') category: BadgeCategory) {
+    return this.badgesService.getBadgesByCategory(category);
+  }
+
+  @Get('badges/:id')
+  @ApiOperation({ summary: 'Get a badge by ID' })
+  getBadge(@Param('id', ParseUUIDPipe) id: string) {
+    return this.badgesService.getBadgeById(id);
+  }
+
+  @Post('badges')
+  @ApiOperation({ summary: 'Create a new badge definition (admin)' })
+  createBadge(@Body() dto: CreateBadgeDto) {
+    return this.badgesService.createBadge(dto);
+  }
+
+  @Post('badges/seed')
+  @ApiOperation({ summary: 'Seed default badge definitions (admin/dev)' })
+  seedBadges() {
+    return this.badgesService.seedDefaultBadges();
+  }
+
+  // ─── My Badges ────────────────────────────────────────────────────────────
+
+  @Get('my/badges')
+  @ApiOperation({ summary: 'Get all badges earned by the current user' })
+  getMyBadges(@CurrentUser() user: { id: string }) {
+    return this.badgesService.getUserBadges(user.id);
+  }
+
+  @Get('my/badges/category/:category')
+  @ApiOperation({ summary: 'Get current user badges filtered by category' })
+  getMyBadgesByCategory(
+    @CurrentUser() user: { id: string },
+    @Param('category') category: BadgeCategory,
+  ) {
+    return this.badgesService.getUserBadgesByCategory(user.id, category);
+  }
+
+  @Get('my/badges/count')
+  @ApiOperation({ summary: 'Get total badge count for current user' })
+  async getMyBadgeCount(@CurrentUser() user: { id: string }) {
+    const count = await this.badgesService.getUserBadgeCount(user.id);
+    return { count };
+  }
+
+  // ─── Leaderboards ─────────────────────────────────────────────────────────
+
+  @Get('leaderboard/points')
+  @ApiOperation({ summary: 'Get top players by points' })
+  getPointsLeaderboard(@Query() query: LeaderboardQueryDto) {
+    return this.leaderboardService.getTopPlayers(query.limit ?? 10);
+  }
+
+  @Get('leaderboard/badges')
+  @ApiOperation({ summary: 'Get top players by badge count' })
+  getBadgeLeaderboard(@Query() query: LeaderboardQueryDto) {
+    return this.leaderboardService.getBadgeLeaderboard(query.limit ?? 10, query.category);
+  }
+
+  @Get('leaderboard/my-rank')
+  @ApiOperation({ summary: 'Get current user rank on the points leaderboard' })
+  async getMyRank(@CurrentUser() user: { id: string }) {
+    const rank = await this.leaderboardService.getUserRank(user.id);
+    return { rank };
+  }
+
+  @Get('leaderboard/my-badge-rank')
+  @ApiOperation({ summary: 'Get current user rank on the badge leaderboard' })
+  async getMyBadgeRank(
+    @CurrentUser() user: { id: string },
+    @Query('category') category?: BadgeCategory,
+  ) {
+    const rank = await this.leaderboardService.getUserBadgeRank(user.id, category);
+    return { rank };
+  }
+
+  // ─── Other Users ──────────────────────────────────────────────────────────
+
+  @Get('users/:userId/badges')
+  @ApiOperation({ summary: 'Get badges for a specific user' })
+  getUserBadges(@Param('userId', ParseUUIDPipe) userId: string) {
+    return this.badgesService.getUserBadges(userId);
+  }
+}