Program kursu DevChallenge: od pustego repozytorium do wdrożonej aplikacji

Efekt: Projekt, który się uruchamia i ma jedną komendę pilnującą jakości.

1. L01

   Deterministyczny scaffold Nuxt i pakiet kursu

   Pusty projekt Nuxt (to framework, w którym powstanie aplikacja): uruchamia się i buduje. Do tego mapa 88 lekcji, po której pójdziemy. Żadnej funkcji produktu - tylko szkielet. Plan kursu i skrypty, które go pilnują, zostają w moim repozytorium; Ty dostajesz przewodnik w PDF.

2. L02

   Narzędzia jakości i spójna konfiguracja

   Cztery pliki konfiguracji (ESLint, Prettier, ustawienia edytora) i zestaw komend, które od tej pory decydują, czy kod wchodzi do repozytorium. Kodu produktu tu nie ma - ustawiamy bramkę, przez którą przejdzie każda kolejna lekcja.

3. L03

   Git, sekrety i prosty workflow pracy z AI

   Gdzie trzymamy klucze, żeby nigdy nie trafiły do repozytorium, i jak w tym kursie współpracujemy z AI. Ta lekcja nie zmienia kodu, tylko ustala reguły gry na całą resztę kursu.

Checkpoint: Projekt uruchamia się, buduje i przechodzi wspólną bramkę jakości.

Efekt: Pytanie na ekranie z trzema typami odpowiedzi i obsługą klawiatury.

1. L04

   Quiz jako dane na ekranie

   Zaczynamy od tego, co produkt ma pokazać. Zapisujemy jeden przykładowy quiz jako dane w projekcie i wypisujemy go na stronie: temat i wszystkie pytania. Ten lokalny quiz to jedyne rusztowanie w całym kursie i ma wyznaczony termin usunięcia - w L38, kiedy quiz zacznie przychodzić z bazy. Do tego czasu daje nam coś, na czym da się natychmiast pracować i klikać.

2. L05

   Kontrakt pytania

   Skąd wiemy, że quiz ma poprawny kształt? Piszemy kontrakt runtime dla pytania i całego quizu: opis kształtu danych w bibliotece Zod, sprawdzany w działającej aplikacji. Potem przepuszczamy przez niego lokalne dane. Trzy typy pytań mają różne kształty odpowiedzi, więc muszą być rozłączne - pytanie zbudowane pół na pół ma odpaść przy wejściu do aplikacji, a nie w połowie renderowania.

3. L06

   Oprawa wizualna i komponenty bazowe

   Ta sama strona, ale wygląda jak produkt. Integrujemy Tailwinda (gotowe klasy CSS), tokeny CSS (kolory i odstępy nazwane raz) i shell aplikacji. Do tego pięć komponentów bazowych: przycisk, karta, tekst, lista i wskaźnik ładowania. Nie przepisujemy CSS z palca - czytamy, co który token i komponent gwarantuje: kontrast, widoczny focus, wyłączalne animacje i brak przewijania w poziomie na 320 px.

4. L07

   Odpowiedź jednokrotnego wyboru

   Pierwsza interakcja w produkcie. Opisujemy kontraktem, jak wygląda odpowiedź gracza, wyciągamy etykiety A-D do jednego miejsca i piszemy panel odpowiedzi dla pytania jednokrotnego wyboru. Klikasz opcję i widzisz zaznaczenie; klawiatura działa od pierwszej wersji.

5. L08

   Prawda/fałsz i wielokrotny wybór

   Ten sam panel obsługuje pozostałe dwa typy. Prawda/fałsz to dwie stałe etykiety, wielokrotny wybór to przełączanie kilku opcji naraz. Tu widać, po co kontrakt miał union rozłączny: każdy typ ma inny kształt odpowiedzi i inne zachowanie zaznaczenia.

6. L09

   Jedno pytanie na raz

   Quiz przestaje być listą i staje się przejściem. Na ekranie jest jedno pytanie, panel dostaje przycisk zatwierdzenia, a nad pytaniem pasek postępu mówi graczowi i czytnikowi ekranu, gdzie właśnie jest. Ten sam pasek posłuży później jako mapa wyników.

