# 🏗️ Logic Spec: Service Finder 3-Level Platform Architecture

**Verzió:** 1.0  
**Dátum:** 2026-07-09  
**Állapot:** Tervezet (Architect Review)  
**Hatáskör:** Teljes platform — Admin (Mission Control), User (Provider Hub), Robot/AI (Intelligence Layer)

---

## 1. 🎯 Modul Célja és Masterbook 2.0 Illeszkedés

### Cél
A Service Finder platform három architekturális szintre bomlik, amelyek együtt alkotják a teljes ökoszisztémát:

| Szint | Elnevezés | Elsődleges Cél |
|-------|-----------|----------------|
| **Szint 1** | 🏛️ **Admin — Mission Control** | Flottavezetők, moderátorok, superadminok irányítóközpontja |
| **Szint 2** | 👤 **User — Provider Hub** | Szolgáltatók és flottatulajdonosok önkiszolgáló felülete |
| **Szint 3** | 🤖 **Robot/AI — Intelligence Layer** | Automatikus adatkinyerés, intelligens rangsorolás, szemantikus keresés |

### Masterbook 2.0 Illeszkedés
- **Dual Entity (Person/User):** Minden jogi entitás két szinten kezelve — hús-vér személy vs. technikai fiók
- **Triple Wallet:** Vásárolt, keresett és szolgáltatási kreditek elkülönített kezelése
- **Dual Control (Moderation):** Kétlépcsős jóváhagyási folyamat minden szolgáltatói rekordhoz
- **2-Step Asset Flow:** Draft → Active életciklus minden jármű és eszköz esetében
- **4-Level Expertise Taxonomy:** Vehicle Type → Industry → Profession → Specific Task
- **P0 Hybrid Vendor Refactor:** Három párhuzamos szolgáltatói adatforrás egyesítése

---

## 2. 📊 Jelenlegi Rendszer Állapota (Audit Summary)

### 2.1 Adatbázis Modellek — Teljes Körkép

#### identity séma
| Tábla | Státusz | Fájl |
|-------|---------|------|
| `users` | ✅ KÉSZ | [`social.py`](backend/app/models/identity/social.py:26) |
| `persons` | ✅ KÉSZ | — |
| `wallets` | ✅ KÉSZ | Triple Wallet (4 zseb) |
| `service_providers` | ✅ KÉSZ | Közösségi szolgáltatók moderációval |
| `provider_validations` | ✅ KÉSZ | Validációs rekordok súlyozással |
| `votes` | ✅ KÉSZ | +1/-1 közösségi szavazás |
| `user_scores` | ✅ KÉSZ | Pontszámok |
| `service_reviews` | ✅ KÉSZ | Értékelés + transaction_id |
| `competitions` | ✅ KÉSZ | Versenyek |

#### marketplace séma
| Tábla | Státusz | Fájl |
|-------|---------|------|
| `service_profiles` | ✅ KÉSZ | [`service.py`](backend/app/models/marketplace/service.py:21) |
| `expertise_tags` | ✅ KÉSZ | 4-level hierarchy (parent_id, path, level) |
| `service_expertise` | ✅ KÉSZ | Junction table |
| `service_staging` | ✅ KÉSZ | Robot-hunted providers |
| `discovery_parameters` | ✅ KÉSZ | Felfedezési paraméterek |
| `costs` | ✅ KÉSZ | Költség főkönyv |
| `organizations` | ✅ KÉSZ | Hivatalos garázs/szerviz szervezetek |
| `organization_members` | ✅ KÉSZ | Tagok szerepkörökkel |
| `branches` | ✅ KÉSZ | PostGIS location, opening_hours |
| `organization_financials` | ✅ KÉSZ | Pénzügyi adatok |

#### ❌ HIÁNYZÓ modellek
| Modell | Tervezett Tábla | Ok |
|--------|-----------------|----|
| `KYCVerification` | `identity.kyc_verifications` | KYC dokumentumok és státusz követése |
| `ServicePricing` | `marketplace.service_pricing` | Szolgáltatás árazás (alkatrész + munkadíj) |
| `ServiceBooking` | `marketplace.service_bookings` | Foglalási napló |
| `VeszélyesZónaGatekeeper` | `system.gatekeeper_log` | Hard/soft delete tranzakció-ellenőrzés |

