User Progress & Gamification (v1)

Training / chapter / lesson completion + quiz/exam progress + score leaderboard

It does NOT modify the existing quiz/exam progress-tracking endpoints. Those (start_student_quiz, finish_student_quiz, save_student_quiz_result, show_quiz_student_answers, reset_student_attempts) remain the single writer of attempts/answers and are documented in Quizzes & Exams progress tracking. This controller only reads their tables.

​

Table of Contents

1. Overview
2. Base URL and Headers
3. How progress is computed (sources of truth)
4. How the gamification score is computed
5. Authorization & company scoping
6. Endpoints
   • 6.1 Training Progress (detailed, one training)
   • 6.2 Trainings Progress (summary list)
   • 6.3 Quiz/Exam Progress (per-question breakdown)
   • 6.4 Quizzes/Exams Progress (summary list)
   • 6.5 Gamification Score (recompute + rank)
   • 6.6 Leaderboard (top-N)
   • 6.7 Recompute Scores (bulk, staff)
7. Per-question correctness model
8. Configuration
9. History Tracking Actions
10. Related Files
11. Future Suggestions

​

1. Overview

• Lesson completion — a row in the student_lesson pivot (written by LessonsController@toggle_lesson_validation).
• Quiz/exam attempts & scores — rows in quiz_student_attempts / quiz_student_answers (written by the progress-tracking controller).

• Per-training progress — which lessons are completed per chapter, how many quizzes are passed, and overall progress %.
• Per-quiz/exam progress — best score, pass state, and a per-question right/wrong breakdown for any attempt.
• A gamification score per user (users.gamification_score) and a top-N leaderboard for the company.

​

2. Base URL and Headers

{{base_url}}/api

Accept: application/json
Authorization: Bearer {{token}}

​

3. How progress is computed (sources of truth)

⚠️ passed_at is NOT used as the pass signal. In the existing tracking controller passed_at is set unconditionally whenever a result is saved, so it does not by itself mean “passed”. The reliable signal is score_percentage >= passing_percentage, which is what this controller uses everywhere.

lessons_progress_%  = completed_lessons / total_lessons * 100
quizzes_progress_%  = passed_quizzes   / total_quizzes  * 100
overall_progress_%  = (completed_lessons + passed_quizzes) / (total_lessons + total_quizzes) * 100

​

4. How the gamification score is computed

gamification_score = (distinct completed lessons      × POINTS_PER_LESSON)        // default 10
                   + (distinct passed quizzes/exams    × POINTS_PER_QUIZ_PASSED)   // default 50

• Idempotent / no double-counting — each completed lesson and each distinct passed quiz/exam is counted exactly once, no matter how many attempts or re-toggles happened.
• Stored denormalized in users.gamification_score (an unsignedInteger, indexed) purely for fast leaderboard reads. It is rebuilt from the sources of truth by GamificationService, never hand-edited.
• It is separate from loyalty_points (which is monetary / convertible to coupons). Gamification score is a learning/achievement metric only.

• On demand for one user via GET /api/progress/score (recomputes that user before returning).
• In bulk for a whole company via POST /api/progress/recompute-scores (run before showing a fresh leaderboard).

​

5. Authorization & company scoping

• Company scoping is manual. Every endpoint requires company_id; CompanyPolicyMiddleware guarantees it matches the caller’s company (super-admin bypasses).
• Who can view a student’s progress:
  • A student may view only their own progress (student_id defaults to the caller).
  • Staff (super-admin, admin, content-manager, instructor) may view any student in their company by passing student_id.
  • Otherwise → 403.
• Recompute (bulk) is staff-only → 403 for students.

​

6. Endpoints

​

6.1 Training Progress (detailed)

GET /api/progress/training/{training_id}

{
  "training_id": 12,
  "training_label": "Intro to Laravel",
  "student_id": 87,
  "summary": {
    "lessons_total": 20,
    "lessons_completed": 13,
    "lessons_progress_percentage": 65.0,
    "quizzes_total": 4,
    "quizzes_passed": 2,
    "quizzes_progress_percentage": 50.0,
    "overall_progress_percentage": 62.5,
    "is_completed": false
  },
  "chapters": [
    {
      "chapter_id": 31,
      "label": "Getting Started",
      "position": 1,
      "lessons_total": 5,
      "lessons_completed": 5,
      "lessons_progress_percentage": 100.0,
      "lessons": [
        { "lesson_id": 101, "label": "Install", "position": 1, "completed": true }
      ],
      "quizzes": [
        { "quiz_id": 9, "label": "Chapter quiz", "passing_percentage": 75.0, "passed": true }
      ]
    }
  ]
}

​

6.2 Trainings Progress (summary list)

GET /api/progress/trainings

{
  "student_id": 87,
  "data": [
    {
      "training_id": 12,
      "training_label": "Intro to Laravel",
      "slug": "intro-to-laravel",
      "lessons_total": 20,
      "lessons_completed": 13,
      "quizzes_total": 4,
      "quizzes_passed": 2,
      "overall_progress_percentage": 62.5,
      "is_completed": false
    }
  ],
  "current_page": 1, "per_page": 15, "total": 3, "last_page": 1
}

​

6.3 Quiz/Exam Progress (per-question breakdown)

