service-finder/plans/logic_spec_66_verified_service_reviews.md at cddcd34ba9d9dfa34ea0723ace52dda2d92d57df

Files

Roo f53e0b53df refaktorálás javításai

2026-03-13 10:22:41 +00:00

11 KiB

Raw Blame History

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

Tranzakció‑alapú verifikáció – transaction_id kötelező, és csak a felhasználó saját tranzakcióira hivatkozhat.
Időkorlát – Az értékelési lehetőség a tranzakció után limitált ideig (pl. 30 nap) él.
Egyszeri értékelés – Egy tranzakciót csak egyszer lehet értékelni (UniqueConstraint).
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:

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:

Verifikált értékelések száma – minél több, annál megbízhatóbb a pontszám.
Trust‑score súlyozás – a magasabb Gondos Gazda Indexű felhasználók véleménye többet nyom.
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

# 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

Sikeres értékelés: Valós tranzakció, időablakon belül, első értékelés.
Duplikált tranzakció: Ugyanazt a tranzakciót másodszor nem lehet értékelni (409 Conflict).
Időablak lejárt: A tranzakció több mint 30 napos → 410 Gone.
Nem a felhasználó tranzakciója: Másik user transaction_id‑ját használja → 403 Forbidden.
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)

Alembic migráció – service_reviews tábla létrehozása.
System paraméterek – REVIEW_WINDOW_DAYS és TRUST_SCORE_INFLUENCE_FACTOR beszúrása.
Service réteg – create_verified_review logika implementálása.
API végpontok – POST /services/{id}/reviews és GET /services/{id}/reviews.
Háttér‑aggregátor – Percenkénti rating‑frissítés.
Tesztelés – Integrációs tesztek a fenti scenáriókra.
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.

11 KiB Raw Blame History Unescape Escape

🤖 Logic Spec: Social 3 – Verifikált Szerviz Értékelések (User → Service)