service-finder/docs/identity_schema_complete_audit.md

# 🔬 identity Séma Teljes Audit (2026-06-06)

## Áttekintés
Az `identity` séma **9 táblát** tartalmaz, amelyek együttesen a teljes felhasználói identitáskezelést lefedik: a természetes személyt (Person), a login entitást (User), a pénztárcát, a közösségi kapcsolatokat, a bizalmi profilt, az eszközöket és a vouchereket.

---

## 1. 📊 TÁBLÁK ÉS ADATAIK

### 1.1 👤 `users` — Login Entitás (Központi tábla)
**Oszlopok (24 db):**
| Oszlop | Típus | Kötelező? | Default | Leírás |
|--------|-------|-----------|---------|--------|
| `id` | INTEGER | PK | nextval(...) | Elsődleges kulcs |
| `email` | VARCHAR(255) | **YES** | — | E-mail cím (UNIQUE) |
| `hashed_password` | VARCHAR | NO | — | Hash-elt jelszó |
| `role` | USERRODE (ENUM) | **YES** | 'user' | Szerepkör (lásd ENUM lent) |
| `person_id` | BIGINT | NO | — | FK → persons(id) |
| `subscription_plan` | VARCHAR(30) | **YES** | 'FREE' | Előfizetési csomag |
| `subscription_expires_at` | TIMESTAMPTZ | NO | — | Előfizetés lejárata |
| `is_vip` | BOOLEAN | **YES** | false | VIP státusz |
| `referral_code` | VARCHAR(20) | NO | — | Meghívókód (UNIQUE) |
| `referred_by_id` | INTEGER | NO | — | FK → users(id) (aki meghívta) |
| `current_sales_agent_id` | INTEGER | NO | — | FK → users(id) (értékesítő) |
| `is_active` | BOOLEAN | **YES** | false | Aktív-e a fiók |
| `is_deleted` | BOOLEAN | **YES** | false | Soft-delete |
| `folder_slug` | VARCHAR(12) | NO | — | Fájltároló slug (UNIQUE) |
| `preferred_language` | VARCHAR(5) | **YES** | 'hu' | Nyelv |
| `region_code` | VARCHAR(5) | **YES** | 'HU' | Régió |
| `preferred_currency` | VARCHAR(3) | **YES** | 'HUF' | Pénznem |
| `ui_mode` | VARCHAR(20) | **YES** | 'personal' | UI mód (personal/fleet) |
| `scope_level` | VARCHAR(30) | **YES** | 'individual' | Scope szint |
| `scope_id` | VARCHAR(50) | NO | — | Scope azonosító |
| `custom_permissions` | JSON | **YES** | '{}' | Egyedi jogosultságok |
| `alternative_emails` | JSON | **YES** | '[]' | Alternatív e-mailek |
| `email_history` | JSON | **YES** | '[]' | E-mail cím történet |
| `created_at` | TIMESTAMPTZ | **YES** | — | Létrehozás ideje |

**Indexek (7 db):**
- `users_pkey` — UNIQUE BTREE (id)
- `users_email_key` — UNIQUE BTREE (email)
- `users_referral_code_key` — UNIQUE BTREE (referral_code)
- `ix_identity_users_folder_slug` — UNIQUE BTREE (folder_slug)
- `ix_identity_users_email` — UNIQUE BTREE (email) (duplikáció!)
- `ix_identity_users_id` — BTREE (id)

---

