# 🤖 Logic Spec: Social 3 – Verifikált Szerviz Értékelések (User → Service)
**Epic:** 4.1 – Gazdasági és Közösségi Motorok (Economy & Social)  
**Kártya:** #66 – Social 3: Verifikált Szerviz Értékelések – User → Service  
**Prioritás:** Magas – Csak igazolt pénzügyi tranzakció után lehet értékelni!

---

## 🎯 Modul Célja és MasterBook 2 Illeszkedés

A **Social 3** modul a Service Finder közösségi véleményrendszerének magas szintű minőségbiztosítását valósítja meg. A MasterBook 2 **“Csak valós tranzakció, valós vélemény”** elvét követi: egy felhasználó csak akkor adhat le értékelést egy szervizről, ha az adott szerviznél korábban **igazolt pénzügyi tranzakció** (számla, fizetés) történt, és az értékelési időablak (konfigurálható) még nem járt le.

### 🛡️ Alapvető Biztonsági Elvek
1. **Tranzakció‑alapú verifikáció** – `transaction_id` kötelező, és csak a felhasználó saját tranzakcióira hivatkozhat.
2. **Időkorlát** – Az értékelési lehetőség a tranzakció után limitált ideig (pl. 30 nap) él.
3. **Egyszeri értékelés** – Egy tranzakciót csak egyszer lehet értékelni (UniqueConstraint).
4. **Trust‑Score súlyozás** – A felhasználó Gondos Gazda Indexe befolyásolja, mennyire számít az értékelése a szerviz globális pontszámában.

---

## 🗄️ Adatmodell (Alembic Terv)

### 1. Új Tábla: `service_reviews` (marketplace séma)
| Mező | Típus | Kötelező | Leírás |
|------|-------|----------|---------|
| `id` | `bigserial` | ✅ | Elsődleges kulcs |
| `service_id` | `integer` | ✅ | FK → `marketplace.service_profiles.id` |
| `user_id` | `integer` | ✅ | FK → `identity.users.id` |
| `transaction_id` | `uuid` | ✅ | FK → **`finance.transactions.id`** (a FinancialLedger transaction_id mezője) |
| `price_rating` | `smallint` | ✅ | Ár‑érték arány (1–10) |
| `quality_rating` | `smallint` | ✅ | Minőség (1–10) |
| `time_rating` | `smallint` | ✅ | Időtartam (1–10) |
| `communication_rating` | `smallint` | ✅ | Kommunikáció (1–10) |
| `comment` | `text` | ❌ | Szabad szöveges vélemény |
| `is_verified` | `boolean` | ✅ | Alapértelmezetten `true` (mert tranzakció‑alapú) |
| `created_at` | `timestamptz` | ✅ | Létrehozás időbélyege |
| `updated_at` | `timestamptz` | ❌ | Frissítés időbélyege |

**Indexek:**
- `idx_service_reviews_service` (`service_id`)
- `idx_service_reviews_user` (`user_id`)
- `idx_service_reviews_transaction` (`transaction_id`) – egyedi index a `UniqueConstraint` miatt

**Egyediségi korlát:**
- `uq_service_review_transaction` – egy tranzakcióhoz csak egy értékelés tartozhat.

**Külső kulcsok:**
- `service_id` → `marketplace.service_profiles.id` (ON DELETE CASCADE)
- `user_id` → `identity.users.id` (ON DELETE SET NULL)
- `transaction_id` → `finance.transactions.id` (ON DELETE RESTRICT)

> **Megjegyzés:** A `finance.transactions` tábla jelenleg a `audit.financial_ledger` tábla `transaction_id` oszlopával azonosítható. A FK hivatkozást ennek megfelelően kell felépíteni.

### 2. Frissítendő Tábla: `service_profiles` (marketplace séma)
A `service_profiles` táblába bekerülnek az aggregált értékelési adatok:

| Új mező | Típus | Leírás |
|---------|-------|---------|
| `rating_verified_count` | `integer` | Összes verifikált értékelés száma |
| `rating_price_avg` | `decimal(3,2)` | Átlagos ár‑érték (1‑10) |
| `rating_quality_avg` | `decimal(3,2)` | Átlagos minőség |
| `rating_time_avg` | `decimal(3,2)` | Átlagos időtartam |
| `rating_communication_avg` | `decimal(3,2)` | Átlagos kommunikáció |
| `rating_overall` | `decimal(3,2)` | Súlyozott összpontszám (trust‑score‑al számolva) |
| `last_review_at` | `timestamptz` | Legutóbbi értékelés ideje |

---

## ⚙️ Admin Kontroll (Hierarchikus Rendszerparaméterek)

A hierarchikus `system_parameters` táblába két új konfigurációs kulcs kerül:

### 1. `REVIEW_WINDOW_DAYS`
- **Alapérték:** `30`
- **Scope:** `GLOBAL` (ország‑ vagy régió‑specifikus felülírható)
- **Leírás:** A tranzakció után ennyi napig lehet értékelést beküldeni. Ha lejárt, az API `HTTP 410 Gone` hibát ad vissza.

### 2. `TRUST_SCORE_INFLUENCE_FACTOR`
- **Alapérték:** `1.0`
- **Scope:** `GLOBAL`
- **Leírás:** A felhasználó Gondos Gazda Indexének súlyozási tényezője.  
  Pl.: `trust_score = 85` → súly = `1.0 + (85 / 100) = 1.85`. A magasabb trust‑score‑ú felhasználók értékelése jobban számít a szerviz összpontszámába.

**Példa beillesztés:**
```sql
INSERT INTO system.system_parameters (key, category, value, scope_level, description)
VALUES 
    ('REVIEW_WINDOW_DAYS', 'social', '{"value": 30}', 'global', 'Értékelési időablak napokban'),
    ('TRUST_SCORE_INFLUENCE_FACTOR', 'social', '{"value": 1.0}', 'global', 'Trust‑score súlyozási tényező');
```

---

## 🧠 Geo‑logika és Service Finder Algoritmus

A verifikált értékelések közvetlenül befolyásolják a **Service Finder keresési rangsorolását**:

### Súlyozott Pontszám Számítása
```
weighted_score = (
    price_avg * price_weight +
    quality_avg * quality_weight +
    time_avg * time_weight +
    communication_avg * communication_weight
) * trust_influence_factor
```
Ahol a súlyok a `system_parameters`‑ből származnak (alapérték: mindegyik 0.25).

### Keresési Rangsorolás
A `ServiceFinder` algoritmus a következő tényezőket veszi figyelembe:
1. **Verifikált értékelések száma** – minél több, annál megbízhatóbb a pontszám.
2. **Trust‑score súlyozás** – a magasabb Gondos Gazda Indexű felhasználók véleménye többet nyom.
3. **Frissesség** – a legutóbbi értékelések nagyobb súllyal szerepelnek (exponenciális lecsengés).

### Cache‑elés
A `service_profiles` táblában tárolt aggregált értékek **percenként frissülnek** egy háttér‑worker (`service_rating_aggregator`) által, így a keresési lekérdezések nem terhelik élőben az adatbázist.

---

## 🔗 Függőségek (Dependencies)

### Bemenet (Mikre támaszkodik)
- **Finance modul:** `audit.financial_ledger` (transaction_id egyedisége és állapota).
- **Identity modul:** `identity.users` (user_id) és `identity.user_trust_profiles` (trust‑score).
- **Marketplace modul:** `marketplace.service_profiles` (service_id).

### Kimenet (Mik támaszkodnak rá)
- **Service Finder keresőmotor:** A súlyozott értékelések befolyásolják a szervizek rangsorolását.
- **AnalyticsService:** A TCO/km számításokhoz szükséges a szerviz minőségi mutatója.
- **Gamification Engine:** Értékelés‑írásért XP‑jutalom jár (csak verifikált tranzakció esetén).

---

## 🛠️ Technikai Specifikációk

### 1. Service Réteg (`marketplace_service.py`)
Új függvények:
- `create_verified_review(service_id, user_id, transaction_id, ratings, comment)`
  1. Ellenőrzi, hogy a `transaction_id` létezik‑e és a `user_id`‑hoz tartozik‑e.
  2. Ellenőrzi, hogy a tranzakció időpontja a `REVIEW_WINDOW_DAYS`‑on belül van‑e.
  3. Ha minden ok, beszúrja a `service_reviews` táblába.
  4. Elindítja a háttér‑aggregátort (`update_service_rating_aggregates`).

