service-finder/plans/logic_spec_provider_taxonomy_search.md

🏗️ Logic Spec: Provider Taxonomy Audit & Smart Search API

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

Mérföldkő: Crowdsourced Partnerkereső (Marketplace Engine) Cél: A szolgáltatói kategóriarendszer (taxonómia) feltöltése és egy okos, egyesített kereső API (search + quick-add) megvalósítása a crowdsourced partnerkereséshez.

Masterbook 2.0 Kapcsolódás

• Epic: Marketplace & Service Discovery (08_Marketplace)
• Robot Kapcsolat: A meglévő service_staging adatok (robotok által gyűjtött) publikusan kereshetővé tétele
• Üzleti Logika: Bárki (még nem verifikált) gyorsan felvehet egy szolgáltatót, ami automatikusan a service_staging táblába kerül, ahol a robotok később feldolgozhatják

2. Adatbázis Audit Eredmények

Meglévő Táblák Állapota

Tábla	Séma	Állapot	Rekordok
expertise_tags	marketplace	ÜRES - nincs egyetlen kategória sem	0
service_specialties	marketplace	ÜRES - egyszerű (id, parent_id, name, slug)	0
service_providers	marketplace	ÜRES - crowdsourced provider tábla	0
organizations (org_type='service_provider')	fleet	NINCS ilyen rekord	0
service_staging	marketplace	Van benne ~2000+ rekord (robot gyűjtés)	~2000

Használandó Meglévő Struktúrák

1. marketplace.expertise_tags - A kategória mestertábla (twin: name_hu/name_en, search_keywords JSONB). Ez a legalkalmasabb.
2. fleet.organizations.aliases - JSONB mező a szolgáltató alternatív neveihez (már létezik!)
3. fleet.organizations.tags - JSONB mező a crowdsourced címkékhez (már létezik!)
4. marketplace.service_staging - Robotok által gyűjtött adatok (már létezik adatokkal)
5. marketplace.service_providers - Crowdsourced provider tábla (üres, de használható)

3. Technikai Terv

3.1 Seed Script: backend/app/scripts/seed_expertise_tags.py

Fájl: backend/app/scripts/seed_expertise_tags.py

Feltölti az expertise_tags táblát az alábbi alapkategóriákkal:

key	name_hu	name_en	category	search_keywords
auto_szerelo	Autószerelő	Car Mechanic	vehicle_service	["szerelő", "autószerelő", "mechanic", "garage"]
motor_szerelo	Motorkerékpár szerelő	Motorcycle Mechanic	vehicle_service	["motor", "motorszerelő", "motorcycle"]
gumiszerviz	Gumiszerviz	Tire Service	vehicle_service	["gumi", "gumis", "tire", "tyre", "abroncs"]
karosszerialakatos	Karosszérialakatos	Body Shop	body_paint	["karosszéria", "lakatos", "bodyshop"]
fényező	Fényező	Painter	body_paint	["fényező", "fényezés", "painter", "spray"]
autómentő	Autómentő / Motormentő	Tow Truck / Roadside	roadside	["mentő", "autómentő", "tow", "roadside"]
benzinkút	Benzinkút	Gas Station	fuel	["benzin", "kút", "gas station", "fuel"]
alkatrész_kereskedés	Alkatrész kereskedés	Parts Store	parts	["alkatrész", "parts", "spares"]
vizsgaállomás	Vizsgaállomás	Inspection Station	inspection	["vizsga", "műszaki", "inspection", "MOT"]
autókozmetika	Autókozmetika	Car Detailing	detailing	["kozmetika", "detailing", "takarítás"]
egyéb	Egyéb szolgáltató	Other Service	other	["egyéb", "other", "szolgáltató"]

Futtatás: docker exec sf_api python3 /app/backend/app/scripts/seed_expertise_tags.py

3.2 API Végpont: GET /api/v1/providers/search

Fájl: backend/app/api/v1/endpoints/providers.py

Végpont Specifikáció

GET /api/v1/providers/search?q={keresőszó}&category={kategória}&city={város}&limit={limit}&offset={offset}

Keresés Logikája (három tábla egyesítése)

flowchart TD
    A[GET /providers/search?q=kereső] --> B{Ellenőrizd a q paramétert}
    B -->|Van| C[Három tábla egyesített keresése]
    B -->|Nincs| D[Kategória/Város szűrés, ha van]
    
    C --> E1[1. fleet.organizations]
    C --> E2[2. marketplace.service_staging]
    C --> E3[3. marketplace.service_providers]
    
    E1 --> F1{org_type = service_provider}
    F1 --> G1[ILIKE a name-re]
    F1 --> G2[ILIKE az aliases JSONB-ben]
    
    E2 --> G3[ILIKE a name-re]
    E2 --> G4[ILIKE a city-re]
    
    E3 --> G5[ILIKE a name-re]
    
    D --> H[Közös UNION / egységesítés]
    H --> I[Forrás jelölés: verified_org / staged_data / crowd_added]
    I --> J[Rendezes + lapozás]
    J --> K[Response]

Response Schema (ProviderSearchResult)

{
  "results": [
    {
      "id": 1,
      "name": "MOL Autószerviz",
      "category": null,
      "specialization": ["autószerelő", "gumiszerviz"],
      "city": "Budapest",
      "address": "Budapest, Kossuth u. 1",
      "source": "verified_org",
      "is_verified": true,
      "rating": 4.5
    }
  ],
  "total": 42,
  "page": 1,
  "per_page": 20
}

