service-finder/plans/logic_spec_admin_user_person_management.md

# 🏗️ Logic Spec: Admin User & Person Management

## 📋 Metadata
- **Tervező:** Service Finder Rendszer-Architect
- **Státusz:** Draft (jóváhagyásra vár)
- **Masterbook 2 illeszkedés:** `docs/masterbook_2.0.1/User_person_kezelés.md`
- **Érintett domain:** `identity` (Person ↔ User Dual Entity)

---

## 1. 🎯 Célkitűzés

A feladat az adminisztrációs felület teljes körű felhasználókezelési rendszerének megtervezése és megvalósítása, amely kiterjed mind a **Person** (természetes személy), mind a **User** (bejelentkezési entitás) entitásokra. Jelenleg a frontend admin felületen **egyetlen user/person kezelő oldal sem létezik**, a meglévő backend végpontok részlegesek.

### Célok:
1. Admin felhasználói lista oldal létrehozása kereséssel, szűréssel, rendezéssel
2. Felhasználói részletek oldal létrehozása (User + Person adatok egy nézetben)
3. Felhasználók szerkesztése (admin által)
4. Person entitások kezelése (listázás, részletek, merge)
5. Statisztikai adatok megjelenítése (összesítő kártyák, trendek)
6. Szervezeti tagságok áttekintése

---

## 2. 📊 Meglévő Rendszer Állapota

### 2.1 Backend API Végpontok Jelenlegi Állapota

| Végpont | Metódus | Létezik? | Leírás |
|---------|---------|----------|--------|
| `/admin/users` | GET | ✅ Teljes | Listázás, keresés, szűrés, lapozás. Outerjoin User→Person→Address→GeoPostalCode |
| `/admin/users/{user_id}/ban` | POST | ✅ Teljes | Kitiltás audit loggal |
| `/admin/users/{user_id}/penalty` | PATCH | ✅ Teljes | Gamification büntetés |
| `/admin/users/bulk-action` | POST | ✅ Teljes | Tömeges műveletek (ban/unban/soft_delete/restore/hard_delete) |
| `/admin/users/{user_id}` | GET | ❌ Hiányzik | Felhasználó részletes adatai |
| `/admin/users/{user_id}` | PATCH | ❌ Hiányzik | Felhasználó szerkesztése admin által |
| `/admin/users/stats` | GET | ❌ Hiányzik | Felhasználói statisztikák |
| `/admin/persons` | GET | ❌ Hiányzik | Person lista |
| `/admin/persons/{person_id}` | GET | ❌ Hiányzik | Person részletek |
| `/admin/persons/{person_id}` | PATCH | ❌ Hiányzik | Person szerkesztése |
| `/admin/persons/{person_id}/merge` | POST | ❌ Hiányzik | Person merge (duplum kezelés) |
| `/admin/users/{user_id}/memberships` | GET | ❌ Hiányzik | Szervezeti tagságok listája |

### 2.2 Frontend Admin Oldalak Jelenlegi Állapota

| Oldal | Létezik? | Megjegyzés |
|-------|----------|------------|
| `/` (Dashboard) | ✅ | Hardcoded statisztikák |
| `/login` | ✅ | Bejelentkezés |
| `/garages` | ✅ | Garázs lista + részletek |
| `/packages` | ✅ | Csomagkezelés |
| `/permissions` | ✅ | RBAC jogosultsági mátrix |
| `/users` | ❌ | **Hiányzik** |
| `/users/[id]` | ❌ | **Hiányzik** |
| `/persons` | ❌ | **Hiányzik** |
| `/persons/[id]` | ❌ | **Hiányzik** |

---

## 3. 🧠 Dual Entity Adatmodell (Person ↔ User)

### 3.1 Person (természetes személy)

| Mező | Típus | Leírás |
|------|-------|--------|
| `id` | int (PK) | Elsődleges kulcs |
| `id_uuid` | UUID | Külső azonosító |
| `identity_hash` | str | Egyedi hash duplum detektáláshoz |
| `last_name` | str | Vezetéknév |
| `first_name` | str | Keresztnév |
| `phone` | Optional[str] | Telefonszám |
| `mothers_last_name` | Optional[str] | Anyja születési vezetékneve |
| `mothers_first_name` | Optional[str] | Anyja születési keresztneve |
| `birth_place` | Optional[str] | Születési hely |
| `birth_date` | Optional[date] | Születési dátum |
| `identity_docs` | Optional[JSON] | Személyi igazolvány/útlevél adatok |
| `ice_contact` | Optional[JSON] | Emergency contact |
| `is_active` | bool | Aktív-e |
| `is_ghost` | bool | Részleges adatú személy |
| `merged_into_id` | Optional[int] | FK -> persons.id (soft merge) |
| `deleted_at` | Optional[datetime] | Soft delete timestamp |

