service-finder/docs/p0_discovery_provider_validation_audit.md

# P0 DISCOVERY - Audit Report: Provider Validation & Scoring Engine

**Dátum:** 2026-07-07
**Auditor:** Service Finder Rendszer-Architect
**Verzió:** 1.0

---

## 🔍 Executive Summary

Az Architect által definiált Trust & Validation scoring logika (Crawler=20, First Entry=40, User Confirm=+20, Auto-Approve Threshold=80, Admin Approve=100) **NINCS egységesen implementálva**. A pontozás három párhuzamos, egymástól független rendszerben fut, és egyik sem felel meg a specifikációnak.

---

## 1. 📡 CRAWLER/IMPORT ENDPOINT AUDIT

### 1.1 Robot 0 (Hunter - Google Places)

| Fájl | Sor |
|------|-----|
| `service_robot_0_hunter.py` | `trust_score=30 # Alapértelmezett bizalmi szint` (line 115) |

```python
new_entry = ServiceStaging(
    ...
    trust_score=30  # Hardcoded!
)
```

**Probléma:** A `trust_score` hardcoded `30`, míg az Architect specifikáció szerint Crawler forrásnál `20` kellene legyen. A `validation_level` mezőt nem állítja be explicit (default: `40` lesz a modellből).

### 1.2 Robot 1 (Scout - OSM)

| Fájl | Sor |
|------|-----|
| `service_robot_1_scout_osm.py` | `"trust_score": 20` (csak raw_data JSONB-ben!) (line 98) |

```python
raw_payload = {
    "osm_tags": tags,
    "source": "osm_scout_v2",
    "trust_score": 20  # CSAK a raw_data JSONB-ben!
}
new_entry = ServiceStaging(
    ...
    raw_data=raw_payload  # trust_score NEM kerül a tényleges oszlopba
)
```

**Probléma:** A `trust_score: 20` a `raw_data` JSONB objektumba kerül, **NEM** a `ServiceStaging.trust_score` mezőbe! Az adatbázis oszlop értéke `0` marad (modell default). Ez adatvesztéshez vezet.

### 1.3 User Submission (Gamification Endpoint)

| Fájl | Sor |
|------|-----|
| `gamification.py` | `trust_weight = min(20 + (user_lvl * 6), 90)` (line 317) |

```python
trust_weight = min(20 + (user_lvl * 6), 90)
...
new_staging = ServiceStaging(
    ...
    trust_score=trust_weight,  # Dinamikus, de NEM a First Entry=40 logikát követi
)
```

**Probléma:** A dinamikus számítás (20 + szint*6) NEM felel meg a "First Entry = 40" szabálynak. Egy 1-es szintű user `26`-ot kap, nem `40`-et.

### 1.4 Crawler Import Endpoint (Admin API)

Az `admin_providers.py` fájlban **nincs dedikált crawler import endpoint**. A meglévő `POST /{provider_id}/approve` és `POST /{provider_id}/reject` végpontok csak a már létező `ServiceProvider` rekordok státuszát módosítják, nem hoznak létre újakat.

---

## 2. ⚙️ VALIDATION ENGINE AUDIT

### 2.1 Több, egymástól független scoring mechanizmus

A rendszerben **három párhuzamos scoring rendszer** létezik, amelyek NINCSENEK összekapcsolva:

| # | Scoring System | Tábla | Mező | Ki működteti? |
|---|---------------|-------|------|---------------|
| 1 | **Trust Score** | `marketplace.service_staging` | `trust_score` (default: **0**) | Robotok, User Submission |
| 2 | **Validation Level** | `marketplace.service_staging` | `validation_level` (default: **40**) | Community validation (`services.py`) |
| 3 | **Validation Score** | `marketplace.service_providers` | `validation_score` (default: **0**) | Admin moderáció (`admin_providers.py`) |

### 2.2 Modellek összehasonlítása

#### `ServiceStaging` (`staged_data.py:54-59`)
```python
trust_score: Mapped[int] = mapped_column(Integer, default=0, server_default=text("0"))
validation_level: Mapped[int] = mapped_column(Integer, default=40, server_default=text("40"))
```
- `trust_score`: Robot bizalmi szint (0-100)
- `validation_level`: Közösségi validációs szint (default 40, max 80)

