service-finder/.roo/rules/02-architecture.md

🏛️ PROJECT ARCHITECTURE & ENVIRONMENT MAP

Ez a fájl tartalmazza a projekt fizikai felépítését és a futtatási környezet szigorú szabályait. Keresés (find) előtt MINDIG ezt a térképet használd iránymutatásként!

Tech Stack: FastAPI (v2, aszinkron), SQLAlchemy (Async), PostgreSQL (Izolált hálózaton), Docker Compose V2.

AI & OCR: Hibrid AI Gateway (Helyi Ollama: 14B Qwen szövegre, Llama Vision képekre. Fallback: Gemini/Groq).

Identity & Auth: "Dual Entity" modell (Person = hús-vér ember, User = technikai fiók). Triple Wallet gazdasági motor.

Deduplikáció (MDM): Csak akkor van merge, ha a make, a technical_code és a hengerűrtartalom egyezik. N/A és UNKNOWN fallback kódok generálása az SQL kényszerek miatt.

🐳 1. KÖRNYEZET ÉS DOCKER SZABÁLYOK (ENVIRONMENT)

• Operációs rendszer: Ubuntu/Linux környezetben dolgozunk.
• Docker Compose (KRITIKUS): A rendszer az új Docker Compose V2-t használja.
  • TILOS a kötőjeles docker-compose parancs használata!
  • KÖTELEZŐ a szóközös docker compose használata (pl. sudo docker compose restart sf_api).
• Jogosultságok: Ha egy Docker parancs permission denied hibát dob, próbáld meg automatikusan sudo-val az elején (pl. sudo docker exec ...), de először kérdezz rá, ha bizonytalan vagy.
• Backend keretrendszer: FastAPI (Python), aszinkron (async/await) megközelítéssel, SQLAlchemy 2.0+ (asyncpg) adatbázis kapcsolattal.

🗺️ 2. PROJEKT TÉRKÉP (DIRECTORY STRUCTURE)

A projekt mappa-szerkezete az alábbi logikát követi. Keresd a fájlokat ezekben a mappákban a funkciójuk szerint:

• /backend/app/models/: Itt találhatók az adatbázis modellek (SQLAlchemy). Ne feledd a sémákat (identity, finance, data, audit, system)!
• /backend/app/api/endpoints/ (vagy api/v1/): Itt vannak a FastAPI végpontok (routerek, endpointok).
• /backend/app/services/: Itt van az üzleti logika és a "motorok" (pl. billing_engine.py, notification_service.py).
• /backend/app/core/: Rendszerbeállítások, konfigurációk, biztonság (pl. config.py).
• /backend/app/test_in/: Belső tesztek, amiket a konténeren belülről, a többi modullal együttműködve futtatunk.
• /backend/app/test_outside/: Külső integrációs tesztek és szkriptek (pl. a verify_financial_truth.py). Ezek futtatása gyakran speciális adatbázis-kezelést igényel.
• /.roo/scripts/: Az AI és a fejlesztést támogató szkriptek (pl. a gitea_manager.py).

🧩 3. KÓDOLÁSI ALAPELVEK (ARCHITECTURE RULES)

• Szeparáció (DDD): Az adatbázis modellek szigorúan sémákra vannak bontva. Ne keverd a finance és a vehicle domainek adatait!
• Aszinkronitás: Minden I/O és adatbázis művelet aszinkron (await session.execute(...)). Ne használj szinkron blokkoló hívásokat a FastAPI végpontokban.

4. SQL és Adatbázis Hibakezelés (Error Handling)

• Unique Constraint hibák: Ha a PostgreSQL InvalidColumnReferenceError vagy UniqueViolation hibát dob az ON CONFLICT miatt, TILOS találgatni a mezőket!
• A kötelező megoldás: Használd az ON CONFLICT ON CONSTRAINT [korlát_neve] DO NOTHING vagy DO UPDATE szintaxist.
• A pontos korlát (constraint) nevét mindig a pgAdmin-ból vagy a \d+ táblanév lekérdezéssel kell kideríteni módosítás előtt.