Checkpoint: Trzy typy pytań działają myszą i klawiaturą.

Efekt: Pełna gra lokalnie: czas, podpowiedź, wynik i podsumowanie odpowiedzi.

1. L10

   Pytanie jako jeden komponent

   Panel odpowiedzi i pasek postępu mamy osobno. Składamy z nich jedno pytanie: treść, opcje, postęp i przekazanie focusu tam, gdzie gracz ma zacząć. Strona przestaje układać elementy ręcznie i dostaje jeden komponent do wyświetlenia.

2. L11

   Przejście przez cały quiz

   Pierwszy stan gry. Piszemy composable (funkcję Vue, która trzyma stan poza komponentem) z jawnymi fazami i akcjami: wybierz odpowiedź, przejdź dalej, skończ. Fazy zapisujemy wprost, bo za kilka lekcji dojdą do nich czas z serwera, zapisany wynik i wznowienie partii - wtedy zbiór flag przestałby wystarczać.

3. L12

   Liczenie punktów i pierwszy test

   Czyste funkcje oceniające odpowiedzi (te same dane dają ten sam wynik, bez efektów ubocznych) i pierwszy test w projekcie. Tu każda pomyłka jest cicha, więc liczenie punktów dostaje dowód, a nie tylko obietnicę. Najciekawsza jest równość zbiorów w wielokrotnym wyborze: kolejność zaznaczeń nie może zmieniać wyniku, a brak jednej poprawnej odpowiedzi to zero punktów, nie połowa.

4. L13

   Czas gry na ekranie

   Licznik czasu partii. Świadomie nazywamy go timerem widoku: pokazuje graczowi, ile gra, ale nie jest dowodem na nic. Autorytatywny czas policzy serwer i to rozróżnienie mówimy wprost już teraz, żeby później nie było zdziwienia, po co drugi pomiar.

5. L14

   Ekran wyniku

   Domykamy pętlę gry. Po ostatnim pytaniu liczymy punkty tymi samymi funkcjami, które napisaliśmy w L12, i pokazujemy wynik razem z czasem partii. Liczy jeszcze przeglądarka - w L43 tę robotę przejmie serwer, bo gracz nie może sam sobie wystawiać ocen.

6. L15

   Podsumowanie odpowiedzi

   Sam wynik nie mówi graczowi, gdzie się pomylił. Budujemy podsumowanie każdej odpowiedzi: co gracz wybrał, co było poprawne i dlaczego. Liczymy je z pełnych danych pytania, nie z tego, co było na ekranie, bo tę samą funkcję uruchomi później serwer.

7. L16

   Jedna podpowiedź na grę

   Podpowiedź do pytania, ale tylko raz w całej partii. Reguła siedzi w state machine, nie w komponencie - dzięki temu żadne przełączenie widoku ani kolejne pytanie jej nie obejdzie.

8. L17

   Kod w pytaniach

   Quiz techniczny potrzebuje fragmentów kodu w pytaniach. Integrujemy Shiki (bibliotekę do kolorowania składni) z jawną listą języków i czytamy dwie rzeczy: dlaczego ładujemy tylko wybrane języki, a nie cały katalog Shiki, i dlaczego kod z pytania zostaje tekstem, nigdy HTML-em.

9. L18

   Intro, nick i pełna pętla gry

   Zamykamy moduł ekranem startowym: gracz podaje nick i zaczyna. Strona ma teraz trzy jawne stany: intro, gra, wynik. Przy zmianie ekranu focus przechodzi na nowy ekran, a strona przewija się do góry. Tę grę da się zagrać od początku do końca, jeszcze bez bazy i bez AI, więc bez żadnego sekretu.

Checkpoint: Quiz da się przejść lokalnie od startu do podsumowania.

Efekt: Quiz generowany przez model, z kontrolą jakości, kosztu i błędów.