### 1.2 🧑 `persons` — Természetes Személy
**Oszlopok (22 db):**
| Oszlop | Típus | Kötelező? | Default | Leírás |
|--------|-------|-----------|---------|--------|
| `id` | BIGINT | PK | nextval(...) | Elsődleges kulcs |
| `user_id` | INTEGER | NO | — | FK → users(id) (aktív fiók) |
| `id_uuid` | UUID | **YES** | gen_random_uuid() | Publikus UUID |
| `address_id` | UUID | NO | — | FK → system.addresses(id) |
| `identity_hash` | VARCHAR(64) | NO | — | Hash: Név+Anyja+DOB (UNIQUE) |
| `last_name` | VARCHAR | **YES** | — | Vezetéknév |
| `first_name` | VARCHAR | **YES** | — | Keresztnév |
| `phone` | VARCHAR | NO | — | Telefonszám |
| `mothers_last_name` | VARCHAR | NO | — | Anyja vezetékneve |
| `mothers_first_name` | VARCHAR | NO | — | Anyja keresztneve |
| `birth_place` | VARCHAR | NO | — | Születési hely |
| `birth_date` | TIMESTAMP | NO | — | Születési dátum |
| `identity_docs` | JSON | **YES** | '{}' | Okmányok (ID_CARD, LICENSE, stb.) |
| `ice_contact` | JSON | **YES** | '{}' | Vészhelyzeti kapcsolattartó |
| `lifetime_xp` | BIGINT | **YES** | -1 | Élettapasztalat pont |
| `penalty_points` | INTEGER | **YES** | -1 | Büntetőpontok |
| `social_reputation` | NUMERIC(3,2) | **YES** | 0.00 | Társadalmi reputáció |
| `is_sales_agent` | BOOLEAN | **YES** | true | Értékesítő-e |
| `is_active` | BOOLEAN | **YES** | true | Aktív-e |
| `is_ghost` | BOOLEAN | **YES** | false | Ghost (soft-delete) |
| `merged_into_id` | BIGINT | NO | — | Összevonva ebbe a Person-ba (csak ORM szinten FK) |
| `created_at` | TIMESTAMPTZ | **YES** | — | Létrehozás |
| `updated_at` | TIMESTAMPTZ | NO | — | Módosítás |

**Indexek (4 db):**
- `persons_pkey` — UNIQUE BTREE (id)
- `persons_id_uuid_key` — UNIQUE BTREE (id_uuid)
- `ix_identity_persons_identity_hash` — UNIQUE BTREE (identity_hash)
- `ix_identity_persons_id` — BTREE (id)

---

### 1.3 💰 `wallets` — Pénztárca
**Oszlopok (6 db):**
| Oszlop | Típus | Kötelező? | Default |
|--------|-------|-----------|---------|
| `id` | INTEGER | PK | nextval(...) |
| `user_id` | INTEGER | **YES** | — (UNIQUE, FK → users(id)) |
| `earned_credits` | NUMERIC(18,4) | **YES** | 0 |
| `purchased_credits` | NUMERIC(18,4) | **YES** | 0 |
| `service_coins` | NUMERIC(18,4) | **YES** | 0 |
| `currency` | VARCHAR(3) | **YES** | — |

**Indexek:**
- `wallets_pkey` — UNIQUE BTREE (id)
- `wallets_user_id_key` — UNIQUE BTREE (user_id)

---

### 1.4 🎫 `active_vouchers` — Aktív Voucher-ek
**Oszlopok (6 db):**
| Oszlop | Típus | Kötelező? | Default |
|--------|-------|-----------|---------|
| `id` | INTEGER | PK | nextval(...) |
| `wallet_id` | INTEGER | **YES** | — (FK → wallets(id) ON DELETE CASCADE) |
| `amount` | NUMERIC(18,4) | **YES** | — |
| `original_amount` | NUMERIC(18,4) | **YES** | — |
| `expires_at` | TIMESTAMPTZ | **YES** | — |
| `created_at` | TIMESTAMPTZ | **YES** | now() |

---

### 1.5 🤝 `social_accounts` — Közösségi Bejelentkezés
**Oszlopok (7 db):**
| Oszlop | Típus | Kötelező? | Default |
|--------|-------|-----------|---------|
| `id` | INTEGER | PK | nextval(...) |
| `user_id` | INTEGER | **YES** | — (FK → users(id) ON DELETE CASCADE) |
| `provider` | VARCHAR(50) | **YES** | — |
| `social_id` | VARCHAR(255) | **YES** | — |
| `email` | VARCHAR(255) | **YES** | — |
| `extra_data` | JSON | **YES** | '{}' |
| `created_at` | TIMESTAMPTZ | **YES** | now() |

**Unique:** `uix_social_provider_id` (provider, social_id)
**Indexek:** social_id

---