### 2.2 Service Layer

| Service | Fájl | Funkciók |
|---------|------|----------|
| `search_providers()` | [`provider_service.py:125`](backend/app/services/provider_service.py:125) | Unified search, geo-filter, trust score |
| `quick_add_provider()` | [`provider_service.py:578`](backend/app/services/provider_service.py:578) | Gyors létrehozás + gamification |
| `update_provider()` | [`provider_service.py:909`](backend/app/services/provider_service.py:909) | Teljes frissítés (category sync, expertise) |
| `_award_provider_points()` | [`provider_service.py:63`](backend/app/services/provider_service.py:63) | Gamification pontozás |
| `_sync_service_expertises()` | [`provider_service.py:742`](backend/app/services/provider_service.py:742) | 4-level hybrid mentés |
| `find_nearby_services()` | [`search_service.py:24`](backend/app/services/search_service.py:24) | PostGIS + weighted ranking |
| `AIService._execute_ai_call()` | [`ai_service.py:23`](backend/app/services/ai_service.py:23) | Ollama → Groq/Gemini fallback |
| `AIService._fallback_ai_call()` | [`ai_service.py:81`](backend/app/services/ai_service.py:81) | Cloud fallback (Gemini → Groq) |
| `AIService.process_ocr_document()` | [`ai_service.py:174`](backend/app/services/ai_service.py:174) | OCR dokumentum feldolgozás |
| `CostService.record_cost()` | [`cost_service.py`](backend/app/services/cost_service.py) | Költségrögzítés |

### 2.3 API Végpontok — Állapot

| Végpont | Metódus | Státusz | Leírás |
|---------|---------|---------|--------|
| `/admin/providers` | GET | ✅ KÉSZ | Unified provider list (3 tábla UNION ALL) |
| `/admin/providers/stats` | GET | ✅ KÉSZ | Statisztikák |
| `/admin/providers/{id}` | GET | ✅ KÉSZ | Detail + history + validations |
| `/admin/providers/{id}/approve` | POST | ✅ KÉSZ | Jóváhagyás + Promotion Engine |
| `/admin/providers/{id}/reject` | POST | ✅ KÉSZ | Elutasítás okával |
| `/admin/providers/{id}/restore` | POST | ✅ KÉSZ | Visszaállítás |
| `/admin/providers/{id}/flag` | POST | ✅ KÉSZ | Megjelölés (audit) |
| `/admin/providers/{id}` | DELETE | ✅ KÉSZ | Soft delete |
| `/admin/providers/{id}` | PATCH | ✅ KÉSZ | Teljes update + ServiceProfile auto-create |
| `/admin/providers/{id}/validations` | GET | ✅ KÉSZ | Validációs rekordok |
| `/admin/providers/{id}/history` | GET | ✅ KÉSZ | Audit log |
| `/search/match` | GET | ✅ KÉSZ | PostGIS geofencing search |

#### ❌ HIÁNYZÓ Végpontok
| Végpont | Metódus | Prioritás |
|---------|---------|-----------|
| `/admin/gatekeeper/hard-delete` | POST | **P0** — Veszélyes zóna hard delete |
| `/admin/gatekeeper/log` | GET | **P0** — Gatekeeper audit log |
| `/admin/kyc/{user_id}` | GET/PUT | **P1** — KYC dokumentumok kezelése |
| `/admin/kyc/pending` | GET | **P1** — Függő KYC kérelmek |
| `/admin/subscriptions` | CRUD | **P1** — Előfizetések kezelése |
| `/admin/analytics/tco` | GET | **P1** — TCO aggregáció |
| `/admin/analytics/provider-rankings` | GET | **P2** — Szolgáltató rangsor analitika |
| `/providers/me/profile` | GET/PUT | **P1** — Szolgáltató saját profil |
| `/providers/me/services` | CRUD | **P1** — Saját szolgáltatások |
| `/providers/me/bookings` | GET | **P2** — Saját foglalások |
| `/search/semantic` | POST | **P2** — NLP alapú keresés |
| `/search/ai-rank` | POST | **P2** — AI rangsorolás |

---

## 3. 🏛️ Admin Level — Mission Control