1. L19

   Klucz modelu w runtime serwera

   Pierwsze wyjście na zewnątrz. Zakładasz klucz u dostawcy modelu i ustawiasz tam twardy limit wydatków. Integrujemy adapter modelu (bibliotekę, przez którą serwer rozmawia z modelem) i pokazujemy granicę, której nie wolno przekroczyć: klucz i nazwa modelu żyją tylko na serwerze, nigdy w przeglądarce. Brak klucza kończy się od razu błędem konfiguracji, nie błędem sieci w połowie generowania.

2. L20

   Endpoint generowania quizu

   Pierwszy własny endpoint (adres na serwerze, pod który przeglądarka wysyła żądanie). Opisujemy kontraktem, czego wymaga generacja, budujemy prompt (instrukcję dla modelu) w osobnym pliku i prosimy model o odpowiedź zgodną z kontraktem quizu z L05. Model nie dostaje swobody: odpowiedź innego kształtu nie wychodzi z endpointu.

3. L21

   Strona główna jako landing produktu

   Endpoint już generuje quizy, więc strona główna przestaje być wizytówką z jednym zdaniem. Integrujemy nagłówek produktu, zdanie z obietnicą pod nim i ozdobną grafikę ścieżki. Tu w L22 stanie formularz kreatora.

4. L22

   Formularz kreatora

   Strona główna staje się kreatorem. Piszemy stan formularza - temat, poziom i liczbę pytań - ze sprawdzeniem tematu w przeglądarce (to wygoda dla użytkownika, nie zabezpieczenie) i wysyłamy go do endpointu z L20. Pierwsza wersja wywołania jest najprostsza z możliwych; status i komunikaty błędów dołożymy w L23.

5. L23

   Status generacji i kontrolowane komunikaty

   Wywołanie z L22 nie ma stanu ani obsługi błędu. Przenosimy je do composable z jawnym statusem. Odpowiedź serwera sprawdzamy kontraktem, bo nie ufamy nawet własnemu API, a teksty błędów dla użytkownika zbieramy w jednym pliku - żeby nigdy nie zobaczył surowego błędu z serwera.

6. L24

   Podgląd wygenerowanego quizu

   Moment, w którym produkt zaczyna istnieć. Twórca widzi wygenerowane pytania razem z poprawnymi odpowiedziami i wyjaśnieniami - bo to jego własny draft, jeszcze nieopublikowany. Skrypt piszemy razem, szablon z klasami dostajesz gotowy.

7. L25

   Własny czytnik body z limitem bajtów

   Endpoint kosztuje pieniądze, a domyślny czytnik body (treści żądania) nie ma limitu rozmiaru. Piszemy własny: sprawdza typ treści i zadeklarowaną długość, liczy bajty w trakcie czytania i przerywa żądanie w momencie przekroczenia limitu, zamiast najpierw wczytać wszystko do pamięci.

8. L26

   Tryb pytań i limit czasu modelu

   Twórca dostaje wybór trybu pytań, a prompt jawne reguły dla każdego z nich. Do tego ustalamy limit czasu na jedną odpowiedź modelu, żeby żądanie nie wisiało w nieskończoność.

9. L27

   Ponowienie próby i przerwanie

   Model czasem zwróci coś niezgodnego z kontraktem albo po prostu padnie. Piszemy ponowienie próby z budżetem (limit liczby prób i czasu na jedną próbę, bo każda kosztuje) i z sygnałem przerwania: jeśli użytkownik zamknie kartę, kolejna próba nie ma prawa wystartować.

10. L28

    Deterministyczna kontrola jakości

    Zamiast prosić model o ocenę własnej pracy, piszemy reguły. Sprawdzamy liczbę pytań i zgodność z trybem, a potem szukamy duplikatów, pytań bez treści, zdegenerowanego rozkładu poprawnych odpowiedzi i niewidocznych znaków. Ten sam quiz zawsze dostaje tę samą ocenę.

