222 lines
11 KiB
Markdown
222 lines
11 KiB
Markdown
# 🤖 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. |