Auth User Optimize — Slim GET /auth/user

​

0. What shipped (19/10/2026) ✅

​

Table of contents

0. What shipped (19/10/2026)
1. What happens today (measured)
2. Why it is slow: three costs, not one
3. What the student app actually reads from the payload
4. Target shape of GET /auth/user (student)
5. Answers to the specific questions
6. Backend plan (LMS_Backend)
7. Frontend plan (LMS_Frontend, student side)
8. Documentation plan (LMS_Documentation)
9. Repo hygiene: the committed payload dump
10. Rollout order and compatibility
11. How to measure before / after
12. Out of scope (but related)

​

1. What happens today (measured)

​

1.1 The boot sequence on the web app

app start / F5 / login
  └─ app.dart:52-56  →  AppService.authUserAndRole()        (awaited: nothing is painted until it returns)
       ├─ GET /auth/user                                     1.5 MB for the sample student
       ├─ handleStudentRole()  app_service.dart:212-264      fans the payload out into 6 providers
       └─ GET /dashboard/user/{id}/progress   (:231)         awaited in series, after the first call

​

1.2 What the 1.5 MB is made of

​

1.3 Where the shape comes from

​

2. Why it is slow: three costs, not one

1. Database time (server). The eager-load tree is ~30 queries, but the $appends accessors add roughly 6 queries per Training and 5 per Quiz at serialization (reviews()->avg, reviews()->count, orders()->count ×2, chapters()->sum, chapters()->count). The sample serializes 4 trainings, 2 chapter quizzes, 7 exams (6 in orders + 1 in cart) → ~60 extra queries, each a real round-trip, and none of them are read by the student UI. Add the two notification queries and the wishlist/orders lazy loads that run inside the resource.
2. Bytes on the wire (network). 1.5 MB of JSON. If the Plesk/nginx vhost does not gzip application/json this is 1.5 MB on a Tunisian mobile connection; gzipped it is still ~150 KB that has to be decoded.
3. Parse and fan-out time (browser main thread). Dart’s jsonDecode + json_serializable fromJson for ~1 500 question objects, then handleStudentRole() and three separate call sites (overview_screen.dart:59-61, student_space.dart:27-29, student_statefulshell.dart:54-66) that walk orders[].trainings[].chapters[].lessons[] on every build to set lesson.isValidate. On CanvasKit web this all runs on the UI thread, so the spinner stays up while it runs.

​

3. What the student app actually reads from the payload

​

3.1 Read and needed at boot

​

3.2 Sent but never read by the Flutter app

​

3.3 Bugs caused by the current shape (they disappear with the new shape)

​

4. Target shape of GET /auth/user (student) (DONE ✅)

