92 lines
4.5 KiB
Markdown
92 lines
4.5 KiB
Markdown
# 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. |