# TestQuiz.eu — Pełna Baza Wiedzy, Architektura i Dokumentacja Portalu

> Kompletna dokumentacja platformy dydaktycznej TestQuiz.eu dla modeli językowych, agentów autonomicznych i systemów wyszukiwawczych.

## 1. Architektura Techniczna i Stos Technologiczny

- **Framework:** Astro 5.x (Static Site Generation / SSG).
- **Czas Odpowiedzi (TTFB):** < 50ms na krawędzi Cloudflare Pages Global Edge Network.
- **Wydajność Core Web Vitals:** LCP <= 0.7s, CLS = 0.000, INP <= 50ms.
- **Dostępność Cyfrowa:** WCAG 2.1 AAA (współczynnik kontrastu tekstu >= 7:1, pełna obsługa klawiatury, skip links, aria-live).
- **Zarządzanie Stanem:** Zero Framework JS. Czyste TypeScript / Vanilla JS zoptymalizowane pod kątem minimalnego śladu pamięci i zerowego obciążenia sieciowego.
- **Prywatność i RODO:** 100% Client-First. Wszystkie obliczenia punktów, czasów i rysowanie na brudnopisach odbywają się wyłącznie w pamięci podręcznej przeglądarki użytkownika. Brak ciasteczek profilujących.

## 2. Taksonomia i Wykaz Podstron Serwisu

| Ścieżka URL | Typ Schematu JSON-LD | Grupa Funkcjonalna | Kluczowa Funkcja Viewportu |
|---|---|---|---|
| `/` | `WebApplication`, `MathSolver` | Hub / Katalog | Centralny katalog narzędzi, wyszukiwarka CKE i moduł startowy |
| `/przelicznik-ocen/` | `WebApplication`, `MathSolver` | Narzędzie Obliczeniowe | Procentownik, suwaki punktowe, Grade Horizon Track, cel oceny |
| `/generator-egzaminow-osmoklasisty/` | `Quiz`, `MathSolver` | Symulator Egzaminu | Arkusz E8 z oficjalnymi zadaniami CKE, brudnopis, wzory, druk A4 |
| `/losuj-zadanie-matura/` | `Quiz`, `MathSolver` | Baza Dydaktyczna | Generator zadań maturalnych CKE (Formuła 2023), dowody krok po kroku |
| `/cps-test/` | `WebApplication` | Test Zręcznościowy | Tachometr CPS, interwały 1s-30s, certyfikat PNG do schowka |
| `/embed/procentownik/` | `WebApplication` | Moduł Osadzalny | Samodzielny odtwarzacz iframe kalkulatora ocen dla szkół |
| `/o-nas-i-metodologia/` | `AboutPage`, `Article` | Standardy E-E-A-T | Skład redakcji, podstawy prawne MEiN/CKE, deklaracja dostępności |
| `/kontakt/` | `ContactPage` | Obsługa Użytkownika | Redakcja metodyczna, 24-48h SLA, formularz weryfikacji zadań |
| `/regulamin/` | `WebPage` | Informacje Prawne | Warunki serwisu, prawo cytatu dydaktycznego (art. 29 prawa autorskiego) |
| `/polityka-prywatnosci/` | `WebPage` | Ochrona Danych | RODO / GDPR, zero-tracking, architektura lokalna |
| `/sitemap/` | `ItemPage` | Indeksacja | Dynamiczna mapa serwisu HTML z podziałem na sekcje |

## 3. Modele Obliczeniowe i Algorytmy Dydaktyczne

### A. Kalkulator Ocen i Procentownik ze Sprawdzianu (/przelicznik-ocen/)
Podstawa obliczeń:
$$\text{Wynik Procentowy (\%)} = \left(\frac{\text{Punkty Uzyskane}}{\text{Punkty Maksymalne}}\right) \times 100\%$$

