# 🏛️ 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.