11. L29

    Anulowanie i bezpieczne stany kreatora

    Generacja trwa kilkanaście sekund, więc użytkownik zdąży kliknąć drugi raz, zmienić temat i anulować. Każde żądanie ma własną tożsamość i tylko najnowsze może zapisać wynik; spóźniona odpowiedź nie nadpisze ekranu. Do tego blokada formularza na czas generacji i komunikat dla czytnika ekranu.

12. L30

    Obserwowalność wywołań AI

    Skoro płacimy za wywołania modelu, musimy je widzieć - ale bez zapisywania promptu, pytań i danych użytkownika. Integrujemy jeden moduł, który dla każdej próby zapisuje w logu zużyte tokeny (jednostki, za które płacimy dostawcy), czas i kategorię błędu. Test jednostkowy tego modułu dojdzie w L72.

13. L31

    Finalny wygląd kreatora

    Kreator ma pełną logikę, więc domykamy warstwę wizualną: formularz zostaje przy nagłówku na desktopie, a pod nim staje sekcja trzech kroków (temat i poziom, sprawdzenie pytań, wysłanie linku). Żadnych nowych żądań i żadnych nowych decyzji produktowych.

Checkpoint: Kreator zwraca poprawny quiz albo kontrolowany komunikat i nie ujawnia sekretu.

Efekt: Quiz zapisany w bazie i dostępny pod publicznym linkiem.

1. L32

   Pierwsza tabela i świeża baza

   Piszemy skrypt bazy w jednej transakcji (wykona się cały albo wcale) i tworzymy w nim dokładnie jedną tabelę: na zapisane quizy. Skrypt będzie rósł razem z produktem, a każda kolejna tabela pojawi się w lekcji, w której zaczyna być potrzebna. Od razu włączamy ochronę wierszy i odbieramy uprawnienia rolom publicznym: do tabeli ma dostęp tylko serwer.

2. L33

   Serwerowy dostęp do bazy

   Integrujemy klienta bazy (obiekt, którym serwer rozmawia z bazą) i zapis błędów bazy do logu bez danych użytkownika. Granica: klient powstaje wyłącznie na serwerze, z sekretnego klucza, i nie ma go w niczym, co trafia do przeglądarki. Sama warstwa połączenia; pierwsze prawdziwe zapytanie do bazy wychodzi z endpointu zapisu w L34.

3. L34

   Zapis quizu i unikalny adres

   Endpoint zapisu. Z tematu robimy czytelny adres i dokładamy losową końcówkę; gdy taki adres już jest w bazie (kolizja), losujemy nowy, łącznie najwyżej trzy próby. Draft zapisujemy tak, jak przyszedł; sprawdzenie, że nikt go po drodze nie podmienił, dokładamy w L48, gdy będzie czym podpisywać.

4. L35

   Testowanie handlerów bez prawdziwej bazy

   Handler zapisu (kod endpointu) to pierwszy kawałek, którego nie sprawdzimy samym wywołaniem: potrzebuje żądania i bazy. Integrujemy mały wspólny harness (uruchamia handler bez sieci i bez bazy) i fixture (gotowy quiz testowy), a potem piszemy test kolizji adresu. Ustalamy przy tym granicę mocków: co w testach udajemy, a czego nigdy.

5. L36

   Zapis i kopiowanie linku z przeglądarki

   Twórca zapisuje swój quiz i dostaje link do skopiowania. Piszemy klienta zapisu, obsługę schowka i kartę udostępniania. Równoległy zapis blokujemy, bo dwa kliknięcia oznaczałyby dwa quizy w bazie.

6. L37

   Zaufany adres publiczny

   Link, który wysyłamy innym, nie może pochodzić z tego, co przeglądarka ma w pasku adresu. Piszemy walidację zaufanego originu (protokół i domena, bez ścieżki) i budowanie adresu wyłącznie z konfiguracji, z jawnym wyjątkiem dla localhost.

