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.

---

Universal Schema Synchronizer Script

Dátum: 2026-03-12 Státusz: Kész ✅ Kapcsolódó fájlok: backend/app/scripts/sync_engine.py, backend/app/models/__init__.py, backend/app/tests_internal/diagnostics/compare_schema.py

Technikai Összefoglaló

Létrehoztunk egy "Universal Schema Synchronizer" scriptet, amely dinamikusan importálja az összes SQLAlchemy modellt az app/models könyvtárból, összehasonlítja a live adatbázis sémával, és létrehozza a hiányzó táblákat és oszlopokat anélkül, hogy bármit törölne. A script célja, hogy ne kelljen Alembic-re támaszkodni a séma szinkronizáláshoz.

Főbb Implementációk:

1. Dinamikus import (sync_engine.py):

   • Az os.walk segítségével bejárja az app/models/ könyvtárat.
   • Minden .py fájlt importál importlib használatával, hogy a Base.metadata.tables automatikusan feltöltődjön.
   • A manuális importok mellett biztosítja, hogy minden modell betöltődik.

2. Séma javítási logika:

   • A compare_schema.py ellenőrzési logikáját felhasználva összehasonlítja a modellek metadatáját a live adatbázissal.
   • Hiányzó táblák esetén CREATE TABLE parancsot generál a SQLAlchemy CreateTable segítségével.
   • Hiányzó oszlopok esetén ALTER TABLE ADD COLUMN parancsot generál, figyelembe véve a PostgreSQL típusokat (String → VARCHAR, Integer → INT, stb.).
   • Kezeli a PostgreSQL enum típusokat (marketplace.moderation_status, marketplace.source_type) a táblák létrehozása előtt.

3. Biztonsági intézkedések:

   • SOHA nem töröl semmit (DROP TABLE/COLUMN).
   • Minden módosítás előtt kiírja a tervezett SQL parancsot a konzolra.
   • Aszinkron kapcsolatot használ, és a run_sync-et alkalmazza az inspector műveletekhez.

4. Modellek __init__.py frissítése:

   • A fájl megtartja a manuális importokat a kompatibilitás érdekében, de a dinamikus import garantálja, hogy minden modell betöltődik a Base.metadata számára.

Futás és Ellenőrzés:

• A script futtatása: docker exec sf_api python /app/app/scripts/sync_engine.py
• A szkript automatikusan futtatja a compare_schema.py diagnosztikát a szinkronizálás után, és csak akkor fejeződik be, ha minden zöld (100%-os szinkron).
• A teszt sikeresen lefutott, és a korábban hiányzó 10 tábla és számos oszlop létrejött.

Függőségek:

• Bemenet: SQLAlchemy modellek (app/models), adatbázis kapcsolat (settings.SQLALCHEMY_DATABASE_URI)
• Kimenet: Séma szinkronizálás, hiányzó elemek létrehozása, konzol log.

Következő lépések

• A script integrálható a CI/CD folyamatba, hogy automatikusan szinkronizálja a sémát fejlesztői környezetekben.
• További fejlesztés: indexek és constraint-ek ellenőrzése/javítása.

---

Megjegyzés: A Universal Schema Synchronizer jelentősen csökkenti a függőséget az Alembic migrációktól, és lehetővé teszi a gyors séma frissítést fejlesztési és teszt környezetekben. A script csak bővítő műveleteket végez, soha nem töröl, íve biztonságos a használata.

---

Automated Schema Registry & Deep Constraint Sync

Dátum: 2026-03-12 Státusz: Kész ✅ Kapcsolódó fájlok:

• backend/app/models/registry.py
• backend/app/database.py
• backend/app/scripts/unified_db_sync.py
• backend/app/scripts/pre_start.sh
• docker-compose.yml

Technikai Összefoglaló