**Relációk:** `users` (1:N User), `active_user_account` (User), `address` (Address), `memberships` (OrganizationMember), `owned_business_entities` (Organization)

### 3.2 User (bejelentkezési entitás)

| Mező | Típus | Leírás |
|------|-------|--------|
| `id` | int (PK) | Elsődleges kulcs |
| `email` | str (unique) | Email cím |
| `hashed_password` | str | Jelszó hash |
| `role_id` | Optional[int] | FK -> system.roles.id (RBAC) |
| `role` | UserRole enum | SUPERADMIN, ADMIN, MODERATOR, SALES_REP, SERVICE_MGR, USER |
| `person_id` | Optional[int] | FK -> identity.persons.id |
| `subscription_plan` | Optional[str] | Előfizetési csomag |
| `subscription_expires_at` | Optional[datetime] | Előfizetés lejárata |
| `is_vip` | bool | VIP státusz |
| `referral_code` | Optional[str] (unique) | MLM referral kód |
| `referred_by_id` | Optional[int] | FK -> identity.users.id (self-ref) |
| `is_active` | bool | Aktív-e |
| `is_deleted` | bool | Törölt-e |
| `deleted_at` | Optional[datetime] | Törlés időpontja |
| `preferred_language` | str | Nyelv (default: "hu") |
| `region_code` | Optional[str] | Régió kód |
| `preferred_currency` | Optional[str] | Pénznem |
| `scope_level` | Optional[str] | global/country/region/organization |
| `scope_id` | Optional[int] | Scope azonosító |
| `custom_permissions` | Optional[JSON] | Egyedi jogosultságok |
| `alternative_emails` | Optional[JSON] | Alternatív emailek |
| `ui_mode` | str | light/dark (default: "light") |
| `visual_settings` | Optional[JSON] | UI beállítások |
| `active_organization_id` | Optional[int] | Aktív szervezet |
| `max_vehicles` | int | Jármű limit |
| `max_garages` | int | Garázs limit |

**Relációk:** `person` (Person), `system_role` (SystemRole), `referrer` (User self-ref), `wallet` (Wallet), `trust_profile` (UserTrustProfile), `social_accounts` (SocialAccount), `owned_organizations` (Organization), `memberships` (OrganizationMember)

### 3.3 OrganizationMember (tagsági kapcsolat)

| Mező | Típus | Leírás |
|------|-------|--------|
| `organization_id` | int (FK) | -> fleet.organizations.id |
| `user_id` | int (FK) | -> identity.users.id |
| `person_id` | int (FK) | -> identity.persons.id |
| `invited_email` | Optional[str] | Meghívott email |
| `expires_at` | Optional[datetime] | Tagság lejárata |
| `role` | str (OrgUserRole) | owner/admin/member |
| `permissions` | JSONB | Egyedi org jogosultságok |
| `status` | str | active/pending/inactive |
| `is_permanent` | bool | Állandó tagság |
| `is_verified` | bool | Ellenőrzött tagság |

### 3.4 Kapcsolatok Diagram

```mermaid
erDiagram
    Person ||--o{ User : "1:N"
    Person ||--o| Address : "lakcim"
    Person ||--o{ OrganizationMember : "tagsagok"
    Person ||--o{ Organization : "tulajdonolt cegek"
    Person ||--o| Person : "merged_into (soft merge)"

    User ||--o| Person : "tartozik"
    User ||--o{ OrganizationMember : "tagsagok"
    User ||--o{ Organization : "tulajdonolt szervezetek"
    User ||--o| User : "referred_by (MLM)"
    User ||--o| SystemRole : "RBAC role"
    User ||--o| Wallet : "penztarca"
    User ||--o| UserTrustProfile : "trust score"

    OrganizationMember }o--|| Organization : "tagja"
```

---

## 4. 🔧 Új Backend API Végpontok Specifikációja

### 4.1 `GET /admin/users/{user_id}` — Felhasználó Részletek

**Cél:** Egy felhasználó összes adatának lekérése, beleértve Person, Address, Wallet, TrustProfile, OrganizationMembership adatokat.

