4. Návrh platformy a prototypu GitPulse

Analýza ukázala potrebu vrstvy, ktorá spojí údaje z viacerých projektov s kontrolnými otázkami predmetu a zároveň zachová možnosť overiť každý výsledok v GitLabe. Samotné webhooky nestačia. GitPulse preto kombinuje rýchle prijatie udalosti, doplnenie aktuálneho stavu cez REST API a výpočet ukazovateľov nad lokálne uloženými údajmi.

4.1 Požiadavky a scenáre používania

Hlavným používateľom je vyučujúci. Na začiatku semestra potrebuje importovať kurz bez ručného vytvárania každej skupiny a projektu. Počas semestra potrebuje nájsť skupiny s chýbajúcimi procesnými krokmi, prejsť od súhrnu ku konkrétnemu študentovi a pri nejasnom výsledku otvoriť pôvodný problém, žiadosť o zlúčenie, revízny komentár alebo proces CI/CD. Študent vidí iba údaje týkajúce sa jeho vlastnej práce a kurzu.

Funkčný prototyp podporuje:

1. prihlásenie cez GitLab a roly administrátor, učiteľ, mentor a študent;
2. vytvorenie kurzu alebo import GitLab skupiny či projektu;
3. štruktúru kurz - skupina - projekt - člen tímu bez zdvojených členstiev;
4. prvotnú a ručnú synchronizáciu problémov, žiadostí o zlúčenie, poznámok, schválení, odovzdaní a procesov CI/CD;
5. priebežnú aktualizáciu po udalostiach GitLab bez dvojitého započítania;
6. vyhodnotenie R01-R13 s nastaviteľnými prahmi, váhami a aktívnymi kontrolami;
7. súhrnný pohľad na kurz a skupiny a podrobný pohľad na projekt a študenta;
8. ručné spustenie synchronizácie a kontrol s viditeľným priebehom;
9. voliteľné cvičenia pre konflikt pri zlučovaní, Dockerfile a zlyhanie CI/CD.

Výsledok kontroly obsahuje vysvetlenie a nie je automatickou známkou. Základná analytická časť je voči repozitárom čítacia; zápis je možný iba v oddelených cvičebných moduloch po vedomej akcii oprávneného používateľa.

4.2 Architektúra a tok udalosti

GitPulse je samostatná webová služba mimo študentských repozitárov. Verejnú požiadavku prijíma Caddy a odovzdá ju aplikácii FastAPI. PostgreSQL je trvalé úložisko. Redis poskytuje vyrovnávaciu pamäť, živé oznámenia a fronty RQ. Pracovný proces dopĺňa objekty cez GitLab REST API a prepočítava ukazovatele.

flowchart LR
  GL[GitLab TUKE] -->|webhook| Caddy[Caddy / TLS]
  Caddy --> API[FastAPI]
  API --> DB[(PostgreSQL)]
  API --> Redis[Redis + RQ]
  Redis --> Worker[Pracovný proces]
  Worker --> DB
  Worker -. REST API .-> GL
  API -->|SSE| UI[Webové rozhranie]

Pri prijatí webhooku aplikácia overí tajný token projektu, uloží pôvodné telo a použije identifikátor udalosti ako jedinečný kľúč. Opakované doručenie preto nevytvorí druhý záznam. Ak je front dočasne nedostupný, udalosť zostane v databáze ako nespracovaná a možno ju obnoviť.

flowchart LR
  Recv[1. Prijatie a overenie]
  Save[2. Uloženie udalosti]
  Queue[3. Zaradenie do frontu]
  Enrich[4. Doplnenie cez REST API]
  Eval[5. Vyhodnotenie kontrol]
  Store[6. Snímka metrík a oznámenie]
  Recv --> Save --> Queue --> Enrich --> Eval --> Store

Prototyp nepoužíva periodický plánovač na opakované prehľadávanie GitLabu. Aktualizáciu spúšťa webhook alebo vedomá ručná synchronizácia. Tým nevznikajú neviditeľné pracovné úlohy ani zbytočné požiadavky na GitLab.