### 1.6 🏆 `user_trust_profiles` — Gondos Gazda Index
**Oszlopok (9 db):**
| Oszlop | Típus | Kötelező? | Default |
|--------|-------|-----------|---------|
| `user_id` | INTEGER | **PK+FK** | — (FK → users(id) ON DELETE CASCADE) |
| `trust_score` | INTEGER | **YES** | 0 |
| `maintenance_score` | NUMERIC(5,2) | **YES** | 0.00 |
| `quality_score` | NUMERIC(5,2) | **YES** | 0.00 |
| `preventive_score` | NUMERIC(5,2) | **YES** | 0.00 |
| `identity_score` | INTEGER | **YES** | 0 |
| `verification_level` | INTEGER | **YES** | 0 |
| `verified_channels` | JSONB | **YES** | '{}' |
| `identity_risk_flag` | BOOLEAN | **YES** | false |
| `last_calculated` | TIMESTAMPTZ | **YES** | now() |

---

### 1.7 📧 `verification_tokens` — Verifikációs Tokenek
**Oszlopok (8 db):**
| Oszlop | Típus | Kötelező? | Default |
|--------|-------|-----------|---------|
| `id` | INTEGER | PK | nextval(...) |
| `token` | UUID | **YES** | — (UNIQUE) |
| `user_id` | INTEGER | **YES** | — (FK → users(id) ON DELETE CASCADE) |
| `token_type` | VARCHAR(20) | **YES** | — |
| `extra_data` | JSON | NO | '{}' |
| `created_at` | TIMESTAMPTZ | **YES** | now() |
| `expires_at` | TIMESTAMPTZ | **YES** | — |
| `is_used` | BOOLEAN | **YES** | — |

---

### 1.8 📱 `devices` — Eszközök
**Oszlopok (4 db):**
| Oszlop | Típus | Kötelező? |
|--------|-------|-----------|
| `fingerprint_hash` | VARCHAR(255) | **PK** |
| `risk_score` | INTEGER | **YES** (default 100) |
| `is_banned` | BOOLEAN | **YES** (default false) |
| `created_at` | TIMESTAMPTZ | **YES** |

---

### 1.9 🔗 `user_device_links` — Eszköz-Felhasználó Kapcsolat
**Oszlopok (6 db):**
| Oszlop | Típus | Kötelező? | Default |
|--------|-------|-----------|---------|
| `id` | UUID | **PK** | — |
| `user_id` | INTEGER | **YES** | — (FK → users(id) ON DELETE CASCADE) |
| `device_hash` | VARCHAR(255) | **YES** | — (FK → devices(fingerprint_hash) ON DELETE CASCADE) |
| `first_seen_at` | TIMESTAMPTZ | **YES** | — |
| `last_seen_at` | TIMESTAMPTZ | NO | — |
| `login_count` | INTEGER | **YES** | 1 |

---

## 2. 🔗 KAPCSOLATOK (FOREIGN KEYS)

### 2.1 Belső Kapcsolatok (identity → identity)

```
users.person_id ─────────────► persons.id
persons.user_id ─────────────► users.id           (aktív fiók)
users.referred_by_id ────────► users.id           (MLM: ki hívta meg)
users.current_sales_agent_id ► users.id           (értékesítő)

social_accounts.user_id ─────► users.id     [CASCADE]
verification_tokens.user_id ─► users.id     [CASCADE]
user_trust_profiles.user_id ─► users.id     [CASCADE]
wallets.user_id ─────────────► users.id
user_device_links.user_id ───► users.id     [CASCADE]

wallets ◄──────────────────── active_vouchers.wallet_id  [CASCADE]
devices ◄──────────────────── user_device_links.device_hash  [CASCADE]
```

### 2.2 Külső Kapcsolatok (identity → system)

```
persons.address_id ──────────► system.addresses(id)
```

### 2.3 ORM Szintű Kapcsolatok (nincs DB FK constraint)

```
persons.merged_into_id ──────► persons(id)  -- SQLAlchemy ORM, use_alter=True
persons.user_id ─────────────► users(id)     -- SQLAlchemy ORM (fk_person_active_user), use_alter=True
```

---

## 3. 🌐 KÜLSŐ HIVATKOZÁSOK (Más sémák hivatkoznak identity táblákra)

