kincses/service-finder
1
0
Fork 0
Code Issues 7 Pull Requests Packages Projects 2 Releases Wiki Activity
Files
cddcd34ba9d9dfa34ea0723ace52dda2d92d57df
service-finder/plans/logic_spec_66_verified_service_reviews.md
Roo f53e0b53df refaktorálás javításai
2026-03-13 10:22:41 +00:00

11 KiB
Raw Blame History

🤖 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:

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

# 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.

Reference in New Issue View Git Blame Copy Permalink