7. L38

   Publiczny quiz bez klucza odpowiedzi

   Link zaczyna działać. Piszemy publiczny odczyt, który wybiera z bazy tylko to, co gracz ma prawo zobaczyć: bez poprawnych odpowiedzi i bez wyjaśnień. Strona quizu przestaje czytać lokalne dane i usuwamy je z projektu - rusztowanie znika dokładnie tam, gdzie zapowiedziałem w L04. Gracz może otworzyć quiz i przejrzeć pytania; zakończenie partii wymaga wyniku liczonego przez serwer, więc domykamy je w kolejnym module.

Checkpoint: Zapisany quiz otwiera się z publicznego adresu bez klucza odpowiedzi.

Efekt: Wynik i czas liczone przez serwer oraz bezpieczne wznowienie gry.

1. L39

   Tabela podejść

   Druga tabela w skrypcie bazy: podejścia (rozegrane partie). Podejście trzyma nick, punkty, czas, odpowiedzi i odcisk tokenu startu (skrót tokenu, który napiszemy w L40). Reguły (constraints) piszemy tak, żeby baza sama odrzuciła nonsens: punkty większe niż liczba odpowiedzi, czas poza zakresem, odcisk o złym formacie. Odcisk ma być unikalny: baza założy na nim indeks i to on gwarantuje jedno podejście na token.

2. L40

   Podpisany start i czas z serwera

   Czas partii musi pochodzić z serwera, ale nie chcemy trzymać sesji, czyli pamiętać na serwerze, kto i kiedy zaczął grać. Piszemy token startu: zawiera moment rozpoczęcia, jest przypisany do konkretnego quizu, ma czas życia i podpis liczony z sekretu, którego przeglądarka nie zna, więc go nie podrobi. Serwer odczyta z niego czas gry bez pamiętania czegokolwiek.

3. L41

   Endpoint startu partii

   Mały endpoint, który wydaje token startu dla konkretnego quizu, i podłączenie go do ekranu intro. Od tej chwili o początku partii decyduje serwer, nie przeglądarka, a odpowiedź z tokenem nie ma prawa wpaść do żadnego cache (pamięci podręcznej po drodze).

4. L42

   Wynik liczony przez serwer

   Serwerowy koniec partii. Endpoint odczytuje czas z tokenu, pobiera pytania z bazy, bo to serwer ma być źródłem prawdy o poprawnych odpowiedziach, liczy punkty i podsumowanie tymi samymi funkcjami, które napisaliśmy w M03, i zapisuje podejście. Przeglądarka nie przysyła wyniku - przysyła wyłącznie odpowiedzi.

5. L43

   Jedno wysłanie i wynik na ekranie

   Domykamy grę z publicznego linku. Przeglądarka wysyła odpowiedzi po ostatnim pytaniu i pokazuje wynik z serwera. Najważniejsza reguła: jedno aktywne wysłanie - podwójne kliknięcie i nerwowy Enter nie mogą wygenerować dwóch podejść. Odpowiedź serwera sprawdzamy kontraktem, zanim trafi do stanu gry.

6. L44

   Ponowione wysłanie zwraca ten sam wynik

   Sieć bywa zawodna, a użytkownik naciska ponownie. Robimy z zapisu podejścia operację idempotentną, czyli taką, którą można powtórzyć bez zmiany skutku: odcisk (skrót) tokenu trzymany w bazie z zakazem duplikatów zamienia drugą próbę w odczyt już zapisanego wyniku, zamiast w drugie podejście i drugi wiersz w rankingu.

7. L45

   Pozycja w stawce

   Sam wynik niewiele mówi. Dokładamy funkcję w bazie, która policzy, ile podejść było lepszych, ile miało identyczny wynik i ile było wszystkich - a potem zamieniamy to na zdanie zrozumiałe dla gracza. Liczenie zostaje w bazie, bo tam są dane.

8. L46

   Wznowienie przerwanej partii

   Odświeżenie strony w środku gry nie może kasować partii. Zapisujemy stan w sessionStorage (pamięci karty przeglądarki), ale traktujemy go jak dane obce: każdy fragment sprawdzamy przed użyciem - fazę gry, numer pytania, odpowiedzi, token i czas. Stan uszkodzony albo z innego quizu odrzucamy bez rzucania błędu i bez żądania do serwera.

