Files
service-finder/plans/logic_spec_service_finder_3_level_architecture.md
2026-07-20 11:17:52 +00:00

27 KiB

🏗️ 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
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
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 Unified search, geo-filter, trust score
quick_add_provider() provider_service.py:578 Gyors létrehozás + gamification
update_provider() provider_service.py:909 Teljes frissítés (category sync, expertise)
_award_provider_points() provider_service.py:63 Gamification pontozás
_sync_service_expertises() provider_service.py:742 4-level hybrid mentés
find_nearby_services() search_service.py:24 PostGIS + weighted ranking
AIService._execute_ai_call() ai_service.py:23 Ollama → Groq/Gemini fallback
AIService._fallback_ai_call() ai_service.py:81 Cloud fallback (Gemini → Groq)
AIService.process_ocr_document() ai_service.py:174 OCR dokumentum feldolgozás
CostService.record_cost() 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:

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:

# 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 — 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 — 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:

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/
  • 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:

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

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

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 a find_nearby_services() metódussal PostGIS ST_DWithin és ST_DistanceSphere függvényeket használ:

-- 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 config-driven súlyozást használ:

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

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, 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 kiterjesztése
9 AI rangsorolás — ML-based ranking 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 — ServiceProvider, ProviderValidation, Vote, ServiceReview
  • service.py — ServiceProfile, ExpertiseTag, ServiceExpertise, ServiceStaging
  • organization.py — Organization, Branch, OrganizationMember
  • audit.py — AuditLog, FinancialLedger

Backend — API Végpontok

Backend — Service Layer

Frontend — Admin (Nuxt)

Frontend — Public (Vue+Vite)

Dokumentációk


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)