**SQL logika:**
```sql
SELECT u.*, p.*, a.*, w.*, tp.*, om.*
FROM identity.users u
LEFT JOIN identity.persons p ON p.id = u.person_id
LEFT JOIN identity.addresses a ON a.id = p.address_id
LEFT JOIN identity.wallets w ON w.user_id = u.id
LEFT JOIN identity.user_trust_profiles tp ON tp.user_id = u.id
LEFT JOIN marketplace.organization_members om ON om.user_id = u.id
WHERE u.id = :user_id
```

**Válasz struktúra:**
```json
{
  "id": 1,
  "email": "user@example.com",
  "role_id": 2,
  "role": "admin",
  "is_active": true,
  "is_deleted": false,
  "is_vip": false,
  "preferred_language": "hu",
  "region_code": "HU",
  "preferred_currency": "HUF",
  "subscription_plan": "premium",
  "subscription_expires_at": "2026-12-31T23:59:59",
  "max_vehicles": 10,
  "max_garages": 5,
  "active_organization_id": 3,
  "scope_level": "organization",
  "scope_id": 3,
  "created_at": "2026-01-15T08:30:00",
  "updated_at": "2026-06-28T14:22:00",
  "person": { "id": 1, "last_name": "Nagy", "first_name": "Istvan", ... },
  "wallet": { "balance": 15000, ... },
  "trust_profile": { "trust_score": 85, ... },
  "memberships": [ { "organization_id": 3, "role": "owner", ... } ],
  "system_capabilities": [...],
  "org_capabilities": [...]
}
```

### 4.2 `PATCH /admin/users/{user_id}` — Felhasználó Szerkesztése

**Admin által szerkeszthető mezők:**
- `email` (csak admin/superadmin)
- `is_active` (letiltás/feloldás)
- `is_vip`
- `preferred_language`, `region_code`, `preferred_currency`
- `subscription_plan`, `subscription_expires_at`
- `max_vehicles`, `max_garages`
- `scope_level`, `scope_id`
- `role_id` (csak superadmin)
- `custom_permissions`

**Person almzők (opcionális):**
- `person.last_name`, `person.first_name`, `person.phone`
- `person.mothers_last_name`, `person.mothers_first_name`
- `person.birth_place`, `person.birth_date`
- `person.identity_docs`

### 4.3 `GET /admin/users/stats` — Felhasználói Statisztikák

```json
{
  "total_users": 2847,
  "active_users": 2100,
  "deleted_users": 120,
  "banned_users": 45,
  "new_users_today": 12,
  "new_users_this_week": 85,
  "new_users_this_month": 320,
  "users_by_role": {
    "superadmin": 2, "admin": 15, "moderator": 8,
    "sales_rep": 23, "service_mgr": 45, "user": 2754
  },
  "users_by_plan": {
    "free": 1500, "basic": 800, "premium": 400, "enterprise": 147
  },
  "users_by_language": { "hu": 2200, "en": 400, "de": 150, "ro": 97 },
  "users_with_person": 2600,
  "users_without_person": 247,
  "registration_trend": [
    { "date": "2026-06-01", "count": 15 },
    { "date": "2026-06-02", "count": 12 }
  ],
  "active_organizations_count": 420,
  "total_memberships": 1800
}
```

### 4.4 `GET /admin/persons` — Person Lista

**Paraméterek:** `search`, `is_ghost`, `is_active`, `has_user`, `is_merged`, `skip`, `limit`

**Válasz:**
```json
{
  "total": 3000,
  "items": [
    {
      "id": 1, "last_name": "Nagy", "first_name": "Istvan",
      "phone": "+36201234567", "birth_date": "1985-03-15",
      "is_ghost": false, "is_active": true, "merged_into_id": null,
      "users_count": 1,
      "active_user": { "id": 1, "email": "user@example.com", "role": "user" },
      "address": { "address_city": "Budapest", "address_zip": "1011" }
    }
  ]
}
```

### 4.5 `GET /admin/persons/{person_id}` — Person Részletek

Teljes Person adatlap kapcsolódó User-ekkel, szervezeti tagságokkal, tulajdonolt cégekkel, merge history-val.

### 4.6 `PATCH /admin/persons/{person_id}` — Person Szerkesztése

Person adatok admin általi módosítása (last_name, first_name, phone, birth data, address, identity_docs, is_active, is_ghost).

### 4.7 `POST /admin/persons/{person_id}/merge` — Person Merge

**Body:**
```json
{ "source_person_id": 42, "keep_source_user": false }
```

**Logika:**
1. Ellenorizze, hogy mindket Person letezik es nincs mar merge-elve
2. Forras Person `merged_into_id` -> cel Person ID
3. Forras User-ek `person_id` -> cel Person ID
4. Forras OrganizationMember `person_id` -> cel Person ID
5. Audit log bejegyzes