### 3.1 Jóváhagyási Munkafolyamat (✅ KÉSZ)

```
flowchart LR
    A[Függő Szolgáltató] --> B{Admin Döntés}
    B -->|Approve| C[Promotion Engine]
    B -->|Reject| D[Elutasítás Indoklással]
    C --> E[ServiceProvider létrehozva]
    C --> F[ServiceProfile auto-generated]
    C --> G[Gamification XP jóváírva]
    C --> H[AuditLog naplózva]
    D --> I[ProviderValidation rekord]
    D --> J[Status: rejected]
    B -->|Flag| K[Audit megjelölés]
    K --> L[Manuális felülvizsgálat]
```

### 3.2 KYC Verifikáció (❌ HIÁNYZIK — P1)

**Tervezett Modell:**
```python
class KYCVerification(Base):
    __tablename__ = "kyc_verifications"
    __table_args__ = {"schema": "identity"}
    id: int (PK)
    user_id: int (FK → users.id)
    person_id: bigint (FK → persons.id)
    documents: dict (JSONB) — feltöltött dokumentumok
    status: enum(pending, verified, rejected)
    verified_by: int (FK → users.id, nullable)
    verified_at: datetime
    notes: text
    expires_at: datetime
    created_at: datetime
    updated_at: datetime
```

### 3.3 Kategória Menedzsment (✅ RÉSZBEN)

**Meglévő:**
- ✅ 4-level ExpertiseTag hierarchia (parent_id, path, level, name_i18n, search_keywords)
- ✅ Seed szkriptek: `seed_expertise_tags.py`, `seed_expertise_taxonomy.py`
- ✅ 136 kategória (utolsó seed: 768)
- ✅ `_sync_service_expertises()` — 4-level hybrid mentés
- ✅ `_create_new_tags()` — Új címkék automatikus létrehozása

**Hiányzó:**
- ❌ Kategória kezelő admin UI (CRUD + átrendezés)
- ❌ Kategória láthatósági szabályok (Global/Country/Region)

### 3.4 Pénzügyi & Előfizetés Kontroll (❌ HIÁNYZIK — P1)

**Meglévő:**
- ✅ Triple Wallet modell (`identity.wallets`)
- ✅ FinancialLedger (`audit.financial_ledger`)
- ✅ Stripe webhook (Double Lock protokoll)
- ✅ Billing Engine (vízesés modell)
- ✅ `Organization.subscription_tier_id`, `subscription_plan`, `subscription_tier` kapcsolat

**Hiányzó:**
- ❌ Admin előfizetés kezelő UI
- ❌ Előfizetés számlázási adatok admin felület
- ❌ Wallet egyenlegek admin áttekintése

### 3.5 Veszélyes Zóna — Gatekeeper (❌ HIÁNYZIK — P0 KRITIKUS)

**Tervezett architektúra:**
```python
# system.gatekeeper_log tábla
class GatekeeperLog(Base):
    __tablename__ = "gatekeeper_log"
    __table_args__ = {"schema": "system"}
    id: int (PK)
    action: enum(soft_delete, hard_delete, restore, purge)
    target_table: str
    target_id: int
    initiated_by: int (FK → users.id)
    approved_by: int (FK → users.id, nullable)
    status: enum(pending, approved, rejected, executed)
    reason: text
    backup_snapshot: dict (JSONB) — hard delete előtti adatmentés
    executed_at: datetime
    created_at: datetime
```

**Hard Delete Folyamat:**
1. Admin kiválaszt egy rekordot hard delete-re
2. GatekeeperLog létrehozása `pending` státusszal
3. Backup snapshot JSONB-ben (mentés az adatról)
4. Második admin jóváhagyása szükséges (Dual Control)
5. Atomi tranzakció: DELETE + AuditLog + GatekeeperLog.status=executed
6. Rollback lehetőség a backup snapshot-ból

**Referencia:** [`test_hard_delete.py`](backend/test_hard_delete.py:7) — létezik referencia implementáció

---

## 4. 👤 User Level — Provider Hub

### 4.1 Profil Menedzsment (✅ RÉSZBEN)