3.3 API Végpont: POST /api/v1/providers/quick-add

Fájl: backend/app/api/v1/endpoints/providers.py

Végpont Specifikáció

POST /api/v1/providers/quick-add
Content-Type: application/json

{
  "name": "Teszt Autószerviz",
  "category_id": 1,
  "city": "Budapest",
  "street": "Kossuth utca 1",
  "tags": ["olcsó", "gyors"]
}

Folyamat

flowchart TD
    A[POST /providers/quick-add] --> B[Authentikáció: current_user]
    B --> C[Validáció: name kötelező]
    C --> D{Kategória ID ellenőrzése}
    D -->|Létezik| E[Létrehozás: Organization]
    D -->|Nem létezik| F[400: Invalid category]
    
    E --> G[Organization létrehozása]
    G --> H[org_type = service_provider]
    H --> I[is_verified = False]
    I --> J[tags = megadott tömbből]
    
    J --> K[ServiceProfile létrehozása]
    K --> L[expertise_tags kapcsolat]
    
    L --> M[Branch létrehozása a címmel]
    M --> N[commit]
    N --> O[Response: quick-add success]

Request Schema (ProviderQuickAddIn)

Mező	Típus	Kötelező	Leírás
name	string	Igen	Szolgáltató neve (2-200 karakter)
category_id	int	Igen	Kategória ID (expertise_tags.id)
city	string	Nem	Város
street	string	Nem	Utca/házszám
tags	string[]	Nem	Címkék (pl. ["olcsó", "gyors"])

Response Schema (ProviderQuickAddResponse)

Mező	Típus	Leírás
id	int	Az új szervezet ID-ja
name	string	A szolgáltató neve
status	string	"pending_verification"
message	string	Sikeres üzenet

3.4 Router Regisztráció

A providers.py-t be kell regisztrálni az api.py-ban:

from app.api.v1.endpoints import providers

api_router.include_router(providers.router, prefix="/providers", tags=["Providers"])

3.5 Szükséges Schémák

Fájl: backend/app/schemas/provider.py (ÚJ)

class ProviderSearchResult(BaseModel):
    id: int
    name: str
    category: Optional[str] = None
    specialization: List[str] = []
    city: Optional[str] = None
    address: Optional[str] = None
    source: str  # "verified_org" | "staged_data" | "crowd_added"
    is_verified: bool = False
    rating: Optional[float] = None
    model_config = ConfigDict(from_attributes=True)

class ProviderSearchResponse(BaseModel):
    results: List[ProviderSearchResult]
    total: int
    page: int = 1
    per_page: int = 20

class ProviderQuickAddIn(BaseModel):
    name: str = Field(..., min_length=2, max_length=200)
    category_id: int = Field(..., ge=1)
    city: Optional[str] = Field(None, max_length=100)
    street: Optional[str] = Field(None, max_length=255)
    tags: List[str] = Field(default_factory=list)

class ProviderQuickAddResponse(BaseModel):
    id: int
    name: str
    status: str = "pending_verification"
    message: str = "Szolgáltató sikeresen rögzítve. Ellenőrzés alatt."

3.6 Service Réteg

Fájl: backend/app/services/provider_service.py (ÚJ)

A service réteg tartalmazza:

• search_providers(db, q, category, city, limit, offset) - Egyesített keresés
• quick_add_provider(db, data, user_id) - Gyors szolgáltató felvétel

4. Adatmodell Változások

4.1 NINCS új modell vagy migráció!

A meglévő modellek és adatbázis táblák TELJESEN lefedik a funkcionalitást:

• marketplace.expertise_tags - már létezik, csak adat kell
• fleet.organizations - már van aliases, tags, org_type mező
• marketplace.service_staging - már létezik adatokkal
• marketplace.service_providers - már létezik (üres)

4.2 Csak Seed Adat Kell

A seed_expertise_tags.py INSERT utasításokkal tölti fel az expertise_tags táblát.

5. Megvalósítási Terv

5.1 Végrehajtandó Lépések

#	Lépés	Fájl	Leírás
1	Seed script	backend/app/scripts/seed_expertise_tags.py	Feltölti a 11 alapkategóriát
2	Seed futtatás	Terminál	docker exec sf_api python3 /app/backend/app/scripts/seed_expertise_tags.py
3	Pydantic schémák	backend/app/schemas/provider.py (ÚJ)	ProviderSearchResult, ProviderQuickAddIn
4	Service réteg	backend/app/services/provider_service.py (ÚJ)	search_providers, quick_add_provider
5	Endpointok	backend/app/api/v1/endpoints/providers.py	GET /search, POST /quick-add
6	Router regisztráció	backend/app/api/v1/api.py	providers router hozzáadása
7	Ellenőrző teszt	Terminál	API hívások tesztelése

5.2 Függőségek

• Bemenet: Meglévő modell réteg (Organization, ServiceStaging, ServiceProvider, ExpertiseTag)
• Kimenet: A /api/v1/providers/search és /api/v1/providers/quick-add végpontok
• Blokkoló: Nincs - minden meglévő kód használható

6. Admin Kontroll

A Seed script FUTTATHATÓ többször is (idempotens) - ON CONFLICT DO NOTHING klauzulával.

A kategóriák később az Admin felületen keresztül módosíthatók/bővíthetők.

7. Geo-Logika

A keresés jelenleg NEM tartalmaz PostGIS távolságszűrést (az külön endpoint: /search/match). A /providers/search csak szöveges keresés (ILIKE).