Files
service-finder/docs/database_schema_audit_partner_models_2026-06-16.md

25 KiB

🏗️ Teljes Adatbázis Séma Audit & Partner Modell Felfedezés

Dátum: 2026-06-16 Auditor: Rendszer-Architect (DeepSeek Reasoner) Cél: Partner/Szolgáltató modellek azonosítása és a teljes adatbázis térkép elkészítése


1. 🔍 CÉLTUDATOS KERESÉS: Cégek / Partnerek / Szolgáltatók

1.1. Találatok összefoglalása

Keresőszó Találat Modell Séma
Company VAN Organization fleet.organizations
Partner RÉSZBEN Organization.is_affiliate_partner fleet.organizations
Vendor NINCS - -
ServiceProvider VAN ServiceProvider (régi) marketplace.service_providers
ServiceProfile VAN ServiceProfile (új) marketplace.service_profiles
Contact/Person VAN Person identity.persons
Tenant NINCS - -
Business VAN Organization (org_type=business) fleet.organizations
Branch/Location VAN Branch fleet.branches

1.2. Fő következtetés

NINCS dedikált "Partner" vagy "Szolgáltató" modell.
A rendszer két különböző, egymástól független entitáskészlettel dolgozik:

  1. fleet.organizations - Szervezetek (Cégek, Flották, Egyéni vállalkozók)
  2. marketplace.service_providers + marketplace.service_profiles - Szerviz szolgáltatók

Ez a két világ gyengén kapcsolódik egymáshoz: a ServiceProfile hivatkozhat egy Organization-ra, de ez opcionális.


2. 📋 MEGLÉVŐ MODELLEK RÉSZLETES ELEMZÉSE

2.1. fleet.organizations (Organization modell)

Fájl: backend/app/models/marketplace/organization.py Tábla: fleet.organizations

Oszlopok csoportosítva:

🏢 Alapadatok

Oszlop Típus Kötelező? Megjegyzés
id INTEGER PK
name VARCHAR(255) Cégnév
full_name VARCHAR Teljes cégnév
display_name VARCHAR(50) Rövid megjelenítési név
folder_slug VARCHAR(12) UNIQUE Rendszer azonosító
org_type ENUM(OrgType) individual, service, service_provider, fleet_owner, club, business

📍 Cím adatok (Denormalizált)

Oszlop Típus
address_id UUID (FK → system.addresses.id)
address_zip, address_city, address_street_name, address_street_type, address_house_number, address_hrsz VARCHAR
country_code VARCHAR(2) → default "HU"
language VARCHAR(5) → default "hu"

🆔 Adóazonosítók

Oszlop Típus Megjegyzés
tax_number VARCHAR(20) UNIQUE Adószám
reg_number VARCHAR(50) Cégjegyzékszám

🛡️ Életút / Biztonság

Oszlop Típus Megjegyzés
legal_owner_id BIGINT (FK → identity.persons.id) Jogi képviselő (Person)
owner_id INTEGER (FK → identity.users.id) Technikai tulajdonos (User)
first_registered_at TIMESTAMPTZ Első regisztráció (örök)
current_lifecycle_started_at TIMESTAMPTZ Aktuális életciklus kezdete
lifecycle_index INTEGER Hányadik életciklus
is_deleted BOOLEAN Soft delete flag
is_active BOOLEAN Aktív flag
is_anonymized BOOLEAN Anonimizált flag
is_verified BOOLEAN KYC verifikáció

💰 Partner / Értékesítés

Oszlop Típus Megjegyzés
is_affiliate_partner BOOLEAN PARTNER FLAGfalse default
subscription_plan VARCHAR(30) "FREE", "PREMIUM", stb.
base_asset_limit INTEGER Eszköz limit
is_ownership_transferable BOOLEAN Átruházható-e

⚙️ Konfiguráció

Oszlop Típus
notification_settings JSON
external_integration_config JSON
visual_settings JSONB

🔗 Kapcsolatok (Relationships)

