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

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:

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:

{
  "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

{
  "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:

{
  "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:

{ "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