refakotorálás előtti állapot

.roo/history.md

@@ -0,0 +1,92 @@
+# 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.