Organization
  ├── assets: List[AssetAssignment]         # Jármű hozzárendelések
  ├── members: List[OrganizationMember]      # Tagok (User/Person)
  ├── owner: User                            # Technikai tulajdonos
  ├── financials: List[OrganizationFinancials] # Pénzügyi adatok
  ├── service_profile: ServiceProfile        # Opcionális szerviz profil (1:1)
  ├── branches: List[Branch]                 # Telephelyek
  ├── legal_owner: Person                    # Jogi képviselő
  └── vehicle_costs: List[VehicleCost]       # Jármű költségek

2.2. marketplace.service_providers (ServiceProvider modell - RÉGI)

Fájl: backend/app/models/marketplace/service.py Tábla: marketplace.service_providers

Oszlop Típus Megjegyzés
id INTEGER PK
name VARCHAR Név
address VARCHAR Cím (egyszerű szöveg)
category VARCHAR Kategória
status USER-DEFINED Státusz (ENUM)
source USER-DEFINED Forrás (ENUM)
validation_score INTEGER Validációs pontszám
evidence_image_path VARCHAR Kép bizonyíték
added_by_user_id INTEGER Ki adta hozzá
created_at TIMESTAMPTZ Létrehozás

⚠️ Ez a tábla egy régebbi verzió. Nem használja a ServiceProfile modell, hanem külön kezelendő.


2.3. marketplace.service_profiles (ServiceProfile modell - ÚJ)

Fájl: backend/app/models/marketplace/service.py Tábla: marketplace.service_profiles

Oszlop Típus Megjegyzés
id INTEGER PK
organization_id INTEGER (FK → fleet.organizations.id) UNIQUE - Kapcsolat a szervezethez
parent_id INTEGER (FK → self) Hierarchia (pl. franchise)
fingerprint VARCHAR(255) UNIQUE INDEX - Robot által generált
location GEOMETRY(POINT) PostGIS hely
status ENUM(ServiceStatus) ghost, active, flagged, suspended
google_place_id VARCHAR(100) UNIQUE Google Places azonosító
trust_score INTEGER Trust engine pontszám
is_verified BOOLEAN Verifikált szolgáltató
vibe_analysis JSONB AI hangulatelemzés
social_links JSONB Közösségi média linkek
specialization_tags JSONB Specializációs címkék
opening_hours JSONB Nyitvatartás
contact_phone VARCHAR Telefon
contact_email VARCHAR Email
website VARCHAR Weboldal
bio TEXT Leírás
rating_overall FLOAT Átfogó értékelés
rating_verified_count INTEGER Verified review-ok száma

🔗 Kapcsolatok

ServiceProfile
  ├── organization: Organization       # 1:1 kapcsolat
  ├── expertises: List[ServiceExpertise] # Szakmai címkék
  └── reviews: List[ServiceReview]      # Vélemények

2.4. marketplace.service_reviews (Verified Service Reviews)

Tábla: marketplace.service_reviews

Oszlop Típus Megjegyzés
id INTEGER PK
service_id INTEGER (FK → marketplace.service_profiles.id) Melyik szerviz
user_id INTEGER (FK → identity.users.id) Ki írta
transaction_id UUID UNIQUE - Tranzakció azonosító
price_rating INTEGER (1-5) Ár értékelés
quality_rating INTEGER (1-5) Minőség értékelés
time_rating INTEGER (1-5) Idő értékelés
communication_rating INTEGER (1-5) Kommunikáció értékelés
comment TEXT Szöveges vélemény
is_verified BOOLEAN Tranzakcióhoz kötött
created_at/updated_at TIMESTAMPTZ Audit

2.5. marketplace.ratings (Általános értékelések)

Tábla: marketplace.ratings

Oszlop Típus Megjegyzés
id INTEGER PK
author_id INTEGER Ki írta
target_organization_id INTEGER Cél szervezet (opcionális)
target_user_id INTEGER Cél felhasználó (opcionális)
target_branch_id UUID Cél telephely (opcionális)
score NUMERIC Pontszám
comment TEXT Szöveges
images JSONB Képek
is_verified BOOLEAN Verifikált

2.6. fleet.branches (Telephelyek)

Tábla: fleet.branches