GET /api/progress/quiz/{quiz_id}

{
  "quiz_id": 9,
  "quiz_label": "Final Exam",
  "is_exam": true,
  "student_id": 87,
  "passing_percentage": 75.0,
  "summary": {
    "attempts_count": 3,
    "finished_attempts_count": 3,
    "best_score_percentage": 90.0,
    "passed": true,
    "questions_total": 10
  },
  "attempts": [
    {
      "attempt_id": 555, "attempt": 1, "finished_at": "2026-06-01 10:00:00",
      "correct_answers": 6, "uncorrect_answers": 4, "score_percentage": 60.0,
      "passed": false, "passed_at": "2026-06-01 10:10:00"
    }
  ],
  "reviewed_attempt": {
    "attempt_id": 557,
    "attempt": 3,
    "questions_correct": 9,
    "questions_total": 10,
    "questions": [
      {
        "question_id": 401,
        "label": "What is Eloquent?",
        "type_id": 2,
        "is_correct": true,
        "explanation": "Laravel's ORM.",
        "selected_option_ids": [12],
        "selected_option_item_ids": [],
        "options": [
          { "option_id": 12, "label": "An ORM", "is_correct": true,  "selected": true  },
          { "option_id": 13, "label": "A queue",  "is_correct": false, "selected": false }
        ]
      }
    ]
  }
}

reviewed_attempt is null if the student has no attempts on this quiz. passed (in summary/attempts) is derived from score_percentage >= passing_percentage.

​

6.4 Quizzes/Exams Progress (summary list)

GET /api/progress/quizzes

{
  "quiz_id": 9,
  "quiz_label": "Final Exam",
  "is_exam": true,
  "training_id": null,
  "chapter_id": null,
  "passing_percentage": 75.0,
  "attempts_count": 3,
  "best_score_percentage": 90.0,
  "passed": true
}

​

6.5 Gamification Score (recompute + rank)

GET /api/progress/score

{
  "student_id": 87,
  "company_id": 1,
  "rank": 4,
  "breakdown": {
    "lessons_completed": 13,
    "quizzes_passed": 2,
    "points_per_lesson": 10,
    "points_per_quiz_passed": 50,
    "lessons_score": 130,
    "quizzes_score": 100,
    "gamification_score": 230
  }
}

​

6.6 Leaderboard (top-N)

GET /api/progress/leaderboard

{
  "company_id": 1,
  "role_id": 1,
  "limit": 10,
  "points_per_lesson": 10,
  "points_per_quiz_passed": 50,
  "leaderboard": [
    { "rank": 1, "user_id": 5,  "first_name": "Sara",  "last_name": "B", "image_id": 22, "gamification_score": 540 },
    { "rank": 2, "user_id": 87, "first_name": "Omar",  "last_name": "K", "image_id": null, "gamification_score": 230 }
  ],
  "me": { "user_id": 87, "rank": 2, "gamification_score": 230 }
}

​

6.7 Recompute Scores (bulk, staff)

POST /api/progress/recompute-scores

{
  "message": "Gamification scores recomputed.",
  "company_id": 1,
  "users_updated": 412
}

​

7. Per-question correctness model

​

8. Configuration

'gamification' => [
    'points_per_lesson'      => env('GAMIFICATION_POINTS_PER_LESSON', 10),
    'points_per_quiz_passed' => env('GAMIFICATION_POINTS_PER_QUIZ_PASSED', 50),
    'leaderboard_size'       => env('GAMIFICATION_LEADERBOARD_SIZE', 10),
],

​

9. History Tracking Actions

​

10. Related Files

​

11. Future Suggestions

1. Real-time score updates. Today the score is recomputed on demand (/score) or in bulk (/recompute-scores). To make the leaderboard live without a bulk job, add a small recompute hook in the two places completion happens:
   • after LessonsController@toggle_lesson_validation attaches/detaches a lesson, call GamificationService::recomputeForUser($student);
   • after save_student_quiz_result persists a passing score, do the same. These are additive (no behavioural change to the existing tracking) but were left out to honour the “do not touch the quiz/exam tracking” constraint. A model observer on QuizStudentAttempt is an alternative that keeps the controller untouched.
2. A score-event ledger (gamification_score_events: user_id, source_type, source_id, points, awarded_at) for a full audit trail and “how did I earn this” UI, while keeping users.gamification_score as the denormalized cache. Enables streaks, daily caps, and reversals.
3. Badges / achievements (badges, badge_user pivot) — e.g. “First Course Completed”, “Perfect Exam”, “7-day streak”. The current score is the foundation; badges become rule evaluations over the same sources of truth.
4. Streaks — consecutive-day activity from student_lesson.created_at and attempt timestamps; bonus points for maintaining streaks.
5. Cross-company / global leaderboard for super-admins (a scope=global option), and time-windowed leaderboards (weekly/monthly) using the score-event ledger.
6. Configurable weights per company — move point values into loyalty_points_settings-style per-company rows instead of global config, so each tenant tunes its own gamification.
7. Caching the leaderboard (e.g. 1–5 min cache) for high-traffic tenants, invalidated on recompute-scores.
8. Completion certificates trigger — when overall_progress_percentage hits 100, auto-suggest issuing the training certificate (ties into the existing certification module).