{
  // ── identity / profile (unchanged keys, trimmed list) ──────────────────────
  "id": 1, "company_id": 1, "role_id": 1,
  "first_name": "…", "last_name": "…", "email": "…", "phone_number": "…",
  "image_id": 12, "image": { "id": 12, "url": "…" },
  "birthday": null, "bio": null, "blocked_at": null, "two_factor_enabled": 0,
  "public_profile_about_me": null, "public_profile_skills": null,
  "public_profile_linkedin_url": null, "public_profile_verification": 0,
  "company": { "id": 1, "label": "…", "currency": "TND", "company_image": { … } },
  "role":    { "id": 1, "label": "Student", "permissions": [ … ] },   // keep: tiny, staff UI gates on it

  // ── notifications: 3 newest + unread count (was 10) ────────────────────────
  "notification_count": 2,
  "notifications": [ { "id": 9, "title": "…", "message": "…", "notification_type_id": 5,
                       "notif_read_status": 0, "created_at": "2026-10-12 09:41:03" } ],

  // ── cart: a badge, not the cart ────────────────────────────────────────────
  "cart_summary": { "id": 156, "items_count": 1, "total_price": 120, "discounted_price": 120 },

  // ── my trainings: one card per owned training (deduped, access_revoked = 0) ─
  "my_trainings": [
    {
      "id": 2, "label": "Business Analysis", "slug": "business-analysis", "level": "…",
      "duration": 1200, "views_count": 311, "updated_at": "2026-09-30 14:02:11",
      "image": { "id": 40, "url": "…" }, "badge_logo": { … } | null,
      "instructor": { "id": 7, "first_name": "…", "last_name": "…", "image_id": 3, "image": { … } },
      "total_chapters_count": 6, "total_lessons_count": 415, "total_quizzes_count": 1,
      "progress": {
        "lessons_completed": 26, "lessons_total": 415,
        "quizzes_passed": 0,     "quizzes_total": 1,
        "overall_progress_percentage": 6.25, "is_completed": false,
        "last_activity_at": "2026-10-11 18:20:44",     // max(student_lesson.created_at, attempt.created_at)
        "next_lesson_id": 1234                         // optional: first non-validated lesson in position order
      },
      "certification_id": null                         // id of the issued certificate, or null
    }
  ],

  // ── my exams: one card per owned exam (access_revoked = 0) ─────────────────
  "my_exams": [
    {
      "id": 22, "label": "Examen Blanc PMP 7 FR", "slug": "examen-blanc-pmp-7",
      "description": "…", "duration": 210, "break_interval": 0, "break_duration": 0,
      "max_attempts": 3, "passing_percentage": 70, "quiz_questions_count": 180,
      "updated_at": "2026-08-01 10:00:00", "image": { … } | null,
      "instructor": { "id": 7, "first_name": "…", "last_name": "…", "image_id": 3, "image": { … } },
      "attempts": {
        "used": 7, "allowed": 12, "reset_count": 3,     // allowed = null when max_attempts == 0 (unlimited)
        "remaining": 5,
        "best_score_percentage": 61.1, "passed": false,
        "last_attempt_at": "2026-07-10 13:10:34"
      },
      "certification_id": null
    }
  ],

  // ── small id lists the course player still needs ───────────────────────────
  "validated_lesson_ids": [ 101, 102, 118, … ],        // replaces `lessons[]`
  "certifications": [ { "id": 4, "certification_id": "CERT-TR00002-…", "training_id": 2, "quiz_id": null,
                        "created_at": "2026-09-01 11:00:00" } ]
}

​

5. Answers to the specific questions

​

5.1 “Why fetch the trainings with chapters, lessons and content after login?”

​

5.2 “Can the 26/300 lessons and 3/5 quizzes be computed in the backend?”

-- 1. totals per training (lessons)           → GROUP BY chapters.training_id
SELECT c.training_id, COUNT(l.id) AS lessons_total
FROM chapters c JOIN lessons l ON l.chapter_id = c.id
WHERE c.training_id IN (…owned…) AND c.deleted_at IS NULL AND l.deleted_at IS NULL
GROUP BY c.training_id;

-- 2. completed per training                   → same join + student_lesson
SELECT c.training_id, COUNT(*) AS lessons_completed
FROM student_lesson sl JOIN lessons l ON l.id = sl.lesson_id JOIN chapters c ON c.id = l.chapter_id
WHERE sl.student_id = ? AND sl.deleted_at IS NULL AND c.training_id IN (…) GROUP BY c.training_id;

-- 3. quizzes per training (training-level + chapter-level)
SELECT COALESCE(q.training_id, c.training_id) AS training_id, COUNT(*) AS quizzes_total, GROUP_CONCAT(q.id)
FROM quizzes q LEFT JOIN chapters c ON c.id = q.chapter_id
WHERE (q.training_id IN (…) OR c.training_id IN (…)) AND q.deleted_at IS NULL GROUP BY 1;

-- 4. passed quizzes per training (same rule as passedQuizIdsFor(): finished, score >= passing)
SELECT training_id, COUNT(DISTINCT a.quiz_id) FROM quiz_student_attempts a JOIN quizzes q … JOIN chapters …
WHERE a.student_id = ? AND a.finished_at IS NOT NULL AND a.score_percentage >= q.passing_percentage GROUP BY training_id;

​

5.3 “My Exams grid and the quiz-start page”

