Gamification features (draft)

.github/workflows/test.yml

@@ -88,4 +88,4 @@ jobs:
           source venv/bin/activate
           export NLTK_DATA=$ZEEGUU_RESOURCES_FOLDER/nltk_data
           export DEV_SKIP_TRANSLATION=1
-          pytest
+          python -m pytest

Dockerfile

@@ -24,13 +24,14 @@ COPY ./setup.py /Zeeguu-API/setup.py
 
 WORKDIR /Zeeguu-API
 
+# RUN python -m pip install --upgrade pip setuptools
 # Install Python requirements with BuildKit cache mount
 # Cache persisted via buildkit-cache-dance action to GitHub Actions cache
 RUN --mount=type=cache,target=/root/.cache/pip \
     echo "=== Pip cache before install ===" && \
     ls -lah /root/.cache/pip 2>/dev/null || echo "Cache empty (first build)" && \
-    python -m pip install -r requirements.txt && \
-    python -m pip install gunicorn && \
+    python -m pip install --default-timeout=300 -r requirements.txt && \
+    python -m pip install --default-timeout=300 gunicorn && \
     echo "=== Pip cache after install ===" && \
     du -sh /root/.cache/pip
 

tools/migrations/26-02-19--add_badges.sql

@@ -0,0 +1,41 @@
+-- tools/migrations/26-02-19--add_badge_and_user_badge_tables.sql
+
+CREATE TABLE badge (
+    id INT AUTO_INCREMENT PRIMARY KEY,
+    code VARCHAR(100) NOT NULL,
+    name VARCHAR(100) NOT NULL,
+    description TEXT,
+    UNIQUE(code)
+);
+
+CREATE TABLE badge_level (
+    id INT AUTO_INCREMENT PRIMARY KEY,
+    badge_id INT NOT NULL,
+    name VARCHAR(100),
+    level INT NOT NULL,
+    target_value INT NOT NULL,
+    icon_name VARCHAR(255),
+    UNIQUE(badge_id, level),
+    FOREIGN KEY (badge_id) REFERENCES badge(id)
+);
+
+CREATE TABLE user_badge_level (
+    id INT AUTO_INCREMENT PRIMARY KEY,
+    user_id INT NOT NULL,
+    badge_level_id INT NOT NULL,
+    achieved_at DATETIME DEFAULT NULL,
+    is_shown BOOLEAN DEFAULT FALSE,
+    UNIQUE(user_id, badge_level_id),
+    FOREIGN KEY (user_id) REFERENCES user(id),
+    FOREIGN KEY (badge_level_id) REFERENCES badge_level(id)
+);
+
+CREATE TABLE user_badge_progress (
+    id INT AUTO_INCREMENT PRIMARY KEY,
+    user_id INT NOT NULL,
+    badge_id INT NOT NULL,
+    current_value INT NOT NULL,
+    UNIQUE(user_id, badge_id),
+    FOREIGN KEY (user_id) REFERENCES user(id),
+    FOREIGN KEY (badge_id) REFERENCES badge(id)
+);

tools/migrations/26-02-24-a-add_username.sql

@@ -0,0 +1,21 @@
+ALTER TABLE user
+ADD COLUMN username VARCHAR(50);
+
+-- This is maybe needed
+SET SQL_SAFE_UPDATES = 0;
+
+-- Option 1 user_<id>
+UPDATE user
+SET username = CONCAT('user_', id)
+WHERE id IS NOT NULL
+AND username IS NULL;
+
+-- In that case remember to enable it again
+SET SQL_SAFE_UPDATES = 1;
+
+-- Change the column to be not null and unique
+ALTER TABLE user
+MODIFY username VARCHAR(50) NOT NULL;
+
+ALTER TABLE user
+ADD CONSTRAINT unique_username UNIQUE (username);

