service-finder/.roo/history.md

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:

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.