4.3 Organizačný a dátový model

Kurz obsahuje nastavenia kontrol a členstvá používateľov. Skupina patrí jednému kurzu a môže združovať viac projektov. Projekt predstavuje konkrétny repozitár GitLab. Import je idempotentný: opakované načítanie aktualizuje existujúce záznamy a nedostupný projekt označí ako neaktívny.

Problémy, žiadosti o zlúčenie, poznámky, schválenia, odovzdania a procesy CI/CD uchovávajú lokálny identifikátor aj identifikátor GitLab. Pôvodné webhooky sa uchovávajú oddelene ako auditný vstup.

4.4 Procesné kontroly

Každá kontrola vracia identifikátor, stav splnenia, vysvetlenie, váhu a čiastkové skóre. Do výsledku vstupujú iba zapnuté kontroly. Predvolené hranice semaforu sú 80 percent pre zelený a 50 percent pre žltý stav, no vyučujúci ich môže zmeniť. Semafor slúži na zoradenie pozornosti, nie na priamy prevod na známku.

R01-R13 pokrývajú väzbu študenta na problém, pracovnú vetvu a žiadosť o zlúčenie, prítomnosť testov, opis a prepojenie žiadosti, zapojenie nezávislých posudzovateľov, diskusiu a odpovede autora, schválenie a úspešný proces CI/CD. Kurz môže určiť, od ktorého akademického týždňa sa kontrola očakáva. Váhy sa podľa týždňa automaticky nemenia a GitPulse nevytvára vlastný modul zadaní.

4.5 Voliteľné cvičebné nástroje

Tri voliteľné moduly sú predvolene vypnuté a používajú oddelený token automatizovaného účtu:

• simulátor konfliktu pripraví riadený konflikt pri zlučovaní;
• analýza Dockerfile vykoná deterministické kontroly zvoleného súboru;
• generátor zlyhaní CI vytvorí scenár v cvičebnej vetve a umožní ho vrátiť.

Analýza textu jazykovým modelom sa v kóde nachádza, ale v produkcii je vypnutá, nepoužíva sa v R01-R13 a nevytvára známku.

4.6 Bezpečnostné hranice

Prihlásenie prebieha cez GitLab OAuth. Oprávnenie sa kontroluje na serverovej trase aj voči konkrétnemu kurzu. Každý projekt používa vlastné tajomstvo webhooku, uložené tokeny GitLab sú šifrované a požiadavky meniace stav sú chránené proti podvrhnutiu. Čítacie tokeny pre analytiku sú oddelené od tokenov cvičebných modulov, ktoré môžu zapisovať do repozitára.

4.7 Hlavný scenár a stav prototypu

Prototyp je dostupný na gitpulse.kpi.fei.tuke.sk. Hlavný scenár vyučujúceho začína upozornením na skupinu, ktorá vyžaduje kontrolu. Upozornenie iba určuje poradie práce; nepredstavuje automatickú známku.

Prvý krok: upozornenie na skupinu s červeným stavom zhody.

Po otvorení upozornenia vyučujúci porovná členov skupiny podľa skóre, stavu, počtu splnených kontrol a základnej aktivity. Hodnoty pochádzajú z reálnej inštancie; mená a používateľské mená sú na snímke anonymizované.

Druhý krok: porovnanie členov skupiny pred podrobnou kontrolou.

V treťom kroku vyučujúci otvorí detail zvoleného študenta. Súhrn ukazuje posledné skóre, semafor a počet splnených kontrol. Na rovnakej stránke môže skontrolovať odovzdania, problémy, žiadosti o zlúčenie, procesy CI/CD a diskusie, z ktorých bol výsledok odvodený.

Tretí krok: súhrn výsledku pred kontrolou zdrojových údajov.

Technická skúška vybraných častí prototypu zahŕňala 350 automatických testov kontrolného mechanizmu, udalostného toku, webhookov, importu skupiny a troch voliteľných nástrojov; všetky prešli. Overenie s vyučujúcimi a meranie prínosu patria do neskoršej etapy práce.