**Meglévő:**
- ✅ `ProviderUpdateInput` séma (category_ids, supported_vehicle_classes, specializations, opening_hours)
- ✅ `update_provider()` — Teljes provider frissítés
- ✅ `quick_add_provider()` — Gyors létrehozás gamification hook-kal
- ✅ AddressManager integráció (P0 Unified Address Refactor)
- ✅ Frontend_admin: [`providers/[id]/edit.vue`](frontend_admin/pages/providers/[id]/edit.vue) — Teljes admin szerkesztő

**Hiányzó:**
- ❌ Szolgáltatói self-service frontend (public felületen)
- ❌ Provider dashboard (saját statisztikák, értékelések)
- ❌ Multi-language profil szerkesztés (name_i18n)

### 4.2 Szolgáltatás Katalógus (❌ HIÁNYZIK — P1)

**Tervezett Modell:**
```python
class ServicePricing(Base):
    __tablename__ = "service_pricing"
    __table_args__ = {"schema": "marketplace"}
    id: int (PK)
    service_profile_id: int (FK → marketplace.service_profiles.id)
    category_id: int (FK → marketplace.expertise_tags.id)
    name: str
    name_i18n: dict (JSONB) — Twin-technika
    description: str
    description_i18n: dict (JSONB)
    labor_cost: Decimal(18,4)
    parts_cost: Decimal(18,4)
    currency: str (default: "HUF")
    is_flat_rate: bool
    estimated_duration_minutes: int
    is_active: bool
    valid_from: datetime
    valid_until: datetime (nullable)
```

### 4.3 Értékelések & Gamifikáció (✅ RÉSZBEN)

**Meglévő:**
- ✅ `ServiceReview` modell — rating, review_text, transaction_id
- ✅ `PointRule` — gamification pontszabályok
- ✅ `_award_provider_points()` — Provider pontozás
- ✅ Gamification admin frontend: [`gamification/`](frontend_admin/pages/gamification/)
- ✅ Leaderboard, badges, competitions, seasons

**Hiányzó:**
- ❌ Review moderációs admin UI (flag-elt review-k)
- ❌ Gamification widget a provider dashboardon
- ❌ Pontszabályok vizuális szerkesztője

### 4.4 Lead Menedzsment (❌ HIÁNYZIK — P2)

**Meglévő:**
- ✅ `ServiceRequest` kapcsolat a `Branch` modellben

**Hiányzó:**
- ❌ Teljes foglalási munkafolyamat (ServiceBooking model)
- ❌ Geofenced broadcast (körzetes értesítés)
- ❌ Értesítési csatornák (email, push, in-app)

---

## 5. 🤖 Robot/AI Level — Intelligence Layer

### 5.1 Szemantikus Keresés (❌ HIÁNYZIK — P2)

**Meglévő:**
- ✅ PostGIS geofencing (`ST_DWithin`, `ST_DistanceSphere`)
- ✅ Config-driven weighted ranking (ad_weight, partner_weight, trust_weight, dist_penalty, pref_weight)
- ✅ Hierarchical ranking config (SystemParameter)

**Tervezett NLP Search:**
```python
class SemanticSearchEngine:
    """
    Tervezett motor a meglévő SearchService kiterjesztésére.
    """
    @classmethod
    async def semantic_search(cls, query: str, lat: float, lng: float, radius_km: float):
        # 1. Query embedding (Ollama / local)
        query_embedding = await AIService.get_embedding(query)
        
        # 2. Hybrid search: PostGIS + embedding similarity
        results = await cls._hybrid_search(query_embedding, lat, lng, radius_km)
        
        # 3. AI re-ranking
        reranked = await AIService.rerank_results(query, results)
        
        return reranked
```

### 5.2 Intelligens Rangsorolás (✅ RÉSZBEN)

**Weighted Scoring Formula** ([`search_service.py:92`](backend/app/services/search_service.py:92)):
```
score = (ad_weight * is_advertiser) +
        (partner_weight * is_partner) +
        (trust_weight * trust_score) -
        (dist_penalty * dist_km) +
        (pref_weight * is_preferred)
```

**Hiányzó:**
- ❌ ML-alapú rangsorolás (felhasználói viselkedés alapján)
- ❌ A/B tesztelési keretrendszer
- ❌ Rangsorolási metrikák admin dashboard

### 5.3 Automatikus Adatkinyerés (✅ RÉSZBEN)

