service-finder/plans/provider_admin_edit_analysis_and_plan.md

# 🔧 Provider Admin Szerkesztés — Teljes Elemzés és Terv

## 🎯 Összefoglaló

**Kérdés:** Hogyan lehet a szolgáltatói adatokat módosítani? Hol van a jóváhagyás/adatmódosítás előzménye? Ki mikor rögzítette? Kik validálták? Admin felületről módosítható-e?

**Válasz röviden:** Az adatok **NINCSENEK bekódolva** — teljes egészében az adatbázisban vannak. A moderáció (approve/reject/flag/delete) **admin felületről működik**, de a provider adatmezőinek szerkesztése (név, cím, telefonszám, email módosítása) **még NINCS implementálva** az admin felületen. Javaslat: új PUT végpont + frontend edit modal.

---

## ✅ 1. ADATOK TÁROLÁSA (NINCSENEK bekódolva)

### `marketplace.service_providers` — Alap szolgáltató adatok

| Oszlop | Típus | Leírás |
|--------|-------|--------|
| `id` | integer (PK) | Automatikus ID |
| `name` | varchar(255) | **Szolgáltató neve** |
| `address` | varchar(255) | Teljes cím (legacy, deprecated) |
| `city` | varchar(100) | **Város** |
| `address_zip` | varchar(20) | **Irányítószám** |
| `address_street_name` | varchar(255) | **Utcanév** |
| `address_street_type` | varchar(50) | Utcatípus (utca, tér, stb.) |
| `address_house_number` | varchar(20) | **Házszám** |
| `plus_code` | varchar(100) | Google Plus Code |
| `contact_phone` | varchar(50) | **Telefonszám** |
| `contact_email` | varchar(255) | **Email** |
| `website` | varchar(255) | **Weboldal** |
| `category` | varchar(100) | **Kategória** (ExpertiseTag ID string) |
| `status` | ENUM (ModerationStatus) | `pending` / `approved` / `rejected` / `flagged` |
| `source` | ENUM (SourceType) | `crowd` / `admin` / `robot` |
| `validation_score` | integer | Validációs pontszám |
| `evidence_image_path` | varchar(500) | Kép bizonyíték |
| `added_by_user_id` | integer (FK→users) | **Ki vette fel** |
| `created_at` | timestamptz | **Mikor vették fel** |

### `marketplace.service_profiles` — Részletes profil és értékelések

**Kapcsolat:** `service_profiles.service_provider_id` → `service_providers.id`

| Oszlop | Típus | Leírás |
|--------|-------|--------|
| `id` | integer (PK) | Automatikus ID |
| `service_provider_id` | integer (FK) | Kapcsolódó service_provider |
| `organization_id` | integer (FK) | Opcionális szervezeti kapcsolat |
| `location` | GEOMETRY (PostGIS) | Földrajzi hely |
| `status` | ENUM (ServiceStatus) | `active` / `inactive` / `suspended` |
| `trust_score` | integer | **Bizalmi pontszám** |
| `is_verified` | boolean | Ellenőrzött-e |
| `verification_log` | jsonb | Validációs napló |
| `rating` | double precision | Google átlagértékelés |
| `user_ratings_total` | integer | Google értékelések száma |
| `rating_verified_count` | integer | Ellenőrzött értékelések száma |
| `rating_price_avg` | double precision | **Ár átlag pontszám** |
| `rating_quality_avg` | double precision | **Minőség átlag pontszám** |
| `rating_time_avg` | double precision | **Idő átlag pontszám** |
| `rating_communication_avg` | double precision | **Kommunikáció átlag pontszám** |
| `rating_overall` | double precision | **Összesített átlag pontszám** |
| `specialization_tags` | jsonb | Specializációs címkék |
| `opening_hours` | jsonb | Nyitvatartás |
| `contact_phone` | varchar(50) | Profil telefonszám |
| `contact_email` | varchar(255) | Profil email |
| `website` | varchar(255) | Profil weboldal |
| `bio` | text | Leírás |
| `created_at` | timestamptz | Létrehozva |
| `updated_at` | timestamptz | **Utolsó módosítás** |

### `marketplace.service_reviews` — Felhasználói értékelések ⭐

**Kapcsolat:** `service_reviews.service_id` → `service_profiles.id`

