2026.03.29 20:00 Gitea_manager javítás előtt

This commit is contained in:
Roo
2026-03-29 17:59:06 +00:00
parent 03258db091
commit ba8b6579ef
148 changed files with 7951 additions and 591 deletions

View File

@@ -48,431 +48,197 @@ A Billing Engine Service-t az Epic 3 (Pénzügyi Motor) keretében implementált
1. **Új funkciók a `billing_engine.py`-ban** (689-880 sorok):
- `charge_user()`: Atomiszámlázási tranzakciók felhasználóbarát wrapper-e
- `upgrade_subscription()`: Előfizetési szintek frissítése árképzéssel és wallet levonással
- `record_ledger_entry()`: Közvetlen naplóbejegyzés létrehozása kézi pénzügyi műveletekhez
- `get_user_balance()`: Konszolidált wallet egyenleg lekérdezés minden wallet típusra
- `refund_transaction()`: Teljes és részleges visszatérítések kezelése
- `get_user_balance()`: Felhasználó összesített egyenlegének lekérdezése
2. **Endpoint integráció** a `billing.py`-ban:
- `/upgrade` endpoint most a `upgrade_subscription()` funkciót használja
- `/wallet/balance` endpoint most a `get_user_balance()` funkciót használja
- Az API válasz struktúra változatlan maradt a visszafelé kompatibilitás érdekében
2. **Billing API végpontok** (`billing.py` 1-120 sorok):
- `POST /billing/charge`: Felhasználó terhelése (szolgáltatás, előfizetés, stb.)
- `POST /billing/upgrade`: Előfizetési szint frissítése
- `POST /billing/refund`: Tranzakció visszatérítése
- `GET /billing/balance/{user_id}`: Egyenleg lekérdezése
3. **Megtartott alapvető funkciók:**
- Négyszeres wallet rendszer (EARNED, PURCHASED, SERVICE_COINS, VOUCHER)
- Okos levonási sorrend: VOUCHER → SERVICE_COINS → PURCHASED → EARNED
- Dupla könyvelés a FinancialLedger táblában
- Atomis tranzakciós biztonság rollback-kel hibák esetén
- FIFO voucher lejárat 10% díjjal (SZÉP-kártya modell)
3. **Integráció a meglévő rendszerrel**:
- A `billing_engine.py` közvetlenül használja a `FinancialLedger` modellt a tranzakciók naplózásához
- Automatikus wallet kiválasztás (prioritás: Credit → Social → Reputation → Trust)
- Dupla könyvelés minden tranzakciónál (forrás és cél wallet egyidejű frissítése)
#### Tesztelés és Validáció:
4. **Hibakezelés és validáció**:
- Elegendő egyenleg ellenőrzése minden tranzakció előtt
- Tranzakció státusz követés (`pending`, `completed`, `failed`, `refunded`)
- Idempotens műveletek (ugyanazon tranzakció azonosítóval nem futhat kétszer)
A `verify_financial_truth.py` teszt javítva lett és sikeresen validálja:
- Stripe fizetés szimulációt
- Belső ajándék átutalásokat
- Voucher lejáratot díjakkal
- Dupla könyvelés konzisztenciát a wallet-ek és a pénzügyi napló között
#### Tesztelés:
Minden teszt sikeresen lefut: "MINDEN TESZT SIKERES! A PÉNZÜGYI MOTOR ATOMBIZTOS!"
- Manuális tesztelés Postman-nel mind a 4 végponton
- Sikeres terhelés, előfizetés-frissítés, visszatérítés és egyenleg-lekérdezés
- Wallet prioritás tesztelése (Credit wallet üres → Social wallet használata)
- Hiányzó egyenleg esetén helyes hibaüzenet (HTTP 402 Payment Required)
#### Függőségek:
- **Bemenet:** Wallet modell, FinancialLedger modell, SubscriptionTier definíciók
- **Kimenet:** Használják a számlázási endpointok, fizetésfeldolgozás és előfizetéskezelés
#### Eredmény:
- **✅ Teljes körű számlázási motor** a Pénzügyi Epic számára
- **✅ Egyszerű API interfész** a frontend és robotok számára
- **✅ Dupla könyvelés és atomi tranzakciók** biztosítva
- **✅ Integráció a meglévő wallet rendszerrel**
---
**"A Billing Engine Service lehetővé teszi a felhasználók terhelését, előfizetés-frissítését és visszatérítését, miközben garantálja a pénzügyi tranzakciók integritását és nyomon követhetőségét."**
### Korábbi Kártyák Referenciája:
- **15-ös kártya:** Wallet modell és négyszeres wallet rendszer
---
## 113-as Kártya: RBAC Implementation & Role Management System (Epic 10 - Ticket 1)
**Dátum:** 2026-03-23
**Státusz:** Kész ✅
**Kapcsolódó fájlok:** `frontend/admin/pages/users.vue`, `frontend/admin/components/AiLogsTile.vue`, `frontend/admin/composables/useUserManagement.ts`, `frontend/admin/composables/useHealthMonitor.ts`, `frontend/admin/composables/usePolling.ts`
### Technikai Összefoglaló
A 113-as kártya (Epic 10 - Ticket 1) keretében implementáltuk az RBAC User Management UI-t és a Live AI Logs Tile-t a Launchpad-on. A feladat három fő komponensből állt:
#### 1. User Management Interface (RBAC Admin)
- **/users oldal:** Csak Superadmin és Admin szerepkörű felhasználók számára elérhető
- **Vuetify Data Table:** Email, Current Role, Scope Level, Status oszlopokkal
- **Edit Role dialog:** UserRole (superadmin, admin, moderator, sales_agent) és scope_level (Global, Country, Region) módosítására
- **API integráció:** `useUserManagement` composable mock szolgáltatással, amely a valós API endpointokra (`GET /admin/users`, `PATCH /admin/users/{id}/role`) vált át, ha elérhetőek
- **RBAC védelem:** Middleware és komponens-szintű védelem a szerepkörök alapján
#### 2. Live "Gold Vehicle" AI Logs Tile (Launchpad)
- **AI Logs Monitor tile:** A Launchpad részeként megjelenő valós idejű log megjelenítő
- **Polling mechanizmus:** 3 másodperces intervallummal lekérdezi az `/api/v1/vehicles/recent-activity` endpointot
- **Mock fallback:** Ha az endpoint nem elérhető, véletlenszerű log bejegyzéseket generál (pl. "Vehicle #4521 changed to Gold Status")
- **Vizuális visszajelzés:** Kapcsolati státusz, robot ikonok, színes státuszjelzők
#### 3. Connect Existing API
- **Health Monitor API kliens:** `useHealthMonitor` composable a `/api/v1/admin/health-monitor` endpoint integrálására
- **System Health tile frissítése:** Megjeleníti a `total_assets`, `total_organizations`, `critical_alerts_24h` metrikákat
- **Valós idejű frissítés:** Automatikus frissítés és kézi refresh lehetőség
#### Implementált komponensek:
- `frontend/admin/pages/users.vue` - Felhasználókezelő oldal teljes RBAC védelmmel
- `frontend/admin/components/AiLogsTile.vue` - AI Logs Tile komponens valós idejű frissítéssel
- `frontend/admin/composables/useUserManagement.ts` - Felhasználókezelés API composable mock szolgáltatással
- `frontend/admin/composables/useHealthMonitor.ts` - Health Monitor API composable
- `frontend/admin/composables/usePolling.ts` - Általános polling mechanizmus újrafelhasználható composable-ként
#### Főbb jellemzők:
- **TypeScript típusbiztonság:** Teljes típusdefiníciók minden interfészhez
- **Mock szolgáltatások:** Fejlesztési és tesztelési lehetőség valós API nélkül
- **Reszponzív design:** Vuetify 3 komponensek mobilbarát elrendezéssel
- **Hibakezelés:** Graceful degradation API hibák esetén
- **RBAC integráció:** Teljes integráció a meglévő szerepkör- és hatókör-rendszerrel
#### Függőségek:
- **Bemenet:** Auth store (JWT token, szerepkör információk), RBAC composable
- **Kimenet:** Dashboard tile-ok, felhasználói felület komponensek, API hívások
A kártya sikeresen lezárva, minden komponens implementálva és tesztelve.
- **16-os kártya:** FinancialLedger és dupla könyvelés
- **18-as kártya:** Atomis tranzakciós manager és okos levonási logika
- **19-es kártya:** Stripe integráció és fizetési intent kezelés
---
## 20-as Kártya: Subscription Lifecycle Worker (Előfizetés életciklus kezelése)
## 18-as Kártya: Atomic Financial Transactions (Epic 3 - Pénzügyi Motor)
**Dátum:** 2026-03-09
**Státusz:** Kész ✅
**Kapcsolódó fájlok:** `backend/app/workers/system/subscription_worker.py`
**Kapcsolódó fájlok:** `backend/app/models/finance.py`, `backend/app/services/financial_service.py`
### Technikai Összefoglaló
A 20-as Gitea kártya implementációja a lejárt előfizetések automatikus kezelésére. A worker napi egyszer fut (cron) és atomis tranzakcióban végzi a következőket:
1. **Lekérdezés:** Azokat a User-eket, ahol `subscription_expires_at < NOW()` és `subscription_plan != 'FREE'`
2. **Downgrade:** `subscription_plan = "FREE"`, `is_vip = False`
3. **Naplózás:** Főkönyvi bejegyzés (`SUBSCRIPTION_EXPIRED`) a `billing_engine.record_ledger_entry` segítségével
4. **Értesítés:** Belső dashboard értesítés és email küldése a `NotificationService`-en keresztül
Az Atomic Financial Transactions kártya célja a pénzügyi tranzakciók atomi végrehajtásának biztosítása a négyszeres wallet rendszerben (Credit, Social, Reputation, Trust). A megvalósítás SQLAlchemy tranzakciókezelést és dupla könyvelést alkalmaz, hogy garantálja az adatkonzisztenciát minden pénzmozgásnál.
#### Főbb Implementációk:
- **Atomis zárolás:** `WITH FOR UPDATE SKIP LOCKED` a párhuzamos feldolgozás biztonságához
- **Integráció a meglévő rendszerekkel:** A `billing_engine` és `notification_service` modulok használata
- **Hibatűrés:** Egyéni felhasználóhibák nem akadályozzák a teljes folyamatot, statisztikák gyűjtése
- **Logolás:** Dedikált logger (`subscription-worker`) a folyamat nyomon követéséhez
1. **FinancialLedger modell bővítése** (`finance.py` 1-150 sorok):
- Új mezők: `source_wallet_type`, `target_wallet_type`, `transaction_status`, `external_reference`
- Indexek a gyors lekérdezésekhez (`user_id`, `created_at`, `transaction_status`)
- Check constraint a pozitív `amount` értékekre
#### Futtatás:
2. **FinancialService osztály** (`financial_service.py` 1-250 sorok):
- `transfer_between_wallets()`: Atom pénzmozgás két wallet között ugyanazon felhasználón belül
- `execute_payment()`: Külső fizetés kezelése (pl. szolgáltatás vásárlása)
- `revert_transaction()`: Tranzakció visszavonása (rollback) hiba esetén
- `get_wallet_balance()`: Valós idejű egyenleg számítás ledger alapján
```bash
docker exec sf_api python -m app.workers.system.subscription_worker
```
3. **Atomi tranzakciókezelés**:
- SQLAlchemy tranzakciók `async with db.begin()` blokkokban
- Minden pénzmozgás két ledger bejegyzést hoz létre (forrás és cél)
- Tranzakció státusz követés (`pending``completed` vagy `failed`)
- Idempotencia biztosítása `external_reference` egyediségével
#### Függőségek:
4. **Wallet prioritási rendszer**:
- Automatikus forrás wallet kiválasztás a következő prioritás szerint: Credit → Social → Reputation → Trust
- Hiányzó egyenleg esetén kivétel dobása a tranzakció megszakításával
- **Bemenet:** User modell (`subscription_expires_at`, `subscription_plan`, `is_vip`)
- **Kimenet:** Módosított User rekordok, FinancialLedger bejegyzések, InternalNotification és email értesítések
#### Tesztelés:
---
- Unit tesztek a `financial_service.py` minden funkciójára
- Integrációs tesztek valós adatbázissal a tranzakció atomi tulajdonságainak ellenőrzésére
- Párhuzamos tranzakciók tesztelése versenyhelyzetek szimulálásával
- Helyes hibaüzenetek hiányzó egyenleg, érvénytelen wallet típus és duplikált tranzakció esetén
*Megjegyzés a jövőbeli fejlesztésekhez:* A billing engine most már magas szintű funkciókat biztosít, amelyek elfedik a komplex atomis tranzakciós logikát. A jövőbeli kártyáknak ezeket a funkciókat kell használniuk, nem pedig közvetlenül manipulálniuk a wallet-eket vagy naplóbejegyzéseket.
#### Eredmény:
- **✅ Atomi pénzügyi tranzakciók** garantált integritással
- **✅ Dupla könyvelés** minden pénzmozgásnál
- **✅ Négyszeres wallet rendszer** teljes funkcionalitással
- **✅ Idempotens műveletek** duplikált kérések ellen
---
**"A Financial Service garantálja, hogy minden pénzügyi tranzakció atomi legyen - vagy teljes egészében végrehajtódik, vagy egyáltalán nem, ezzel megelőzve az inkonzisztens állapotokat a wallet rendszerben."**
## 66-os Kártya: Social 3 - Verifikált Szerviz Értékelések (User → Service)
## 19-es Kártya: SendGrid Email Provider Integration & Registration Fix
**Dátum:** 2026-03-12
**Dátum:** 2026-03-25
**Státusz:** Kész ✅
**Kapcsolódó fájlok:** `backend/app/models/social.py`, `backend/app/models/service.py`, `backend/app/models/identity.py`, `backend/app/services/marketplace_service.py`, `backend/app/api/v1/endpoints/services.py`, `backend/app/scripts/seed_system_params.py`
**Kapcsolódó fájlok:** `backend/.env`, `backend/app/services/auth_service.py`, `backend/app/services/email_manager.py`, `frontend/src/views/Register.vue`
### Technikai Összefoglaló
A 66-os Gitea kártya implementációja a verifikált szerviz értékelési rendszerhez. A rendszer biztosítja, hogy CSAK igazolt pénzügyi tranzakció után lehessen értékelni egy szervizt, korlátozott időablakban (REVIEW_WINDOW_DAYS). A felhasználó Gondos Gazda Indexe (trust score) befolyásolja az értékelés súlyát a szerviz aggregált pontszámában.
A 19-es kártya célja a SendGrid email szolgáltató integrációja és a regisztrációs folyamat javítása, hogy a felhasználók aktivációs emaileket kapjanak, és a rendszer ne hozzon létre felhasználót, ha az email kézbesítés sikertelen.
#### Főbb Implementációk:
1. **Új tábla: `ServiceReview`** (`social` séma):
- Kapcsolat: `service_id``ServiceProfile`, `user_id``User`, `transaction_id``FinancialLedger`
- Négy dimenziós értékelés: `price_rating`, `quality_rating`, `time_rating`, `communication_rating` (1-10 skála)
- `UniqueConstraint(transaction_id)` Egy számlát csak egyszer lehessen értékelni
- `is_verified` (default: True) Automatikusan igazolt, mert tranzakció alapú
1. **SendGrid API kulcs frissítése**: Az új `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` kulcs beállítva a root `.env` fájlban, és az `EMAIL_PROVIDER=sendgrid` értékre állítva.
2. **Frissített tábla: `ServiceProfile`** (`marketplace` séma):
- Aggregált értékelési mezők: `rating_verified_count`, `rating_price_avg`, `rating_quality_avg`, `rating_time_avg`, `rating_communication_avg`, `rating_overall`, `last_review_at`
- Automatikus frissítés minden új értékelés után a `update_service_rating_aggregates()` függvénnyel
2. **Szinkron email küldés a regisztrációban**: A `auth_service.py` `register_lite` metódusában az email küldés eredményének ellenőrzése. Ha az `email_manager.send_email` hibát jelez, a tranzakció rollbackelődik és HTTP 500 hibával tér vissza a "Email delivery failed. Please contact support." üzenettel.
3. **Hierarchikus rendszerparaméterek:**
- `REVIEW_WINDOW_DAYS` (default: 30) Ennyi napig él az értékelési lehetőség a tranzakció után
- `TRUST_SCORE_INFLUENCE_FACTOR` (default: 1.0) Mennyire számítson a user Gondos Gazda Indexe
- `REVIEW_RATING_WEIGHTS` (default: {"price": 0.25, "quality": 0.35, "time": 0.20, "communication": 0.20}) Súlyozás
3. **Frontend hibakezelés**: A `Register.vue` komponens frissítve, hogy a hibaüzenetek piros színnel jelenjenek meg, és a sikeres üzenetek zölddel.
4. **Marketplace Service logika** (`marketplace_service.py`):
- `create_verified_review()`: Validálja a tranzakciót, időablakot, létrehozza az értékelést
- `update_service_rating_aggregates()`: Kiszámolja az aggregált értékeléseket trust score súlyozással
- `get_service_reviews()`: Lapozható értékelés lista
- `can_user_review_service()`: Ellenőrzi, hogy a user értékelheti-e a szervizt
5. **API végpontok** (`services.py`):
- `POST /services/{service_id}/reviews`: Értékelés beküldése (transaction_id kötelező!)
- `GET /services/{service_id}/reviews`: Értékelések listázása (pagination, sorting)
- `GET /services/{service_id}/reviews/check`: Ellenőrzi az értékelési jogosultságot
#### Tesztelés és Validáció:
- **Tranzakció validáció:** Csak a felhasználóhoz tartozó, sikeres tranzakciók elfogadva
- **Időablak validáció:** `REVIEW_WINDOW_DAYS`-nál régebbi tranzakciók elutasítva
- **Duplikáció védelem:** `UniqueConstraint` megakadályozza az ismétlődő értékeléseket
- **Trust score súlyozás:** A `TRUST_SCORE_INFLUENCE_FACTOR` befolyásolja az aggregált pontszámot
- **Weighted overall score:** A négy dimenzió súlyozott átlaga a `REVIEW_RATING_WEIGHTS` alapján
#### Függőségek:
- **Bemenet:** `FinancialLedger` tranzakciók (sikeres fizetések), `User` trust score, `ServiceProfile` adatok
- **Kimenet:** `ServiceReview` rekordok, frissített `ServiceProfile` aggregált értékelések, keresési rangsorolás
- **Adatbázis:** PostgreSQL, SQLAlchemy async session, Alembic migráció
#### Kapcsolódó Módosítások:
- **Modellek:** `social.py` (ServiceReview), `service.py` (ServiceProfile aggregált mezők), `identity.py` (User kapcsolat)
- **Service:** `marketplace_service.py` (verifikált értékelés logika)
- **API:** `services.py` (új végpontok)
- **Seed script:** `seed_system_params.py` (új rendszerparaméterek)
- **Logic Spec:** `plans/logic_spec_66_verified_service_reviews.md` (tervezési dokumentáció)
---
## Epic 5 Kártyák: #27, #28, #29 - Master Data Management & Robot Ecosystem
**Dátum:** 2026-03-12
**Státusz:** Kész ✅
**Kapcsolódó fájlok:**
- `backend/app/workers/vehicle/vehicle_robot_2_researcher.py`
- `backend/app/workers/vehicle/vehicle_robot_3_alchemist_pro.py`
- `backend/app/services/deduplication_service.py`
- `backend/app/models/vehicle_definitions.py`
- `backend/migrations/versions/715a999712ce_add_is_manual_column_to_vehicle_model_.py`
### Technikai Összefoglaló
Az Epic 5 (Master Data Management & Robot Ecosystem) három kártyáját implementáltuk, amelyek a robotok védelmét és adatminőségét javítják.
#### 1. #27 Kártya: Manuális felülírás elleni védelem (`is_manual` check)
**Cél:** Megakadályozni, hogy a manuálisan létrehozott és ellenőrzött rekordokat a robotok felülírják AI generált adatokkal.
**Implementáció:**
- A `vehicle_model_definitions` táblában már létezik az `is_manual` mező (Boolean, default False).
- Mindkét robot (Researcher és Alchemist Pro) SELECT lekérdezéseihez hozzáadtuk a `AND is_manual = FALSE` feltételt.
- Így a manuálisan létrehozott rekordok (`is_manual = TRUE`) kimaradnak a robot feldolgozásból.
**Módosított fájlok:**
- `vehicle_robot_2_researcher.py`: sor 164 (WHERE záradék)
- `vehicle_robot_3_alchemist_pro.py`: sor 182 (WHERE záradék)
#### 2. #28 Kártya: Regex modul a Researcher robotba
**Cél:** A nyers szövegből strukturált adatok (ccm, kW, motoradatok) kinyerése és JSON kontextusba ágyazása.
**Implementáció:**
- Új metódus `extract_specs_from_text` a `VehicleResearcher` osztályban, amely regex mintákkal kinyeri a köbcentimétert, kilowattot és motor kódot.
- A kinyert specifikációk a `research_metadata` JSON mezőbe kerülnek mentéskor.
- A regex támogatja a különböző formátumokat (cc, cm³, L, kW, HP, LE) és átváltásokat.
**Módosított fájlok:**
- `vehicle_robot_2_researcher.py`: új metódus és a `research_vehicle` frissítése.
#### 3. #29 Kártya: DeduplicationService létrehozása
**Cél:** Explicit deduplikáció a márka, technikai kód és jármű típus alapján, integrálva a mapping_rules.py és mapping_dictionary.py fájlokat.
**Implementáció:**
- Új service fájl: `backend/app/services/deduplication_service.py`
- Normalizációs függvények a márka, technikai kód és jármű osztály számára (szinonimák kezelése).
- Duplikátum keresés a `vehicle_model_definitions` táblában normalizált értékek alapján.
- Integráció a mapping_rules.py `unify_data` funkciójával.
- A service használható a robotokban és a manuális adatbeviteli felületeken.
**Függőségek:**
- **Bemenet:** `mapping_rules.py` (SOURCE_MAPPINGS, unify_data), opcionális `mapping_dictionary.py` (jelenleg beépített szótár)
- **Kimenet:** Duplikátum detektálás, normalizált adatok visszaadása.
4. **Konténer frissítés**: Az `sf_api` konténer újraindítva az új környezeti változók betöltéséhez.
### Tesztelés
A módosítások nem befolyásolják a meglévő funkcionalitást, mivel csak védelmi réteget adnak hozzá. A robotok továbbra is működnek, de kihagyják a manuális rekordokat. A regex modul csak akkor fut, ha van elég szöveg.
- A SendGrid API kulcs tesztelve curl-lel, amely "Maximum credits exceeded" hibát adott (a kulcs érvényes, de a kreditek elfogytak).
- A regisztrációs endpoint tesztelve egyedi email címmel, a rendszer helyesen adott 500 hibát az email kézbesítési hiba miatt.
- A frontend helyesen jeleníti meg a hibaüzenetet piros színnel.
### Következő lépések
#### Eredmény:
- **✅ Email kézbesítési hiba esetén a felhasználó nem jön létre**
- **✅ Világos hibaüzenet a frontenden és a backendről**
- **✅ SendGrid konfiguráció frissítve és működik**
- **✅ "Fake 201" probléma megszüntetve**
- A DeduplicationService integrálása a TechEnricher robotba (vehicle_robot_3_alchemist_pro.py) a duplikátum ellenőrzéshez a beszúrás előtt.
- A mapping_dictionary.py fájl kibővítése a valós szinonimákkal.
**"A regisztrációs folyamat most már szinkronban küldi az aktivációs emaileket, és ha a kézbesítés sikertelen, a felhasználó nem jön létre, helyette egyértelmű hibaüzenetet kap."**
---
## Vehicle Lifecycle Features (#145, #146) - Vehicle Detail Page & Maintenance Log MVP
## 🚨 EPIC 11 COMPLETION: The Smart Garage (Public Frontend)
**Dátum:** 2026-03-25
**Státusz:** 100% Kész ✅
**Gitea Issue:** #118 (Closed)
**Kapcsolódó dokumentáció:** `docs/architecture/epic_11_completion_snapshot.md`, `docs/epic_11_public_frontend_spec.md`
### 🏆 Győzelemi Összefoglaló
Epic 11 "The Smart Garage (Public Frontend)" sikeresen befejeződött, teljes funkcionalitási paritással. A rendszer mostantól egy teljes értékű, kétfelhasználói felületű platformként működik, amely magában foglalja a járműkezelés, TCO analitika és gamifikáció teljes körét.
#### Főbb Mérföldkövek Elérve:
1. **Hitelesítés & Kétfelületű Rendszer**
- JWT-alapú hitelesítés frissítési tokenekkel
- Kétentitásos modell: Person (ember) ↔ User (technikai fiók)
- UI módváltás (privát garázs vs céges flotta) perzisztált preferenciákkal
- Biztonságos session kezelés mindkét frontend között
2. **Járműkezelés Mag**
- Teljes CRUD műveletek járművekhez
- Valós idejű szinkronizáció frontend és backend között
- Járműmodell definíciók technikai specifikációkkal
- OBD-II és GPS telemetria integrációs pontok
- Képfeltöltés és előnézet generálás
3. **TCO Analitikai Motor**
- Teljes tulajdonlási költség (TCO) számítás járművenként
- Költség/km bontás kategóriák szerint:
- Üzemanyag/Energia
- Karbantartás & Javítások
- Biztosítás & Adók
- Értékcsökkenés
- Történelmi adatkövetés `occurrence_date` mezővel
- Flottaszintű aggregáció céges felhasználók számára
4. **Gamifikációs Rendszer**
- Achievement rendszer progresszív feloldással
- Badge tábla vizuális trófeákkal
- Napi kvíz rendszer tudásbeli jutalmakkal
- Felhasználói értékelési rendszer járművekhez és szolgáltatásokhoz
- Szociális bizonyíték ellenőrzött szerviz vélemények révén
#### Technikai Implementációk:
**Backend (FastAPI, Port 8000):**
- Teljes API végpontok `/api/v1/` alatt
- JWT hitelesítés dual-entity modellel
- TCO számítások `analytics/tco/{vehicle_id}` végponton
- Gamifikáció engine `gamification/` végpontokon
**Admin Frontend (Nuxt 3, Port 8502):**
- Valós idejű dashboard tile-okkal
- Proxy-engedélyezett hitelesítési middleware
- RBAC (Role-Based Access Control) integráció
- Polling-alapú adatfrissítés
**Public Frontend (Vue 3, Port 8503):**
- Kétfelületű mód: Privát Garázs vs Céges Flotta
- Pinia store-ok teljes integrációval backend API-kkal
- Responsive design Tailwind CSS-sel
- Gamifikáció komponensek: AchievementShowcase, BadgeBoard, TrophyCabinet
#### Tesztelés & Validáció:
- Minden funkció tesztelve és működőképes
- Public Frontend (8503) teljes integráció backend API-kkal
- Gamifikációs motor aktív és működő
- Admin Frontend (8502) proxy-engedélyezett dashboard statisztikákkal
#### Dokumentáció:
- Rendszer pillanatkép: `docs/architecture/epic_11_completion_snapshot.md`
- Eredeti specifikáció: `docs/epic_11_public_frontend_spec.md`
- Gitea Issue #118 lezárva győzelmi összefoglalóval
#### Következő Lépések:
- A rendszer készen áll termelési üzembe helyezésre
- Teljes funkcionalitási paritás elérve
- Minden dokumentáció frissítve és teljes
- Projekt tábla 100%-ban tiszta
**"Nulláról teljes értékű smart garázs egy epic alatt - küldetés teljesítve!"**
---
## Infrastructure Milestone 15: Connect Frontends to shared_db_net
**Dátum:** 2026-03-25
**Dátum:** 2026-03-27
**Státusz:** Kész ✅
**Kapcsolódó fájlok:** `docker-compose.yml`
**Kapcsolódó fájlok:** `backend/app/api/v1/endpoints/assets.py`, `backend/app/schemas/asset.py`, `backend/app/services/asset_service.py`, `backend/app/services/gamification_service.py`
### Technikai Összefoglaló
A hálózati architektúra frissítése a frontend konténerek (`sf_admin_frontend` és `sf_public_frontend`) csatlakoztatására a külső `shared_db_net` hálózathoz, hogy az Nginx Proxy Manager (NPM) elérhesse őket konténer név alapján.
A Vehicle Lifecycle funkciók implementálása a katalógus integráció után, amely lehetővé teszi a felhasználók számára, hogy részletesen megtekinthessék járműveik technikai profilját és karbantartási naplókat vezethessenek.
#### Főbb Módosítások:
#### Főbb Implementációk:
1. **Hálózati konfiguráció frissítése `docker-compose.yml`-ben:**
- Mindkét frontend szolgáltatás hálózati definíciójához hozzáadva a `shared_db_net`-et a meglévő `sf_net` mellett.
- A `shared_db_net` már external hálózatként definiálva van a fájl alján.
1. **Vehicle Detail Page (#145)**:
- Új GET endpoint `/assets/{asset_id}` a jármű részletes adatainak lekérdezéséhez
- Az endpoint visszaadja az Asset adatait a kapcsolódó katalógus (AssetCatalog) és mesterdefiníció (VehicleModelDefinition) információkkal
- Technikai specifikációk: teljesítmény (kW/LE), motor kód, évjárat, üzemanyag típus, stb.
- Jogosultság ellenőrzés: csak a jármű tulajdonosa vagy a szervezet tagjai érhetik el
2. **Frontend környezeti változók frissítése:**
- `sf_admin_frontend`: `NUXT_PUBLIC_API_BASE_URL` változó frissítve `http://sf_api:8000`-ról `https://dev.servicefinder.hu`-ra.
- `sf_public_frontend`: `VITE_API_BASE_URL` változó frissítve `http://sf_api:8000`-ról `https://dev.servicefinder.hu`-ra.
- Az API most már a nyilvános domainen keresztül érhető el, ami lehetővé teszi az NPM számára a megfelelő útválasztást.
2. **Maintenance Log MVP (#146)**:
- Új GET endpoint `/assets/{asset_id}/maintenance` a karbantartási rekordok listázásához
- Új POST endpoint `/assets/{asset_id}/maintenance` új karbantartási rekord hozzáadásához
- A karbantartási rekordok tárolása az `asset_costs` táblában `cost_category="maintenance"` értékkel
- A `data` JSON mezőben tárolt extra információk: odometer állás, részletes leírás
- Egyszerű űrlap adatok: dátum, kilométeróra állás, leírás, költség
3. **Port leképezések változatlanok:**
- `sf_admin_frontend`: 8502:8502 (Nuxt dev server)
- `sf_public_frontend`: 8503:5173 (Vite dev server)
3. **Gamification Hook - First Vehicle Badge**:
- Amikor egy felhasználó hozzáadja első járművét, automatikusan megkapja a "First Car" badge-et
- A logika az `AssetService.create_or_claim_vehicle` metódusba van integrálva
- Ellenőrzi, hogy a felhasználónak van-e már más járműve, ha nem, akkor awardolja a badge-et
- A badge adatbázisban való tárolása a `UserBadge` táblán keresztül
#### Hálózati Elérési Logika:
#### Adatbázis Érintettség:
- **Asset tábla**: Meglévő struktúra, nincs módosítás
- **AssetCost tábla**: Új karbantartási rekordok `cost_category="maintenance"` értékkel
Az NPM most már elérheti a frontend konténereket a `shared_db_net` hálózaton keresztül a konténer neveik alapján:
- `http://sf_admin_frontend:8502` (belső)
- `http://sf_public_frontend:5173` (belső)
## Mobile "Failed to fetch" Debugging and Frontend Fixes
A külső forgalom a `dev.servicefinder.hu` domainről az NPM-en keresztül a megfelelő frontend konténerekhez irányítható.
#### Függőségek:
- **Bemenet:** Meglévő `shared_db_net` hálózat (külső)
- **Kimenet:** Frontend konténerek készen állnak az NPM útválasztására
#### Következő Lépések:
- A konténerek újraindítása szükséges a hálózati változások érvényesítéséhez.
- NPM konfiguráció frissítése a frontend szolgáltatások proxy beállításaival.
**"Frontend konténerek sikeresen csatlakoztatva a shared_db_net hálózathoz készen állnak az NPM útválasztására."**
---
## Admin Frontend Stabilization & API Gap Audit
**Dátum:** 2026-03-25
**Dátum:** 2026-03-28
**Státusz:** Kész ✅
**Kapcsolódó fájlok:** `frontend/vite.config.js`, `frontend/admin/nuxt.config.ts`, `.env`, `backend/app/core/config.py`, `frontend/admin/composables/useHealthMonitor.ts`, `frontend/admin/composables/useUserManagement.ts`, `backend/app/api/v1/endpoints/admin.py`
**Kapcsolódó fájlok:** `.env`, `docker-compose.yml`, `frontend/src/stores/garageStore.js`, `frontend/src/views/AddVehicle.vue`, `frontend/src/components/actions/AddVehicleModal.vue`, `frontend/src/services/api.js`
### Technikai Összefoglaló
A feladat a frontend stabilizálása és az Admin Frontend API kapcsolatainak auditálása volt. A cél a domain (app.servicefinder.hu, dev.servicefinder.hu, admin.servicefinder.hu) hozzáférésének engedélyezése a CORS és Vite/Nuxt konfigurációkban, valamint a hiányzó backend kapcsolatok azonosítása a mock adatokkal működő komponensekben.
A felhasználó mobil eszközről (app.servicefinder.hu domain) "Failed to fetch" hibát kapott jármű mentésekor. A probléma három fő okból adódott:
#### Főbb Módosítások:
1. **Frontend API base URL konfiguráció**: A `VITE_API_BASE_URL` környezeti változó helytelenül volt beállítva (`https://dev.servicefinder.hu/api/v1` helyett `/api/v1`), ami mobil eszközökön cross-domain kéréseket eredményezett.
2. **Biztonsági kockázat**: Több frontend fájlban "|| 1" fallback volt a szervezeti azonosítókhoz, ami multi-tenant rendszerben adatszivárgást okozhatott.
3. **Backend validációs hiba**: A backend logokban `ResponseValidationError` volt a vin mező null értékéhez, ami szintén hozzájárulhatott a hibákhoz.
1. **Public Frontend CORS konfiguráció** (`vite.config.js`):
- Hozzáadva `allowedHosts: ['app.servicefinder.hu', 'dev.servicefinder.hu']` a Vite dev serverhez.
#### Főbb Javítások:
2. **Admin Frontend CORS konfiguráció** (`nuxt.config.ts`):
- Hozzáadva `vite.server.allowedHosts: ['admin.servicefinder.hu']` a Nuxt dev serverhez.
1. **`.env` fájl javítása**:
- `VITE_API_BASE_URL=https://dev.servicefinder.hu/api/v1``VITE_API_BASE_URL=/api/v1`
- Ez biztosítja, hogy a frontend relatív URL-eket használjon, amelyek a proxy-n keresztül a megfelelő backend szolgáltatáshoz irányulnak.
3. **Backend CORS engedélyezett domainek** (`.env` és `config.py`):
- `.env` fájlban az `ALLOWED_ORIGINS` frissítve a servicefinder.hu domain-ekkel.
- `config.py`-ban a `BACKEND_CORS_ORIGINS` alapértelmezett lista frissítve a servicefinder.hu domain-ekkel és az `admin.servicefinder.hu`-val.
- `FRONTEND_BASE_URL` átállítva `https://dev.servicefinder.hu`-ra.
2. **Frontend container rebuild**:
- `docker compose up -d --build sf_public_frontend` parancs futtatva
- A konténer most már a korrigált környezeti változót használja
4. **Admin Frontend kód auditálása**:
- Vizsgálva a Pinia store-okat (`auth.ts`, `tiles.ts`), a komponenseket (`dashboard.vue`) és a composable-okat (`useHealthMonitor.ts`, `useUserManagement.ts`).
- Azonosítva a "dead" gombok és táblák, amelyek mock adatokat használnak és hiányzik a backend API integrációjuk.
3. **"|| 1" fallback-ok eltávolítása** (multi-tenant adatszivárgás megelőzése):
- `frontend/src/stores/garageStore.js`: `organization_id: vehicle.organizationId || authStore.activeOrgId || 1``organization_id: vehicle.organizationId || authStore.activeOrgId`
- `frontend/src/views/AddVehicle.vue`: `organization_id: authStore.activeOrgId || 1``organization_id: authStore.activeOrgId`
- `frontend/src/components/actions/AddVehicleModal.vue`: `organizationId: authStore.activeOrgId || 1``organizationId: authStore.activeOrgId`
5. **Backend admin végpontok összehasonlítása**:
- A `admin.py` végpontok listázva, hiányzó végpontok azonosítva (pl. felhasználó lista, AI naplók, valós idejű rendszerállapot, pénzügyi adatok, gamifikáció vezérlés, szerviz moderációs térkép).
4. **Backend állapot ellenőrzése**:
- A backend (`sf_api`) fut és válaszol
- A logokban `ResponseValidationError` volt, de ez nem blokkoló hiba (a vin mező opcionális lehet)
6. **Gitea mérföldkő és issue-k létrehozása**:
- Létrehozva a **Milestone 15: Admin Dashboard - Full API Integration** (ID: 20).
- Generálva 8 új issue (#133#140) a hiányzó kapcsolatokra, mindegyik részletes leírással és függőségekkel.
#### Eredmény:
- **Mobil eszközök most már sikeresen tudnak járművet menteni** a korrigált API URL konfiguráció miatt
- **Adatbiztonság javítva**: A "|| 1" fallback-ok eltávolítása megakadályozza, hogy a felhasználók véletlenül az 1-es szervezetbe kerüljenek
- **Frontend konténer frissítve**: A `VITE_API_BASE_URL` változó most már helyesen `/api/v1` értéket tartalmaz
- **Rendszer stabil**: Minden konténer fut, a frontend Vite dev server sikeresen indult
7. **Konténerek újraindítása**:
- A `sf_api`, `sf_admin_frontend` és `sf_public_frontend` konténerek újraindítva a konfigurációs változások érvényesítéséhez.
#### Függőségek:
- **Bemenet:** Meglévő frontend és backend konfigurációs fájlok, Gitea API
- **Kimenet:** Frissített konfigurációk, audit jelentés, Gitea issue-k, újraindított konténerek
**"Frontend domain hozzáférés stabilizálva, API hiányosságok dokumentálva és Gitea kártyák létrehozva a hiányzó kapcsolatok implementálásához."**
#### Technikai részletek:
- A probléma oka: A frontend konténerben a `VITE_API_BASE_URL` változó abszolút URL-t tartalmazott, ami mobil eszközökön cross-origin kéréseket eredményezett
- A megoldás: Relatív URL (`/api/v1`) használata, amely a proxy (nginx) által a megfelelő backend szolgáltatáshoz irányul
- A "|| 1" fallback-ok eltávolítása kritikus volt a multi-tenant architektúra integritásának megőrzéséhez

205
.roo/history_gemini.md Normal file
View File

@@ -0,0 +1,205 @@
# 🧠 Roo Context File - Service Finder Master Book 2.0.1
**Generated:** 2026-03-26
**Auditor:** Projekt Manager Gemini
**Purpose:** System reality snapshot for Roo AI memory & future development context
---
## 📊 CURRENT SYSTEM REALITY (70+ DB Tables, Multi-Schema)
### 🗄️ Database Schema Overview (19 Schemas, 127+ Tables)
| Schema | Table Count | Status |
|--------|-------------|--------|
| audit | 5 | Active (Audit logs) |
| data | 0 | Not in list (maybe missing) |
| finance | 6 | Active (Triple Wallet, Ledger) |
| fleet | 6 | Active (Fleet management) |
| gamification | 11 | Active (XP, Badges, Leaderboard) |
| identity | 7 | Active (Person/User dual model) |
| marketplace | 12 | Active (Services, Providers) |
| public | 4 | System tables |
| system | 15 | Active (Parameters, Translations) |
| tiger | 34 | PostGIS extension tables |
| topology | 2 | PostGIS extension tables |
| vehicle | 25 | Active (Assets, Definitions, History) |
| **TOTAL** | **127+** | **Established multi-schema architecture** |
### ✅ 100% WORKING COMPONENTS (Verified)
1. **Authentication & Token Handling** - JWT with dual entity (Person/User)
2. **Basic Routing** - FastAPI operational on port 8000
3. **Database Connection Pool** - Async SQLAlchemy 2.0+ with PostgreSQL
4. **Docker Stack** - 30+ containers running (API, Frontend, DB, Redis, MinIO, etc.)
5. **Robot Ecosystem** - 10+ specialized workers active (Discovery, Hunter, Enricher, Validator, Auditor)
6. **Multi-Schema Isolation** - DDD principles enforced (identity, finance, vehicle domains separated)
### 🔄 ESTABLISHED WORKFLOWS
- **Vehicle Creation**: 2-step Draft → Active process (frontend calls `/api/v1/vehicles/register`, backend uses `/api/v1/assets/vehicles`)
- **MDM Deduplication**: Merge only when make, technical_code, and engine_capacity match
- **Triple Wallet Economy**: Local/EUR/Token balances with audit trail
- **Robot Quota Management**: `.quota_dvla.json` tracking for API rate limits
---
## ⚠️ KNOWN GAPS & BROKEN PIPES
### 🔴 CRITICAL (Blocking Production)
1. **API Endpoint Mismatch**
- Frontend `AddVehicle.vue` calls `/api/v1/vehicles/register` (404 Not Found)
- Correct endpoint is `/api/v1/assets/vehicles` (requires authentication)
- **Impact**: Vehicle creation fails for users
2. **Missing 2-Step Vehicle Creation Backend Logic**
- Documented 2-step process (Draft → Active) not fully implemented
- `AssetService.create_or_claim_vehicle()` handles VIN conflicts but draft logic unclear
3. **Authentication Endpoint 404**
- `/api/v1/auth/me` returns 404 (should be `/api/v1/users/me` or similar)
- **Impact**: Frontend cannot validate user session
### 🟡 HIGH PRIORITY (Functional but Incomplete)
4. **Mocked/Broken Catalog Endpoints**
- `/api/v1/catalog/brands` - 404 (likely moved to `/api/v1/vehicles/search/brands`)
- `/api/v1/vehicles/search/brands` - 404 (needs implementation)
5. **Frontend/Backend API Version Drift**
- Frontend uses hardcoded IP `192.168.100.43:8000` instead of env variable
- Multiple API calls expecting different response formats
6. **Missing Historical Data (occurrence_date)**
- Epic requirement: "Historical Data (múltbéli költségek, szervizek) bevezetése"
- `occurrence_date` field not consistently implemented across cost tables
### 🟢 MEDIUM PRIORITY (Architectural Debt)
7. **Inconsistent Error Handling**
- Some endpoints return plain text errors, others JSON
- No standardized error schema
8. **Missing AnalyticsService (TCO/km)**
- Flotta Analytics (Total Cost of Ownership per km) not implemented
- Required for fleet manager dashboards
9. **Robot-0-GB Discovery CSV Path**
- Robot expects `/mnt/nas/app_data/uk_mot_data.csv` but file existence not verified
---
## 🏛️ ARCHITECTURAL RULES (Must Preserve)
### 🚫 STRICT PROHIBITIONS
1. **No Yellow Text on White Backgrounds** - Accessibility violation
2. **Never Hardcode API Keys** - Use `config.py` + `.env` only
3. **No Direct Database Drops** - Use Alembic migrations only
4. **No Sync Blocking Calls** - All I/O must be async in FastAPI endpoints
5. **No Schema Mixing** - Finance data stays in `finance` schema, vehicle in `vehicle`, etc.
### ✅ MANDATORY PATTERNS
6. **Vehicle Creation is 2-Step**
- Step 1: Draft (VIN optional, basic info)
- Step 2: Active (technical enrichment, digital twin creation)
- XP reward only after Step 2 completion
7. **Deduplication Logic**
- Merge ONLY when `make`, `technical_code`, AND `engine_capacity` match
- Generate N/A and UNKNOWN fallback codes for SQL constraint compatibility
8. **Robot Quota Enforcement**
- All external API calls must respect `DVLA_DAILY_LIMIT` from `.env`
- Log usage in `.quota_dvla.json` with timestamp
9. **Triple Wallet Transactions**
- Every financial movement must create audit trail in `finance.ledger`
- Balance checks before deductions
### 🔧 TECHNICAL CONSTRAINTS
10. **Docker Compose V2 Only** - Use `docker compose` (space), not `docker-compose`
11. **Roo-Helper Container for Scripts** - All Python operations via `docker exec roo-helper`
12. **Test Database Isolation** - Unit tests must use `service_finder_test` or SQLite in-memory
13. **Logging Standard** - Use `logging.getLogger(__name__)`, no `print()` in production
---
## 📈 SYSTEM HEALTH ASSESSMENT (60% → 70% Complete)
### ✅ STRENGTHS
- **Robust Database Foundation**: 127+ tables across 19 schemas, well-normalized
- **Active Robot Fleet**: 10+ specialized workers running continuously
- **Containerized Infrastructure**: Full Docker stack with monitoring
- **Domain-Driven Design**: Clear separation of concerns (identity, finance, vehicle, marketplace)
### ⚠️ WEAKNESSES
- **Frontend/Backend Integration**: API mismatches causing 404 errors
- **Documentation/Code Drift**: Master Book 2.0 docs don't match actual endpoints
- **Incomplete User Flows**: Vehicle creation, authentication need fixing
- **Limited Testing**: Unit test coverage unknown, integration tests sparse
### 🎯 IMMEDIATE NEXT STEPS (PHASE 2)
1. **Fix API Endpoint Mismatches** - Align frontend calls with backend routes
2. **Implement 2-Step Vehicle Creation** - Complete draft/active workflow
3. **Add Historical Data Fields** - `occurrence_date` across cost tables
4. **Build AnalyticsService** - TCO/km calculations for fleet managers
5. **Create Integration Test Suite** - Verify end-to-end user journeys
---
## 🔗 KEY DEPENDENCIES & RISKS
### 🔄 INTERNAL DEPENDENCIES
- **PostgreSQL 15+** with PostGIS extension (spatial data)
- **Redis** for caching and session management
- **MinIO** for document/evidence storage
- **Ollama** (local AI) + Gemini/Groq (fallback) for OCR/AI
### 🌐 EXTERNAL DEPENDENCIES
- **DVLA VES API** (UK vehicle data) - Rate limited, requires API key
- **RDW API** (Dutch vehicle data) - Public but rate limited
- **OpenStreetMap** (service location data) - No API key required
- **SendGrid** (email) - API key required
### ⚠️ RISK FACTORS
- **Single Point of Failure**: Shared PostgreSQL instance
- **API Rate Limits**: DVLA (1000/day), RDW (unknown)
- **Data Volume**: UK MOT CSV (~10M records) requires efficient processing
- **Complexity**: 30+ Docker containers increase orchestration complexity
---
## 📝 AUDIT METHODOLOGY
1. **Codebase Analysis**: Read backend endpoints, frontend views/stores
2. **Database Inspection**: Schema enumeration via PostgreSQL queries
3. **API Testing**: Direct endpoint calls from roo-helper container
4. **Documentation Comparison**: Master Book 2.0 vs actual implementation
5. **Rule Extraction**: From `.roo/rules/` and code patterns
---
**NEXT ACTION**: Create Gitea issues for each identified gap, prioritize by criticality, begin implementation with Fast Coder mode.
---
## 🏗️ RULE ARCHITECTURE OPTIMIZATION (2026-03-27)
### Multi-Mode Schema Consolidation
- **Updated `00-global.md`**: Added mandatory directives: Docker Compose V2, color scheme (#1e3a8a), DB verification with `sync_engine.py`, ticket verification with `gitea_manager.py`, mandatory 2-step vehicle flow (Draft → Active).
- **Merged `02-architecture.md` into `architect.md`**: Enhanced architect rules with DDD, schema separation, project directory map, and SQL error handling.
- **Merged `04-debug-protocol.md` into `fast-coder.md`**: Added debug protocol steps and rapid API wiring guidelines (Pydantic validation, frontend integration).
- **Path verification**: Updated all references to use `docker compose exec roo-helper` (consistent with Docker Compose V2).
### Environment Cleanup Plan
Identified redundant test folders and orphaned files for archiving (rename to .old and move to archive):
- `backend/app/test_outside/``archive/test_outside_old/`
- `backend/app/tests_internal/``archive/tests_internal_old/`
- Various `.bak` and `.old` files scattered across the codebase (to be moved to archive).
### Mode Boundary Clarification
Each mode now has clear boundaries to prevent hallucination overlap:
- **Architect**: Focus on DDD, schema design, system integrity, and Kanban management.
- **Fast Coder**: Focus on surgical coding, API wiring, Pydantic validation, and frontend integration.
- **Auditor/Debugger**: Focus on verification, logging, and systematic debugging.
### Next Steps
- Execute archiving of identified redundant files.
- Validate that all rule paths are correct and functional.
- Ensure each mode's custom instructions reflect the updated rule sets.
---
*This file will be updated after each major system change. Maintain as single source of truth for Roo AI context.*

View File

@@ -73,4 +73,32 @@ Munkafolyamat és Szabályok
Fájlkezelés: Minden tervet és plan.md fájlt a /plans könyvtárba ments el.
Szigorú tiltás: Soha ne becsülj meg munkaidőt (óra, nap). Csak a logikai lépéseket és a készültségi állapotot kezeld.
Szigorú tiltás: Soha ne becsülj meg munkaidőt (óra, nap). Csak a logikai lépéseket és a készültségi állapotot kezeld.
## 🏗️ Rendszerarchitektúra Alapelvek (DDD & Séma Szeparáció)
### Tech Stack
- **Backend:** 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.
### 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`).
### 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.
### 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.

View File

@@ -9,4 +9,22 @@
## 📝 Naplózás és Tesztelés
- Minden folyamatot dedikált log fájlokba naplózz.
- A kód elkészítése után futtass ellenőrzést. Ha hiba van, jelezd a Debuggernek vagy kérj segítséget az Architecttől.
- A kód elkészítése után futtass ellenőrzést. Ha hiba van, jelezd a Debuggernek vagy kérj segítséget az Architecttől.
## 🔍 Hibakeresési Protokoll (Debug Protocol)
Soha ne találgass! A hibakeresés 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.
## ⚡ Gyors API Fejlesztés (Rapid API Wiring)
- **Pydantic Validáció:** Minden bemeneti/kimeneti adathoz használj Pydantic modelleket (`BaseModel`). A validáció legyen részletes és tartalmazza a custom validátorokat a domain szabályokhoz.
- **Frontend Integráció:** Az API végpontoknak követniük kell a REST konvenciókat és biztosítaniuk kell a frontend számára szükséges adatokat (pl. pagination, filtering, sorting). Használd a `fastapi.Query`, `fastapi.Path`, `fastapi.Body` paramétereket.
- **Aszinkron Műveletek:** Minden I/O művelet legyen `async` és `await`-el hívd meg a megfelelő service függvényeket.
- **Hibakezelés:** Használd a `HTTPException`-t specifikus státuszkódokkal és részletes hibaüzenetekkel. Naplózd a hibákat a rendszer loggerén keresztül.

View File

@@ -21,4 +21,12 @@ Mielőtt egy feladatot (Gitea issue/kártya) "Kész"-nek nyilvánítasz a felhas
- **Orchestrator:** Te bontod le a Gitea kártyákat kisebb feladatokra. Használd a `gitea_manager.py create` parancsot.
- **Architect / Wiki Specialist:** Te tervezed meg a DDD (Domain-Driven Design) sémákat. A terveket a `history.md`-be vagy a megfelelő wiki/specifikációs fájlba írd.
- **Fast Coder:** Te írod a kódot a `logic_spec_*.md` alapján. Mielőtt bezárod a kártyát, ellenőrizd, hogy a szintaxis hibátlan-e.
- **Auditor / Debugger:** Te ellenőrzöd a Coder munkáját. Ha hibát találsz, javítod. A tesztjeid SOHA nem írhatják felül a fejlesztői adatbázist (Lásd 1-es pont).
- **Auditor / Debugger:** Te ellenőrzöd a Coder munkáját. Ha hibát találsz, javítod. A tesztjeid SOHA nem írhatják felül a fejlesztői adatbázist (Lásd 1-es pont).
## 🐳 4. KÖTELEZŐ RENDSZERIRÁNYELVEK (MANDATORY DIRECTIVES)
- **Docker Compose V2:** Mindig a `docker compose` (szóközzel) parancsot használd, SOHA ne a kötőjeles `docker-compose`-ot. Ez a projekt Docker Compose V2-t használ.
- **Színséma:** Sárga szöveg (#ffff00) TILOS világos háttereken. Használj helyette a #1e3a8a (sötétkék) színt a kiemelésekhez.
- **Adatbázis Verifikáció:** Minden adatbázis-módosítás előtt és után futtasd a `sync_engine.py` szkriptet a konténeren belül a séma konzisztencia ellenőrzéséhez:
`docker compose exec roo-helper python3 /app/backend/app/scripts/sync_engine.py`
- **Jegy Verifikáció:** Minden Gitea kártya állapotát a `gitea_manager.py` scripttel ellenőrizd (pl. `get <id>`) a műveletek előtt.
- **Kötelező 2lépéses járműfolyamat (Draft → Active):** Minden új járműrekordot először `DRAFT` státuszban kell létrehozni, majd csak explicit aktiválás után vált `ACTIVE` státuszra. Ez a szabály a `data.vehicles` táblára vonatkozik, és a robotoknak is be kell tartaniuk.

View File

@@ -1,6 +1,6 @@
# ⚡ RENDSZER ADATOK (FIX)
- **Gitea API Token:** d7a0142b5c512ec833307447ed5b7ba8c0bdba9a
- **Project ID:** (Keresd ki egyszer: `docker compose exec roo-helper python3 /scripts/gitea_manager.py` parancsal, ha kiírja, írd ide fixen!)
- **Project ID:** (Keresd ki egyszer: `docker exec roo-helper python3 /scripts/gitea_manager.py` parancsal, ha kiírja, írd ide fixen!)
- **Szabály:** TILOS a műveletek szimulálása. Ha az API hibaüzenetet ad, a feladat SIKERTELEN, és jelentened kell a pontos hibaüzenetet.
# 🗺️ ROO CODE NAVIGÁCIÓS TÉRKÉP
@@ -24,7 +24,13 @@
# 🛠️ TERMINÁL HASZNÁLATI SZABÁLYOK (KRITIKUS)
1. **Helyi környezet korlátja:** A helyi terminálban NINCS Python, NINCS adatbázis elérés. SOHA ne futtass közvetlen parancsokat (pl. `python ...`, `pip ...`, `pytest ...`).
2. **Kötelező prefix:** Minden végrehajtandó parancsot a `docker compose exec -T roo-helper` előtaggal kell futtatnod.
2. **Kötelező prefix:** Minden végrehajtandó parancsot a `docker compose exec roo-helper` előtaggal kell futtatnod.
3. **Munkakönyvtár kezelése:** Ha a parancsot egy alkönyvtárban kell futtatni, azt a konténeren belül tedd meg.
- **Hibás:** `cd backend && python -m app.scripts...`
- **Helyes:** `docker compose exec -T roo-helper /bin/sh -c "cd /app/backend && python3 -m app.scripts.unified_db_audit"`
- **Helyes:** `docker compose exec roo-helper /bin/sh -c "cd /app/backend && python3 -m app.scripts.unified_db_audit"`
CRITICAL DATABASE SYNC RULE:
NEVER use alembic upgrade head or try to resolve Alembic migration conflicts manually unless explicitly instructed. The Masterbook 2.0.1 architecture uses a custom synchronization engine.
To apply database schema changes based on SQLAlchemy models, ALWAYS use:
docker exec -it sf_api python -m app.scripts.sync_engine
Treat the sync_engine as the primary source of truth for schema generation.