| Séma | Tábla | Oszlop | Hivatkozott tábla |
|------|-------|--------|-------------------|
| `audit` | audit_logs | user_id | identity.users |
| `audit` | financial_ledger | user_id, person_id | identity.users, identity.persons |
| `audit` | operational_logs | user_id | identity.users |
| `finance` | withdrawal_requests | user_id | identity.users |
| `fleet` | organization_members | user_id, person_id | identity.users, identity.persons |
| `gamification` | points_ledger | user_id | identity.users |
| `gamification` | user_badges | user_id | identity.users |
| `gamification` | user_contributions | user_id | identity.users |
| `gamification` | user_scores | user_id | identity.users |
| `gamification` | user_stats | user_id | identity.users |
| `marketplace` | service_requests | user_id | identity.users |
| `marketplace` | service_reviews | user_id | identity.users |
| `marketplace` | votes | user_id | identity.users |
| `system` | internal_notifications | user_id | identity.users |
| `system` | user_scores_deprecated | user_id | identity.users |

**Összesen: 17 külső FK hivatkozás 7 különböző sémából.**

---

## 4. 🏷️ ENUM TÍPUSOK

### `identity.userrole` ENUM
| Érték | Leírás |
|-------|--------|
| `owner_old` | (régi, deprecated) |
| `ADMIN` | Rendszergazda |
| `FLEET_MANAGER` | Flottakezelő |
| `DRIVER` | Sofőr |
| `owner` | Tulajdonos |
| `admin` | Adminisztrátor |
| `user` | **Alapértelmezett** — sima felhasználó |

**Megjegyzés:** Több érték is duplikált (pl. owner/owner_old, ADMIN/admin). Valószínűleg refaktorálásra szorul, hogy csak a kívánt 9 érték maradjon meg.

---

## 5. 🗺️ KAPCSOLATI ÁBRA (ERD)

```
                    ┌──────────────────────────────────┐
                    │          identity.users           │ ◄──── social_accounts
                    │  (24 oszlop - központi entitás)  │ ◄──── verification_tokens
                    └───┬────┬────┬────┬────┬──────────┘ ◄──── user_trust_profiles
                        │    │    │    │    │            ◄──── wallets
                        │    │    │    │    │            ◄──── user_device_links
            ┌───────────┘    │    │    │    └───────────────┐
            ▼                ▼    ▼    ▼                    ▼
      ┌──────────┐   ┌───────────┐   ┌───────────────┐  ┌──────────┐
      │ persons  │   │  wallets  │   │  devices      │  │ (saját)  │
      │(22 oszl.)│   │ (6 oszl.) │   │ (4 oszlop)    │  │ referrer │
      └────┬─────┘   └─────┬─────┘   └───────┬───────┘  │ sales_ag.│
           │               │                 │          └──────────┘
           ▼               ▼                 ▼
    system.addresses  active_vouchers   user_device_links
    (GPS, cím)        (FIFO voucher)    (kapcsolótábla)
```

---

## 6. 📝 MEGJEGYZÉSEK

1. **Körkörös függőség:** A `users` és `persons` táblák között **körkörös FK** van: `users.person_id → persons(id)` és `persons.user_id → users(id)`. Ezt az ORM szinten `post_update=True` és `use_alter=True` paraméterekkel oldják fel.

2. **ORM-only FKs:** A `persons.merged_into_id` és a `persons.user_id` (második FK, `fk_person_active_user`) **csak ORM szinten** léteznek, adatbázis szintű FK constraint nélkül.

3. **JSON mezők:** 5 JSON típusú mező van a sémában, amelyek rugalmas adattárolást tesznek lehetővé: `identity_docs`, `ice_contact`, `custom_permissions`, `alternative_emails`, `email_history`, `extra_data` (social_accounts), `verified_channels`.

4. **UNIQUE megszorítások:** Összesen 7 UNIQUE constraint van, ezek közül az `identity_hash` a legkritikusabb — ez biztosítja a deduplikációt.

---

## 7. KÖVETKEZTETÉS

Az identity séma **teljes körű emberközpontú identitáskezelést** valósít meg, amely lefedi:
- ✅ Személyes adatok (Person)
- ✅ Bejelentkezési adatok (User)
- ✅ Pénzügyek (Wallet, Vouchers)
- ✅ Okmányok (identity_docs JSON)
- ✅ Közösségi kapcsolatok (Social accounts)
- ✅ Bizalmi index (Trust Profile)
- ✅ Eszközazonosítás (Devices)
- ✅ MLM/Referral rendszer (referred_by, sales_agent)
- ✅ Verifikáció (Verification tokens)