feat: v1.7 overhaul - identity hash, triple wallet, financial ledger, and security audit system
This commit is contained in:
@@ -132,4 +132,35 @@ A technikai belépési pont.
|
||||
A rendszer támogatja a "Ghost Person" (Árnyék személy) entitásokat.
|
||||
- **Ghost Person:** Olyan `data.persons` rekord, amelyet a Robot 2 hozott létre nyilvános adatok (pl. cégjegyzék) alapján.
|
||||
- **Identity Linkage:** Regisztrációkor a `AuthService.complete_kyc` kötelezően ellenőrzi a meglévő Ghost rekordokat (Adószám/Név egyezés).
|
||||
- **Merge Action:** Találat esetén a rendszer összefűzi a technikai User fiókot a Ghost Person rekorddal, aktiválja a jogosultságokat, és megszünteti a Ghost státuszt.
|
||||
- **Merge Action:** Találat esetén a rendszer összefűzi a technikai User fiókot a Ghost Person rekorddal, aktiválja a jogosultságokat, és megszünteti a Ghost státuszt.
|
||||
|
||||
## 2. The Dual Entity Model (Person vs. User)
|
||||
|
||||
A rendszer alapja a természetes személy (**Person**) és a felhasználói fiók (**User**) szigorú szétválasztása az adatbiztonság és az üzleti folytonosság érdekében.
|
||||
|
||||
### 2.1 Person (A DNS - "Az Örök Személy")
|
||||
A `persons` tábla rekordja soha nem törlődik teljesen (GDPR esetén anonimizálódik), így biztosítva a rendszer memóriáját.
|
||||
* **Identity Hash:** Egyedi SHA256 lenyomat (`normalized(name + mother + birth_place + birth_date)`), amely megakadályozza a multi-account visszaéléseket és felismeri a visszatérő felhasználókat.
|
||||
* **Örök Adatok:**
|
||||
* `lifetime_xp`: A valaha szerzett összes tapasztalati pont.
|
||||
* `penalty_points`: A büntetési szint (0-3). Ez nem nullázódik új regisztrációval!
|
||||
* `social_reputation`: A közösségi megbízhatósági index (1.00 = 100%).
|
||||
* `is_sales_agent`: Jogosult-e jutalékra.
|
||||
|
||||
### 2.2 User (A Kulcs - "A Munkamenet")
|
||||
A `users` tábla a belépési pont. Törölhető, eldobható, újraregisztrálható.
|
||||
* **Kapcsolat:** Minden User egyetlen Person-höz tartozik (`person_id`).
|
||||
* **Időkorlátos Jogok:**
|
||||
* `subscription_plan`: FREE / PREMIUM / VIP.
|
||||
* `subscription_expires_at`: A prémium funkciók lejárata.
|
||||
* **Sales Kapcsolat:**
|
||||
* `referral_code`: Saját meghívó kód.
|
||||
* `current_sales_agent_id`: Ki kapja a "Farming" jutalékot ez után a felhasználó után.
|
||||
|
||||
### 2.3 Jogosultsági Szintek (Scope-Based RBAC)
|
||||
A jogosultság nem csak szerepkör (Role), hanem hatókör (Scope) alapú:
|
||||
1. **Global:** Superadmin.
|
||||
2. **Country:** Országos Admin (pl. HU).
|
||||
3. **Region:** Régiós Admin (pl. Pest megye).
|
||||
4. **Entity:** Szerviz Tulajdonos (saját cég).
|
||||
5. **Individual:** Átlagfelhasználó (saját adatok).
|
||||
@@ -201,4 +201,13 @@ A rendszer az adatintegritás és a sebesség érdekében hibrid modellt haszná
|
||||
## 2.4 Financial & Enrichment Tables
|
||||
- **data.organization_financials:** Éves gazdasági adatok (árbevétel, profit, létszám) tárolása historikus elemzéshez.
|
||||
- **data.service_profiles.specialization_tags:** JSONB mező a szigorú szakmai szűréshez (pl. márkák, specifikus javítási típusok).
|
||||
- **data.service_profiles.google_place_id:** Külső validációs kulcs a Google Places API-hoz.
|
||||
- **data.service_profiles.google_place_id:** Külső validációs kulcs a Google Places API-hoz.
|
||||
|
||||
|
||||
### Identity & Economy Module (v1.6+)
|
||||
* **`data.persons`**: Természetes személyek, Identity Hash, Örök XP/Büntetés.
|
||||
* **`data.users`**: Login fiókok, Előfizetési idő, Sales kapcsolatok.
|
||||
* **`data.wallets`**: 3-as osztású egyenleg (`earned`, `purchased`, `coins`).
|
||||
* **`data.financial_ledger`**: Pénzügyi tranzakciók főkönyve.
|
||||
* **`data.security_audit_logs`**: Biztonsági események és 4-szem jóváhagyások.
|
||||
* **`data.org_sales_assignments`**: Cég-Üzletkötő kapcsolat (Farming jog).
|
||||
@@ -113,4 +113,24 @@ A meghívók érvényessége a típustól függ:
|
||||
|
||||
### 5.3 Biztonság
|
||||
* A meghívó link tartalmaz egy aláírt JWT tokent, amely rögzíti a `target_org_id`-t (melyik flottába hívjuk) és a `role`-t (pl. sofőr).
|
||||
* A kód felhasználása után a link érvénytelenné válik (One-time use).
|
||||
* A kód felhasználása után a link érvénytelenné válik (One-time use).
|
||||
|
||||
## 1. Háromlépcsős Onboarding (v1.5)
|
||||
|
||||
### 1.1 Step 1: Lite Registration
|
||||
- Technikai `User` létrehozása (inaktív). Email ellenőrzés indítása.
|
||||
|
||||
### 1.2 Step 2: Individual Setup (Privát Identitás)
|
||||
- **Cél:** A természetes személy (`Person`) és privát szférájának rögzítése.
|
||||
- **Művelet:** - `Person` rögzítése/frissítése.
|
||||
- Privát `Organization` létrehozása (`org_type='individual'`, `is_ownership_transferable=False`).
|
||||
- **Központi Telephely (Main Branch)** létrehozása a lakcím alapján.
|
||||
- Privát Flotta és Wallet inicializálása.
|
||||
|
||||
### 1.3 Step 3: Business Setup (Céges Identitás)
|
||||
- **Cél:** Államilag nyilvántartott gazdasági egység rögzítése.
|
||||
- **Művelet:**
|
||||
- Adószám bekérése + VIES/Cégjegyzék ellenőrzés.
|
||||
- Új, különálló `Organization` létrehozása (`org_type='business'`, `is_ownership_transferable=True`).
|
||||
- Székhely rögzítése mint **Main Branch**.
|
||||
- Opcionális további telephelyek rögzítése.
|
||||
@@ -110,4 +110,31 @@ A rendszer támogatja a dinamikus árazást a kozmetikai elemeknél is.
|
||||
4. **Equip:** Opcionálisan azonnali beállítás (pl. profilkép keret).
|
||||
|
||||
### 5.3 Bővíthetőség
|
||||
Új elem hozzáadásához **nem kell kódot módosítani**, csak a `shop_catalog` JSON-t kell frissíteni az Admin felületen. A kliens alkalmazás (App/Web) dinamikusan tölti be a kínálatot ebből a JSON-ből.
|
||||
Új elem hozzáadásához **nem kell kódot módosítani**, csak a `shop_catalog` JSON-t kell frissíteni az Admin felületen. A kliens alkalmazás (App/Web) dinamikusan tölti be a kínálatot ebből a JSON-ből.
|
||||
|
||||
## 3. The Triple Wallet System (3-as Pénztárca)
|
||||
|
||||
A `wallets` tábla három elkülönített alszámlát kezel a transzparencia érdekében:
|
||||
|
||||
| Alszámla | Kód | Forrás | Felhasználás | Átváltható? |
|
||||
| :--- | :--- | :--- | :--- | :--- |
|
||||
| **Earned Credits** | `earned_credits` | Munka (validálás), Referral, Jutalék | Prémium funkciók, Szolgáltatás vásárlás | IGEN |
|
||||
| **Purchased Credits** | `purchased_credits` | Bankkártyás feltöltés (Stripe) | Prémium funkciók, Szolgáltatás vásárlás | IGEN |
|
||||
| **Service Coins** | `service_coins` | B2B Csomagok, Partneri jóváírás | **Kizárólag** Hirdetés, Kiemelés, Szponzoráció | **NEM** |
|
||||
|
||||
## 4. Sales Commission Model (Hunting & Farming)
|
||||
|
||||
Az üzletkötők ösztönzése két fázisban történik:
|
||||
|
||||
### 4.1 Hunting (Vadász) Jutalék
|
||||
* **Esemény:** Új fizető ügyfél behozatala (első tranzakció).
|
||||
* **Mérték:** 10% (Alapértelmezett `system_parameter`).
|
||||
* **Jóváírás:** Azonnal, `earned_credits` formájában.
|
||||
|
||||
### 4.2 Farming (Gazda) Jutalék
|
||||
* **Esemény:** Meglévő ügyfél havidíj megújítása.
|
||||
* **Mérték:** 5% (Alapértelmezett `system_parameter`).
|
||||
* **Átruházhatóság:** A jutalékot nem a User, hanem az `OrganizationSalesAssignment` tábla aktív rekordja határozza meg. Ha az üzletkötő kilép, a portfóliója (és a Farming joga) átruházható egy másik ügynökre.
|
||||
|
||||
### 4.3 Financial Ledger (Pénzügyi Napló)
|
||||
Minden tranzakció (Vásárlás, Jutalék jóváírás, Költés) bekerül a `financial_ledger` táblába, amely megmásíthatatlan (Append-only) és tartalmazza a `related_agent_id`-t a visszakövethetőségért.
|
||||
@@ -365,4 +365,120 @@ A rendszer most már képes egyetlen KYC folyamat alatt aktiválni a felhasznál
|
||||
|
||||
### 🔜 Következő Lépések
|
||||
- Gamification és Moderátori felület (Admin UI) tervezése az adatok tisztítására.
|
||||
- Logikai szabályrendszer (Business Rules) véglegesítése a "Robot vs. Ember" adatkonfliktusokra.
|
||||
- Logikai szabályrendszer (Business Rules) véglegesítése a "Robot vs. Ember" adatkonfliktusokra.
|
||||
|
||||
|
||||
# Changelog - Service Finder Project
|
||||
**Dátum:** 2026-02-15
|
||||
**Verzió:** Backend v1.9.8 / Robot v1.0.7 (Deep Hunter)
|
||||
**Fókusz:** Adatbázis séma bővítése, RDW API integráció stabilizálása, Multi-vehicle támogatás.
|
||||
|
||||
## 🏛️ Adatbázis és Architektúra (Alembic & SQLAlchemy)
|
||||
### Hozzáadva
|
||||
- **Új Migráció (`enrich_catalog_technical_schema`):**
|
||||
- `power_kw` (Integer, Indexed): Teljesítmény tárolása.
|
||||
- `engine_capacity` (Integer, Indexed): Hengerűrtartalom (ccm).
|
||||
- `max_weight_kg` (Integer): Megengedett legnagyobb össztömeg.
|
||||
- `euro_class` (String): Környezetvédelmi besorolás.
|
||||
- **Új Migráció (`add_axles_and_body_type`):**
|
||||
- `axle_count` (Integer): Tengelyek száma (Teherautókhoz/Kamionokhoz).
|
||||
- `body_type` (String): Felépítmény (pl. Sedan, Box, Camper).
|
||||
- **Modell Frissítés (`asset.py`):**
|
||||
- Az `AssetCatalog` osztály szinkronba hozva az új DB sémával.
|
||||
- `UniqueConstraint` és indexek optimalizálása a gyors kereséshez.
|
||||
|
||||
### Javítva
|
||||
- **Alembic Syntax Error:** Javítva a `ddef` elírás a migrációs fájlban.
|
||||
- **Column Duplication:** Javítva az `axle_count` duplikált létrehozási kísérlete a második migrációban.
|
||||
|
||||
## 🤖 Robot / Worker (Data Ingestion)
|
||||
### Módosítva
|
||||
- **Robot Upgrade (v1.0.2 -> v1.0.7 Deep Hunter):**
|
||||
- **License Plate Bridge (Rendszám-híd):** Új stratégia az API 400-as hibák megkerülésére. A robot mostantól:
|
||||
1. Lekéri az alapadatokat (`m9d7-ebf2`).
|
||||
2. Kivesz egy minta rendszámot.
|
||||
3. Ezzel a rendszámmal lekérdezi a `FUEL`, `AXLE` és `BODY` táblákat.
|
||||
- **Pagination (Lapozás):** `$offset` támogatás beépítése, így a robot képes 50.000+ rekordos márkákat is végigolvasni.
|
||||
- **Camper Detection:** Automatikus lakóautó (`camper`) kategória felismerés a "kampeerwagen" kulcsszó alapján.
|
||||
- **Category Mapping:** Angol nyelvű kategóriák (Car, Truck, Motorcycle, Agricultural) kényszerítése.
|
||||
|
||||
### Javítva
|
||||
- **RDW API 400 Bad Request:** Megoldva a `merk` vs `merknaam` paraméterek eltérésének kezelésével (átállás a fő táblára).
|
||||
- **AttributeError:** Javítva a hibás `TECH_API_URL` hivatkozás.
|
||||
|
||||
## 💾 Adat (Seeding & SQL)
|
||||
- **Grand Seeder v2:**
|
||||
- SQL szkript létrehozva a világmárkák (Toyota, BMW, Scania, John Deere, stb.) tömeges betöltésére.
|
||||
- `model` mező feltöltése `'ALL'` értékkel a `NOT NULL` kényszer miatt.
|
||||
- Státuszok visszaállítása `pending`-re a teljes újradolgozáshoz.
|
||||
|
||||
# CHANGELOG - 2026.02.16 (Architectural Overhaul: Identity & Economy Engine)
|
||||
|
||||
## 🏆 Napi Összefoglaló
|
||||
A mai napon alapjaiban strukturáltuk át az identitáskezelést (`Identity`), a jogosultsági rendszert (`RBAC`) és a gazdasági motort (`Economy`). Bevezetésre került a "Dual Entity" modell (Person vs. User), a 3-szintű Wallet rendszer, valamint a "Hunting & Farming" üzletkötői jutalékrendszer alapjai. A biztonságot a 4-szem elvű (Four-Eyes Principle) audit naplózás garantálja.
|
||||
|
||||
---
|
||||
|
||||
## 🏛️ 1. Architektúra és Logika (Master Book Updates)
|
||||
|
||||
### A. Identitás Filozófiája (The Dual Entity Rule)
|
||||
* **Person (A DNS):** A természetes személy, aki "örök". Nem törlődik GDPR törléskor sem, csak anonimizálódik.
|
||||
* Tárolja: `lifetime_xp` (életút pontok), `penalty_points` (büntetések 0-3 szint), `social_reputation`.
|
||||
* **Identity Hash:** Egyedi SHA256 lenyomat (Kisbetűsített Anyja neve + Születési hely + Idő) a duplikációk és visszaélések ellen.
|
||||
* **User (A Kulcs):** A belépési fiók. Bármikor törölhető/eldobható.
|
||||
* Kapcsolódik a Person-höz.
|
||||
* Tárolja: `subscription_plan`, `is_vip`, `session_data`.
|
||||
|
||||
### B. Gazdasági Modell (The Triple Wallet)
|
||||
A pénztárcát (`Wallet`) három, szigorúan elkülönített alszámlára bontottuk:
|
||||
1. **Earned Credits:** Munkával (validálás) és Referral jutalékból szerzett. (Beváltható Prémiumra).
|
||||
2. **Purchased Credits:** Valódi pénzért vásárolt egyenleg. (Beváltható Prémiumra).
|
||||
3. **Service Coins:** B2B egység. Kizárólag hirdetésre és kiemelésre fordítható. (NEM váltható Prémiumra).
|
||||
|
||||
### C. Üzletkötői Rendszer (Hunting & Farming)
|
||||
* **Hunting (Vadász) Jutalék:** Egyszeri jutalék az első behozatalért (tervezett: 10%).
|
||||
* **Farming (Gazda) Jutalék:** Folyamatos jutalék a havidíjakból (tervezett: 5%).
|
||||
* **Átruházhatóság:** A Farming jog nem az üzletkötőhöz, hanem a Cég-Üzletkötő kapcsolathoz (`OrganizationSalesAssignment`) kötődik. Ha az üzletkötő kilép, a portfóliója (és a jutalék) átruházható másra.
|
||||
|
||||
### D. Biztonság (Audit & 4-Eyes)
|
||||
* **Operational Log:** Napi üzemi események (pl. jármű rögzítés).
|
||||
* **Financial Ledger:** Minden pénzmozgás (Kredit/Coin/HUF) központi főkönyve.
|
||||
* **Security Audit Log:** Kiemelt biztonsági események (pl. VIP státusz adása).
|
||||
* **4-szem elv:** Kritikusan érzékeny műveleteknél kötelező egy második admin jóváhagyása (`confirmed_by_id`).
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ 2. Adatbázis és Modell Változások
|
||||
|
||||
### Új/Módosított Táblák (`data` séma)
|
||||
| Tábla | Változás | Leírás |
|
||||
| :--- | :--- | :--- |
|
||||
| **persons** | **UPDATE** | Új mezők: `identity_hash`, `lifetime_xp`, `penalty_points`, `social_reputation`, `is_sales_agent`. |
|
||||
| **users** | **UPDATE** | Új mezők: `subscription_expires_at`, `is_vip`, `referral_code`, `current_sales_agent_id`. |
|
||||
| **wallets** | **REFACTOR** | Régi balance törölve. Új: `earned_credits`, `purchased_credits`, `service_coins`. |
|
||||
| **org_sales_assignments** | **NEW** | Kapcsolótábla: Melyik cég után ki kapja épp a Farming jutalékot. |
|
||||
| **financial_ledger** | **NEW** | Pénzügyi tranzakciók megmásíthatatlan naplója. |
|
||||
| **security_audit_logs** | **NEW** | Adminisztrátori műveletek és 4-szem elv naplózása. |
|
||||
| **operational_logs** | **NEW** | Általános rendszerhasználati napló. |
|
||||
|
||||
---
|
||||
|
||||
## 📂 3. Érintett Fájlok Listája (Checklist)
|
||||
|
||||
Kérlek, ellenőrizd, hogy ezek a fájlok a legfrissebb verziót tartalmazzák-e a mentésedben:
|
||||
|
||||
- [x] **`backend/app/models/identity.py`** (A teljes Person/User/Wallet logika alapja)
|
||||
- [x] **`backend/app/models/audit.py`** (A Ledger és Security Log definíciók)
|
||||
- [x] **`backend/app/models/organization.py`** (A SalesAssignment tábla hozzáadása)
|
||||
- [x] **`backend/app/models/__init__.py`** (Az összes modell regisztrációja az Alembic számára)
|
||||
- [x] **`backend/app/db/base.py`** (A metadata importok frissítése)
|
||||
- [x] **`backend/app/core/validators.py`** (Az IdentityNormalizer és Hash generáló logika)
|
||||
- [x] **`backend/migrations/versions/XXXX_full_ecosystem_upgrade_v1_6.py`** (A generált migrációs fájl)
|
||||
|
||||
---
|
||||
|
||||
## 🔮 4. Következő Lépések (Roadmap)
|
||||
|
||||
1. **Service Réteg Implementálása:** Megírni a logikát, ami ténylegesen számolja a 10/5%-os jutalékot és beírja a `FinancialLedger`-be.
|
||||
2. **Admin UI:** Felületet készíteni a `system_parameters` (Jutalék szintek) állítására.
|
||||
3. **Robot v1.8:** A "Ghost" szervizek bekötése az új `Person` logikába (automata `identity_hash` generálás a cégadatokból).
|
||||
@@ -129,4 +129,26 @@ A `rank: 100` szintű felhasználó (SuperAdmin) az egyetlen, aki:
|
||||
- `POST /admin/translations/sync`:
|
||||
- **Trigger:** Manuális (Gombnyomás a Dashboardon).
|
||||
- **Action:** `data.translations` -> `static/locales/*.json`.
|
||||
- **Permission:** SuperAdmin ONLY.
|
||||
- **Permission:** SuperAdmin ONLY.
|
||||
|
||||
|
||||
## 5. Security & Audit Logging
|
||||
|
||||
A rendszer két szinten naplózza az eseményeket:
|
||||
|
||||
### 5.1 Operational Log (Üzemi Napló)
|
||||
* **Cél:** Hibakeresés, User Activity követés.
|
||||
* **Tartalom:** Jármű rögzítés, Adatjavítás, Keresés.
|
||||
* **Hozzáférés:** Moderátor szinttől felfelé.
|
||||
|
||||
### 5.2 Security Audit Log (Biztonsági Napló)
|
||||
* **Cél:** Visszaélések megelőzése, Jogosultságok védelme.
|
||||
* **Tartalom:** Rang emelés (Role Change), Kredit manuális jóváírása, VIP státusz adása, Admin belépés.
|
||||
* **Hozzáférés:** Csak Superadmin és Country Admin (Szigorított).
|
||||
|
||||
### 5.3 The "Four-Eyes" Principle (4-Szem Elv)
|
||||
Kritikus műveletek (pl. egy User `is_vip` státuszának kézi átállítása vagy `penalty_points` törlése) esetén a rendszer:
|
||||
1. Rögzíti a kérést a `security_audit_logs`-ban.
|
||||
2. A státusz "Pending" marad.
|
||||
3. A változás **csak akkor lép életbe**, ha egy MÁSIK Adminisztrátor jóváhagyja azt (`confirmed_by_id` kitöltése).
|
||||
4. Szuperadmin esetén a `is_critical` flag aktiválódik, és azonnali riasztás megy a többi adminnak.
|
||||
24
docs/V01_gemini/23_BRANCH_AND_LOCATION_SPEC.md
Normal file
24
docs/V01_gemini/23_BRANCH_AND_LOCATION_SPEC.md
Normal file
@@ -0,0 +1,24 @@
|
||||
# 🏢 23_BRANCH_AND_LOCATION_SPEC (v1.0)
|
||||
|
||||
## 1. Telephely (Branch) Logika
|
||||
A rendszer alapelve, hogy a jogi entitás (Organization) és a fizikai helyszín (Branch) elválik egymástól.
|
||||
|
||||
### 1.1 Struktúra
|
||||
- **Organization:** Jogi egység (Adószám, név).
|
||||
- **Branch (Telephely):** Konkrét fizikai pont, ahol a szolgáltatás zajlik vagy ahol a flotta állomásozik.
|
||||
- **Main Branch:** Minden szervezetnek van legalább egy "Fő" telephelye (`is_main=True`).
|
||||
|
||||
### 1.2 Kapcsolatok
|
||||
- **Szerviz:** Az értékelések és a nyitvatartás a `Branch`-hez kötődik.
|
||||
- **Flotta:** A jármű hozzárendelés (`AssetAssignment`) opcionálisan tartalmaz egy `branch_id`-t, meghatározva a jármű fizikai helyét.
|
||||
|
||||
## 2. Részletes Címkezelés
|
||||
A címeket atomizált formában tároljuk a `data.branches` és `data.addresses` táblákban:
|
||||
- `postal_code`, `city`
|
||||
- `street_name`, `street_type` (utca, út, tér)
|
||||
- `house_number`, `stairwell`, `floor`, `door`
|
||||
- `hrsz` (Helyrajzi szám külterületi vagy speciális telkekhez)
|
||||
|
||||
## 3. Életút Követés (Dual Twin)
|
||||
- **Törlés:** A telephelyek "Soft Delete" (`is_deleted`) alá esnek.
|
||||
- **Áthelyezés:** Ha egy telephely megszűnik, a hozzárendelt járművek automatikusan visszaállnak a Szervezet "Main Branch" helyszínére.
|
||||
Reference in New Issue
Block a user