| Oszlop | Típus | Leírás |
|--------|-------|--------|
| `id` | integer (PK) | Automatikus ID |
| `service_id` | integer (FK) | Melyik service_profile-ra |
| `user_id` | integer (FK→users) | **Ki értékelt** |
| `price_rating` | integer | **Ár pontszám** (1-5) |
| `quality_rating` | integer | **Minőség pontszám** (1-5) |
| `time_rating` | integer | **Idő/gördülékenység pontszám** (1-5) |
| `communication_rating` | integer | **Kommunikáció pontszám** (1-5) |
| `comment` | text | Szöveges vélemény |
| `is_verified` | boolean | Ellenőrzött tranzakcióhoz tartozik |
| `transaction_id` | uuid | Kapcsolódó tranzakció |
| `created_at` | timestamptz | Értékelés ideje |

### `marketplace.provider_validations` — Validációs előzmények

| Oszlop | Típus | Leírás |
|--------|-------|--------|
| `id` | integer (PK) | Automatikus ID |
| `provider_id` | integer (FK) | Melyik provider |
| `voter_user_id` | integer (FK→users) | **Ki validált** |
| `validation_type` | varchar(20) | `approve` / `reject` / `flag` |
| `weight` | integer | Súly érték |
| `metadata` | jsonb | Extra adatok (reason, stb.) |
| `created_at` | timestamptz | Validáció ideje |

**UNIQUE:** `(voter_user_id, provider_id)` — egy user csak egyszer szavazhat.

### `marketplace.votes` — Szavazatok

| Oszlop | Leírás |
|--------|--------|
| `vote_value` | integer (+1/-1) |

### `marketplace.ratings` — Általános értékelés

| Oszlop | Leírás |
|--------|--------|
| `score` | numeric(3,2) (max 9.99) |
| `comment` | text |
| `images` | jsonb |

### `gamification.point_rules` — Pontszabályok

| ID | action_key | points | description | is_active |
|----|-----------|--------|-------------|-----------|
| 3 | `ADD_NEW_PROVIDER` | 500 | Új szolgáltató rögzítése | ✅ |
| 4 | `USE_UNVERIFIED_PROVIDER` | 200 | Szervizesemény nem ellenőrzött szolgáltatónál | ✅ |
| 5 | `RATE_PROVIDER` | 250 | Szolgáltató értékelése (tagekkel) | ✅ |
| 6 | `UPDATE_PROVIDER` | 100 | Szolgáltató adatainak szerkesztése | ✅ |

---

## ✅ 2. AUDIT TRAIL — Ki mit csinált, mikor?

### `audit.audit_logs` — Központi audit napló

```sql
user_id     → FK users (ki)
severity    → ENUM (info, warning, error)
action      → varchar (pl. "admin_provider_approve")
target_type → varchar (pl. "service_provider")
target_id   → varchar (pl. "42")
old_data    → JSON (előző állapot)
new_data    → JSON (új állapot)
ip_address  → varchar
user_agent  → text
timestamp   → timestamptz (mikor)
```

Az [`admin_providers.py`](backend/app/api/v1/endpoints/admin_providers.py:147) `_log_moderation_action()` függvénye minden moderációs műveletet naplóz ide.

### Kapcsolati háló

```
identity.users
  ├── added_by_user_id ──→ marketplace.service_providers   (ki adta hozzá)
  ├── user_id ──→ marketplace.service_reviews              (ki értékelt)
  │               └── service_id ──→ service_profiles
  ├── author_id ──→ marketplace.ratings                    (ki értékelt általában)
  ├── user_id ──→ marketplace.votes                        (ki szavazott)
  │               └── provider_id ──→ service_providers
  └── voter_user_id ──→ marketplace.provider_validations   (ki validált)
                        └── provider_id ──→ service_providers
```

---

## ✅ 3. ADMIN FELÜLETRŐL MÓDOSÍTHATÓ? — ÁLLAPOTFELMÉRÉS

### ✅ MEGLÉVŐ — Moderációs műveletek admin felületről

| Művelet | Backend végpont | Frontend oldal |
|---------|----------------|----------------|
| Listázás | `GET /admin/providers` | `/providers` (index.vue) |
| Statisztika | `GET /admin/providers/stats` | `/providers` (index.vue) |
| Részletek | `GET /admin/providers/{id}` | `/providers/[id]` |
| **Jóváhagyás** | `POST /admin/providers/{id}/approve` | `/providers/[id]` |
| **Elutasítás** | `POST /admin/providers/{id}/reject` | `/providers/[id]` |
| **Megjelölés** | `POST /admin/providers/{id}/flag` | `/providers/[id]` |
| **Törlés** | `DELETE /admin/providers/{id}` | `/providers/[id]` |
| Függőben queue | — | `/providers/pending` |