**Meglévő:**
- ✅ [`AIService`](backend/app/services/ai_service.py) — Multi-Agent gateway
- ✅ Ollama local → Groq/Gemini cloud fallback
- ✅ `process_ocr_document()` — OCR dokumentum feldolgozás
- ✅ `get_gold_data_from_research()` — Arany adatkinyerés
- ✅ `get_clean_vehicle_data()` — Adattisztítás
- ✅ `robot_1_ocr_processor.py` — OCR robot

**Hiányzó:**
- ❌ Document pipeline admin UI (OCR eredmények ellenőrzése)
- ❌ AI prompt konfigurációs admin panel
- ❌ Fallback monitoring és naplózás

---

## 6. 🔧 Adatmodell Terv — Részletes

### 6.1 Meglévő Modellek Összefoglalója

| Séma | Tábla | Oszlopok | Kulcs (PK/FK) | JSONB | i18n | Soft Delete |
|------|-------|----------|---------------|-------|------|-------------|
| `identity` | `users` | 20+ | PK, FK→persons | preferences | — | `deleted_at` |
| `identity` | `persons` | 22+ | PK, FK→users, FK→address | identity_docs, ice_contact | — | `deleted_at` |
| `identity` | `service_providers` | 12+ | PK, FK→address | — | — | `status=rejected` |
| `identity` | `wallets` | 10+ | PK, FK→users | — | — | — |
| `marketplace` | `service_profiles` | 18+ | PK, FK→service_providers | opening_hours, specializations | — | — |
| `marketplace` | `expertise_tags` | 10+ | PK, FK→self (parent) | name_i18n, search_keywords | ✅ 4 mező | — |
| `marketplace` | `organizations` | 25+ | PK, FK→address | custom_features, visual_settings, settings, aliases, tags | — | `is_deleted` |
| `marketplace` | `branches` | 12+ | PK, FK→organization, FK→address | opening_hours | — | `is_deleted` |
| `marketplace` | `service_staging` | 12+ | PK | raw_data | — | — |
| `audit` | `financial_ledger` | 8+ | PK, FK→users | details | — | — |

### 6.2 Twin-technika (Többnyelvűség)

**Meglévő implementáció:**
- `ExpertiseTag.name_i18n` (JSONB) — {"hu": "Olajcsere", "en": "Oil Change", "de": "Ölwechsel"}
- `ExpertiseTag.description_i18n` (JSONB)
- `ExpertiseTag.search_keywords` (JSONB) — {"hu": ["olaj", "motorolaj"], "en": ["oil", "motor oil"]}

**Kötelező minden új i18n mezőre:**
```python
name_i18n: Mapped[dict] = mapped_column(JSONB, server_default=text("'{}'::jsonb"))
```

### 6.3 Soft-delete Logika

| Tábla | Soft Delete Mező | Típus |
|-------|------------------|-------|
| `users` | `deleted_at` | DateTime (nullable) |
| `persons` | `deleted_at` | DateTime (nullable) |
| `organizations` | `is_deleted` | Boolean |
| `branches` | `is_deleted` | Boolean |
| `service_providers` | `status = rejected` | Enum |
| `organization_members` | `status != active` | Enum |

**Hiányzó Gatekeeper:** A Veszélyes Zóna funkcióhoz dedikált `gatekeeper_log` tábla szükséges (Lásd 3.5)

### 6.4 Hiányzó Modellek — Alembic Migration Terv

| # | Modell | Tábla | Típus | Migráció |
|---|--------|-------|-------|----------|
| 1 | `GatekeeperLog` | `system.gatekeeper_log` | **P0** | `gatekeeper_log_v1` |
| 2 | `KYCVerification` | `identity.kyc_verifications` | P1 | `kyc_verification_v1` |
| 3 | `ServicePricing` | `marketplace.service_pricing` | P1 | `service_pricing_v1` |
| 4 | `ServiceBooking` | `marketplace.service_bookings` | P2 | `service_booking_v1` |
| 5 | `AIRequestLog` | `audit.ai_request_logs` | P2 | `ai_request_log_v1` |

---

## 7. ⚙️ Admin Kontroll Rendszerváltozók

### 7.1 Hierarchikus Config Változók

A rendszer négy szinten kezeli a konfigurációs változókat:

| Szint | Tábla | Hatáskör |
|-------|-------|-----------|
| **Global** | `system.system_parameters` | Az összes régióra és felhasználóra |
| **Country** | `system.system_parameters` (scope=country) | Adott országra |
| **Region** | `system.system_parameters` (scope=region) | Adott régióra |
| **User** | `identity.users.preferences` | Egyedi felhasználóra |

### 7.2 Meglévő Rendszerváltozók

| Kulcs | Típus | Scope | Érték |
|-------|-------|-------|-------|
| `GAMIFICATION_MASTER_CONFIG` | JSONB | Global | Gamification master config |
| `AI_REQUEST_DELAY` | Float | Global | Késleltetés AI hívások között |
| `AI_TEMPERATURE` | Float | Global | AI hőmérséklet paraméter |
| `AI_TIMEOUT_LOCAL` | Integer | Global | Helyi AI timeout (sec) |
| `ENABLE_AI_FALLBACK` | Boolean | Global | Cloud fallback engedélyezése |
| `AI_MODEL_TEXT` | String | Global | Szöveg AI modell neve |
| `AI_MODEL_VISION` | String | Global | Kép AI modell neve |
| `DVLA_DAILY_LIMIT` | Integer | Global | Napi DVLA API limit |

### 7.3 Tervezett Új Változók

| Kulcs | Típus | Scope | Cél |
|-------|-------|-------|-----|
| `SEARCH_RANKING_CONFIG` | JSONB | Global | Súlyozási mátrix (ad/partner/trust/dist/pref) |
| `GATEKEEPER_REQUIRED_APPROVALS` | Integer | Global | Hány admin kell hard delete-hez |
| `KYC_REQUIRED_LEVELS` | JSONB | Country | Országonkénti KYC követelmények |
| `PROVIDER_AUTO_APPROVE` | Boolean | Country | Automatikus jóváhagyás engedélyezése |
| `REVIEW_MODERATION_ENABLED` | Boolean | Global | Review moderáció bekapcsolása |

---

## 8. 🌍 Geo-Logika és Rangsorolás

### 8.1 PostGIS Alapú Keresés

A [`search_service.py`](backend/app/services/search_service.py:24) a `find_nearby_services()` metódussal PostGIS `ST_DWithin` és `ST_DistanceSphere` függvényeket használ:

```sql
-- Generált SQL (lekérdezés logika)
SELECT o.id, o.name, gpc.city,
       b.branch_rating,
       ST_DistanceSphere(b.location, ST_MakePoint(:lng, :lat)) AS distance_meters
FROM marketplace.organizations o
JOIN marketplace.branches b ON o.id = b.organization_id
LEFT JOIN system.addresses a ON a.id = b.address_id
LEFT JOIN system.geo_postal_codes gpc ON gpc.id = a.postal_code_id
WHERE o.is_active = true
  AND b.is_deleted = false
  AND ST_DWithin(b.location, ST_MakePoint(:lng, :lat), :radius_meters)
ORDER BY distance_meters ASC;
```

### 8.2 Súlyozott Rangsorolás

A [`SearchService`](backend/app/services/search_service.py) config-driven súlyozást használ:

```python
score = (
    r["ad_weight"] * is_advertiser +      # Hirdetési súly (default: 10)
    r["partner_weight"] * is_partner +     # Partner súly (default: 5)
    r["trust_weight"] * trust_score -      # Bizalmi súly (default: 2)
    r["dist_penalty"] * dist_km +          # Távolság büntetés (default: 0.5)
    r["pref_weight"] * is_preferred        # Preferált súly (default: 3)
)
```

### 8.3 Csomag Szintek Szerinti Rangsorolás

| Csomag Szint | ad_weight | partner_weight | max_distance_km | Prioritás |
|-------------|-----------|----------------|-----------------|-----------|
| **Free** | 0 | 0 | 20 | Alacsony |
| **Basic** | 2 | 1 | 50 | Közepes |
| **Premium** | 5 | 3 | 100 | Magas |
| **Enterprise** | 10 | 5 | 200 | Legmagasabb |

---

## 9. 📅 Implementációs Sorrend és Függőségek

### 9.1 Függőségi Gráf