tools/migrations/26-02-24-b-add_username.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python
+"""
+Migration script to automatically populate usernames for existing users.
+
+The usernames are generated in the format 'adjective_noun1234' (e.g., 'brave_tiger5678')
+and are guaranteed to be unique across the user base. 
+This script should be run after the database schema has been updated to include the new 'username' column in the 'user' table.
+
+26-02-24-a-add_username.sql should have been run first to add the 'username' column to the 'user' table.
+
+Run with: source ~/.venvs/z_env/bin/activate && python tools/migrations/26-02-24-b-add_username.py
+"""
+import sys
+import os
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
+
+from zeeguu.core.model.user import User
+from zeeguu.core.model import db
+
+def generate_unique_username():
+
+    while True:
+        username = User.generate_username()
+        exists = User.query.filter_by(username=username).first()
+        if not exists:
+            return username
+
+def populate_usernames():
+    users : list[User] = User.query.all()
+    for user in users:
+        user.username = generate_unique_username()
+    db.session.commit()
+
+
+if __name__ == "__main__":
+
+    from zeeguu.api.app import create_app
+    from zeeguu.core.model import db
+
+    app = create_app()
+    app.app_context().push()
+
+    print("Starting random username population...")
+    populate_usernames()
+    print("Username population completed.")

tools/migrations/26-02-24-friendship_system.sql

@@ -0,0 +1,25 @@
+-- friends table
+CREATE TABLE friends (
+    id INT AUTO_INCREMENT PRIMARY KEY,
+    user_id INT NOT NULL,
+    friend_id INT NOT NULL,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    friend_streak INT DEFAULT 0,
+    friend_streak_last_updated DATETIME,
+    CONSTRAINT unique_user_friend UNIQUE (user_id, friend_id),
+    CONSTRAINT unique_friend_user UNIQUE (friend_id, user_id),
+    FOREIGN KEY (user_id) REFERENCES user(id),
+    FOREIGN KEY (friend_id) REFERENCES user(id)
+);
+
+-- Friend requests table
+CREATE TABLE friend_requests (
+    id INT AUTO_INCREMENT PRIMARY KEY,
+    sender_id INT NOT NULL,
+    receiver_id INT NOT NULL,
+    status ENUM('pending', 'accepted', 'rejected') DEFAULT 'pending',
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    responded_at DATETIME,
+    FOREIGN KEY (sender_id) REFERENCES user(id),
+    FOREIGN KEY (receiver_id) REFERENCES user(id)
+);

tools/migrations/26-02-26--add_max_streak_to_user_language.sql

@@ -0,0 +1,10 @@
+-- Add max_streak tracking to user_language table
+ALTER TABLE user_language
+ADD COLUMN max_streak INT NOT NULL DEFAULT 0,
+ADD COLUMN max_streak_date DATETIME NULL;
+
+-- Seed max_streak from current daily_streak for users with active streaks
+UPDATE user_language
+SET max_streak = daily_streak,
+    max_streak_date = last_practiced
+WHERE daily_streak > 0;

tools/migrations/26-02-28--insert_default_badges.sql