Oszlop Típus Megjegyzés
id UUID PK
organization_id INTEGER (FK → fleet.organizations.id) Melyik szervezethez
address_id UUID (FK → system.addresses.id) Cím (strukturált)
name VARCHAR(100) Telephely név
is_main BOOLEAN Központi telephely
postal_code, city, street_name, stb. VARCHAR Denormalizált cím
location GEOMETRY(POINT) PostGIS
opening_hours JSONB Nyitvatartás
branch_rating FLOAT Telephely értékelés
status VARCHAR(30) active, inactive
is_deleted BOOLEAN Soft delete

3. 🗺️ TELJES ADATBÁZIS TÉRKÉP (Minden séma és tábla)

3.1. Identity séma (Személyek, Felhasználók, Hitelesítés)

Tábla Leírás Státusz
identity.persons Természetes személyek (DNS szint) Aktív
identity.users Technikai fiókok (bejelentkezés) Aktív
identity.wallets Pénztárcák (Triple Wallet) Aktív
identity.active_vouchers Aktív voucher-ek Aktív
identity.user_trust_profiles Trust score profilok Aktív
identity.verification_tokens Email/telefon verifikáció Aktív
identity.one_time_passwords OTP kódok Aktív
identity.social_accounts Közösségi média kapcsolatok Aktív
identity.devices Eszköz fingerprint Aktív
identity.user_device_links User-Eszköz kapcsolatok Aktív

3.2. Fleet séma (Szervezetek, Flották)

Tábla Leírás Státusz
fleet.organizations Szervezetek (cégek, flották, szolgáltatók) Aktív
fleet.organization_members Tagságok (User/Person → Organization) Aktív
fleet.organization_financials Pénzügyi adatok (éves) Aktív
fleet.branches Telephelyek Aktív
fleet.asset_assignments Jármű hozzárendelések Aktív
fleet.org_sales_assignments Értékesítési hozzárendelések Aktív

3.3. Vehicle séma (Járművek, Katalógus)

Tábla Leírás Státusz
vehicle.vehicle_model_definitions Jármű modellek (MDM) Aktív
vehicle.vehicle_catalog Katalógus sablonok Aktív
vehicle.assets Fizikai eszközök (Digital Twin) Aktív
vehicle.vehicle_types Jármű típusok Aktív
vehicle.feature_definitions Felszereltség elemek Aktív
vehicle.model_feature_maps Modell-Felszereltség kapcsolatok Aktív
vehicle.dict_body_types Karosszéria típus szótár Aktív
vehicle.cost_categories Költségkategóriák Aktív
vehicle.costs Jármű költségek (TCO) Aktív
vehicle.vehicle_expenses Jármű kiadások (jelentésekhez) Aktív
vehicle.odometer_readings Kilométeróra állások Aktív
vehicle.vehicle_ownership_history Tulajdonos történet Aktív
vehicle.vehicle_transfer_requests Átruházási kérelmek Aktív
vehicle.catalog_discovery Katalógus felfedező várólista Aktív
vehicle.gb_catalog_discovery UK piaci felfedező Aktív
vehicle.auto_data_crawler_queue Crawler várólista Aktív
vehicle.vehicle_logbook Jármű naplókönyv Aktív
vehicle.motorcycle_specs Motorkerékpár specifikációk Aktív
vehicle.external_reference_library Külső referencia könyvtár Aktív
vehicle.reference_lookup Referencia kereső Aktív
vehicle.vehicle_user_ratings Felhasználói jármű értékelések Aktív
vehicle.asset_costs Eszköz költségek Aktív
vehicle.asset_events Eseménynapló Aktív
vehicle.asset_financials Pénzügyi adatok Aktív
vehicle.asset_inspections Ellenőrzések Aktív
vehicle.asset_reviews Eszköz vélemények Aktív
vehicle.asset_telemetry Telemetria adatok Aktív

3.4. Marketplace séma (Piactér, Szervizek)

