service-finder/.roo/rules/04-debug-protocol.md

🔍 Service Finder Debug & Hibavadász Protokoll

🎯 Alapvető Küldetés

Soha ne találgass! A hibakeresés nálunk tényalapú és szisztematikus. Ha valami nem működik, tilos azonnal átírni a kódot. Előbb diagnosztizálj!

🕵️‍♂️ A Hibakeresés Kötelező Lépései:

1. Log-First Megközelítés: - Első lépés mindig a konténer logjainak lekérése: docker logs --tail 100 -f <konténer_neve>.

   • Ha teljesítményprobléma gyanús, ellenőrizd a docker stats kimenetét.

2. Környezeti Audit (Sync Check):

   • Ha a logok szerint a módosított kód nem frissült, AZONNAL ellenőrizd a docker-compose.yml volume beállításait.
   • Ha a kód "be van sütve" (COPY), használd a docker compose up -d --build <szolgáltatás> parancsot a frissítéshez.

3. SQL Trace & Adatbázis Audit:

   • Adatbázis hiba (pl. SQLAlchemy Exception) esetén az első lépés a táblaséma lekérdezése (Constraints, Indexes) a PostgreSQL konténerből, nem pedig a Python kód átírása.

   🕵️‍♂️ A Hibakeresés Kötelező Lépései:

Backend és Adatbázis Hibák Esetén:

1. Log-First Megközelítés: Első lépés mindig a konténer logjainak lekérése: docker compose logs --tail 100 -f <konténer_neve>.
2. Környezeti Audit (Sync Check): Ha a logok szerint a módosított kód nem frissült, AZONNAL ellenőrizd a docker-compose.yml volume beállításait, vagy építsd újra a konténert.
3. SQL Trace & Adatbázis Audit: Adatbázis hiba (pl. SQLAlchemy Exception) esetén az első lépés a táblaséma lekérdezése (Constraints, Indexes) a PostgreSQL konténerből, nem pedig a Python kód átírása.

Frontend és Távoli Tesztelési Hibák Esetén (UI/E2E):

Soha ne találgass vizuális vagy frontend API hibáknál! A tesztek a távoli faktor01 szerveren futnak, így a hálózat is okozhat hibát.

1. Playwright Artifacts: Ha egy E2E teszt elbukik, AZONNAL olvasd be a hiba stack trace-t és a legutóbbi képernyőfotót (screenshot) a frontend/test-results/ mappából. Keresd a szétcsúszott komponenseket vagy a "Timeout" hibákat.
2. Hálózati Vakfoltok (CORS & Proxy): Ha a távoli böngésző "Failed to fetch" vagy "Network Error" hibát kap a frontenden:
   • Ellenőrizd a frontend/.env fájlban a VITE_API_BASE_URL értékét.
   • Ellenőrizd a vite.config.ts proxy beállításait. A frontend kéréseknek a helyi proxy-n keresztül kell elérniük a backendet.
3. Távoli Böngésző Állapota: Ha a Playwright WebSocket hibaüzenetet ad (pl. nem tud csatlakozni a ws:// hálózathoz), tilos a kódot módosítani! Jelezd a felhasználónak, hogy a távoli Docker konténer valószínűleg leállt a faktor01 szerveren.