#### `ServiceProvider` (`social.py:59`)
```python
validation_score: Mapped[int] = mapped_column(Integer, default=0)
```
- `validation_score`: Moderációs pontszám (csak admin által állítható)

#### `ProviderValidation` (`social.py:87-123`)
```python
class ProviderValidation(Base):
    __tablename__ = "provider_validations"
    # validation_type: approve | reject | flag
    # weight: admin weight (default=1, admin uses 5)
    # metadata: JSONB for details
```

### 2.3 ProviderValidation tábla - Jelenlegi használat

A `_create_provider_validation()` függvény minden admin akciókor (approve/reject/restore/flag) létrehoz egy rekordot:

| Akció | `validation_type` | `weight` | `validation_score` módosítás |
|-------|-------------------|----------|------------------------------|
| Approve | `approve` | 5 | `+= 50` |
| Reject | `reject` | 5 | `= 0` |
| Restore | `approve` | 5 | `= 50` |
| Flag | `flag` | 5 | `-= 20` (min 0) |

**Hiányzó funkció:** A `weight` mezőt soha nem aggregálja a rendszer. Nincs olyan logika, ami a `ProviderValidation.weight`-ok összegét vizsgálná, és annak alapján auto-approve/-reject döntést hozna.

### 2.4 Community Validation (SocialService)

| Fájl | Sor |
|------|-----|
| `social_service.py` | `validation_score += vote_value` (lines 45-53) |

```python
provider.validation_score += vote_value  # +1 vagy -1
if provider.validation_score >= 5:
    provider.status = ModerationStatus.approved
elif provider.validation_score <= -3:
    provider.status = ModerationStatus.rejected
```

**Probléma:** Ez az OLD community voting rendszer (`Vote` tábla, `+-1` szavazatok), ami NEM kapcsolódik a `validation_level` vagy az Architect által definiált scoring logikához. A küszöbértékek (`5` és `-3`) teljesen függetlenek a `80`-as auto-approve threshold-tól.

### 2.5 Service Validation (User Confirm)

| Fájl | Sor |
|------|-----|
| `services.py` | `validation_level += 10` (max 80) (lines 72-75) |

```python
new_level = staging.validation_level + 10
if new_level > 80:
    new_level = 80
```

Ez a `validation_level`-t növeli (max 80), de ez **NEM befolyásolja** sem a `trust_score`-t, sem a `validation_score`-t. A `+20` User Confirm bónusz NINCS implementálva.

---

## 3. 🚀 PROMOTION LOGIC AUDIT (Threshold = 80)

### 3.1 System Robot 2 (ServiceAuditor)

| Fájl | Sor |
|------|-----|
| `system_robot_2_service_auditor.py` | Threshold default: **50** (line 37) |

```python
threshold = value.get('trust_score', 50) if isinstance(value, dict) else 50
if stage.trust_score >= threshold:
    # SIKERES AUDIT -> Organization + ServiceProfile
```

**GAP:** A threshold default **50**, nem **80**. És a `trust_score`-t vizsgálja, nem a `validation_level`-t.

### 3.2 Service Robot 5 (Auditor)

| Fájl | Sor |
|------|-----|
| `service_robot_5_auditor.py` | Threshold default: **70** (lines 40-45) |

```python
param = result.scalar_one_or_none()
if param and param.value:
    return int(param.value)
return 70  # Default
if staging.trust_score < trust_threshold:
    staging.status = 'rejected'
```

**GAP:** A threshold default **70**, nem **80**. És itt is a `trust_score`-t vizsgálja.

### 3.3 Admin Approve (validation_level = 100)

| Fájl | Sor |
|------|-----|
| `admin.py` | `validation_level = 100` (lines 265-266) |

```python
staging.validation_level = 100
staging.status = "approved"
```

**Egyedül ez felel meg** az Architect specifikáció "Admin Approve = 100" szabályának, de ez csak a `ServiceStaging` rekordot jelöli meg, nem hoz létre `ServiceProvider`-t vagy `Organization`-t automatikusan.

---

## 4. 📊 HIÁNYOSSÁGOK ÖSSZEGZÉSE

### 🔴 P0 Critical Gaps