### 4.8 `GET /admin/users/{user_id}/memberships` — Szervezeti Tagsagok

Egy felhasznalo szervezeti tagsagainak listazasa.

---

## 5. 🖼️ Frontend Admin UI Specifikacio

### 5.1 Oldalak Terkepe

```
frontend_admin/pages/
  users/
    index.vue         -> Felhasznaloi lista (GET /admin/users)
    [id]/index.vue    -> Felhasznalo reszletek (GET /admin/users/{id})
  persons/
    index.vue         -> Person lista (GET /admin/persons)
    [id]/index.vue    -> Person reszletek (GET /admin/persons/{id})
```

### 5.2 `users/index.vue` — Felhasznaloi Lista Oldal

**Elrendezes:**
- Header: "Felhasznalok" cim
- **Statisztikai kartyak sor:** Osszes, Aktiv, Torolt, Kitiltott, Mai regisztraciok
- **Keresomezo:** Email, nev, telefonszam
- **Szurolok:** Statusz (active/deleted/banned/all), Szerepkor (role), Elofizetes
- **Tablazat:** ID, Email, Nev (Person), Szerepkor, Statusz (szines jelolo), Elofizetes, Regisztracio datuma, Nyelv, Muveletek
- **Tomeges muveletek checkbox-szal:** Kitiltas, Feloldas, Torles, Visszaallitas

### 5.3 `users/[id]/index.vue` — Felhasznalo Reszlet Oldal

**Tab-ok:**
1. **Attekintes (Overview)** — Alapadatok, statusz, szerepkor
2. **Szemelyes adatok (Person)** — Person adatok, lakcim
3. **Penzingyek (Finance)** — Wallet, elofizetes
4. **Tagsagok (Memberships)** — Szervezeti tagsagok
5. **Bizalom (Trust)** — Trust score, gamification
6. **Tevekenyseg (Activity)** — Naplozott tevekenysegek

### 5.4 `persons/index.vue` — Person Lista Oldal

- Kereso: Nev, telefonszam, szuletesi adatok
- Szurok: Ghost statusz, Aktiv/Inaktiv, Van-e User, Merge statusz
- Tablazat: ID, Nev, Telefon, Szuletesi datum, Userek szama, Aktiv email, Statusz

### 5.5 `persons/[id]/index.vue` — Person Reszlet Oldal

- Szemely adatok
- Kapcsolodo User-ek
- Cim adatok
- Szervezeti tagsagok
- Merge informacio (forras/cel)
- Tulajdonolt cegek

### 5.6 Navigacios Frissites

Oldalsav uj bejegyzesek:
```
  Felhasznalok       -> /users
    Felhasznalok     -> /users/
    Szemelyek        -> /persons/
```

### 5.7 i18n Kovetelmenyek

Uj fordítási kulcsok (`hu.json` / `en.json`):
- `users.title`, `users.search_placeholder`, `users.filter_role`
- `users.status.active`, `users.status.deleted`, `users.status.banned`
- `users.table.id`, `users.table.email`, `users.table.name`, `users.table.role`, `users.table.status`
- `users.bulk.ban`, `users.bulk.unban`, `users.bulk.delete`, `users.bulk.restore`
- `persons.title`, `persons.search_placeholder`
- `person.merge.title`, `person.merge.confirm`, `person.merge.source`, `person.merge.target`
- `stats.total_users`, `stats.active_users`, `stats.new_today`

### 5.8 Permission Check (RBAC)

Minden admin user/person oldalnak ellenoriznie kell:
- `users:view` — Felhasznalok listazasa
- `users:edit` — Felhasznalok szerkesztese
- `users:ban` — Kitiltas
- `users:delete` — Torles
- `persons:view` — Person lista
- `persons:edit` — Person szerkesztes
- `persons:merge` — Person merge

Hasznald a meglévo `admin_permissions.py` rendszert es a `RequirePermission()` fuggoseget.

---

## 6. 📦 EPIC Bontas (3A Granularitas)

### 6.1 EPIC-1: Backend — User Management Vegpontok

| # | Task | Scope | Type | Fuggoseg |
|---|------|-------|------|-----------|
| 1.1 | `GET /admin/users/{user_id}` endpoint | Backend | Feature | - |
| 1.2 | `PATCH /admin/users/{user_id}` endpoint | Backend | Feature | 1.1 |
| 1.3 | `GET /admin/users/stats` endpoint | Backend | Feature | - |
| 1.4 | `GET /admin/users/{user_id}/memberships` | Backend | Feature | 1.1 |