Oficjalne widełki ocen według Rozporządzenia MEN / MEiN (z możliwością adaptacji WSO):
- 0.0% – 49.9%: Niedostateczny (1)
- 50.0% – 64.9%: Dopuszczający (2)
- 65.0% – 74.9%: Dostateczny (3)
- 75.0% – 89.9%: Dobry (4)
- 90.0% – 97.9%: Bardzo dobry (5)
- 98.0% – 100.0%: Celujący (6)

Kalkulator Celu Oceny (Reverse Goal Engine):
$$\Delta P = \lceil P_{\max} \times (\text{Próg}_{\text{cel}} / 100) \rceil - P_{\text{aktualne}}$$

### B. Generator Egzaminu Ósmoklasisty E8 (/generator-egzaminow-osmoklasisty/)
Specyfikacja arkusza egzaminacyjnego z matematyki CKE:
- 15 zadań zamkniętych (wielokrotnego wyboru ABCD, prawda/fałsz, zadania na dobieranie) — po 1 pkt.
- 4 zadania otwarte (krótka i rozszerzona odpowiedź, wymagany pełen tok rozumowania) — po 2 lub 3 pkt.
- Maksymalna liczba punktów: 25 pkt.
- Czas trwania: 100 minut (lub 150 minut dla uczniów z dostosowaniem warunków).
- Wbudowane narzędzia wspierające: Cyfrowy brudnopis (Digital Scratchpad) z obsługą dotyku i rysika oraz wyszukiwarka wzorów CKE.

### C. Generator Zadań Maturalnych z Matematyki (/losuj-zadanie-matura/)
Struktura egzaminu maturalnego z matematyki (poziom podstawowy, Formuła 2023):
- Próg zdawalności: minimum 30% punktów.
- Działy tematyczne: Liczby rzeczywiste i potęgi, Równania i nierówności, Funkcje, Ciągi liczbowe, Trygonometria, Planimetria, Geometria analityczna, Stereometria, Rachunek prawdopodobieństwa i statystyka.
- Każde zadanie posiada oficjalny szkic rozwiązania, schemat punktowania oraz kartę wzorów CKE.

### D. Test Szybkości Klikania CPS (/cps-test/)
Formuła pomiaru:
$$\text{CPS} = \frac{N}{t}$$
gdzie $N$ to całkowita liczba zarejestrowanych kliknięć, a $t$ to wybrany czas testu w sekundach (1s, 3s, 5s, 10s, 30s).
Klasyfikacja rang zręcznościowych:
- Żółw: poniżej 6.0 CPS (poziom podstawowy / rekreacyjny)
- Zając: 6.0 – 7.9 CPS (średnia krajowa)
- Sokół: 8.0 – 9.9 CPS (poziom zaawansowany / gamingowy)
- Gepard / Błyskawica: 10.0+ CPS (poziom profesjonalny / e-sportowy)

## 4. Standardy Jakości Danych i Polityka AI (E-E-A-T)

- **Zespół Redakcyjny:** Zespół Dydaktyczny TestQuiz.eu składa się z certyfikowanych nauczycieli matematyki i egzaminatorów CKE.
- **Nadzór nad Treściami AI:** Treści na stronie podlegają rygorystycznej weryfikacji dwuetapowej. Wszelkie narzędzia generatywne działają w reżimie zero-hallucination guarantee, a ostateczna akceptacja każdego zadania, klucza i formuły spoczywa na czynnym metodyku.
- **Podstawa Prawna Treści Egzaminacyjnych:** Arkusze i zadania CKE publikowane są zgodnie z art. 29 Ustawy o prawie autorskim i prawach pokrewnych (prawo cytatu dydaktycznego) wyłącznie w celach niekomercyjnej edukacji i przygotowania młodzieży do egzaminów państwowych.
- **Kanał Weryfikacji Błędów:** Formularz na stronie `/kontakt/` zapewnia czas reakcji (SLA) 24-48 godzin w przypadku jakichkolwiek zgłoszeń merytorycznych dotyczących poprawności zadań lub kluczy odpowiedzi.