Řešení reálného zadání: Anonymní profil a přenosový kód v StudentProgressService

Anonymní identita a synchronizace bez hesel

Jedním ze zásadních architektonických požadavků naší vzdělávací platformy agy-laravel je nulová třecí plocha (zero-friction onboarding):

• Uživatel nemusí zadávat e-mail, heslo ani procházet procesem registrace.
• Přesto se jeho postup kurzem a výsledky kvízů musí spolehlivě ukládat.
• Student musí mít možnost přenést svůj postup na jiné zařízení (např. z mobilu na pracovní počítač).

Tento požadavek řeší doménová služba StudentProgressService v součinnosti s modelem StudentProfile.

Architektura anonymního profilu

1. UUID Token: Každému návštěvníkovi je při prvním přístupu vygenerováno unikátní UUID v4, které je uloženo v HTTP-only cookie s platností 1 rok (agy_student_token).
2. Přenosový kód (Transfer Code): Pro snadné opsání člověkem na jiné zařízení generujeme krátký kód formátu AGY-XXXX-XXXX (např. AGY-7K2M-9P4W).
3. JSONB sloupce v PostgreSQL: Seznam dokončených lekcí (completed_lessons) i skóre z kvízů (quiz_scores) jsou uloženy v JSON formátu přímo v tabulce student_profiles.

Bezkolizní generování přenosového kódu

Přenosový kód musí být krátký, aby se dal snadno přepsat, ale zároveň unikátní v celé databázi. V StudentProgressService k tomu využíváme do-while cyklus s náhodným generováním:

public function generateUniqueTransferCode(): string
{
    do {
        $chunk1 = strtoupper(Str::random(4));
        $chunk2 = strtoupper(Str::random(4));
        $code = "AGY-{$chunk1}-{$chunk2}";
    } while (StudentProfile::where('transfer_code', $code)->exists());

    return $code;
}

Využitím 8 alfanumerických znaků s velkými písmeny a číslicemi vzniká prostor $36^8 \approx 2{,}8 \times 10^{12}$ možných kombinací, což poskytuje zanedbatelnou pravděpodobnost kolize i při desítkách tisíc studentů.

Doménová pravidla v recordQuizScore

Služba StudentProgressService také spravuje byznys pravidla pro dokončování lekcí:

public function recordQuizScore(StudentProfile $profile, int $lessonId, int $scorePercent): StudentProfile
{
    /** @var array<string, int> $scores */
    $scores = (array) ($profile->quiz_scores ?? []);
    $key = (string) $lessonId;

    // Uchováme vždy nejvyšší dosažené skóre studenta
    $scores[$key] = max((int) ($scores[$key] ?? 0), $scorePercent);
    $profile->quiz_scores = $scores;

    /** @var list<int> $completed */
    $completed = array_map('intval', (array) ($profile->completed_lessons ?? []));

    // Byznys pravidlo: Skóre >= 66 % automaticky označí lekci jako splněnou
    if ($scorePercent >= 66 && ! in_array($lessonId, $completed, true)) {
        $completed[] = $lessonId;
        sort($completed);
        $profile->completed_lessons = $completed;
    }

    $profile->last_active_at = now();
    $profile->save();

    return $profile;
}

Všimněte si, jak služba garantuje atomicitu a konzistenci:

• Skóre se nikdy nesníží (používá se funkce max()).
• Pokud student dosáhne alespoň 66 % správných odpovědí, lekce se automaticky zařadí do pole completed_lessons.
• Pole jsou seřazena a normalizována jako celá čísla (intval).
• Aktualizuje se časové razítko last_active_at.