```mermaid
flowchart TD
    P0[P0: Veszélyes Zóna Gatekeeper] --> P1a[P1: KYC Verifikáció]
    P0 --> P1b[P1: Előfizetés Admin UI]
    P1a --> P2a[P2: Szolgáltató Self-Service]
    P1b --> P2b[P2: Foglalási Rendszer]
    P2a --> P2c[P2: NLP Szemantikus Keresés]
    P2b --> P2d[P2: AI Rangsorolás]
    
    style P0 fill:#ff4444,color:#fff
    style P1a fill:#ffaa00,color:#000
    style P1b fill:#ffaa00,color:#000
    style P2a fill:#44aa44,color:#fff
    style P2b fill:#44aa44,color:#fff
    style P2c fill:#44aa44,color:#fff
    style P2d fill:#44aa44,color:#fff
```

### 9.2 Prioritási Sorrend

#### P0 — Kritikus (Hiányzó biztonsági funkciók)
| # | Feladat | Érintett Fájlok |
|---|---------|-----------------|
| 1 | **Gatekeeper hard/soft delete** — Tranzakció-ellenőrzés Dual Control-lal | [`admin_providers.py`](backend/app/api/v1/endpoints/admin_providers.py:1109), [`test_hard_delete.py`](backend/test_hard_delete.py) |
| 2 | **Gatekeeper admin API** — DELETE jogosultság ellenőrzés + AuditLog | új végpont |

#### P1 — Magas Prioritás (Hiányzó üzleti funkciók)
| # | Feladat | Érintett Fájlok |
|---|---------|-----------------|
| 3 | **KYCVerification modell + API** — Dokumentumfeltöltés és státusz | új modell + endpoint |
| 4 | **KYC admin UI** — Függő kérelmek kezelése | új frontend oldal |
| 5 | **ServicePricing modell + API** — Árazási adatok | új modell + endpoint |
| 6 | **Előfizetés admin UI** — Subscription CRUD | új frontend oldal |
| 7 | **Szolgáltatói self-service API** — Saját profil kezelés | új végpontok |

#### P2 — Fejlesztési Cél (Intelligens funkciók)
| # | Feladat | Érintett Fájlok |
|---|---------|-----------------|
| 8 | **NLP szemantikus keresés** — Embedding + hybrid search | [`search_service.py`](backend/app/services/search_service.py) kiterjesztése |
| 9 | **AI rangsorolás** — ML-based ranking | [`ai_service.py`](backend/app/services/ai_service.py) kiterjesztése |
| 10 | **Foglalási rendszer** — ServiceBooking flow | új modell + endpoint |
| 11 | **Lead management** — Értesítési csatornák | új service |
| 12 | **Document pipeline admin UI** — OCR eredmények | új frontend oldal |

### 9.3 Implementációs Szekvencia

**Fázis 1 — Biztonsági Alapok (P0)**
1. `GatekeeperLog` modell létrehozása (`system` séma)
2. Admin hard-delete API végpont (Dual Control)
3. Admin gatekeeper log UI
4. Meglévő DELETE végpontok gatekeeper-en keresztül vezetése

**Fázis 2 — Admin Kibővítés (P1)**
5. `KYCVerification` modell + API
6. KYC admin frontend
7. `ServicePricing` modell + API
8. Előfizetés admin UI

**Fázis 3 — Önkiszolgálás (P1)**
9. Provider self-service API (CRUD)
10. Provider dashboard frontend
11. Multi-language profil szerkesztés

**Fázis 4 — Intelligens Réteg (P2)**
12. NLP szemantikus keresőmotor
13. AI rangsorolás
14. Foglalási rendszer
15. Lead management

---

## 10. 🔗 Érintett Fájlok Teljes Listája

### Backend — Modellek
- [`social.py`](backend/app/models/identity/social.py) — ServiceProvider, ProviderValidation, Vote, ServiceReview
- [`service.py`](backend/app/models/marketplace/service.py) — ServiceProfile, ExpertiseTag, ServiceExpertise, ServiceStaging
- [`organization.py`](backend/app/models/marketplace/organization.py) — Organization, Branch, OrganizationMember
- [`audit.py`](backend/app/models/audit.py) — AuditLog, FinancialLedger

