2026.06.04 frontend építés közben

old_maps/plans/logic_spec_66_verified_service_reviews.md

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

old_maps/plans/logic_spec_80_gamification_2_0.md

@@ -0,0 +1,224 @@
+# 🎮 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.*

old_maps/plans/logic_spec_b2b_shadow.md

@@ -0,0 +1,20 @@
+# B2B Meghívó és Shadow Identity Specifikáció
+
+## 1. Modul célja és Masterbook 2 illeszkedés
+A fejlesztés célja a B2B flotta csatlakozási folyamat megvalósítása a Masterbook 2 "Shadow Identity Check" logikájával. A tulajdonosok vagy adminisztrátorok e-mail alapján meghívhatnak tagokat a szervezetükbe.
+
+## 2. Adatmodell változások (Alembic terv)
+A `VerificationToken` táblában szükséges a `user_id` mezőt nullable-re állítani, valamint egy `extra_data` JSON mezőt hozzáadni a meghívó metaadatainak (org_id, role, email) tárolásához, mivel új (még nem regisztrált) felhasználók számára is készülhet meghívó token.
+
+A `sync_engine.py` segítségével legeneráljuk az Alembic migrációt.
+
+## 3. Shadow Identity Check Logika
+A `complete_kyc` folyamat során, mielőtt egy frissen regisztrált `User` `Person` rekordja véglegesítésre kerülne, a rendszer azonosítja a "Shadow" profilokat a `last_name`, `first_name` (és opcionálisan `birth_date`) alapján.
+- Ha egyezés van: az új `User` megörökli az eddig "Shadow" formában (pl. AI általi OCR betöltéssel) létező `Person` rekordot, és a megárvult eredeti `Person` rekord deaktiválódik.
+
+## 4. Új API Végpontok (`organizations.py`)
+- `POST /{org_id}/invitations`: Meghívó küldése (e-mail ellenőrzéssel). Meglévő felhasználónál `OrganizationMember` készül "pending" státusszal. Új felhasználónál `VerificationToken` generálódik.
+- `POST /invitations/{token}/accept`: Meghívó elfogadása token alapján.
+
+## 5. Tesztelés
+E2E teszt script (`test_invitation_e2e.py`) futtatása az `sf_api` konténerben a fenti forgatókönyvek ellenőrzésére.

old_maps/plans/logic_spec_mlm_network.md

@@ -0,0 +1,30 @@
+# MLM Referral, Gamification és Credit Payout Specifikáció
+
+## Modul célja és Masterbook 2 illeszkedés
+P2P Gamification, MLM Referral System, és Credit Wallet kifizetések bevezetése a Masterbook 2 "Triple Wallet" és "Dual Entity" alapelvei szerint. 
+A cél egy 3-szintű meghívásos hálózat (L1, L2, L3) technikai megvalósítása, XP (Social Point) jóváírása az L1 tagnak a meghívott sikeres KYC folyamata után, valamint előfizetési jutalékok (10%, 5%, 3%) automatikus lekönyvelése a CREDIT tárcába (Financial Ledger).
+
+## Adatmodell: Alembic terv, Twin-technika
+- **auth.py (Schema):** `UserLiteRegister` kiegészül a `referred_by_code: Optional[str]` mezővel.
+- **User Modell (Identity):** A `referral_code` (saját kód, pl. 8 karakteres slug) és `referred_by_id` (a meghívó L1 ID-ja, ForeignKey a `users.id`-ra) alapból adott a "Dual Entity" elvek szerint (ellenőrizni kell az identity sémában, ha hiányzik, Alembic-kel hozzáadni, de vélhetően már létezik vagy felvehető a modellbe).
+- **Gamification Service:** KYC végén a `gamification_p2p_invite_xp` beírása a Social Point (XP) részre.
+- **Financial Ledger:** Payout generálásánál `transaction_type=MLM_CREDIT`, `wallet_type=CREDIT` bejegyzések a `finance.ledger` táblában.
+
+## Admin kontroll: Global/Country/Region/User szintű változók
+Az SSoT (`system_parameters`) táblában a következő globális beállítások szükségesek:
+- `mlm_level1_percent`: 10
+- `mlm_level2_percent`: 5
+- `mlm_level3_percent`: 3
+- `gamification_p2p_invite_xp`: 50
+
+Ezeket egy inicializáló szkript tölti fel, hogy Admin felületről később dinamikusan módosíthatók legyenek.
+
+## Logika: P2P Gamification & Payout
+1. **Regisztráció (`register_lite`):** Ha a kérésben szerepel `referred_by_code`, a rendszer felkutatja az ehhez tartozó Usert, majd az új User `referred_by_id`-ját erre a megtalált ID-ra állítja.
+2. **KYC befejezése (`complete_kyc`):** Ha a frissen KYC-zett Usernek van `referred_by_id`-ja, a Gamification Service 50 XP-t ad a szülőnek ("P2P_REFERRAL_SUCCESS").
+3. **MLM Hálózat Lekérdezés (`GET /me/network`):** 
+   - L1: `referred_by_id == current_user.id` (Visszaadva: email, kód, csatlakozás).
+   - L2: Az L1 tagok által meghívottak (Visszaadva: szigorúan csak a kód és dátum adatvédelmi okokból).
+   - L3: Az L2 tagok által meghívottak (szintén csak kód és dátum).
+4. **CREDIT Payout Engine (Mock tesztelés):** Rekurzív/Iteratív szülő-keresés a `referred_by_id` mentén (max 3 szint mélyen). L1 kap 10%-ot, L2 5%-ot, L3 3%-ot a befizetésből, közvetlenül a CREDIT tárcájába.
+