# Service Finder Fejlesztési Történet ## 17-es Kártya: Billing Engine Service (Epic 3 - Pénzügyi Motor) **Dátum:** 2026-03-09 **Státusz:** Kész ✅ **Kapcsolódó fájlok:** `backend/app/services/billing_engine.py`, `backend/app/api/v1/endpoints/billing.py` ### Technikai Összefoglaló A Billing Engine Service-t az Epic 3 (Pénzügyi Motor) keretében implementáltuk, amely a 18-as kártya atomi tranzakciós logikájára épül. Az implementáció egyszerűsített interfészeket biztosít a gyakori számlázási műveletekhez, miközben megtartja az alapvető négyszeres wallet rendszert és a dupla könyvelést. #### Főbb Implementációk: 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 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 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) #### Tesztelés és Validáció: 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 Minden teszt sikeresen lefut: "MINDEN TESZT SIKERES! A PÉNZÜGYI MOTOR ATOMBIZTOS!" #### 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 --- ### Korábbi Kártyák Referenciája: - **15-ös kártya:** Wallet modell és négyszeres wallet rendszer - **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) **Dátum:** 2026-03-09 **Státusz:** Kész ✅ **Kapcsolódó fájlok:** `backend/app/workers/system/subscription_worker.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 #### 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 #### Futtatás: ```bash docker exec sf_api python -m app.workers.system.subscription_worker ``` #### Függőségek: - **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 --- *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. --- ## 66-os Kártya: Social 3 - Verifikált Szerviz Értékelések (User → Service) **Dátum:** 2026-03-12 **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` ### 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. #### 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ú 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 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 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. ### 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. ### Következő lépések - 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. --- ## 4 Korrekció a 100%-os szinkronhoz **Dátum:** 2026-03-16 **-e --- ### 2026-03-22 - Codebase Audit (Jegy #42) Elindítva - **Esemény:** Az automatizált Audit Scanner lefutott, és legenerálta a 240 fájl leltárát a .roo/audit_ledger_94.md fájlba. - **Fájlok száma:** 240 Python fájl (több mint a várt 94) - **Kategóriák:** API Endpoints (26), Core (7), Models (28), Schemas (20), Scripts (19), Services (41), Tests (41), Workers (49), Other (9) - **Szkript:** `backend/app/scripts/audit_scanner.py` sikeresen létrehozva és futtatva - **Státusz:** A Gitea #42-es jegy elindítva, az audit ledger kész, a tényleges fájlellenőrzés hátravan. ### 2026-03-22 - Epic 9 Kártyák Létrehozása - **Esemény:** A 42-es jegy lezárva. Az Epic 9 öt új audit kártyája sikeresen létrehozva a Gitea-ban. ### 2026-03-22 - Epic 9: Workers Audit (#106) - **Esemény:** A Workers mappa (49 fájl) osztályozása megtörtént az audit_ledger_94.md fájlban. Várakozás a Tulajdonos jóváhagyására a törlésekhez/refaktorálásokhoz. ### 2026-03-22 - Epic 9: Workers Audit (#106) - TELJES - **Esemény:** Auditor módban mind a 49 worker fájl szigorú átvizsgálása és osztályozása megtörtént az audit_ledger_94.md-ben. ### 2026-03-22 - Epic 9: Workers Audit (#106) - Biztonsági mentés - **Soft Delete:** 5 elavult worker fájl átnevezve .py.old kiterjesztésre törlés helyett. - **Refaktor:** Felfüggesztve, a Tulajdonos felülvizsgálja az architektúrát (pl. Google alternatívák). ### 2026-03-22 - Epic 9: Workers Audit (#106) Befejezve - **Eredmény:** Soft delete kész. Google validátor Enum hibája javítva. Megtervezve a jövőbeli 5-szintes AI-vezérelt validációs pipeline jegye. ### 2026-03-22 - Epic 9: Services Audit (#107) - Röntgenkép - **Esemény:** Auditor módban 41 services fájl szigorú átvizsgálása megtörtént az audit_ledger_94.md-ben. Várakozás a Tulajdonos jóváhagyására. 2026-03-22 14:45: Services mappa technikai adósság tisztítása kész (Ticket #107). ### 2026-03-22 - Epic 9: API Audit (#108) - Röntgenkép - **Esemény:** Auditor módban 26 API fájl szigorú átvizsgálása megtörtént az audit_ledger_94.md-ben. Várakozás a Tulajdonos jóváhagyására. ### 2026-03-22 - Epic 9: API Audit (#108) Befejezve - **Eredmény:** Az API végpontok szigorú RBAC védelme beállítva. A zárt ökoszisztéma elve alapján minden végpont (katalógus, szolgáltatók, analitika) regisztrációhoz kötött. ### 2026-03-22 - Epic 9: Models & Schemas Audit (#109) - Röntgenkép - **Esemény:** Auditor módban az adatstruktúrák (55 fájl) szigorú átvizsgálása megtörtént az audit_ledger_94.md-ben. Várakozás a Tulajdonos jóváhagyására. ### 2026-03-22 - Epic 9: Tests & Scripts Audit (#110) - Röntgenkép - **Esemény:** Auditor módban a tesztek és szkriptek szigorú átvizsgálása megtörtént az audit_ledger_94.md-ben. A 109-es jegy lezárva. Várakozás a Tulajdonos jóváhagyására az utolsó tisztításhoz. ### 2026-03-22 - Epic 9: Befejezve (110-es Jegy Lezárva) - **Eredmény:** A padlástakarítás (Scripts & Tests) kész, 3 elavult migrációs szkript archiválva. Ezzel a TELJES 240 fájlos Codebase Audit sikeresen lezárult. A projekt technikai adóssága minimalizálva, a biztonság maximalizálva. ### 2026-03-22 - Epic 9: AI Pipeline (#111) Indítása - **Esemény:** A meglévő adatmodellek feltérképezve. A validation_pipeline.py skeleton (vázlat) és a gondolatmenet létrehozva a biztonságos, párhuzamos implementációhoz. ### 2026-03-22 - Epic 9: AI Pipeline (#111) Korrekció - **Esemény:** A Tulajdonos elutasította a hibás vízesést. A validation_pipeline.py újraírva a helyes, költséghatékony sorrenddel (1. OSM, 2. VIES, 5. Google Fallback). ### 2026-03-22 - Epic 9: AI Pipeline (#111) 1. Fázis - **Esemény:** A Validation Orchestrator és az 1. Szint (OSM Nominatim API hívás) sikeresen implementálva. A többi szint egyelőre fallback-et ad. ### 2026-03-22 - Epic 7: Gamification 2.0 (#79) Felderítés - **Esemény:** Az Alembic elvetve. A kód-szintű modellek felmérése és a custom sync_engine.py futtatása megtörtént a valós DB állapot (diff) feltérképezésére. ### 2026-03-22 - Epic 7: Gamification 2.0 (#79) Befejezve - **Esemény:** A SeasonalCompetitions modell és a negatív szintek implementálva. A sync_engine.py sikeresen szinkronizálta az új sémákat az adatbázisba Alembic nélkül. ### 2026-03-22 - Epic 9: AI Pipeline (#111) 2. Fázis - **Esemény:** Az EU VIES REST API integráció és a helyi Ollama (Qwen) AI JSON Parser sikeresen implementálva a 2. szinthez. ### 2026-03-22 - Epic 9: AI Pipeline (#111) Befejezve - **Esemény:** A 3. (Foursquare), 4. (Web Scraping) és 5. (Google Fallback) szintek implementálva. Az 5-szintes AI validációs motor teljesen működőképes. ### 2026-03-22 - Admin Javítások (#105) Felderítés - **Esemény:** Az Admin API végpontok felmérése és a hiányosságok elemzése megtörtént. Várakozás a Tulajdonos döntésére az Admin UI kapcsán. ### 2026-03-22 - Frontend Előkészületek - **Esemény:** A seed_v2_0.py elkészült a mock adatokhoz. Az Epic 10 (Admin Frontend) specifikációja legenerálva a dokumentációk közé. ### 2026-03-22 - Epic 10 Előkészítés (#113) - **Esemény:** A legfontosabb Admin API végpontok (AI trigger, Térkép lokáció frissítés, Büntető szintek kiosztása) sikeresen implementálva a Nuxt 3 dashboard számára.