39 lines
3.3 KiB
Markdown
Executable File
39 lines
3.3 KiB
Markdown
Executable File
# 🏛️ 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. |