| # | Gap | Helye | Következmény |
|---|-----|-------|-------------|
| **G1** | **Nincs egységes scoring engine** | A teljes scoring logika hiányzik | A Crawler=20, First Entry=40, User Confirm=+20 szabályok NINCSENEK sehol implementálva |
| **G2** | **Robot 1 (Scout) trust_score elveszik** | `service_robot_1_scout_osm.py:98` | A `trust_score: 20` a `raw_data` JSONB-ben landol, NEM az oszlopban. A rekord trust_score=0 marad. |
| **G3** | **Auto-Approve Threshold=80 sehol nem érvényesül** | `system_robot_2_service_auditor.py:37` és `service_robot_5_auditor.py:45` | A robotok 50-es és 70-es threshold-ot használnak. A validation_level max 80-as limit elérése nem triggerel semmit. |

### 🟡 P1 Medium Gaps

| # | Gap | Helye | Következmény |
|---|-----|-------|-------------|
| **G4** | **Három független scoring rendszer** | `trust_score`, `validation_level`, `validation_score` | Nincs átjárás a rendszerek között. Egy magas validation_level nem növeli a validation_score-t. |
| **G5** | **ProviderValidation weight aggregáció hiányzik** | `admin_providers.py:211` | A `weight` mező létezik, de soha nincs összegezve auto-approve döntéshez. |
| **G6** | **User submission scoring nem spec-konform** | `gamification.py:317` | `min(20 + (user_lvl*6), 90)` helyett `40` kellene First Entry-nél. |

### 🟢 P2 Minor Gaps

| # | Gap | Helye | Következmény |
|---|-----|-------|-------------|
| **G7** | **Admin approve nem hoz létre Organization-t** | `admin.py:265-266` | Csak a `validation_level=100`-at állítja, de a promotion logika (Staging→Organization) nem fut le. |
| **G8** | **SocialService vote nem kapcsolódik a scoring engine-hez** | `social_service.py:45-53` | A community vote (`+-1`) teljesen külön úton halad, a threshold-ok (5/-3) nem konfigurálhatók. |

---

## 5. 📋 Adatfolyam Diagram (Current State vs Desired State)

### Jelenlegi állapot (As-Is):

```mermaid
flowchart LR
    A[Robot 0 Hunter] -->|trust_score=30| B[ServiceStaging]
    C[Robot 1 Scout] -->|trust_score=0 raw_data.trust_score=20| B
    D[User Submission] -->|trust_score=26-90| B
    B -->|status=auditor_ready| E[System Robot 2]
    E -->|trust_score>=50| F[Organization + ServiceProfile]
    B -->|status=pending| G[Community Validation]
    G -->|validation_level+=10 max 80| B
    B -->|status=auditing| H[Service Robot 5]
    H -->|trust_score>=70| I[Organization + ServiceProfile]
    J[Admin] -->|validation_score+=50| K[ServiceProvider]
```

### Kívánt állapot (To-Be) az Architect specifikáció alapján:

```mermaid
flowchart LR
    A[Crawler Import] -->|Crawler=20| B[Validation Engine]
    C[First Entry User] -->|First Entry=40| B
    D[User Confirm] -->|+20| B
    E[Admin Approve] -->|=100| B
    B -->|score>=80 Auto-Approve| F[Organization + ServiceProvider]
    B -->|score<80| G[Pending Review]
```

---

## 6. 🔧 Javasolt Javítási Sorrend

1. **P0 - Create a unified `validation_service.py`** that implements the Architect's scoring math:
   - `Crawler = 20` (source="bot")
   - `First Entry = 40` (source="manual", first submission)
   - `User Confirm = +20` (max 80)
   - `Auto-Approve Threshold = 80`
   - `Admin Approve = 100`

2. **P0 - Fix Robot 1 Scout** to write `trust_score` to the actual column, not just `raw_data`.

3. **P1 - Unify thresholds** in System Robot 2 and Service Robot 5 to use `validation_level` (or a unified score) instead of `trust_score`.

4. **P1 - Connect scoring systems** so `validation_level` increments also affect the provider's `validation_score`.

5. **P2 - Add auto-promotion** when unified score >= 80: auto-create `ServiceProvider` (or `Organization`) from `ServiceStaging`.