Interný nástroj · technická špecifikácia

Apolo Bug Reporter

Nahlás raz. Oprav rýchlo.

Jeden klik vo vnútri Apola → hlásenie sa obohatí o presný technický kontext, Claude ho roztriedi a napíše hotový návod na opravu, a padne do admin fronty. Programátor (Petr) už nič nevyšetruje — dostane tiket pripravený na opravu cez Claude Code.

🐞 Skúsiť demo 🔧 Admin hlásení ← GoMerch AI Liga

Princíp

Ako to funguje — 5 krokov

Od kliknutia po pripravený tiket bežia tieto kroky automaticky.

📡

Zber kontextu

Widget potichu zbiera kliky, zmeny polí, navigáciu, JS chyby a zlyhané requesty.

📨

Odoslanie

Popis pracovníka + celý kontext idú ako JSON na náš server (/api/bug).

🤖

Claude triáž

Claude určí typ, prioritu P1–P4, oblasť (FE/BE), kroky na reprodukciu a fix-prompt.

💾

Uloženie

Hlásenie + analýza sa uložia do Supabase (tabuľka apolo_hlasenia).

🔧

Admin fronta

Tiket sa objaví v admine — s logom aj s promptom na opravu na skopírovanie.

Architektúra

Komponenty

Stojí to na rovnakej infraštruktúre ako zvyšok GoMerch AI Liga: Next.js na Verceli + Supabase + Claude API.

🐞 Widget (klient)

Malý <script>, ktorý sa vloží do Apola. Pridá plávajúce tlačidlo „Nahlásiť", od načítania ticho zbiera kontext a po odoslaní pošle JSON na server. Žiadne kľúče v prehliadači.

📨 API `/api/bug`

Serverová route (Next.js). Prijme hlásenie, zavolá Claude na triáž, výsledok aj kontext uloží do Supabase. Beží na serveri — API kľúč ani service-role kľúč sa nikdy nedostanú do prehliadača.

🤖 Claude triáž

Model claude-sonnet-4-6 cez Anthropic API. Z logu zrekonštruuje, čo sa stalo, určí prioritu a oblasť, a napíše fix-prompt do Claude Code.

💾 Supabase + 🔧 Admin

Postgres tabuľka so všetkými hláseniami. Admin stránka (/apolo-debug/admin) ich zobrazuje — chránená rovnakým heslom ako admin v AI Lige.

Kontext

Čo widget zbiera (automaticky)

Pracovník napíše len vlastnými slovami, čo sa stalo. Zvyšok sa priloží sám — toto je to, čo programátorovi inak chýba.

🧭 Breadcrumbs

Kliky na tlačidlá/odkazy
Zmeny polí (názov poľa + hodnota)
Navigácia medzi sekciami

⚠️ Chyby

JavaScript chyby (message, stack)
Zlyhané requesty (URL, HTTP status, odpoveď servera)
Console.error výpisy

📍 Prostredie

Stránka / URL (napr. #/orders/detail/4521)
Prihlásený používateľ
Čas, prehliadač

✍️ Od pracovníka

Typ: Bug / Vylepšenie / Otázka
Dopad: Blokuje / Obmedzuje / Kozmetické
Popis vlastnými slovami

AI triáž

Čo Claude vyprodukuje

Z hlásenia + kontextu vznikne štruktúrovaný tiket — vrátane hotového promptu na opravu.

Názov tiketu — krátky, výstižný (napr. „Uloženie zákazky #4521 padá na 500").
Zhrnutie pre programátora — čo sa deje a prečo, jednou-dvoma vetami.
Priorita P1–P4 — podľa dopadu (P1 = blokuje, urgent).
Oblasť — frontend / backend / databáza, kde pravdepodobne leží príčina.
Kroky na reprodukciu — zrekonštruované z click-trailu.
Technický dôkaz — konkrétny failed request / chybová hláška.
🔧 Fix-prompt do Claude Code — hotový text, ktorý Petr vloží do Claude Code v Apolo repe a model rovno navrhne/spraví opravu.

💡 Fix-prompt je jadro nástroja. Nie je to len popis chyby — je to pripravený príkaz pre Claude Code: kde v kóde začať, čo je príčina, čo opraviť a na čo dať pozor. Z hlásenia od netechnického kolegu sa stane úloha pripravená na vyriešenie za pár minút.

Dátový model

Tabuľka `apolo_hlasenia` (Supabase)

Jedna tabuľka drží surové hlásenie aj výsledok triáže.

Stĺpec	Typ	Význam
`id`	uuid	identifikátor
`vytvorene`	timestamptz	čas nahlásenia
`typ`	text	Bug / Vylepšenie / Otázka
`dopad`	text	Blokuje / Obmedzuje / Kozmetické
`popis`	text	text od pracovníka
`stranka`	text	URL kde sa to stalo
`pouzivatel`	text	kto nahlásil
`kontext`	jsonb	breadcrumbs + JS chyby + failed requesty
`nazov`	text	názov tiketu (Claude)
`diagnoza`	text	čo sa deje a prečo, 2–4 vety (Claude)
`priorita`	text	P1–P4 (Claude)
`oblast`	text	frontend / backend / db (Claude)
`fix_prompt`	text	prompt na opravu do Claude Code (Claude)
`stav`	text	nové / v riešení / vyriešené
`riesil`	text	kto to rieši / vyriešil

Nasadenie

Ako sa vloží do Apola

Stačí jeden riadok pred </body>. Widget sa sám pripojí a začne zbierať kontext.

<!-- na koniec stránky Apola -->
<script src="https://offlineid.com/apolo-bug-reporter.js"></script>

Hlásenia potom chodia na https://offlineid.com/api/bug a objavujú sa v admine. Widget je možné vložiť aj na iné naše weby — vždy posiela, z ktorej stránky a od koho hlásenie prišlo.

Bezpečnosť

Kde žijú kľúče

Anthropic API kľúč a Supabase service-role kľúč žijú iba na serveri (Vercel env premenné) — nikdy sa nedostanú do prehliadača.
Widget v prehliadači iba odosiela hlásenie; všetko ostatné (Claude triáž, zápis do DB) beží na serveri.
Admin stránka je chránená heslom (rovnaké ako admin v AI Lige). Bez neho sa hlásenia nezobrazia.
Databáza má zapnuté RLS; zápisy a admin akcie idú cez serverové API.

Stav

Čo je hotové a čo nás čaká

Hotové & naživo Reálny widget apolo-bug-reporter.js (zber kontextu + odoslanie)
Hotové & naživo Serverové API /api/bug s automatickou Claude triážou
Hotové & naživo Supabase tabuľka apolo_hlasenia
Hotové & naživo Admin /apolo-debug/admin — zoznam, log, fix-prompt na kopírovanie, stav & priorita
Hotové & naživo Demo na vyskúšanie celého toku (/apolo-debug) + táto špecifikácia
Posledný krok Vložiť widget snippet do reálneho Apola (riadok vyššie) — vtedy začnú chodiť ostré hlásenia
Voliteľné Notifikácia pri P1 (e-mail / Slack)