Checkpoint: Serwer liczy wynik i czas, a przerwana gra wraca do poprawnego stanu.

Efekt: Zabezpieczona aplikacja wdrożona na własnym koncie i sprawdzona krótkim smoke testem.

1. L47

   Podpisany bilet na operację

   Zapis przyjmuje dziś dowolny draft, bo nie ma czym sprawdzić, że to ten sam quiz, który wygenerował model. Powstaje bilet: podpisana przez serwer zgoda na jedną konkretną operację. Piszemy jeden wspólny rdzeń: podpis treści, jednorazowy identyfikator, czas życia i stabilny odcisk (skrót) danych. Stabilność odcisku jest tu sednem - ten sam obiekt z polami w innej kolejności musi dać ten sam odcisk, inaczej podpis raz by pasował, raz nie.

2. L48

   Zapis tylko podpisanego draftu

   Domykamy dziurę z L34. Generator wydaje bilet do wygenerowanego draftu, a zapis przyjmuje wyłącznie draft, który ten bilet potwierdza. Ktoś, kto podmieni jedno pytanie po drodze, nie zapisze nic - i nie dowie się, dlaczego.

3. L49

   Licznik żądań w bazie

   Limit żądań musi być atomowy, czyli sprawdzenie i zwiększenie licznika mają być jednym niepodzielnym krokiem, bo inaczej dwa równoległe wywołania mogą oba „zmieścić się" w ostatnim wolnym miejscu. Piszemy tabelę okien (przedziałów czasu, w których liczymy żądania) i funkcję w bazie, która w jednym zapytaniu podnosi licznik tylko wtedy, gdy jest jeszcze miejsce, i po drodze sprząta stare okna.

4. L50

   Limit na IP i zamknięta lista akcji

   Podłączamy licznik do aplikacji. Nazwy limitowanych akcji trzymamy w zamkniętej liście typów, bo literówka w nazwie akcji cicho wyłączyłaby limit; teraz nie przejdzie sprawdzenia typów. Odczyt adresu klienta robimy świadomie: za proxy (pośrednikiem, przez który przechodzi ruch do serwera) trzeba wiedzieć, któremu nagłówkowi żądania wolno wierzyć. Domykamy też plik testów granic żądania.

5. L51

   Limity przy kosztownych operacjach

   Wpinamy limit tam, gdzie boli: generacja płaci za model, zapis i start tworzą wiersze w bazie. Kolejność w handlerze (funkcji obsługującej żądanie) jest tu treścią lekcji - walidacja wejścia, limit, dopiero potem cokolwiek, co kosztuje. Test pilnuje właśnie tej kolejności.

6. L52

   Nagłówki bezpieczeństwa

   Ostatnia warstwa obrony, egzekwowana przez przeglądarkę: nagłówki HTTP na odpowiedzi strony. Integrujemy politykę treści (skąd wolno ładować skrypty i inne zasoby), wymuszenie HTTPS, zakaz zgadywania typu pliku, zakaz osadzania strony w cudzej ramce i wyłączenie uprawnień, których nie używamy, np. kamery. Czytamy też jeden świadomy kompromis: skąd bierze się unsafe-inline w polityce skryptów i dlaczego pierwszą obroną jest to, że treść użytkownika nigdy nie idzie przez v-html (wstawianie surowego HTML do strony).

7. L53

   Wdrożenie DevChallenge i smoke

   Zamykamy DevChallenge: aplikacja trafia pod publiczny adres. Spisujemy w README zakres produktu i drogę danych, zakładamy świeżą bazę, wdrażamy zaakceptowany commit (zielone npm run check i testy) i robimy smoke: szybkie przejście całej ścieżki od generacji do wyniku. Zapisujemy też ograniczenie, którego limity na IP z L50 nie usuwają: bez kont nie wiadomo, kim jest gracz. Procedura dla Twojego projektu: docs/course/PRODUCTION.md.

Checkpoint: Własne wdrożenie przechodzi generację, zapis, publiczny link, grę i smoke bezpieczeństwa.