garázs fejlesztés

2026-07-20 11:17:52 +00:00
parent 2e0abc62a7
commit 4594de6c11
80 changed files with 9135 additions and 8702 deletions
--- a/plans/logic_spec_service_finder_3_level_architecture.md
+++ b/plans/logic_spec_service_finder_3_level_architecture.md
@@ -0,0 +1,626 @@
+# 🏗️ 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)
+