Self hosted FLOSS fitness/workout, nutrition and weight tracker
Add Phase 8: Documentation & Finalization
Jeremy8bd378c5f844
diff --git a/wger/trophies/README.md b/wger/trophies/README.mdnew file mode 100644index 000000000..0a03a2474--- /dev/null+++ b/wger/trophies/README.md@@ -0,0 +1,380 @@+# Trophy System++The trophy (achievement) system allows users to earn trophies based on their workout activities.++## Features++- **Multiple Trophy Types**: Time-based, volume-based, count-based, sequence-based, date-based, and custom trophies+- **Progressive Trophies**: Show user progress towards earning a trophy+- **Hidden Trophies**: Secret achievements that are revealed only when earned+- **Automatic Evaluation**: Trophies are evaluated automatically when workout data changes+- **Statistics Tracking**: Denormalized statistics for efficient trophy evaluation+- **API Endpoints**: Full REST API for trophy data and progress tracking++## Configuration++### Global Settings++Add to your `settings.py` or `settings_global.py`:++```python+WGER_SETTINGS = {+ # Enable/disable the trophy system globally+ 'TROPHIES_ENABLED': True,++ # Number of days of inactivity before skipping trophy evaluation for a user+ 'TROPHIES_INACTIVE_USER_DAYS': 30,+}+```++### User Preferences++Users can enable/disable trophies in their profile settings via the `trophies_enabled` field on `UserProfile`.++## Database Models++### Trophy+Defines an achievement that users can earn.++**Fields:**+- `name`: Trophy name+- `description`: How to earn it+- `trophy_type`: Type (time, volume, count, sequence, date, other)+- `checker_class`: Python class that checks if trophy is earned (e.g., 'count_based')+- `checker_params`: JSON parameters for the checker (e.g., `{'count': 10}`)+- `is_hidden`: Hidden until earned+- `is_progressive`: Shows progress percentage+- `is_active`: Can be earned (admins can disable)+- `order`: Display order++### UserTrophy+Links users to their earned trophies.++**Fields:**+- `user`: User who earned the trophy+- `trophy`: The trophy earned+- `earned_at`: Timestamp when earned+- `progress`: Progress percentage (0-100)+- `is_notified`: For future notification system++### UserStatistics+Denormalized statistics for efficient trophy checking.++**Fields:**+- `user`: OneToOne with User+- `total_weight_lifted`: Cumulative weight in kg+- `total_workouts`: Number of workout sessions+- `current_streak`: Current consecutive workout days+- `longest_streak`: Longest streak ever achieved+- `earliest_workout_time`: Earliest workout time ever+- `latest_workout_time`: Latest workout time ever+- `weekend_workout_streak`: Consecutive weekends with workouts+- `last_complete_weekend_date`: Last Saturday with both days worked+- `worked_out_jan_1`: Has worked out on any January 1st+- `last_inactive_date`: Last workout before 30+ day gap++## Trophy Checkers++Trophy checkers are Python classes that determine if a user has earned a trophy.++### Available Checkers++1. **count_based**: Check if user reached a count+ - Params: `{'count': 10}`+ - Example: "Complete 10 workouts"++2. **streak**: Check for consecutive day streaks+ - Params: `{'days': 30}`+ - Example: "30-day workout streak"++3. **weekend_warrior**: Check for consecutive complete weekends+ - Params: `{'weekends': 4}`+ - Example: "Work out on Saturday AND Sunday for 4 weekends"++4. **volume**: Check for cumulative weight lifted+ - Params: `{'kg': 5000}`+ - Example: "Lift 5,000 kg total"++5. **time_based**: Check for workout at specific time+ - Params: `{'before': '06:00'}` or `{'after': '21:00'}`+ - Example: "Work out before 6:00 AM"++6. **date_based**: Check for workout on specific date+ - Params: `{'month': 1, 'day': 1}`+ - Example: "Work out on January 1st"++7. **inactivity_return**: Check for return after inactivity+ - Params: `{'inactive_days': 30}`+ - Example: "Return to training after 30 days inactive"++## Management Commands++### Load Trophies++Load the initial set of trophies into the database:++```bash+# Load new trophies (skip existing)+python manage.py load_trophies++# Update existing trophies+python manage.py load_trophies --update++# Verbose output+python manage.py load_trophies -v 2+```++### Evaluate Trophies++Manually trigger trophy evaluation:++```bash+# Evaluate for a specific user+python manage.py evaluate_trophies --user username++# Evaluate a specific trophy for all users+python manage.py evaluate_trophies --trophy 5++# Evaluate all trophies for all active users+python manage.py evaluate_trophies --all++# Force re-evaluation (check already earned trophies)+python manage.py evaluate_trophies --all --force-reevaluate+```++### Recalculate Statistics++Rebuild user statistics from workout history:++```bash+# Recalculate for a specific user+python manage.py recalculate_statistics --user username++# Recalculate for all users+python manage.py recalculate_statistics --all++# Recalculate for active users only+python manage.py recalculate_statistics --all --active-only+```++## API Endpoints++### Trophy Endpoints++```+GET /api/v2/trophy/+ List all active trophies+ - Hidden trophies excluded unless earned by user++GET /api/v2/trophy/{id}/+ Get specific trophy details++GET /api/v2/trophy/progress/+ Get progress for all trophies (current user)+ - Returns earned status and progress percentage+ - Includes current/target values for progressive trophies+```++### User Trophy Endpoints++```+GET /api/v2/user-trophy/+ List current user's earned trophies+ - Ordered by earned_at (newest first)++GET /api/v2/user-trophy/{id}/+ Get specific earned trophy details+```++### User Statistics Endpoints++```+GET /api/v2/user-statistics/+ Get current user's trophy statistics+```++## Adding New Trophies++### Method 1: Using Code (Recommended for new trophy types)++1. **Create a new checker class** (if needed) in `wger/trophies/checkers/`:++```python+# wger/trophies/checkers/my_checker.py+from .base import BaseTrophyChecker++class MyCustomChecker(BaseTrophyChecker):+ def check(self) -> bool:+ # Your logic here+ return True++ def get_progress(self) -> float:+ # Calculate progress 0-100+ return 50.0++ def get_current_value(self):+ return "current"++ def get_target_value(self):+ return "target"+```++2. **Register the checker** in `wger/trophies/checkers/registry.py`:++```python+from .my_checker import MyCustomChecker++class CheckerRegistry:+ _registry: Dict[str, Type[BaseTrophyChecker]] = {+ # ... existing checkers ...+ 'my_custom': MyCustomChecker,+ }+```++3. **Add the trophy** via Django admin or shell:++```python+from wger.trophies.models import Trophy++Trophy.objects.create(+ name="My Custom Trophy",+ description="Description of how to earn it",+ trophy_type=Trophy.TYPE_OTHER,+ checker_class='my_custom',+ checker_params={'param1': 'value1'},+ is_hidden=False,+ is_progressive=True,+ order=100,+)+```++### Method 2: Using Existing Checkers++Simply create a new Trophy object with an existing checker:++```python+Trophy.objects.create(+ name="Heavy Lifter",+ description="Lift 10,000 kg total",+ trophy_type=Trophy.TYPE_VOLUME,+ checker_class='volume',+ checker_params={'kg': 10000},+ is_progressive=True,+ order=50,+)+```++### Method 3: Using Fixtures++Create a JSON fixture in `wger/trophies/fixtures/`:++```json+[+ {+ "model": "trophies.trophy",+ "pk": 10,+ "fields": {+ "name": "My Trophy",+ "description": "Description",+ "trophy_type": "count",+ "checker_class": "count_based",+ "checker_params": {"count": 100},+ "is_hidden": false,+ "is_progressive": true,+ "is_active": true,+ "order": 100+ }+ }+]+```++Load with: `python manage.py loaddata my_trophies`++## How It Works++### Signal-Based Updates++When a user logs a workout:++1. `WorkoutSession` or `WorkoutLog` is saved+2. Django signal fires (`post_save`)+3. `UserStatisticsService.increment_workout()` updates statistics incrementally+4. `TrophyService.evaluate_all_trophies()` checks for newly earned trophies+5. Earned trophies create `UserTrophy` records++### Celery Tasks (Optional)++For async evaluation:++```python+from wger.trophies.tasks import evaluate_user_trophies_task++# Evaluate asynchronously+evaluate_user_trophies_task.delay(user_id)+```++### Performance Considerations++- **Denormalized Statistics**: `UserStatistics` table provides O(1) lookups+- **Incremental Updates**: Statistics update incrementally, not full recalculation+- **Inactive User Skipping**: Users inactive >30 days are skipped+- **Bulk Operations**: Batch evaluation supports chunking for large user sets++## Testing++Run the trophy test suite:++```bash+# All trophy tests+python manage.py test wger.trophies.tests++# Specific test files+python manage.py test wger.trophies.tests.test_models+python manage.py test wger.trophies.tests.test_checkers+python manage.py test wger.trophies.tests.test_services+python manage.py test wger.trophies.tests.test_api+python manage.py test wger.trophies.tests.test_integration+```++## Initial Trophies++The system includes 9 initial trophies:++1. **Beginner**: Complete your first workout+2. **Unstoppable**: Maintain a 30-day workout streak+3. **Weekend Warrior**: Work out on Saturday and Sunday for 4 consecutive weekends+4. **Lifter**: Lift a cumulative total of 5,000 kg+5. **Atlas**: Lift a cumulative total of 100,000 kg+6. **Early Bird**: Complete a workout before 6:00 AM+7. **Night Owl**: Complete a workout after 9:00 PM+8. **New Year, New Me**: Work out on January 1st+9. **Phoenix** (Hidden): Return to training after being inactive for 30 days++Load them with: `python manage.py load_trophies`++## Troubleshooting++### Trophies not being awarded++1. Check if trophy system is enabled: `TROPHIES_ENABLED = True`+2. Check user's profile: `user.userprofile.trophies_enabled`+3. Check user activity: Not inactive >30 days+4. Check trophy is active: `trophy.is_active = True`+5. Recalculate statistics: `python manage.py recalculate_statistics --user username`++### Statistics not updating++1. Check signals are connected (should happen automatically)+2. Manually recalculate: `python manage.py recalculate_statistics --all`+3. Check for errors in logs++### Performance issues++1. Add database indexes (already included in migrations)+2. Enable Celery for async evaluation+3. Adjust `TROPHIES_INACTIVE_USER_DAYS` to skip more users+4. Disable trophies for inactive users in bulk++## License++AGPL-3.0 (same as wger Workout Manager)diff --git a/wger/trophies/api/views.py b/wger/trophies/api/views.pyindex 7af17c1ba..566c7d256 100644--- a/wger/trophies/api/views.py+++ b/wger/trophies/api/views.py@@ -15,6 +15,10 @@# along with this program. If not, see <http://www.gnu.org/licenses/>.# Third Party+from drf_spectacular.utils import (+ OpenApiResponse,+ extend_schema,+)from rest_framework import viewsetsfrom rest_framework.decorators import actionfrom rest_framework.response import Response@@ -83,6 +87,24 @@ class TrophyViewSet(viewsets.ReadOnlyModelViewSet):# Anonymous users only see non-hidden trophiesreturn queryset.filter(is_hidden=False)+ @extend_schema(+ summary="Get trophy progress",+ description="""+ Return all trophies with progress information for the current user.++ For each trophy, returns:+ - Trophy information (id, name, description, type, etc.)+ - Whether the trophy has been earned+ - Earned timestamp (if earned)+ - Progress percentage (0-100)+ - Current and target values (for progressive trophies)++ Hidden trophies are excluded unless earned (or user is staff).+ """,+ responses={+ 200: TrophyProgressSerializer(many=True),+ },+ )@action(detail=False, methods=['get'])def progress(self, request):"""diff --git a/wger/trophies/migrations/0003_load_initial_trophies.py b/wger/trophies/migrations/0003_load_initial_trophies.pynew file mode 100644index 000000000..403e394c0--- /dev/null+++ b/wger/trophies/migrations/0003_load_initial_trophies.py@@ -0,0 +1,158 @@+# Generated by Django 5.2.9 on 2025-12-03 18:33++from django.db import migrations+++def load_initial_trophies(apps, schema_editor):+ """+ Load the initial set of 9 trophies.++ This migration is idempotent - it will skip trophies that already exist+ based on the trophy name.+ """+ Trophy = apps.get_model('trophies', 'Trophy')++ # Define the initial trophies (same as in load_trophies management command)+ trophies_data = [+ {+ 'name': 'Beginner',+ 'description': 'Complete your first workout',+ 'trophy_type': 'count',+ 'checker_class': 'count_based',+ 'checker_params': {'count': 1},+ 'is_hidden': False,+ 'is_progressive': False,+ 'order': 1,+ },+ {+ 'name': 'Unstoppable',+ 'description': 'Maintain a 30-day workout streak',+ 'trophy_type': 'sequence',+ 'checker_class': 'streak',+ 'checker_params': {'days': 30},+ 'is_hidden': False,+ 'is_progressive': True,+ 'order': 2,+ },+ {+ 'name': 'Weekend Warrior',+ 'description': 'Work out on Saturday and Sunday for 4 consecutive weekends',+ 'trophy_type': 'sequence',+ 'checker_class': 'weekend_warrior',+ 'checker_params': {'weekends': 4},+ 'is_hidden': False,+ 'is_progressive': True,+ 'order': 3,+ },+ {+ 'name': 'Lifter',+ 'description': 'Lift a cumulative total of 5,000 kg',+ 'trophy_type': 'volume',+ 'checker_class': 'volume',+ 'checker_params': {'kg': 5000},+ 'is_hidden': False,+ 'is_progressive': True,+ 'order': 4,+ },+ {+ 'name': 'Atlas',+ 'description': 'Lift a cumulative total of 100,000 kg',+ 'trophy_type': 'volume',+ 'checker_class': 'volume',+ 'checker_params': {'kg': 100000},+ 'is_hidden': False,+ 'is_progressive': True,+ 'order': 5,+ },+ {+ 'name': 'Early Bird',+ 'description': 'Complete a workout before 6:00 AM',+ 'trophy_type': 'time',+ 'checker_class': 'time_based',+ 'checker_params': {'before': '06:00'},+ 'is_hidden': False,+ 'is_progressive': False,+ 'order': 6,+ },+ {+ 'name': 'Night Owl',+ 'description': 'Complete a workout after 9:00 PM',+ 'trophy_type': 'time',+ 'checker_class': 'time_based',+ 'checker_params': {'after': '21:00'},+ 'is_hidden': False,+ 'is_progressive': False,+ 'order': 7,+ },+ {+ 'name': 'New Year, New Me',+ 'description': 'Work out on January 1st',+ 'trophy_type': 'date',+ 'checker_class': 'date_based',+ 'checker_params': {'month': 1, 'day': 1},+ 'is_hidden': False,+ 'is_progressive': False,+ 'order': 8,+ },+ {+ 'name': 'Phoenix',+ 'description': 'Return to training after being inactive for 30 days',+ 'trophy_type': 'other',+ 'checker_class': 'inactivity_return',+ 'checker_params': {'inactive_days': 30},+ 'is_hidden': True,+ 'is_progressive': False,+ 'order': 9,+ },+ ]++ created_count = 0+ skipped_count = 0++ for trophy_data in trophies_data:+ # Check if trophy already exists+ if not Trophy.objects.filter(name=trophy_data['name']).exists():+ Trophy.objects.create(**trophy_data)+ created_count += 1+ else:+ skipped_count += 1++ if created_count > 0:+ print(f'Trophy migration: Created {created_count} trophies, skipped {skipped_count}')+++def reverse_load_trophies(apps, schema_editor):+ """+ Reverse migration - delete the initial trophies.++ This is optional and can be left as a no-op if you want to keep+ trophies even when rolling back migrations.+ """+ Trophy = apps.get_model('trophies', 'Trophy')++ trophy_names = [+ 'Beginner',+ 'Unstoppable',+ 'Weekend Warrior',+ 'Lifter',+ 'Atlas',+ 'Early Bird',+ 'Night Owl',+ 'New Year, New Me',+ 'Phoenix',+ ]++ deleted_count = Trophy.objects.filter(name__in=trophy_names).delete()[0]+ if deleted_count > 0:+ print(f'Trophy migration reverse: Deleted {deleted_count} trophies')+++class Migration(migrations.Migration):++ dependencies = [+ ('trophies', '0002_add_last_complete_weekend_date'),+ ]++ operations = [+ migrations.RunPython(load_initial_trophies, reverse_load_trophies),+ ]