### ❌ HIÁNYZÓ — Adatok szerkesztése admin felületről

| Funkció | Backend | Frontend |
|---------|---------|----------|
| **Provider adatok szerkesztése** (név, cím, tel., email, web, kategória) | ❌ Nincs PUT/PATCH végpont | ❌ Nincs edit form |
| **Provider history/log nézet** | ❌ Nincs GET history végpont | ❌ Nincs history panel |
| **Pontszabályok bővítése** (PROVIDER_DISCOVERY, stb.) | ❌ Hiányzó DB rekordok | — |

---

## 📋 4. TERV — JAVASOLT FEJLESZTÉSEK

### 🟢 P0 — Admin Provider Edit (Kötelező — Hiány #1)

#### Backend: Új PUT végpont (admin_providers.py)

```python
class ProviderUpdateInput(BaseModel):
    name: Optional[str] = None
    city: Optional[str] = None
    address_zip: Optional[str] = None
    address_street_name: Optional[str] = None
    address_street_type: Optional[str] = None
    address_house_number: Optional[str] = None
    plus_code: Optional[str] = None
    contact_phone: Optional[str] = None
    contact_email: Optional[str] = None
    website: Optional[str] = None
    category: Optional[str] = None

@router.put("/{provider_id}", response_model=ModerationResponse)
async def update_provider(
    provider_id: int,
    data: ProviderUpdateInput,
    db: AsyncSession = Depends(get_db),
    current_user: User = Depends(require_admin),
):
    """Admin általi provider adatmódosítás. AuditLog capture old vs new values."""
    # 1. Lekéri a meglévő provider-t
    # 2. Elmenti a régi értékeket (old_data JSON)
    # 3. Frissíti a megadott mezőket
    # 4. AuditLog írás: action="admin_provider_update", old_data → new_data
    # 5. ProviderValidation létrehozása: validation_type="admin_edit"
    # 6. validation_score reset 0-ra (újra kell validálni)
    # 7. Ha van service_profile, annak updated_at frissítése
```

**Adatbázis érintettség:**
- `marketplace.service_providers` → UPDATE
- `audit.audit_logs` → INSERT (old_data → new_data JSON capture)
- `marketplace.provider_validations` → INSERT (admin_edit record)
- `marketplace.service_profiles.updated_at` → UPDATE (ha van kapcsolódó profil)

#### Frontend: Edit modal (providers/[id].vue)

- **"Szerkesztés" gomb** a provider detail nézetben (csak approved státuszúaknál)
- **Modal vagy inline form** a következő mezőkkel:
  - **Név** (name) — text input
  - **Cím blokk**: város, irányítószám, utcanév, utcatípus, házszám, plus_code
  - **Kapcsolat**: telefon, email, weboldal
  - **Kategória** (category) — select a meglévő kategóriákból
- **Mentés gomb** → `PUT /admin/providers/{id}` hívás
- **Sikeres mentés** után: adatok frissítése a nézetben + toast "Sikeres módosítás"
- **Validation**: mezők validálása mentés előtt

### 🟢 P0 — Pontszabályok bővítése (Kötelező — Hiány #4)

Új rekordok beszúrása a `gamification.point_rules` táblába:

| action_key | points | description |
|-----------|--------|-------------|
| `PROVIDER_DISCOVERY` | 300 | Új, még nem létező provider felfedezése |
| `PROVIDER_CONFIRMATION` | 150 | Meglévő provider adatainak megerősítése |
| `PROVIDER_VERIFIED_USE` | 100 | Már validált provider használata költség rögzítésnél |

**Létrehozás:** Seed script vagy egyszerű SQL INSERT.

### 🟡 P1 — Provider History Panel (Javasolt — Hiány #3)

#### Backend: Új GET végpont

```python
@router.get("/{provider_id}/history", response_model=List[AuditLogEntry])
async def get_provider_history(...):
    """Visszaadja a provider-hez kapcsolódó összes audit log rekordot."""
```

- Lekérdezés az `audit.audit_logs` táblából: `target_type='service_provider' AND target_id='{provider_id}'`
- Rendezés: `timestamp DESC`

#### Frontend: History tab

- Új "Előzmények" fül a provider detail oldalon (`providers/[id].vue`)
- Táblázatos nézet:
  | Dátum | Művelet | Ki | Részletek |
  |-------|---------|-----|-----------|
  | 2026-06-30 | Létrehozás | János | új provider |
  | 2026-06-30 | Jóváhagyás | Admin | +50 score |
  | 2026-06-30 | Szerkesztés | Admin | név, cím módosítva |

---

