Skip to content

Latest commit

 

History

History
178 lines (128 loc) · 4.79 KB

PHASE13_EXECUTION.md

File metadata and controls

178 lines (128 loc) · 4.79 KB

Phase 13: Gamification - Execution Log

Date: 2026-02-02

Objective

Implement gamification system with XP, levels, badges, and leaderboards.

Implementation Summary

1. Badge Entity

Created Badge.cs with:

  • Tenant isolation (ITenantEntity)
  • Slug, Name, Description, Icon fields
  • XpReward for awarding XP when badge earned
  • IsActive flag for enabling/disabling badges
  • SortOrder for display ordering
  • Predefined badge slugs (FirstListing, FirstConnection, etc.)

2. UserBadge Entity

Created UserBadge.cs with:

  • User/Badge junction
  • EarnedAt timestamp
  • Unique constraint (one badge per user)

3. XpLog Entity

Created XpLog.cs with:

  • User reference
  • Amount, Source, ReferenceId, Description fields
  • Predefined sources (listing_created, connection_made, etc.)
  • Default XP amounts for various actions

4. User Entity Updates

Added to User.cs:

  • TotalXp field (cumulative XP earned)
  • Level field (calculated from XP)
  • UserBadges navigation property
  • XpLogs navigation property
  • Static methods for level calculation

5. GamificationService

Created GamificationService.cs with:

  • AwardXpAsync() - Awards XP and handles level-ups
  • AwardBadgeAsync() - Awards badges with XP rewards
  • CheckAndAwardBadgesAsync() - Automatic badge checks based on actions

6. Database Configuration

Added to NexusDbContext:

  • badges, user_badges, xp_logs tables
  • Global query filters for tenant isolation
  • Unique constraints for badge slugs and user badges

7. GamificationController Endpoints

Method Endpoint Description
GET /api/gamification/profile Current user's gamification profile
GET /api/gamification/profile/{userId} Another user's profile
GET /api/gamification/badges All available badges with earned status
GET /api/gamification/badges/my Current user's earned badges
GET /api/gamification/leaderboard XP leaderboard (all/week/month/year)
GET /api/gamification/xp-history Current user's XP history

8. XP Integration

Added XP awards to existing controllers:

  • ListingsController: XP for creating listings
  • ConnectionsController: XP for accepted connections
  • WalletController: XP for completed transactions
  • GroupsController: XP for creating groups
  • EventsController: XP for creating events
  • FeedController: XP for creating posts and comments

9. Badge Seeding

Added 10 badges per tenant to SeedData:

  • First Listing (25 XP)
  • First Connection (25 XP)
  • First Transaction (30 XP)
  • First Post (15 XP)
  • Event Host (30 XP)
  • Helpful Neighbor (100 XP) - 10 transactions
  • Community Builder (50 XP) - created a group
  • Event Organizer (75 XP) - 5 events
  • Popular Post (40 XP) - 10+ likes
  • Veteran (100 XP) - 1 year member

To Apply Migration

# Start the Docker stack (migrations run automatically)
docker compose up -d

# Or run migrations manually inside container
docker compose exec api dotnet ef database update

Test Script

Run after API is running:

powershell -ExecutionPolicy Bypass -File "C:\Users\jaspe\AppData\Local\Temp\claude\c--xampp-htdocs-asp-net-backend\18a553b7-f5b3-4456-9c43-ff9a0cd73a0b\scratchpad\test-gamification.ps1"

Files Created

New Files

  • src/Nexus.Api/Entities/Badge.cs
  • src/Nexus.Api/Entities/UserBadge.cs
  • src/Nexus.Api/Entities/XpLog.cs
  • src/Nexus.Api/Services/GamificationService.cs
  • src/Nexus.Api/Controllers/GamificationController.cs

Modified Files

  • src/Nexus.Api/Entities/User.cs - Added TotalXp, Level, helper methods
  • src/Nexus.Api/Data/NexusDbContext.cs - Added 3 new DbSets and configurations
  • src/Nexus.Api/Data/SeedData.cs - Added badge seeding
  • src/Nexus.Api/Program.cs - Registered GamificationService
  • src/Nexus.Api/Controllers/ListingsController.cs - Added XP integration
  • src/Nexus.Api/Controllers/ConnectionsController.cs - Added XP integration
  • src/Nexus.Api/Controllers/WalletController.cs - Added XP integration
  • src/Nexus.Api/Controllers/GroupsController.cs - Added XP integration
  • src/Nexus.Api/Controllers/EventsController.cs - Added XP integration
  • src/Nexus.Api/Controllers/FeedController.cs - Added XP integration

XP Rewards

Action XP Amount
Create listing 10
Make connection 5
Complete transaction 20
Create post 5
Create event 15
Attend event 10
Create group 20
Add comment 2

Level System

Levels are calculated using the formula: XP needed for level N = 50 × N × (N - 1)

Level XP Required
1 0
2 100
3 300
4 600
5 1000
10 4500
20 19000

Test Results

=== Phase 13: Gamification Tests ===

(Run the test script after migration to populate results)

Phase 13 Complete ✓