szolgáltatók beálltásai, szerkesztése , létrehozása

2026-06-17 11:52:25 +00:00
parent 213ba3b0f1
commit bf3a971ff1
56 changed files with 14421 additions and 1512 deletions
--- a/plans/logic_spec_provider_taxonomy_search.md
+++ b/plans/logic_spec_provider_taxonomy_search.md
@@ -0,0 +1,271 @@
+# 🏗️ 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)
+
+```mermaid
+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)
+
+```json
+{
+  "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
+
+```mermaid
+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:
+
+```python
+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)
+
+```python
+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).