Tábla Leírás Státusz
marketplace.service_providers Szolgáltatók (RÉGI, egyszerű) ⚠️ Használaton kívül?
marketplace.service_profiles Szerviz profilok (ÚJ) Aktív
marketplace.service_reviews Verifikált vélemények Aktív
marketplace.expertise_tags Szakmai címkék Aktív
marketplace.service_expertises Szerviz-Szakma kapcsolatok Aktív
marketplace.service_specialties Specializációk (hierarchikus) Aktív
marketplace.service_staging Robot által gyűjtött adatok Aktív
marketplace.discovery_parameters Robot keresési paraméterek Aktív
marketplace.service_requests Szervizigények Aktív
marketplace.ratings Általános értékelések Aktív
marketplace.votes Szavazatok Aktív
marketplace.costs Költségnapló (Trust Engine) Aktív

3.5. Finance séma (Pénzügyek)

Tábla Leírás Státusz
finance.credit_logs Hitel napló Aktív
finance.exchange_rates Árfolyamok Aktív
finance.issuers Kibocsátók Aktív
finance.org_subscriptions Szervezeti előfizetések Aktív
finance.user_subscriptions Felhasználói előfizetések Aktív
finance.payment_intents Fizetési szándékok Aktív
finance.withdrawal_requests Kifizetési kérelmek Aktív

3.6. System séma (Rendszeradatok)

Tábla Leírás Státusz
system.addresses Strukturált címek Aktív
system.documents Dokumentumok Aktív
system.translations Többnyelvű fordítások Aktív
system.system_parameters Rendszer paraméterek Aktív
system.internal_notifications Belső értesítések Aktív
system.pending_actions Függőben lévő műveletek Aktív
system.service_catalog Szolgáltatás katalógus Aktív
system.subscription_tiers Előfizetési szintek Aktív
system.service_staging Szolgáltatás staging ⚠️ Duplikáció?
system.staged_vehicle_data Jármű adat staging Aktív
system.geo_postal_codes Irányítószám adatok Aktív
system.geo_streets Utcák Aktív
system.geo_street_types Utca típusok Aktív
system.competitions_deprecated Versenyek (DEPR) Deprecated
system.user_scores_deprecated Pontszámok (DEPR) Deprecated
system.service_staging_deprecated Staging (DEPR) Deprecated
system.system_data_completion_weights Adatteljességi súlyok Aktív

3.7. Audit séma (Naplózás)

Tábla Leírás Státusz
audit.audit_logs Általános audit napló Aktív
audit.financial_ledger Pénzügyi főkönyv Aktív
audit.operational_logs Működési napló Aktív
audit.process_logs Folyamat napló Aktív
audit.security_audit_logs Biztonsági audit napló Aktív

3.8. Gamification séma (Játékosítás)

Tábla Leírás Státusz
gamification.badges Jelvények Aktív
gamification.competitions Versenyek Aktív
gamification.level_configs Szint konfigurációk Aktív
gamification.point_rules Pont szabályok Aktív
gamification.points_ledger Pont főkönyv Aktív
gamification.seasonal_competitions Szezonális versenyek Aktív
gamification.seasons Szezonok Aktív
gamification.user_badges Felhasználói jelvények Aktív
gamification.user_contributions Felhasználói hozzájárulások Aktív
gamification.user_scores Felhasználói pontszámok Aktív
gamification.user_stats Felhasználói statisztikák Aktív

4. 🔗 KAPCSOLATOK TÉRKÉP (Entity Relationship)

