kincses/service-finder
1
0
Fork 0
Code Issues 53 Pull Requests Packages Projects 2 Releases Wiki Activity

2026.06.04 frontend építés közben

Browse Source
This commit is contained in:
Roo
2026-06-04 07:26:22 +00:00
parent 7adf6cc3e3
commit 59a30ac428
3302 changed files with 24091 additions and 1771 deletions
Download Patch File Download Diff File Expand all files Collapse all files

222
plans/logic_spec_66_verified_service_reviews.md
View File

@@ -1,222 +0,0 @@
# 🤖 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.

224
plans/logic_spec_80_gamification_2_0.md
View File

@@ -1,224 +0,0 @@
# 🎮 Logic Spec 80: Gamification 2.0, Verseny és Önvédelmi Rendszer
**Verzió:** 1.0
**Dátum:** 2026-03-15
**Szerző:** Rendszer-Architect
**Kapcsolódó mérföldkő:** [MILESTONE_8_GAMIFICATION_PRO.md](../MILESTONE_8_GAMIFICATION_PRO.md)
## 🎯 Modul célja és Masterbook 2 illeszkedés
### Cél
A Gamification 2.0 modul kiterjeszti a meglévő XP‑ és szintrendszert szezonális versenyekkel, önvédelmi mechanizmusokkal és egy robusztus moderációs keretrendszerrel. A modul biztosítja, hogy a felhasználók által beküldött szervizadatok biztonságosan, ellenőrzött módon kerüljenek a productionba, miközben a spam és rosszindulatú tevékenységeket automatikusan szűri.
### Masterbook 2 illeszkedés
- **Epic 7: Marketplace & API (A Külvilág felé)** – A szervizek publikálása és a marketplace minőségbiztosítása.
- **Epic 5: Robot Ecosystem** – A service robot pipeline (0–4) hibáinak kijavítása és kiegészítése.
- **Epic 3: Identity & Social** – Felhasználói reputáció, trust score és büntetési rendszer.
## 🗄️ Adatmodell
### 1. Season tábla (`system.seasons`)
Féléves versenyek tárolása. Minden szezonhoz tartozik egy ranglista, amely a szezonban szerzett XP alapján rangsorol.
| Mező | Típus | Leírás |
|------|-------|---------|
| `id` | `INTEGER` (PK) | Egyedi azonosító |
| `name` | `VARCHAR(100)` | Szezon neve (pl. "2026 Tavasz") |
| `start_date` | `DATE` | Szezon kezdete |
| `end_date` | `DATE` | Szezon vége |
| `is_active` | `BOOLEAN` | Aktív szezon? (egyidőben legfeljebb egy lehet) |
| `created_at` | `TIMESTAMPTZ` | Létrehozás időbélyege |
**Indexek:**
- `idx_seasons_active` (`is_active`) WHERE `is_active = TRUE`
- `idx_seasons_dates` (`start_date`, `end_date`)
**Alembic terv:**
```sql
CREATE TABLE system.seasons (
id INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
name VARCHAR(100) NOT NULL,
start_date DATE NOT NULL,
end_date DATE NOT NULL,
is_active BOOLEAN DEFAULT FALSE,
created_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE UNIQUE INDEX idx_seasons_active_unique
ON system.seasons (is_active) WHERE is_active = TRUE;
```
### 2. UserContribution tábla (`gamification.user_contributions`)
Spam védelem: minden felhasználó csak 90 naponként kaphat XP‑t ugyanazon szerviz (fingerprint) beküldéséért.
| Mező | Típus | Leírás |
|------|-------|---------|
| `id` | `INTEGER` (PK) | Egyedi azonosító |
| `user_id` | `INTEGER` | `identity.users.id` hivatkozás |
| `service_fingerprint` | `VARCHAR(255)` | A beküldött szerviz hash‑je (MD5) |
| `action_type` | `VARCHAR(30)` | `submit_service`, `claim_business`, `review` |
| `earned_xp` | `INTEGER` | Az adott akcióért kapott XP |
| `cooldown_end` | `TIMESTAMPTZ` | Cooldown vége (90 nap a `submit_service` esetén) |
| `created_at` | `TIMESTAMPTZ` | Létrehozás időbélyege |
**Indexek:**
- `idx_user_contributions_user` (`user_id`, `service_fingerprint`, `action_type`)
- `idx_user_contributions_cooldown` (`cooldown_end`) WHERE `cooldown_end > NOW()`
**Alembic terv:**
```sql
CREATE TABLE gamification.user_contributions (
id INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
user_id INTEGER NOT NULL REFERENCES identity.users(id) ON DELETE CASCADE,
service_fingerprint VARCHAR(255) NOT NULL,
action_type VARCHAR(30) NOT NULL,
earned_xp INTEGER NOT NULL DEFAULT 0,
cooldown_end TIMESTAMPTZ NOT NULL,
created_at TIMESTAMPTZ DEFAULT NOW()
);
COMMENT ON TABLE gamification.user_contributions IS
'Spam védelem: felhasználók csak 90 naponként kaphatnak XP‑t ugyanazon szerviz beküldéséért.';
```
### 3. UserStats bővítés (`system.user_stats`)
A meglévő táblához új mezők a restrikciós szintek és büntető kvóták kezeléséhez.
| Mező | Típus | Leírás | Alapérték |
|------|-------|--------|-----------|
| `restriction_level` | `INTEGER` | 0 (normál), -1 (figyelmeztetés), -2 (korlátozott), -3 (banned) | 0 |
| `penalty_quota_remaining` | `INTEGER` | Hátralévő büntető kvóta (pl. 3 strike) | 3 |
| `banned_until` | `TIMESTAMPTZ` | Kitiltás vége (ha restriction_level = -3) | NULL |
**Alembic terv (meglévő tábla módosítása):**
```sql
ALTER TABLE system.user_stats
ADD COLUMN restriction_level INTEGER NOT NULL DEFAULT 0,
ADD COLUMN penalty_quota_remaining INTEGER NOT NULL DEFAULT 3,
ADD COLUMN banned_until TIMESTAMPTZ;
```
### 4. ServiceStaging bővítés (`marketplace.service_staging`)
Hiányzó mezők hozzáadása a teljes adatátvitel érdekében.
| Mező | Típus | Leírás |
|------|-------|---------|
| `contact_phone` | `VARCHAR` | Telefonszám (Robot 4 vagy user által megadható) |
| `website` | `VARCHAR` | Weboldal URL |
| `external_id` | `VARCHAR` | Külső rendszer azonosító (pl. Google Place ID) |
| `contact_email` | `VARCHAR` | E‑mail cím |
**Alembic terv:**
```sql
ALTER TABLE marketplace.service_staging
ADD COLUMN contact_phone VARCHAR,
ADD COLUMN website VARCHAR,
ADD COLUMN external_id VARCHAR,
ADD COLUMN contact_email VARCHAR;
```
### 5. SystemParameter bővítés (`system.system_parameters`)
Dinamikus küszöbértékek a gamification és moderáció számára.
| Kulcs | Érték (JSON) | Leírás |
|-------|--------------|---------|
| `service_promotion_threshold` | `{"trust_score": 50}` | Minimális trust_score a staging → promotionhoz |
| `xp_reward_base` | `{"submit_service": 50, "claim_business": 200}` | Alap XP jutalmak |
| `penalty_multiplier` | `{"level_-1": 0.5, "level_-2": 0.2}` | XP szorzó restrikciós szint szerint |
| `strike_policy` | `{"max_strikes": 3, "cooldown_days": 90}` | Strike‑ok és cooldown beállítások |
**Megjegyzés:** A meglévő tábla módosítása nem szükséges, csak új rekordok beszúrása.
## 🛡️ Admin kontroll: Global/Country/Region/User szintű változók
A `system.system_parameters` tábla `scope` mezője (`global`, `country`, `region`, `user`) lehetővé teszi a különböző szintű beállításokat. A Gamification 2.0 paraméterei alapértelmezetten `global` scope‑kal rendelkeznek, de felülírhatók country vagy region szinten (pl. különböző országokban eltérő trust_score küszöb).
**Példa a hierarchiára:**
1. **Global:** `service_promotion_threshold = 50`
2. **Country (HU):** `service_promotion_threshold = 40` (lazább feltételek Magyarországon)
3. **Region (Budapest):** `service_promotion_threshold = 60` (szigorúbb Budapesten)
A prioritás: `user` > `region` > `country` > `global`.
## 🤖 Robot Refactoring Tervek
### 1. Robot 3 (Enricher) – Logika finomhangolása
**Jelenlegi állapot:** `enrich_ready` → `researched` (trust_score növelés).
**Új állapot:** `enrich_ready` → `auditor_ready` (trust_score növelés, de nem publikál).
**Módosítások:**
- A státusz neve `auditor_ready` legyen, jelezve, hogy az Auditor feldolgozhatja.
- A trust_score számítás változatlan marad.
- A robot továbbra is csak a `service_staging` táblát módosítja.
### 2. Robot 2 (Auditor) – Új implementáció
**Fájl:** `service_robot_5_auditor.py` (vagy `service_robot_2_auditor.py`)
**Feladat:** Atom módon feldolgozza az `auditor_ready` státuszú staging bejegyzéseket.
**Lépések:**
1. **Kiválasztás:** `FOR UPDATE SKIP LOCKED` egy `auditor_ready` rekordra.
2. **Küszöb ellenőrzés:** Lekéri a `service_promotion_threshold` értékét a `system_parameters`‑ből.
3. **Döntés:**
- Ha `trust_score >= küszöb`:
- Organization létrehozása (ha még nem létezik) a `fleet.organizations` táblában.
- ServiceProfile létrehozása a `marketplace.service_profiles` táblában, a staging adatokkal.
- Státusz beállítása `pending_validation` (vagy `active`, ha azonnal publikálható).
- Audit log rögzítése (`audit.service_audit_log`).
- Egyébként:
- Státusz beállítása `needs_moderation`.
- InternalNotification létrehozása a moderátorok számára.
4. **Staging frissítés:** Státusz `audited`, `audited_at` időbélyeg.
**Technikai részletek:**
- Tranzakció használata (minden lépés egy tranzakcióban).
- Hibakezelés: hiba esetén `status = 'error'` és logolás.
- Időzítés: folyamatos feldolgozás (pl. 30 másodperces ciklus).
### 3. Robot 4 (Validator) – Integráció
A Validator továbbra is a `service_profiles` táblán dolgozik, de ha a rekord `pending_validation` státuszú, a Validator frissítheti a hiányzó mezőket (contact_phone, website) a Google Places API‑ból, majd átállítja `active`‑ra.
## 🔧 SystemParameter integráció
A Gamification 2.0 minden dinamikus értékét a `system.system_parameters` táblából olvassa ki. Ez lehetővé teszi a rendszer finomhangolását anélkül, hogy kódot kellene módosítani.
**Példa lekérdezésre:**
```python
async def get_promotion_threshold(db):
param = await db.scalar(
select(SystemParameter)
.where(SystemParameter.key == 'service_promotion_threshold')
.where(SystemParameter.scope == 'global')
)
if param:
return param.value.get('trust_score', 50)
return 50
```
## 📝 Geo‑logika (Service Finder algoritmus)
A Service Finder alapvetően lokáció‑alapú keresést valósít meg. A Gamification 2.0 nem módosítja a keresési algoritmust, de befolyásolja a találatok minőségét:
1. **Trust Score súlyozás:** Magasabb trust_score‑ú szervizek magasabbra kerülnek a találati listában.
2. **Szezonális bónusz:** Aktív szezonban beküldött szervizek extra láthatóságot kaphatnak.
3. **Restrikciók:** `restriction_level < 0` esetén a felhasználó beküldései nem jelennek meg, amíg a korlátozás fennáll.
## 🚀 Migrációs lépések (Alembic)
1. **Új táblák létrehozása:**
- `system.seasons`
- `gamification.user_contributions`
2. **Meglévő táblák bővítése:**
- `system.user_stats` (új mezők)
- `marketplace.service_staging` (hiányzó mezők)
3. **Alapértelmezett paraméterek beszúrása:**
- `service_promotion_threshold`, `xp_reward_base`, `penalty_multiplier`, `strike_policy`
4. **Robot kód frissítése:**
- Robot 3 státusz átnevezése `auditor_ready`‑re.
- Robot 5 (Auditor) implementálása.
- Robot 4 integrációja a `pending_validation` státusszal.
## ✅ Jóváhagyási pont
Ez a logic specifikáció a Modell Fázis (Foundation) teljes tervét tartalmazza. A következő lépés a tervek implementálása a Code módban. **Állj meg és kérj jóváhagyást a felhasználótól, mielőtt továbblépsz.**
---
*Ez a dokumentum a `/plans` könyvtárban található, és a 8. mérföldkő technikai specifikációjaként szolgál.*