@@ -0,0 +1,62 @@
+-- tools/migrations/26-02-28--insert_default_badge.sql
+
+INSERT INTO badge (id, code, name, description)
+VALUES
+        (1, 'TRANSLATED_WORDS', 'Meaning Builder', 'Translate {target_value} unique words while reading.'),
+        (2, 'CORRECT_EXERCISES', 'Practice Builder', 'Solve {target_value} exercises correctly.'),
+        (3, 'COMPLETED_AUDIO_LESSONS', 'Sound Scholar', 'Complete {target_value} audio lessons.'),
+        (4, 'STREAK_COUNT', 'Consistency Champion', 'Maintain a streak for {target_value} days.'),
+        (5, 'LEARNED_WORDS', 'Word Collector', 'Learn {target_value} new words.'),
+        (6, 'READ_ARTICLES', 'Active Reader', 'Read {target_value} articles.'),
+        (7, 'NUMBER_OF_FRIENDS', 'Influencer', 'Add {target_value} friends.');
+
+INSERT INTO badge_level (id, badge_id, name, level, target_value, icon_name)
+VALUES
+        -- Translated Words
+        (1, 1, '', 1, 10, NULL),
+        (2, 1, '', 2, 100, NULL),
+        (3, 1, '', 3, 500, NULL),
+        (4, 1, '', 4, 1000, NULL),
+        (5, 1, '', 5, 2500, NULL),
+
+        -- Correct Exercises
+        (6, 2, '', 1, 10, NULL),
+        (7, 2, '', 2, 250, NULL),
+        (8, 2, '', 3, 1000, NULL),
+        (9, 2, '', 4, 5000, NULL),
+        (10, 2, '', 5, 20000, NULL),
+
+        -- Completed Audio Lessons
+        (11, 3, '', 1, 1, NULL),
+        (12, 3, '', 2, 25, NULL),
+        (13, 3, '', 3, 50, NULL),
+        (14, 3, '', 4, 150, NULL),
+        (15, 3, '', 5, 300, NULL),
+
+        -- Streak Count
+        (16, 4, '', 1, 7, NULL),
+        (17, 4, '', 2, 30, NULL),
+        (18, 4, '', 3, 90, NULL),
+        (19, 4, '', 4, 180, NULL),
+        (20, 4, '', 5, 365, NULL),
+
+        -- Learned Words
+        (21, 5, '', 1, 1, NULL),
+        (22, 5, '', 2, 10, NULL),
+        (23, 5, '', 3, 50, NULL),
+        (24, 5, '', 4, 250, NULL),
+        (25, 5, '', 5, 750, NULL),
+
+        -- Read Articles
+        (26, 6, '', 1, 5, NULL),
+        (27, 6, '', 2, 25, NULL),
+        (28, 6, '', 3, 100, NULL),
+        (29, 6, '', 4, 500, NULL),
+        (30, 6, '', 5, 1000, NULL),
+
+        -- Number of Friends
+        (31, 7, '', 1, 1, NULL),
+        (32, 7, '', 2, 3, NULL),
+        (33, 7, '', 3, 5, NULL),
+        (34, 7, '', 4, 7, NULL),
+        (35, 7, '', 5, 10, NULL);

tools/migrations/26-03-13--add_user_avatar.sql

@@ -0,0 +1,9 @@
+CREATE TABLE user_avatar (
+    id INT AUTO_INCREMENT PRIMARY KEY,
+    user_id INT NOT NULL,
+    image_name VARCHAR(100),
+    character_color VARCHAR(7),
+    background_color VARCHAR(7),
+    UNIQUE(user_id),
+    FOREIGN KEY (user_id) REFERENCES user(id)
+);

zeeguu/api/endpoints/__init__.py

@@ -48,3 +48,5 @@
 from . import user_stats
 from . import session_history
 from . import daily_streak
+from . import badges
+from . import friends

zeeguu/api/endpoints/activity_tracking.py

@@ -1,12 +1,13 @@
 import flask
 from flask import request
+
+from zeeguu.api.utils.route_wrappers import cross_domain, requires_session
+from zeeguu.core.badges.badge_progress import increment_badge_progress, BadgeCode
+from zeeguu.core.model import UserActivityData, User
 from zeeguu.core.user_activity_hooks.article_interaction_hooks import (
     distill_article_interactions,
 )
-
 from . import api, db_session
-from zeeguu.api.utils.route_wrappers import cross_domain, requires_session
-from zeeguu.core.model import UserActivityData, User
 
 
 @api.route("/upload_user_activity_data", methods=["POST"])
@@ -102,10 +103,10 @@ def _check_and_notify_article_completion_on_scroll(user, form_data):
             # Debug: log the scroll data structure
             from zeeguu.logging import log
             log(f"[article_completion] Scroll data received: {scroll_data[:3] if isinstance(scroll_data, list) and len(scroll_data) > 3 else scroll_data}")
-            
+
             # Use a more lenient approach or fallback to max percentage
             completion_percentage = find_last_reading_percentage(scroll_data, max_jump=50, max_total_update=80)
-            
+
             # Fallback: if the algorithm returns 0 but we have scroll data, use max percentage
             if completion_percentage == 0 and scroll_data:
                 max_percentage = max([point[1] for point in scroll_data if len(point) >= 2]) / 100.0
@@ -135,6 +136,9 @@ def _check_and_notify_article_completion_on_scroll(user, form_data):
 
             user_article.completed_at = datetime.now()
 
+            # Update READ_ARTICLES badge progress
+            increment_badge_progress(db_session, BadgeCode.READ_ARTICLES, user.id)
+
             # Send notification if enabled
             from flask import current_app