erDiagram
    PERSON ||--o{ USER : "has"
    PERSON ||--o{ ORGANIZATION_MEMBER : "member of"
    PERSON ||--o{ ORGANIZATION : "legal owner of"
    USER ||--o{ ORGANIZATION : "technical owner of"
    USER ||--o{ SERVICE_REVIEW : "writes"
    USER ||--o{ SERVICE_REQUEST : "creates"
    USER ||--o{ VEHICLE_USER_RATING : "rates"
    ORGANIZATION ||--o{ ORGANIZATION_MEMBER : "has members"
    ORGANIZATION ||--o{ BRANCH : "has locations"
    ORGANIZATION ||--o| SERVICE_PROFILE : "optional service"
    ORGANIZATION ||--o{ ASSET_ASSIGNMENT : "owns vehicles"
    ORGANIZATION ||--o{ VEHICLE_COST : "pays costs"
    SERVICE_PROFILE ||--o{ SERVICE_REVIEW : "receives"
    SERVICE_PROFILE ||--o{ SERVICE_EXPERTISE : "specializes"
    SERVICE_PROFILE ||--o{ BRANCH : "operates"
    BRANCH ||--o{ RATING : "rated by"
    BRANCH ||--o{ SERVICE_REQUEST : "receives requests"
    VEHICLE_MODEL_DEFINITION ||--o{ ASSET_CATALOG : "has variants"
    VEHICLE_MODEL_DEFINITION ||--o{ VEHICLE_COST : "has costs"
    VEHICLE_MODEL_DEFINITION ||--o{ VEHICLE_USER_RATING : "rated by users"
    ASSET_CATALOG ||--o{ ASSET : "defines"
    ASSET ||--o{ ASSET_EVENT : "has events"
    ASSET ||--o{ SERVICE_REQUEST : "referenced in"
    ADDRESS ||--o{ PERSON : "lives at"
    ADDRESS ||--o{ ORGANIZATION : "located at"
    ADDRESS ||--o{ BRANCH : "address"

5. 💡 JAVASLATOK a "Közösségi Kereső" funkciókhoz

5.1. Jelenlegi hiányosságok

  1. Nincs dedikált "Partner" entitás - A fleet.organizations-ban az is_affiliate_partner egy egyszerű boolean, nincs hozzá partner-specifikus adat (pl. jutalék ráta, partner kategória, szerződés állapota).
  2. ServiceProvider (régi) és ServiceProfile (új) kettősség - A régi marketplace.service_providers tábla használaton kívülinek tűnik, de még létezik.
  3. Nincs "aliases" (álnév) támogatás - Egyik táblában sincs JSONB aliases mező.
  4. Kategória rendszer hiányos - A marketplace.expertise_tags és marketplace.service_specialties párhuzamos címke rendszert alkot.

5.2. Javasolt bővítés: Organization kiegészítése (AJÁNLOTT)

Ahelyett, hogy új Partner táblát hoznánk létre, bővítsük a meglévő fleet.organizations táblát az alábbi JSONB oszlopokkal:

# Javasolt új mezők az Organization modellben
class Organization(Base):
    # ... meglévő mezők ...
    
    # ÚJ: Partnerek / Közösségi kereső
    aliases: Mapped[dict] = mapped_column(
        JSONB, server_default=text("'[]'::jsonb"),
        comment="Álnevek / alternatív nevek (pl. 'AutoShop Kft.', 'Autóshop')"
    )
    is_verified: Mapped[bool] = mapped_column(
        Boolean, server_default=text("false"),
        comment="Hivatalosan verifikált szervezet"
    )
    verification_level: Mapped[str] = mapped_column(
        String(20), server_default=text("'basic'"),
        comment="Verifikációs szint: basic, email, phone, kyc, premium"
    )
    partner_category: Mapped[str] = mapped_column(
        String(50), server_default=text("'none'"),
        comment="Partner kategória: none, basic, silver, gold, platinum"
    )
    commission_rate: Mapped[Optional[float]] = mapped_column(
        Numeric(5, 2), nullable=True,
        comment="Jutalék ráta (%-ban)"
    )
    service_radius_km: Mapped[Optional[int]] = mapped_column(
        Integer, nullable=True,
        comment="Szolgáltatási körzet (km)"
    )
    tags: Mapped[dict] = mapped_column(
        JSONB, server_default=text("'[]'::jsonb"),
        comment="Címkék a közösségi kereséshez"
    )
    search_keywords: Mapped[dict] = mapped_column(
        JSONB, server_default=text("'{}'::jsonb"),
        comment="Kereső kulcsszavak több nyelven"
    )
    social_profiles: Mapped[dict] = mapped_column(
        JSONB, server_default=text("'{}'::jsonb"),
        comment="Közösségi média profilok (Facebook, Instagram, Google Business)"
    )
    contact_persons: Mapped[dict] = mapped_column(
        JSONB, server_default=text("'[]'::jsonb"),
        comment="Kapcsolattartó személyek adatai"
    )

5.3. Alternatíva: Új partner_profiles tábla

Ha a fleet.organizations túl nagyra nőne, hozzunk létre egy új táblát:

class PartnerProfile(Base):
    """Bővített partner profil a Közösségi Keresőhöz."""
    __tablename__ = "partner_profiles"
    __table_args__ = {"schema": "marketplace"}
    
    id: Mapped[int] = mapped_column(Integer, primary_key=True)
    organization_id: Mapped[int] = mapped_column(
        Integer, ForeignKey("fleet.organizations.id"), unique=True, nullable=False
    )
    
    # --- ALAPADATOK ---
    aliases: Mapped[dict] = mapped_column(JSONB, server_default=text("'[]'::jsonb"))
    partner_category: Mapped[str] = mapped_column(String(50), default="none")
    
    # --- VERIFIKÁCIÓ ---
    verification_level: Mapped[str] = mapped_column(String(20), default="basic")
    verified_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
    verified_by_id: Mapped[Optional[int]] = mapped_column(Integer, ForeignKey("identity.users.id"))
    
    # --- KERESÉS ---
    search_keywords: Mapped[dict] = mapped_column(JSONB, server_default=text("'{}'::jsonb"))
    tags: Mapped[dict] = mapped_column(JSONB, server_default=text("'[]'::jsonb"))
    service_radius_km: Mapped[Optional[int]] = mapped_column(Integer)
    
    # --- GAZDASÁGI ADATOK ---
    commission_rate: Mapped[Optional[float]] = mapped_column(Numeric(5, 2))
    contract_start: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
    contract_end: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
    
    # --- KAPCSOLATOK ---
    social_profiles: Mapped[dict] = mapped_column(JSONB, server_default=text("'{}'::jsonb"))
    contact_persons: Mapped[dict] = mapped_column(JSONB, server_default=text("'[]'::jsonb"))
    
    # --- AUDIT ---
    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
    updated_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True), onupdate=func.now())

5.4. Ajánlott stratégia

  1. Rövid táv: Az Organization modell bővítése JSONB mezőkkel (aliases, tags, search_keywords, social_profiles). Ez azonnal használható, nincs szükség új táblára.
  2. Közép táv: Ha a partnerek száma eléri a 10.000+ rekordot, hozzuk létre a dedikált partner_profiles táblát az marketplace sémában.
  3. Hosszú táv: A régi marketplace.service_providers tábla archiválása/eltávolítása, mivel a ServiceProfile és a bővített Organization lefedi a funkcióit.

5.5. Megjegyzések a "Céges nyilvántartás" funkcióról

A rendelkezésre álló kód és adatbázis alapján:

  • Van "Céges nyilvántartás"fleet.organizations tábla
  • Van tagságkezelésfleet.organization_members tábla (User/Person + role)
  • Van telephelykezelésfleet.branches tábla (PostGIS támogatással)
  • Van szolgáltatói profilmarketplace.service_profiles tábla
  • Van értékelési rendszermarketplace.service_reviews (verifikált) + marketplace.ratings (általános)
  • NINCS dedikált partner modell - Az is_affiliate_partner boolean nem elegendő
  • NINCS keresőoptimalizált adat (aliases, tags, keywords)

6. ⚠️ FIGYELMEZTETÉSEK

6.1. Duplikált táblák

  • marketplace.service_staging és system.service_staging - Valószínűleg csak egy kellene.
  • marketplace.costs és vehicle.costs - Két külön költség tábla, különböző sémákban.
  • system.competitions_deprecatedgamification.competitions
  • system.user_scores_deprecatedgamification.user_scores

6.2. Kettős modell architektúra

  • marketplace.service_providers (régi, egyszerű) vs marketplace.service_profiles (új, komplex)
  • A régi tábla használata nem javasolt új fejlesztésekhez.

6.3. Soft delete következetlenség

  • fleet.organizations: is_deleted + is_active boolean mezők
  • marketplace.service_profiles: státusz alapú (ghost, active, flagged, suspended)
  • identity.persons: deleted_at datetime mező
  • identity.users: is_active boolean
  • Hiányzik egy egységes soft-delete stratégia az egész rendszerben.

Jelentés vége. A javasolt bővítések implementálása előtt egyeztetés szükséges a Vezető Tervezővel.