### 6.2 EPIC-2: Backend — Person Management Vegpontok

| # | Task | Scope | Type | Fuggoseg |
|---|------|-------|------|-----------|
| 2.1 | `GET /admin/persons` endpoint | Backend | Feature | - |
| 2.2 | `GET /admin/persons/{person_id}` endpoint | Backend | Feature | 2.1 |
| 2.3 | `PATCH /admin/persons/{person_id}` endpoint | Backend | Feature | 2.2 |
| 2.4 | `POST /admin/persons/{person_id}/merge` | Backend | Feature | 2.2 |

### 6.3 EPIC-3: Frontend — User List & Detail Oldalak

| # | Task | Scope | Type | Fuggoseg |
|---|------|-------|------|-----------|
| 3.1 | `users/index.vue` — Felhasznaloi lista | Frontend | Feature | 1.x |
| 3.2 | `users/[id]/index.vue` — Reszlet oldal | Frontend | Feature | 1.1, 3.1 |
| 3.3 | Navigacios menu frissitese | Frontend | Feature | 3.1 |

### 6.4 EPIC-4: Frontend — Person List & Detail Oldalak

| # | Task | Scope | Type | Fuggoseg |
|---|------|-------|------|-----------|
| 4.1 | `persons/index.vue` — Person lista | Frontend | Feature | 2.x |
| 4.2 | `persons/[id]/index.vue` — Reszlet oldal | Frontend | Feature | 2.2, 4.1 |

### 6.5 EPIC-5: Frontend — Statisztikak & Dashboard

| # | Task | Scope | Type | Fuggoseg |
|---|------|-------|------|-----------|
| 5.1 | Dashboard statisztika kartyak dinamikus adatokkal | Frontend | Feature | 1.3 |
| 5.2 | Felhasznaloi trend diagram komponens | Frontend | Feature | 1.3 |

### 6.6 EPIC-6: i18n & Permission Integration

| # | Task | Scope | Type | Fuggoseg |
|---|------|-------|------|-----------|
| 6.1 | i18n forditasok felvetele (hu/en) | Frontend | Feature | 3.x, 4.x |
| 6.2 | RBAC permission check implementacio | Frontend | Feature | 3.x, 4.x |

---

## 7. 📐 Megvalosítási Terv (Phasing)

### Phase 0 (P0) — Alap Felhasznaloi Muv-eletek
- **Backend:** EPIC-1 (1.1, 1.2, 1.3) — User reszletek, szerkesztes, statisztikak
- **Frontend:** EPIC-3 (3.1) — User lista oldal
- **Indoklas:** A legalapvetobb admin funkcio

### Phase 1 (P1) — Person Management & Tagsagok
- **Backend:** EPIC-1 (1.4), EPIC-2 (2.1, 2.2, 2.3) — Person vegpontok
- **Frontend:** EPIC-3 (3.2), EPIC-4 (4.1) — User reszlet + Person lista

### Phase 2 (P2) — Halado Funkciok
- **Backend:** EPIC-2 (2.4) — Person merge
- **Frontend:** EPIC-4 (4.2), EPIC-5, EPIC-6

---

## 8. ✅ Jovahagyasi Pont

**A terv felulvizsgalatra es jovahagyasra var.**

Kerdesek:
1. **Prioritas:** A Phase 0 -> Phase 1 -> Phase 2 sorrend megfelelo?
2. **Hianyzo funkcio:** Van olyan admin funkcio a user/person kezelesben, ami kimaradt?
3. **Adatbiztonsag:** A szerkesztheto mezo-k listaja (Section 4.2) megfelelo?
4. **Megerosites:** Ha a terv rendben van, kerem a jovahagyast a megvalositas megkezdesehez.

---

## 9. 🔗 Kapcsolodo Fajlok

| Fajl | Leiras |
|------|--------|
| `backend/app/models/identity/identity.py` | Person, User modellek |
| `backend/app/models/marketplace/organization.py` | OrganizationMember modell |
| `backend/app/schemas/user.py` | User/Person Pydantic semak |
| `backend/app/api/v1/endpoints/admin.py` | Meglevo admin vegpontok (list_users, bulk_action) |
| `backend/app/api/v1/endpoints/admin_permissions.py` | RBAC permission management |
| `frontend_admin/pages/index.vue` | Dashboard (statisztikak frissitendok) |
| `frontend_admin/nuxt.config.ts` | Nuxt konfig (i18n, proxy) |
| `docs/masterbook_2.0.1/User_person_kezeles.md` | Masterbook dokumentacio |