- `update_service_rating_aggregates(service_id)`
  - Újraszámolja az összes aggregált mezőt a `service_profiles` táblában.

### 2. API Végpontok (`marketplace.py`)
- **`POST /api/v1/services/{service_id}/reviews`**  
  Szigorú validáció: `transaction_id` kötelező, a hitelesített felhasználónak kell lennie a tranzakció tulajdonosának.

- **`GET /api/v1/services/{service_id}/reviews`**  
  Lapozható listázás, opcionális szűrés `is_verified` szerint.

### 3. Háttér‑feldolgozás
- **Rating Aggregator Worker:** Percenként frissíti a `service_profiles` aggregált értékeit.
- **Lejárt értékelési ablakok figyelése:** Napi egyszer jelez, ha egy tranzakció értékelési ablaka lejárt (értesítés a felhasználónak).

---

## 📊 Migrációs Terv (Alembic)

### 1. Lépés: Új tábla létrehozása
```python
# migrations/versions/xxxx_verified_service_reviews.py
def upgrade():
    op.create_table(
        'service_reviews',
        sa.Column('id', sa.BigInteger(), primary_key=True),
        sa.Column('service_id', sa.Integer(), nullable=False),
        sa.Column('user_id', sa.Integer(), nullable=False),
        sa.Column('transaction_id', sa.UUID(), nullable=False),
        # ... további mezők
        schema='marketplace'
    )
    op.create_foreign_key(
        'fk_service_reviews_transaction', 'service_reviews',
        'financial_ledger', ['transaction_id'], ['transaction_id'],
        source_schema='marketplace', referent_schema='audit'
    )
    op.create_unique_constraint(
        'uq_service_review_transaction', 'service_reviews',
        ['transaction_id'], schema='marketplace'
    )
```

### 2. Lépés: `service_profiles` bővítése aggregált mezőkkel
### 3. Lépés: Rendszerparaméterek beszúrása

---

## ✅ Tesztelési Scenáriók

1. **Sikeres értékelés:** Valós tranzakció, időablakon belül, első értékelés.
2. **Duplikált tranzakció:** Ugyanazt a tranzakciót másodszor nem lehet értékelni (409 Conflict).
3. **Időablak lejárt:** A tranzakció több mint 30 napos → 410 Gone.
4. **Nem a felhasználó tranzakciója:** Másik user transaction_id‑ját használja → 403 Forbidden.
5. **Trust‑score súlyozás:** Két felhasználó (trust 30 vs 90) értékelései különböző súllyal számítanak.

---

## 🚀 Következő Lépések (3A Granularitás)

1. **Alembic migráció** – `service_reviews` tábla létrehozása.
2. **System paraméterek** – `REVIEW_WINDOW_DAYS` és `TRUST_SCORE_INFLUENCE_FACTOR` beszúrása.
3. **Service réteg** – `create_verified_review` logika implementálása.
4. **API végpontok** – `POST /services/{id}/reviews` és `GET /services/{id}/reviews`.
5. **Háttér‑aggregátor** – Percenkénti rating‑frissítés.
6. **Tesztelés** – Integrációs tesztek a fenti scenáriókra.
7. **Dokumentáció** – Swagger + felhasználói kézikönyv.

---

## ⚠️ Kockázatok és Megoldások

| Kockázat | Megoldás |
|----------|----------|
| A `finance.transactions` tábla nem létezik, csak `audit.financial_ledger` | FK a `financial_ledger.transaction_id`‑re mutat, a séma neve `audit`. |
| Trust‑score még nincs minden felhasználónál | Alapérték 50, a súlyozás ezzel működik. |
| Túl sok értékelés terheli az élő adatbázist | Aggregált mezők + cache‑elés (percenkénti háttér‑frissítés). |

---

**Jóváhagyás szükséges:** A fenti tervezet alapján lehet továbblépni a megvalósításra. A migrációs szkriptek és a API végpontok pontos kódja csak a jóváhagyás után készül el.