## 📊 5. ADATBÁZIS ÉRINTETTSÉG ÖSSZESÍTÉS

| Séma | Tábla | Művelet | Leírás |
|------|-------|---------|--------|
| `marketplace` | `service_providers` | UPDATE | Admin általi mezőmódosítás |
| `marketplace` | `service_profiles` | UPDATE | `updated_at` frissítés |
| `marketplace` | `provider_validations` | INSERT | Admin edit naplózása |
| `audit` | `audit_logs` | INSERT | Változásnaplózás (old→new) |
| `gamification` | `point_rules` | INSERT | Új pontszabályok |

---

## 🗂️ 6. ÉRINTETT FÁJLOK

| Fájl | Művelet |
|------|---------|
| [`backend/app/api/v1/endpoints/admin_providers.py`](backend/app/api/v1/endpoints/admin_providers.py) | **MÓDOSÍTÁS**: ÚJ PUT végpont + ProviderUpdateInput schema |
| [`frontend_admin/pages/providers/[id].vue`](frontend_admin/pages/providers/[id].vue) | **MÓDOSÍTÁS**: Edit modal/űrlap hozzáadása (P0) + History tab (P1) |
| [`frontend_admin/i18n/locales/hu.json`](frontend_admin/i18n/locales/hu.json) | **MÓDOSÍTÁS**: Magyar szövegek |
| [`frontend_admin/i18n/locales/en.json`](frontend_admin/i18n/locales/en.json) | **MÓDOSÍTÁS**: Angol szövegek |
| `backend/app/scripts/seed_provider_point_rules.py` | **LÉTREHOZÁS**: Seed script az új pontszabályokhoz |
| [`backend/app/models/identity/social.py`](backend/app/models/identity/social.py) | **NINCS változás** — meglévő modell használható |

---

## 🚀 7. JAVASOLT GITEA KÁRTYÁK (Jóváhagyás után)

### 1. kártya — Backend: Admin provider edit PUT végpont
**Cím:** `Backend: Admin provider edit PUT /admin/providers/{id} végpont`
**Mérföldkő:** P0 Service Provider Admin
**Cél:** Admin általi provider adatmódosítás lehetővé tétele

**Függőségek:**
- **Bemenet:** `admin_providers.py`, `ServiceProvider` modell, `AuditLog` modell
- **Kimenet:** Admin frontend edit form (2. kártya)

**Leírás:** ÚJ PUT végpont a `admin_providers.py`-ban, ami lehetővé teszi admin számára a provider adatmezők szerkesztését (name, city, address_*, contact_*, website, category). AuditLog capture (old_data → new_data JSON). ProviderValidation record létrehozása `validation_type='admin_edit'`. validation_score reset 0-ra.

### 2. kártya — Frontend: Admin provider edit modal
**Cím:** `Frontend: Admin provider edit modal/űrlap`
**Mérföldkő:** P0 Service Provider Admin
**Cél:** Admin felületi lehetőség a provider adatok szerkesztésére

**Függőségek:**
- **Bemenet:** 1. kártya (PUT végpont)
- **Kimenet:** — (frontend feature)

**Leírás:** Edit modal hozzáadása a `providers/[id].vue` oldalhoz. "Szerkesztés" gomb, form mezők (név, cím, kapcsolat, kategória), validálás, PUT hívás, sikeres mentés utáni frissítés. Magyar és angol i18n szövegek.

### 3. kártya — Pontszabályok bővítése
**Cím:** `Seed: Új gamification pontszabályok provider rendszerhez`
**Mérföldkő:** P0 Gamification
**Cél:** Provider discovery és confirmation pontozás bevezetése

**Függőségek:**
- **Bemenet:** `gamification.point_rules` tábla
- **Kimenet:** Gamification motor (pontozás működése)

**Leírás:** 3 új pontszabály beszúrása: PROVIDER_DISCOVERY (300p), PROVIDER_CONFIRMATION (150p), PROVIDER_VERIFIED_USE (100p). Seed script létrehozása.

### 4. kártya — Provider history nézet (P1)
**Cím:** `Backend+Frontend: Provider audit history megjelenítése`
**Mérföldkő:** P1 Admin Experience
**Cél:** Provider teljes életciklusának áttekinthetősége

**Függőségek:**
- **Bemenet:** `audit.audit_logs` tábla
- **Kimenet:** Jobb admin áttekinthetőség

**Leírás:** GET `/admin/providers/{id}/history` végpont az `audit.audit_logs`-ból. History tab a frontenden: dátum, művelet, ki, részletek.