### Backend — API Végpontok
- [`admin_providers.py`](backend/app/api/v1/endpoints/admin_providers.py) — Admin provider moderáció (1224+ sor)
- [`providers.py`](backend/app/api/v1/endpoints/providers.py) — Public provider API
- [`search.py`](backend/app/api/v1/endpoints/search.py) — Geofencing kereső (99 sor)

### Backend — Service Layer
- [`provider_service.py`](backend/app/services/provider_service.py) — Provider CRUD, gamification, search
- [`search_service.py`](backend/app/services/search_service.py) — PostGIS + weighted ranking
- [`ai_service.py`](backend/app/services/ai_service.py) — Multi-Agent AI gateway (Ollama → Groq/Gemini)
- [`cost_service.py`](backend/app/services/cost_service.py) — Költségrögzítés

### Frontend — Admin (Nuxt)
- [`providers/index.vue`](frontend_admin/pages/providers/index.vue) — Provider lista
- [`providers/pending.vue`](frontend_admin/pages/providers/pending.vue) — Függő jóváhagyások
- [`providers/[id]/index.vue`](frontend_admin/pages/providers/[id]/index.vue) — Provider részletek
- [`providers/[id]/edit.vue`](frontend_admin/pages/providers/[id]/edit.vue) — Provider szerkesztés
- [`gamification/`](frontend_admin/pages/gamification/) — Gamification admin felület

### Frontend — Public (Vue+Vite)
- [`provider/ProviderEditModal.vue`](frontend_app/src/components/provider/ProviderEditModal.vue) — Provider szerkesztés
- [`provider/ProviderDetailModal.vue`](frontend_app/src/components/provider/ProviderDetailModal.vue) — Provider részletek
- [`provider/ProviderQuickAddModal.vue`](frontend_app/src/components/provider/ProviderQuickAddModal.vue) — Gyors hozzáadás
- [`dashboard/ServiceFinderCard.vue`](frontend_app/src/components/dashboard/ServiceFinderCard.vue) — Kereső widget

### Dokumentációk
- [`admin_providers_root_cause_analysis.md`](docs/admin_providers_root_cause_analysis.md) — Root cause analysis
- [`epic_10_admin_frontend_spec.md`](docs/sf/epic_10_admin_frontend_spec.md) — Epic 10 spec
- [`Masterbook_2.0_Status.md`](docs/Masterbook_2.0_Status.md) — Projekt státusz
- [`full_db_schema_blueprint.md`](docs/full_db_schema_blueprint.md) — Teljes séma blueprint

---

## ✅ Verifikációs Checklist

### Admin Level
- [ ] Admin provider moderáció (approve/reject/flag/restore) — ✅ KÉSZ
- [ ] UNION ALL query (3 tábla egyesítése) — ✅ KÉSZ
- [ ] Promotion Engine (Staging → Live) — ✅ KÉSZ
- [ ] Veszélyes Zóna Gatekeeper — ❌ HIÁNYZIK (P0)
- [ ] KYC Verifikáció — ❌ HIÁNYZIK (P1)
- [ ] Előfizetés admin UI — ❌ HIÁNYZIK (P1)
- [ ] Kategória menedzsment admin UI — ❌ HIÁNYZIK (P1)

### User Level
- [ ] Provider CRUD (quick_add, update) — ✅ KÉSZ
- [ ] Geofencing kereső (PostGIS) — ✅ KÉSZ
- [ ] Szolgáltatói self-service — ❌ HIÁNYZIK (P1)
- [ ] ServicePricing modell — ❌ HIÁNYZIK (P1)
- [ ] Foglalási rendszer — ❌ HIÁNYZIK (P2)
- [ ] Értékelés és gamifikáció — ✅ RÉSZBEN

### Robot/AI Level
- [ ] Multi-Agent AI Gateway (Ollama → Groq/Gemini) — ✅ KÉSZ
- [ ] OCR dokumentum feldolgozás — ✅ KÉSZ
- [ ] Config-driven weighted ranking — ✅ KÉSZ
- [ ] NLP szemantikus keresés — ❌ HIÁNYZIK (P2)
- [ ] ML-alapú rangsorolás — ❌ HIÁNYZIK (P2)
- [ ] AI prompt admin panel — ❌ HIÁNYZIK (P2)