A manuális SQL javítások (pl. Unique Constraint hibák) kiküszöbölésére egy teljesen automatizált, deklaratív szinkronizációs rendszert építettünk ki. A rendszer központi modell regisztert használ, amely dinamikusan betölti az összes SQLAlchemy modellt, és egy kibővített sync engine, amely a hiányzó egyedi kényszereket és indexeket is létrehozza.

Főbb Implementációk:

1. Központi Modell Regiszter (registry.py):

• Automatikusan bejárja az app/models könyvtárat és importál minden .py fájlt.
• Biztosítja, hogy a Base.metadata teljesen feltöltődjenek a táblákkal, kényszerekkel és indexekkel.
• Két kulcsfüggvény: load_all_models() (dinamikus import) és ensure_models_loaded() (idempotens betöltés).
• A database.py-ban egy késleltetett import (ensure_models_loaded) garantálja, hogy az API indulásakor már minden modell elérhető legyen.

2. Unified Sync Engine (unified_db_sync.py):

• A korábbi sync_engine.py kibővítése, amely most már a hiányzó UniqueConstraint és Index objektumokat is detektálja és javítja.
• A inspector.get_unique_constraints() és inspector.get_indexes() metódusokkal összehasonlítja a modellben definiált kényszereket az adatbázis aktuális állapotával.
• Hiányzó kényszer esetén ALTER TABLE ... ADD CONSTRAINT UNIQUE SQL parancsot generál és végrehajt (ha --apply kapcsolóval futtatjuk).
• Hiányzó index esetén CREATE INDEX parancsot generál.
• A script támogatja a dry‑run módot (--apply nélkül), amikor csak kiírja a javasolt SQL‑eket.

3. Startup Automatizálás (pre_start.sh):

• Egy bash script, amelyet az API konténer indításakor futtatunk.
• Először lefuttatja az unified_db_sync.py --apply parancsot, hogy a séma és a kényszerek szinkronban legyenek.
• Ha a szinkronizáció sikeres, elindítja a FastAPI szervert (uvicorn).

4. Docker‑compose integráció:

• Az api szolgáltatás command mezője át lett írva a pre_start.sh futtatására.
• Így minden konténer indulás előtt automatikusan lefut a séma‑ és kényszer‑szinkronizáció.

Tesztelés és Validáció:

• UniqueConstraint hozzáadása a CatalogDiscovery modellhez: A CatalogDiscovery osztályhoz hozzáadtunk egy második egyedi kényszert (uq_make_model_class), amely a make, model és vehicle_class oszlopok kombinációját biztosítja egyedinek.
• Sync futtatása: Az unified_db_sync.py --apply parancs futtatásakor a script észlelte, hogy a kényszer már létezik az adatbázisban (korábbi migrációk miatt), így nem hozott létre újat. A kimenetben a ✅ Unique constraint on ('make', 'model', 'vehicle_class') exists. üzenet igazolta, hogy a rendszer helyesen működik.
• Adatbázis ellenőrzés: A PostgreSQL pg_constraint táblájában látható, hogy a uq_make_model_class kényszer valóban jelen van.

Függőségek:

• Bemenet: SQLAlchemy modellek (összes app/models/*.py), live PostgreSQL adatbázis kapcsolat.
• Kimenet: Szinkronizált séma, hiányzó táblák, oszlopok, egyedi kényszerek és indexek létrehozva.
• Környezet: Docker konténer (sf_api), shared‑postgres adatbázis.

Kapcsolódó Módosítások:

• Modellek: asset.py – a CatalogDiscovery.__table_args__ kibővítve egy új UniqueConstraint-tel.
• Database: database.py – ensure_models_loaded() függvény bevezetése a körkörös importok elkerülésére.
• Scriptek: unified_db_sync.py (új), pre_start.sh (új).
• Docker: docker‑compose.yml – az api service command módosítása.

Következő lépések

• A unified_db_sync.py továbbfejleszthető a foreign key és check constraint ellenőrzésével.
• A script integrálható a CI/CD folyamatba, hogy minden pull request előtt lefusson egy dry‑run és jelezzen, ha a modellváltozások SQL parancsokat igényelnek.

---