• The grid (/student-my-content/exams) reads only card fields plus questions.length. Send quiz_questions_count (one withCount('quiz_questions'), no question rows) and stop sending quiz_questions inside orders[].quizzes[]. The card’s “no questions” guard becomes quiz_questions_count == 0.
• The quiz-start page (/student-my-content/quiz-start/:id) already fetches what it needs when it opens: GET /quiz/{id} then GET /quiz/show_quiz_student_answers?quiz_id&is_exam=1. Keep that. Two fixes there: hoist the FutureProvider out of build() (it refires on every rebuild, quiz_home_main.dart:91-92), and stop shipping the answer key on GET /quiz/{id} to students before an attempt is finished (clean_up.md G.1 #5–6; out of scope for this file but the same is_correct problem).

​

5.4 “How and where are exam attempts calculated, and what is the fastest way?”

SELECT quiz_id, COUNT(*) AS used, MAX(attempt) AS max_attempt, MAX(score_percentage) AS best,
       MAX(created_at) AS last_attempt_at,
       SUM(finished_at IS NOT NULL AND score_percentage >= ?) …      -- or compare to quizzes.passing_percentage via JOIN
FROM quiz_student_attempts WHERE student_id = ? AND quiz_id IN (…owned exams…) GROUP BY quiz_id;

SELECT quiz_id, COUNT(*) AS reset_count FROM quiz_student_resets WHERE student_id = ? AND quiz_id IN (…) GROUP BY quiz_id;

​

5.5 “Attempts page: fetch only when /student-my-content/attempts opens”

​

5.6 Dates: 2026-06-19T07:40:12.000000Z vs serializeDate, cost, and which dates to keep

1. Pick one wire format for the whole API and stick to it. The existing convention is Y-m-d H:i:s in Africa/Tunis (backend CLAUDE.md §8), and the Flutter code depends on it (passedAt.substring(0,16) in exam_attempts_datasource.dart:107). Keep it. In resources, emit dates through the model format ($this->created_at?->format('Y-m-d H:i:s'), or a tiny Dates::wire() helper) instead of the raw Carbon. If one day the app needs real timezone handling for users outside Tunisia, switch everything to toIso8601String() (2026-06-19T07:40:12+01:00) in one release; do not mix.
2. Only send dates the UI shows. In the student payload that is: my_trainings[].updated_at (the “Last updated MM/yyyy” chip), my_trainings[].progress.last_activity_at, my_exams[].attempts.last_attempt_at, notifications[].created_at, certifications[].created_at. Attempt rows (on their own page) keep created_at, finished_at, passed_at. Drop updated_at, deleted_at, archived_at, pivot timestamps everywhere else.
3. Frontend: parse once, not on every build. Give the Dart models DateTime? fields with a small JsonConverter (Y-m-d H:i:s ⇄ DateTime) instead of String? + DateTime.parse inside build() (glass_training_card.dart:636-643, helper.dart:351,384). Formatting for display (MM/yyyy, “3 h ago”) stays in the client because it is locale-dependent (en/fr/ar).

​

5.7 Notifications: 3 at boot instead of 10

​

5.8 Cart

​

6. Backend plan (LMS_Backend) (DONE ✅)

​

6.1 New payload builder (whitelist pattern, like MarketplacePreviewService / ClassroomPayloadService)

build(User $user): array
├─ base(User)               profile scalars + image + company + role(+permissions)
├─ notifications(User)      3 newest (6 columns) + unread count          2 queries
├─ studentBlocks(User)      only when $user->isStudent()
│   ├─ ownedTrainingIds / ownedExamIds   via orders (type 3, status 4/5, access_revoked = 0)   1 query
│   │                                     (reuse the logic of MarketplacePreviewService::ownedTrainingIds();
│   │                                      do NOT use User::trainings()/exams(), they are miswired — CLAUDE.md §12)
│   ├─ trainingCards        Training::whereIn('id')->select(card columns)->with(image, badge_logo, instructor:safe cols)
│   │                         ->withCount('chapters')->withSum('chapters', 'lessons_count')   1–3 queries
│   │                       → setAppends([]) on each model (or ->toBase()) so Training::$appends never fire
│   ├─ trainingProgress     the 4 grouped queries of §5.2, keyed by training_id             4 queries
│   ├─ examCards            Quiz::whereIn('id')->isExam()->without('instructor')->withCount('quiz_questions')
│   │                         ->with(image, instructor:safe cols)                              1–2 queries
│   ├─ examAttempts         the 2 grouped queries of §5.4, keyed by quiz_id                   2 queries
│   ├─ validatedLessonIds   DB::table('student_lesson')->where(student_id)->whereNull(deleted_at)->pluck(lesson_id)   1 query
│   ├─ certifications       select id, certification_id, training_id, quiz_id, created_at   1 query
│   └─ cartSummary          Order type 2 + order_items count + totals                        1 query
└─ dates through one helper → 'Y-m-d H:i:s'

​

6.2 AuthController::auth_user()

• Replace the User::with([...]) block + UserResource::make() with User::with(['image','company.companyImage','role.permissions'])->find(auth()->id()) and response()->json(app(AuthUserPayloadService::class)->build($user)). Keep $this->authorize('view', $user).
• Transition flag (see §10): while the frontend switches, accept ?legacy=1 to return the old UserResource so a stale web bundle keeps working; delete the flag and UserResource’s order/attempt branches afterwards.

​

6.3 Related endpoints (small, same release)

​

6.4 Indexes (migration)

• student_lesson (student_id, lesson_id, deleted_at)
• quiz_student_attempts (student_id, quiz_id) and (quiz_id, student_id, finished_at)
• order_items (order_id, training_id) / (order_id, quiz_id) if not already there
• notifications (student_id, notif_archive_status, created_at)

​

6.5 Tests (tests/Feature/AuthUserPayloadTest.php, SQLite like the other exposure tests)

1. Student payload has my_trainings, my_exams, validated_lesson_ids, cart_summary, certifications, 3 notifications max.
2. Student payload never contains the strings is_correct, "content", quiz_questions", explanation, revenue_percentage, an instructor email, or the keys orders / quiz_student_attempts / lessons.
3. Revoked exams/trainings are excluded; a training bought twice appears once.
4. Progress numbers match fixtures (26 validated lessons → lessons_completed: 26; a passed quiz → quizzes_passed: 1).
5. attempts.allowed is null for max_attempts = 0, equals max_attempts * (reset_count + 1) otherwise.
6. Every date in the payload matches /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.
7. Staff payload has no student blocks; query count assertion (DB::enableQueryLog, expect ≤ 15).

​

6.6 Clean-up in the same pass

• UserResource.php: delete the dead commented blocks and the wishlist/orders lazy ->load() branches once the legacy flag is gone. Keep the class if admin tooling uses it (grep UserResource first).
• Training::$appends / Quiz::$appends: nothing in this plan removes them globally (other endpoints rely on them), but every list-type endpoint should opt out (setAppends([]) or ->withAvg/withCount instead). Note it in clean_up.md G.2 as a follow-up.
• Update LMS_Backend/CLAUDE.md §10/§12 with a line: “GET /auth/user is whitelist-based (AuthUserPayloadService); extend by adding to the whitelist, never by loading relations on the user.”
• Update clean_up.md G.2 row “GET /auth/user” to ✅ when done.

​

7. Frontend plan (LMS_Frontend, student side) (DONE ✅)

​

7.1 Models (lib/core/data/remote/…, then dart run build_runner build -d)

​

7.2 Boot (lib/core/providers/app_service.dart)

• handleStudentRole(): fill StudentTrainingProvider.myTrainings from user.myTrainings, QuizProvider.myExams from user.myExams, certificateStudent from user.certifications, NotificationProvider from the 3 notifications + count, CartProvider from cartSummary, StudentTrainingProvider.validatedLessonIds from user.validatedLessonIds. Delete the orders[].trainings / orders[].quizzes access_revoked filters (the backend already filtered) and the studentQuizAttempts / studentExamAttempts assignment.
• Do not await GET /dashboard/user/{id}/progress in series at boot (:231). Either fire it from the “Learning activity” card when it mounts or run it in Future.wait with /auth/user.
• Send ?legacy=0 (or nothing once the backend default flips, see §10).

​

7.3 Progress widgets: read, don’t compute

• TrainingProgressProvider (training_progress_provider.dart:54-66): remove validateLessonsInTraining at boot and the per-build calls in overview_screen.dart:59-61, student_space.dart:27-29, student_statefulshell.dart:54-66. allTrainingsWithProgress becomes a thin wrapper around myTrainings (each already carries progress).
• ContinueLearningCard (continue_learning_card.dart:136-173), enrolled_training_screens.dart:170-188, learner_progress_cards.dart:151-205, overview_screen.dart:640-655: replace calculateValidatedLessons / calculateTotalItems / quizzes.where(passed) with training.progress.lessonsCompleted / lessonsTotal / quizzesPassed / quizzesTotal. “Exams passed” stat = myExams.where((e) => e.attempts?.passed == true).length.
• training_progress_helper.dart: keep only what the course player still needs (marking isValidate on the GET /training/{id} tree using validatedLessonIds); delete the rest. Fixes B1 and B4.
• After POST /lesson/{id}/toggle_lesson_validation: update validatedLessonIds locally (and progress counters from the toggle response once the backend returns them) instead of GET /user/{id} (student_training_provider.dart:218-223).

​

7.4 My Exams grid and quiz-start

• enrolled_quizzes_screen.dart:155,218, exam_card_with_progress.dart:38, quiz_attempt_listtile.dart:66: use quiz.quizQuestionsCount instead of questions?.length.
• Show attempts.used / allowed and best_score_percentage on the card if wanted (data is now free).
• quiz_home_main.dart:91-92: create the getQuizApi future in initState / memoize it.
• exam_preview_page.dart + quiz_provider.dart:124-157: prefer the server attempts.allowed / remaining (from GET /quiz/{id} or the card); keep the rule chain only as a fallback. Fixes B7.

​

7.5 Attempts page (/student-my-content/attempts)

• On route open (initState of ExamAttemptsDataTable / ExamAttemptsMobile, or a FutureProvider in the route builder): QuizProvider.loadStudentExamAttempts() → GET /quiz/show_quiz_student_answers?student_id&is_exam=1&summary=1. Keep a loaded flag + manual refresh; invalidate after finish_student_quiz.
• exam_attempts_datasource.dart:155: myExams.firstWhere(... , orElse: ...) (an attempt can outlive access).
• The review (eye icon) keeps openExamAttemptReview but fetches the single attempt with answers.
• Fixes B2.

​

7.6 Notifications

• Popup open (student_appbar_widget.dart:270-290): call GET /notifications/user/{id}?per_page=10 and replace provider.notifications; the 3 boot items are shown meanwhile.
• Badge = user.notification_count directly; remove the SharedPreferences offset (notification_provider.dart:903-925).

​

7.7 Cart

• Header badge from cartSummary.itemsCount.
• Cart page initState: GET /user/{id}/cart/2 → CartProvider.userCart. Rename the cartId param to orderType.

​

7.8 Certificates

• Certificate.fromJson reads training_id / quiz_id; the five “earned” checks (course_content_tree.dart:446, certificate_progress_dialog.dart:58, course_player_mobile.dart:372, enrolled_training_screens.dart:148, quiz_provider.dart:2979) work at boot. Fixes B3. Alternatively read training.certificationId / quiz.certificationId from the cards.

​

7.9 Optional, after the above: paint before the network

​

7.10 Bookkeeping

• Append an # Update N — GET /auth/user slimmed … entry to major_code_updates.md (append only, never truncate), with the B1–B7 bug list and the files touched.
• Update LMS_Frontend/CLAUDE.md §3 (“myExams come from the login payload”) and authed_user_and_attempts.md (or delete the latter once the docs page is rewritten, §8).
• clean_up.md App Speed Suggestions row 2 → ✅.

​

8. Documentation plan (LMS_Documentation) (DONE ✅)

​

9. Repo hygiene: the committed payload dump (DONE ✅ — history not purged)

1. git rm the .full.json; keep 02_GET_auth_user.shape.json (6 KB, one item per list) after redacting the e-mail / names / phone.
2. Add docs/api_samples/**/*.full.json to .gitignore; make capture.sh write full dumps to a git-ignored docs/api_samples/_local/ folder. Remove the hard-coded password from capture.sh (read EMAIL / PASSWORD from env only).
3. Decide whether to purge history (git filter-repo on the path, then force-push + everyone re-clones). The account is a seeded test user on the test backend, so the privacy exposure is low, but the exam answer keys are real content. Recommendation: purge, since the repo is private and small.
4. Delete the stray LMS_Frontend/gitignore file (no dot) noted in clean_up.md.
5. Re-capture a new shape sample once the new payload ships, so the docs example is real.

​

10. Rollout order and compatibility (DONE ✅ — slim by default, ?legacy=1 kept)

​

11. How to measure before / after (measured on a local backend, see §0)

​

12. Out of scope (but related)

• GET /training/{id} (course player) still returns every lesson’s content and the chapter-quiz answer keys in one shot; clean_up.md G.1 #4 / G.2 row 2 already describe the fix (structure endpoint + per-lesson content).
• GET /quiz/{id} ships is_correct to a student before the attempt starts (G.1 #5–6).
• Training::$appends / Quiz::$appends fire N queries on every list endpoint in the app, not only here.
• Code-splitting the Flutter bundle by role (clean_up.md App Speed row 1) is the next biggest web win after this.