Initial commit: Robot ökoszisztéma v2.0 - Stabilizált jármű és szerviz robotok
This commit is contained in:
Kincses
29
archive/2026.02.18 Archive_old_mapps/V01_gemini/00_README.md
Executable file
29
archive/2026.02.18 Archive_old_mapps/V01_gemini/00_README.md
Executable file
@@ -0,0 +1,29 @@
|
||||
# 📘 SERVICE FINDER - GRAND MASTER BOOK (v1.0)
|
||||
**Traffic Ecosystem SuperApp 2.0**
|
||||
|
||||
Ez a dokumentáció a rendszer "Egyetlen Igazságforrása" (Single Source of Truth). Minden fejlesztésnek, API hívásnak és üzleti logikának az itt leírtakat kell követnie.
|
||||
|
||||
## 🚀 Gyorslinkek
|
||||
- **01 Project Overview:** [Mit építünk?](./01_Project_Overview.md)
|
||||
- **02 Architecture:** [Hogyan működik?](./02_Architecture_System_Context.md)
|
||||
- **06 Database:** [Adatmodell és Logika](./06_Database_Guide.md)
|
||||
- **10 Billing & Tiers:** [Üzleti Modell](./10_Billing_Credits_Subscriptions.md)
|
||||
|
||||
## 🚦 Státusz Snapshot (2026-02-03)
|
||||
- **Fázis:** Architektúra stabilizálás & Migráció (Pre-Beta).
|
||||
- **Infrastruktúra:** Profibot SW1 (80 Core) - ÉLES.
|
||||
- **Frontend:** Vue3 + Tailwind (Port 3000).
|
||||
- **Backend:** FastAPI v2 (Port 8000).
|
||||
- **Adatbázis:** PostgreSQL 15 (55 tábla, Seed adatokkal).
|
||||
|
||||
# Master Book - Automotive Intelligence Ecosystem
|
||||
Ez a dokumentáció a projekt technikai és üzleti felépítését tartalmazza.
|
||||
|
||||
## Projekt Célkitűzés
|
||||
Egy európai szintű, intelligens járműipari ökoszisztéma kiépítése, amely egyesíti a mély járműkatalógus-adatokat (Deep Asset Catalog) és a hitelesített szervizkeresőt (Service Finder).
|
||||
|
||||
## Főbb Komponensek
|
||||
- **Data Core:** 21,000+ rekordos járműadatbázis (Holland, USA, EU forrásokból).
|
||||
- **Service Hunter:** n8n alapú, automatizált szerviz-felderítő rendszer.
|
||||
- **Trust Engine:** Pontszám alapú validációs algoritmus az adatok hitelességének biztosítására.
|
||||
- **Robot Ökoszisztéma:** Python alapú adatgyűjtő és öngyógyító (Auto-Heal) ágensek.
|
||||
19
archive/2026.02.18 Archive_old_mapps/V01_gemini/01_Project_Overview.md
Executable file
19
archive/2026.02.18 Archive_old_mapps/V01_gemini/01_Project_Overview.md
Executable file
@@ -0,0 +1,19 @@
|
||||
# 🧠 PROJECT OVERVIEW & VISION
|
||||
|
||||
## 🎯 A Cél
|
||||
Egy **Digital Twin** (Digitális Iker) alapú jármű-ökoszisztéma létrehozása.
|
||||
**"A jármű örök, a tulajdonos vándor."**
|
||||
Nem csak költségkövető, hanem egy Service Marketplace, Trust Engine és Gamifikált közösség.
|
||||
|
||||
## 🏗️ Fő Modulok
|
||||
1. **Core Fleet:** Jármű életút, Költségek, TCO (Total Cost of Ownership).
|
||||
2. **Marketplace:** Szervizkereső (Geo+Routing), Ajánlatkérés, Időpontfoglalás.
|
||||
3. **Evidence Store:** Bizonyíték alapú előélet (Fotó, Számla, OCR).
|
||||
4. **Economy:** Kreditrendszer, Előfizetések, Jutalékok.
|
||||
|
||||
## 📖 Terminológia (Glossary)
|
||||
- **PERSON:** A természetes személy (Élő ember). Nem törölhető, csak rejtetté tehető (Soft Delete).
|
||||
- **USER:** A technikai belépési fiók. Egy Person-höz több User tartozhat.
|
||||
- **COMPANY:** Jogi entitás (Céges flotta). Van Tulajdonosa (Person) és Flotta Managere (User).
|
||||
- **PROVIDER:** Szolgáltató (Szerviz, Gumis, Autómosó).
|
||||
- **VALIDATOR:** Magas rangú felhasználó, aki kreditért cserébe adatokat ellenőriz.
|
||||
@@ -0,0 +1,23 @@
|
||||
# 🏗️ ARCHITECTURE & SYSTEM CONTEXT
|
||||
|
||||
## 🧩 Komponensek
|
||||
- **Frontend:** Vue 3 + Tailwind CSS + Pinia (State) + Vite. "Dumb Frontend" elv: Csak megjelenít, nem dönt.
|
||||
- **Backend API:** Python 3.12 + FastAPI. Minden üzleti logika itt fut. Pydantic validáció.
|
||||
- **Database:** PostgreSQL 15. Külön `data` (üzleti) és `public` (rendszer) sémák.
|
||||
- **Storage:** MinIO (S3 kompatibilis). Képek, számlák titkosított tárolása.
|
||||
- **Proxy:** Nginx Proxy Manager. SSL terminálás (`dev.profibot.hu`).
|
||||
|
||||
## 🛡️ Hálózati Határok
|
||||
- **Internal Net (`shared_db_net`):** A Backend és az Adatbázis közötti dedikált, zárt csatorna.
|
||||
- **Public Net:** Csak a 80/443 (NPM) nyitott a világ felé. A DB port (5432) és Admin portok (5050, 8888) csak VPN-en vagy localhoston érhetők el.
|
||||
|
||||
# 02. Architecture & System Context
|
||||
|
||||
## Rendszerarchitektúra v2.0
|
||||
A rendszer egy eseményvezérelt, mikroszolgáltatás-alapú architektúrára épül, ahol az **n8n** tölti be a központi idegrendszer (Orchestrator) szerepét.
|
||||
|
||||
### Adatáramlási Folyamat
|
||||
1. **Discovery Layer:** n8n által vezérelt robotok (Robot A) pásztázzák a hálót (OSM, DDG, FB, e-Cégközlöny).
|
||||
2. **Staging Layer:** A nyers adatok egy átmeneti (Stage) táblába kerülnek további elemzésre.
|
||||
3. **Audit Layer:** A validátor robot (Robot B) ellenőrzi az adószámokat, TEAOR kódokat és a digitális lábnyomot.
|
||||
4. **Core Database:** Csak a Trust Engine által hitelesített adatok kerülnek az éles jármű- és szervizkatalógusba.
|
||||
@@ -0,0 +1,59 @@
|
||||
(Fejlesztői kézikönyv.)
|
||||
# 👨💻 DEVELOPER RUNBOOK
|
||||
|
||||
## 🚀 Indítás
|
||||
```bash
|
||||
cd /opt/docker/dev/service_finder
|
||||
docker compose up -d
|
||||
|
||||
🔍 Logok és Debug
|
||||
|
||||
API log: docker logs -f service_finder_api
|
||||
|
||||
Frontend log: docker logs -f service_finder_frontend
|
||||
|
||||
DB Console: docker exec -it shared-postgres psql -U kincses -d service_finder
|
||||
|
||||
⚠️ Known Pitfalls (Hibaelhárítás)
|
||||
|
||||
API URL: A frontend .env fájljában a VITE_API_BASE_URL nem lehet localhost, ha konténerben fut. Használd a belső IP-t vagy domain-t.
|
||||
|
||||
Login 404: A /api/v1/users/me végpontot a backend routerben regisztrálni kell (jelenleg hiányzik vagy path mismatch van).
|
||||
|
||||
OpenAPI 404: A helyes cím /api/v2/openapi.json.
|
||||
|
||||
# 03. Development Environment Runbook
|
||||
|
||||
## 3.1. System Initialization (Bootstrap)
|
||||
Ha az adatbázis üres (vagy törölve lett), az első SuperAdmin felhasználót manuálisan kell létrehozni, mivel a regisztrációs végpontok védettek vagy nem adnak admin jogot.
|
||||
|
||||
### 3.1.1. SuperAdmin Létrehozása (Recommended)
|
||||
A jelszó hash-elési eltérések elkerülése érdekében használjuk a Python scriptet a konténeren belül:
|
||||
|
||||
```bash
|
||||
docker exec -it service_finder_api python3 -c "
|
||||
import bcrypt
|
||||
import asyncio
|
||||
from sqlalchemy import text
|
||||
from app.db.session import SessionLocal
|
||||
|
||||
async def bootstrap_admin():
|
||||
# 1. Jelszó generálás
|
||||
password = 'InitialPassword123'.encode('utf-8')
|
||||
hashed = bcrypt.hashpw(password, bcrypt.gensalt()).decode('utf-8')
|
||||
|
||||
async with SessionLocal() as db:
|
||||
# 2. Person és User létrehozása/Frissítése
|
||||
# (A script feltételezi, hogy a Person rekord már létezik vagy itt hozod létre)
|
||||
sql = text(\"\"\"
|
||||
UPDATE data.users
|
||||
SET hashed_password = :h, role = 'superadmin', is_active = true, preferred_language = 'hu'
|
||||
WHERE email = 'admin@servicefinder.hu'
|
||||
\"\"\")
|
||||
await db.execute(sql, {'h': hashed})
|
||||
await db.commit()
|
||||
print('✅ SuperAdmin Ready')
|
||||
|
||||
if __name__ == '__main__':
|
||||
asyncio.run(bootstrap_admin())
|
||||
"
|
||||
@@ -0,0 +1,27 @@
|
||||
# 🐳 DOCKER STACK & PORTS
|
||||
|
||||
## Szolgáltatások
|
||||
| Service | Image | Internal Port | Host Port | Volume Mapping |
|
||||
| :--- | :--- | :--- | :--- | :--- |
|
||||
| **API** | `python:3.12` | 8000 | 8000 | `./backend:/app` |
|
||||
| **Frontend** | `node:20` | 80 | 3000 | `./frontend:/app` |
|
||||
| **DB** | `postgres:15` | 5432 | 5432 | `postgres_data:/var/lib/postgresql/data` |
|
||||
| **MinIO** | `minio/minio` | 9000, 9001 | 9000, 9001 | `minio_data:/data` |
|
||||
| **Redis** | `redis:alpine` | 6379 | - | - |
|
||||
|
||||
## Hardening Terv
|
||||
A `Host Port` oszlopban lévő portokat éles üzemben le kell venni (kivéve 80/443), és csak a
|
||||
|
||||
# 04. Infrastructure & Docker Stack
|
||||
|
||||
## Hardver Erőforrás
|
||||
- **Szerver:** 128 GB RAM (High-Performance Node).
|
||||
- **Kihasználtság cél:** Moduláris konténerek futtatása alacsony (5-10%) alapterhelés mellett, magas skálázhatósági tartalékkal.
|
||||
|
||||
## Docker Ökoszisztéma (Bővített)
|
||||
A stack a következő konténereket tartalmazza:
|
||||
1. **n8n (Orchestrator):** Vizuális munkafolyamat-kezelő.
|
||||
2. **PostgreSQL:** Központi adattár (Járművek + Szervizek).
|
||||
3. **Browserless (Chrome):** "Fej nélküli" böngésző az n8n számára a komplex scraping feladatokhoz.
|
||||
4. **Python Robots:** Konténerizált adatgyűjtő és dúsító ágensek (v1.9.2+).
|
||||
5. **Proxy/VPN Node:** IP-rotációt biztosító modul a globális felderítéshez.
|
||||
166
archive/2026.02.18 Archive_old_mapps/V01_gemini/05_AUTH_AND_IDENTITY_SPEC.md
Executable file
166
archive/2026.02.18 Archive_old_mapps/V01_gemini/05_AUTH_AND_IDENTITY_SPEC.md
Executable file
@@ -0,0 +1,166 @@
|
||||
# 🔐 05_AUTH_AND_IDENTITY_SPEC (v1.3)
|
||||
|
||||
## 1. Azonosítási Stratégia
|
||||
A rendszer alapelve a **technikai hozzáférés** (User) és a **valós identitás** (Person) szigorú szétválasztása.
|
||||
|
||||
### 1.1. Identitás szintek
|
||||
- **User (Login):** Email + Jelszó. Kizárólag a belépéshez és a munkamenet (session) kezeléséhez szükséges technikai entitás.
|
||||
- **Person (Identity):** A valós személy adatai (Név, anyja neve, születési adatok, okmányok). Minden Person kap egy globális egyedi azonosítót (**UUID**).
|
||||
|
||||
### 1.2. Social Auth (Google / Facebook)
|
||||
- **Működés:** Engedélyezett a gyors belépéshez.
|
||||
- **Kényszerített KYC:** Social Auth esetén a 2. lépésben kötelező a KYC adatok pótlása.
|
||||
- **Korlátozás:** Amíg a KYC adatok hiányoznak, a felhasználó "Free User" marad, és nem fér hozzá a regisztrációkor járó extra prémium szolgáltatásokhoz.
|
||||
|
||||
### 1.3. Soft Delete & Re-regisztráció
|
||||
- **Nincs fizikai törlés:** A felhasználó törléskor `is_hidden` vagy `deleted_at` flag-et kap.
|
||||
- **Ismételt regisztráció:** Ha az email/név/okmány alapján a rendszer felismeri a visszatérőt:
|
||||
- Új technikai User fiók jön létre, de a korábbi **Person ID**-hoz kapcsolódik.
|
||||
- **Adat-izoláció:** A felhasználó csak az új regisztráció utáni eseményeket látja, a régi adatok (statisztika, elemzés) csak a háttérben maradnak meg.
|
||||
|
||||
---
|
||||
|
||||
## 2. Bizalmi Szintek (Trust Tiers)
|
||||
A rendszer a "Tier-based Access Control" (szintezett hozzáférés) elvét alkalmazza az adatszolgáltatás mértékétől függően.
|
||||
|
||||
| Szint | Megnevezés | Követelmény | Jogosultságok |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **Tier 0** | Anonymous | Nincs | Csak publikus adatok megtekintése. |
|
||||
| **Tier 1** | Verified Email | Step 1 (Regisztráció) sikeres | Belépés, saját profil megtekintése. |
|
||||
| **Tier 2** | KYC Submitted | Step 2 (Személyi adatok + Telefon) | **Privát Széf/Flotta aktiválása**, Wallet használat. |
|
||||
| **Tier 3** | AI/OCR Verified | Okmánykép AI általi ellenőrzése | Harmadik fél szolgáltatásainak igénybevétele. |
|
||||
|
||||
---
|
||||
|
||||
## 3. KYC és Bővített Adattár (Safety)
|
||||
A `persons` tábla progresszív feltöltéssel tárolja az adatokat a "Minimal Friction" elv mentén.
|
||||
|
||||
### 3.1. Kötelező Adatkör (Step 2 - Tier 2)
|
||||
A "Privát Széf" aktiválásához az alábbi adatok megadása kötelező:
|
||||
- **Alapadatok:** `last_name`, `first_name`, `birth_place`, `birth_date`, `mothers_name`.
|
||||
- **Kapcsolat:** Valós telefonszám (nemzetközi formátum).
|
||||
- **Hivatalos okmányok:** Személyi ig. szám, Jogosítvány (szám, kategóriák, érvényesség), Lakcímkártya, TAJ, Adóazonosító.
|
||||
- **Biztonság (ICE):** "In Case of Emergency" adatok (értesítendő személy neve és telefonszáma).
|
||||
- **Vészhelyzeti adatok:** Vércsoport, Allergia.
|
||||
|
||||
### 3.2. Jutalom Trigger
|
||||
A teljes körű adategyeztetésért (100%-os profilkitöltöttség) **2 hét PRÉMIUM** tagság jár.
|
||||
|
||||
---
|
||||
|
||||
## 4. Céges Azonosítás és Verifikáció
|
||||
A szervezetek (Companies) hitelesítése és bizalmi szintjeinek kezelése.
|
||||
|
||||
### 4.1. Verifikációs Státuszok
|
||||
- **Unverified (Nem ellenőrzött):** Kézi rögzítés utáni alapállapot. 30 napos türelmi időt biztosít a funkciókhoz.
|
||||
- **Verified (Hitelesített):** Hitelesített állapot (VIES API találat vagy Admin kézi jóváhagyás után).
|
||||
- **Suspended (Felfüggesztett):** Megszűnt cég vagy le nem igazolt adatok esetén az időszakos ellenőrzés során.
|
||||
|
||||
### 4.2. Ellenőrzési Logika (Robot & Admin)
|
||||
1. **Robot:** A `VAT_NUMBER` rögzítésekor a rendszer azonnal meghívja az EU-s **VIES API**-t. Egyezőség esetén azonnal `Verified`.
|
||||
2. **Hibrid Validálás:** Ha a VIES API nem ad eredményt, a rendszer céges dokumentum feltöltését kéri.
|
||||
3. **Ellenőrzés:** Adminisztrátori jóváhagyás vagy AI-alapú dokumentum-validálás után válik a státusz véglegessé.
|
||||
4. **Időszakos ellenőrzés:** Ütemezett feladat (Cron) 30 naponta újraellenőrzi a cégeket. Megszűnés esetén `Suspended` státusz és értesítés.
|
||||
|
||||
### 4.3. Korlátozások (Suspended/Unverified)
|
||||
- Nem rögzíthető új jármű a flottába.
|
||||
- Nem generálható meghívó (Invite Token).
|
||||
- Statisztikai kimutatások korlátozása.
|
||||
|
||||
---
|
||||
|
||||
## 5. Jutalék és Gazdasági Rendszer
|
||||
### 5.1. Piramis rendszer (3 szint)
|
||||
A meghívó lánc alapján számolt jóváírások (Referral):
|
||||
- **1. szint (Közvetlen):** 10%
|
||||
- **2. szint:** 5%
|
||||
- **3. szint:** 2%
|
||||
*Megjegyzés: A százalékok a befizetés pillanatában érvényes admin beállítások alapján rögzülnek (Snapshot technika).*
|
||||
|
||||
### 5.2. Wallets
|
||||
Minden regisztrációnál automatikusan létrejön:
|
||||
- **Coin Wallet:** Belső fizetőeszköz (Kredit).
|
||||
- **XP Ledger:** Tapasztalati pontok (Gamification és rangsor).
|
||||
|
||||
---
|
||||
|
||||
## 6. Moderáció és Validálás
|
||||
- **Validált vélemény:** Csak igazolt ott-tartózkodás (GPS log) vagy számlafotó (OCR) feltöltése után adható.
|
||||
- **Fellebbezés:** A szervizek kérhetik a vélemények felülvizsgálatát, amit moderátorok bírálnak el.
|
||||
|
||||
---
|
||||
|
||||
## 7. Adattárolási Stratégia (Technikai)
|
||||
- A rugalmas okmányadatokat (`identity_docs`) és a vészhelyzeti kapcsolatokat (`ice_contact`) **JSONB** mezőkben tároljuk a `persons` táblában a kereshetőség és a jövőbeli bővíthetőség érdekében.
|
||||
|
||||
## 4. Multi-Account & Identity Linking
|
||||
A felhasználók több e-mail címet is csatolhatnak egyetlen profilhoz, hogy könnyen válthassanak a magánszemély és a céges flotta-menedzser szerepkörök között.
|
||||
|
||||
### 4.1 Szabályrendszer
|
||||
* **Limit:** Egy felhasználói profilhoz maximum **3** másodlagos e-mail cím csatolható.
|
||||
* **Elsődleges cím:** Ez a belépési azonosító és a hivatalos értesítési cím.
|
||||
* **Context Switching:** A felhasználó a fejlécben válthat a "Személyes" és a "Céges" nézetek között (pl. Flotta Manager mód).
|
||||
|
||||
### 4.2 Account Linking Folyamat
|
||||
1. User belép az elsődleges fiókba.
|
||||
2. `Settings -> Linked Accounts -> Add New`.
|
||||
3. Rendszer küld egy megerősítő linket az új címre.
|
||||
4. Ha a linkre kattint, az új cím hozzáadódik a `user_identities` táblához.
|
||||
5. Ha az új címen már volt regisztráció: A rendszer felajánlja az **Account Merge** (Fiókegyesítés) lehetőségét (biztonsági kérdések után).
|
||||
|
||||
```markdown
|
||||
# 05. Authentication & Identity Specification
|
||||
|
||||
## 5.2. Data Models (Identity)
|
||||
|
||||
### 5.2.1. User Entity (`data.users`)
|
||||
A technikai belépési pont.
|
||||
- **id**: Integer (PK)
|
||||
- **email**: String (Unique)
|
||||
- **hashed_password**: String (Bcrypt)
|
||||
- **role**: Enum (superadmin, admin, user, service, driver)
|
||||
- **person_id**: FK -> `data.persons.id` (A TWINS kapcsolat)
|
||||
- **preferred_language**: String (Default: 'hu') [ÚJ v1.2.5]
|
||||
- **region_code**: String (Default: 'HU') [ÚJ v1.2.5]
|
||||
- **is_active**: Boolean
|
||||
|
||||
### 5.2.2. TWINS Concept Update
|
||||
- A `User` (User) és `Person` (Shadow Identity) szétválasztása szigorú.
|
||||
- Belépéskor a rendszer a `User` táblából olvassa ki a `preferred_language` és `region_code` beállításokat, és ezeket a Token válaszban visszaadja a Frontendnek.
|
||||
|
||||
## 1.3 Shadow Identity & Merging Logic
|
||||
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.
|
||||
|
||||
## 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).
|
||||
223
archive/2026.02.18 Archive_old_mapps/V01_gemini/06_Database_Guide.md
Executable file
223
archive/2026.02.18 Archive_old_mapps/V01_gemini/06_Database_Guide.md
Executable file
@@ -0,0 +1,223 @@
|
||||
# 🗄️ 06_DATABASE_GUIDE & DATA INTEGRITY (v1.4)
|
||||
|
||||
Ez a dokumentum az adatbázis-architektúra alapelveit és az adatintegritási szabályokat tartalmazza.
|
||||
|
||||
## 1. Soft Delete & Újraregisztráció Logika
|
||||
A rendszerben **nincs fizikai törlés**. A `data.users` tábla speciális indexeléssel kezeli a törölt és visszatérő felhasználókat.
|
||||
|
||||
- **Indexelés:** Az `email` mezőn egy *Partial Unique Index* (`idx_user_email_active_only`) található.
|
||||
- **Működés:** - Ha `is_deleted = FALSE`, az email foglalt, nem használható újra.
|
||||
- Ha a felhasználó törli magát (`is_deleted = TRUE`), az email felszabadul.
|
||||
- **Identitás megőrzése:** Új regisztrációkor a rendszer új `user_id`-t generál, de ha a KYC (személyazonosító) adatok egyeznek, az új technikai User a régi `person_id`-hoz kapcsolódik.
|
||||
|
||||
---
|
||||
|
||||
## 2. Person (Identitás) - KYC & Safety
|
||||
A `data.persons` tábla a valós, banki szintű személyazonosságot tárolja.
|
||||
|
||||
### 2.1. JSONB struktúrák
|
||||
Rugalmas adatszerkezet az okmányok és orvosi adatok kezelésére:
|
||||
- **`identity_docs`**:
|
||||
- `id_card`: szám és lejárati dátum.
|
||||
- `driver_license`: szám, lejárat és kategóriák (pl. ["A", "B", "C"]).
|
||||
- `special_permits`: hajó- vagy repülőgép-vezetői engedélyek.
|
||||
- **`medical_emergency`**: Vércsoport, allergiák, krónikus betegségek.
|
||||
|
||||
### 2.2. Jutalom Trigger
|
||||
A profil 100%-os kitöltése (név, születési adatok, okmányok) után automatikusan aktiválódik a `system_settings`-ben meghatározott **PRÉMIUM** időszak (alapértelmezett: 14 nap).
|
||||
|
||||
---
|
||||
|
||||
## 3. Technikai Integritás és Séma
|
||||
### 3.1. Adatbázis sémák
|
||||
- **`public`**: Csak technikai metaadatok (pl. `alembic_version`).
|
||||
- **`data`**: Az üzleti logika összes táblája (55+ tábla).
|
||||
|
||||
### 3.2. Fejlesztői megjegyzések
|
||||
- **Enum Case Sensitivity:** A Postgres `userrole` típusa **kisbetűérzékeny**. A Python kódból érkező értékeket (pl. `user`, `admin`) kényszerítve kisbetűvel kell rögzíteni.
|
||||
- **Séma Frissítés:** A `metadata.create_all` nem frissíti a meglévő táblákat. Új oszlopok esetén manuális `ALTER TABLE` vagy Alembic migráció szükséges.
|
||||
- **Audit:** Minden státuszmódosítás és adatváltozás snapshot-olva kerül az `audit_logs` táblába.
|
||||
|
||||
---
|
||||
|
||||
## 4. Economy, Regionalizáció és Valuta
|
||||
A rendszer EU-s piacra optimalizált multi-currency logikát használ.
|
||||
|
||||
- **`data.regional_settings`**: Országkódok (ISO 3166-1), alapértelmezett nyelvek és pénznemek.
|
||||
- **`data.exchange_rates`**: Napi frissítésű váltószámok (Bázis: EUR).
|
||||
- **Valuta Logika:** Minden költséget elmentünk helyi pénznemben (`currency_code`) és a rögzítéskori váltószámmal átszámított EUR-ban is.
|
||||
- **Képlet:** $$Cost_{EUR} = Cost_{Local} \cdot ExchangeRate$$
|
||||
|
||||
### 4.1. Wallet & Economy
|
||||
- **Wallets:** Minden regisztrációkor létrejön egy rekord a `data.wallets` táblában (0 Coin, 0 XP).
|
||||
- **Referral Snapshot:** Jutalék kifizetésekor a rendszer rögzíti a tranzakció pillanatában érvényes `%`-ot (`commission_percentage`), védve az adatot a későbbi módosításoktól.
|
||||
|
||||
---
|
||||
|
||||
## 5. Flotta és Tulajdonjog Szabályok
|
||||
A flották (Organization) és járművek tulajdonjogi logikája:
|
||||
|
||||
- **Átruházhatóság (Transferability):**
|
||||
- `INDIVIDUAL` flotta: Nem átruházható, a felhasználóhoz kötött.
|
||||
- `FLEET_OWNER / SERVICE` flotta: Átruházható, új tulajdonoshoz (`owner_id`) rendelhető.
|
||||
- **Cég Megszűnése:** Soft delete (`is_active: False`). A járművek életútja (history) megmarad a visszakövethetőség miatt.
|
||||
- **Opcionális Járművek:** Egy flotta létezhet jármű rögzítése nélkül is (pl. tisztán menedzseri kör).
|
||||
|
||||
---
|
||||
|
||||
## 6. Szervezeti Egységek és CRM
|
||||
A flottákhoz tartozó humán és üzleti kapcsolatok kezelése.
|
||||
|
||||
- **`data.organizations`**: Bővítve: `tax_number`, `reg_number`, `headquarters_address`, `notification_settings` (JSONB).
|
||||
- **`data.organization_contacts`**: Mini-CRM funkciók (kapcsolattartók típusai: billing, primary, operational).
|
||||
- **Kapcsolódás:** `external_crm_id` mező biztosítja az API kapcsolatot külső ERP rendszerekkel.
|
||||
|
||||
---
|
||||
|
||||
## 7. Gazdasági Izoláció és Rating
|
||||
- **Gamification Korlát:** Csak `INDIVIDUAL` típusú flottákhoz tartozó `Person`-ok gyűjthetnek XP-t. A cégek (`Company`) nem kapnak `XP_Ledger`-t és `Coin_Wallet`-et.
|
||||
- **Validáció:** Cég nem validálhat szervizpontot, csak a hozzárendelt, azonosított `Person` (technikus).
|
||||
- **Rating Rendszer:** Külön értékelést kap a **Person** (megbízhatóság), a **Service** (minőség) és a **Vehicle** (műszaki állapot). A cég hírneve ezekből adódik össze.
|
||||
|
||||
---
|
||||
|
||||
## 8. Dinamikus Paraméterezés (`data.system_settings`)
|
||||
Minden üzleti változó az Admin UI-ról állítható:
|
||||
- `auth.reward_days`: Regisztrációs prémium hossza (default: 14).
|
||||
- `auth.reward_tier`: Kapott csomag típusa (default: PREMIUM).
|
||||
- `referral.l1`: Első szintű jutalék mértéke (default: 10%).
|
||||
|
||||
---
|
||||
|
||||
## 9. Kulcs Táblacsoportok
|
||||
1. **Fleet:** `vehicles`, `user_vehicles`, `vehicle_events`, `engine_specs`.
|
||||
2. **Marketplace:** `service_providers`, `service_specialties`, `organization_locations`.
|
||||
3. **Economy:** `wallets`, `transactions`, `shop_items`.
|
||||
4. **Identity:** `users`, `persons`, `companies`.
|
||||
|
||||
---
|
||||
|
||||
## 10. Migrációs Állapot (Dev Info)
|
||||
- **Eszköz:** Alembic
|
||||
- **Current Head:** `10b73fee8967`
|
||||
- **Hiányzó láncszem:** A `persons` tábla véglegesítése és a meglévő `users` tábla adatintegrációs migrációja folyamatban.
|
||||
|
||||
## 4.2 Dokumentum és Irattár (Vault Logic)
|
||||
- **Központi tárolás:** A `data.documents` tábla kezeli az összes csatolmányt (parent_type: 'org', 'asset', 'person').
|
||||
- **Metadata:** Tároljuk a dokumentum kibocsátóját (issuer_id) és tárgyát (subject_id) a szervizstatisztikákhoz.
|
||||
- **Verifikáció:** `status` mező (pending, verified, rejected).
|
||||
|
||||
## 4.3 Crowdsourced Szervezetek
|
||||
- **Lifecycle:** draft_user -> draft_bot -> community_verified -> official.
|
||||
- **Gamification:** XP/Kredit jóváírás csak sikeres Bot vagy Owner validáció után.
|
||||
|
||||
## 6. Service & Organization Extensions (V2)
|
||||
|
||||
### 6.1 `data.system_configs` (Dinamikus Beállítások)
|
||||
Kódba égetett értékek helyett adatbázisból vezérelt működés.
|
||||
* `key` (VARCHAR): Pl. `referral_bonus_L1`, `exchange_rate_EUR`, `payout_threshold`.
|
||||
* `value` (JSONB): Pl. `{"amount": 10, "unit": "percent"}`, `{"rate": 400.0}`.
|
||||
* `is_active` (BOOLEAN).
|
||||
|
||||
### 6.2 `data.service_reviews` (Okos Értékelés)
|
||||
* `user_id`, `organization_id`.
|
||||
* `rating` (1-5).
|
||||
* `proof_url` (Számla/Munkalap fotó URL).
|
||||
* `is_active` (BOOLEAN): Csak az aktív számít bele az átlagba (lásd Gamification logika).
|
||||
|
||||
### 6.3 `data.wallet_transactions`
|
||||
* `original_currency`: (HUF, EUR, USD).
|
||||
* `exchange_rate`: Az adott pillanatban érvényes váltószám.
|
||||
|
||||
## 7. Referrals & Invitations
|
||||
* `data.referrals`: Hierarchikus fa szerkezet (`inviter_id`, `invitee_id`, `level`).
|
||||
* `data.invitations`:
|
||||
* `code`: Random string (pl. `X7K9P2`).
|
||||
* `type`: 'private' (72h) vagy 'company' (168h).
|
||||
* `target_role`: A meghívott jogosultsága (Driver, Manager).
|
||||
|
||||
## 8. Virtual Goods & Inventory (Digitális Javak)
|
||||
|
||||
### 8.1 `data.user_inventory`
|
||||
Ez a tábla tárolja a felhasználó által megszerzett vagy vásárolt kozmetikai elemeket (NEM jogosultságok, hanem vagyontárgyak).
|
||||
|
||||
* `id` (UUID): Egyedi azonosító.
|
||||
* `user_id` (FK): A tulajdonos.
|
||||
* `item_id` (VARCHAR): A katalógusban lévő azonosító (pl. `avatar_frame_neon`).
|
||||
* `metadata` (JSONB): Opcionális egyedi tulajdonságok (pl. sorszámozott NFT-szerű elemknél: `{"serial": 42}`).
|
||||
* `acquired_at` (TIMESTAMP): Mikor szerezte.
|
||||
* `is_equipped` (BOOLEAN): Éppen használja-e (pl. ez az aktív avatar kerete).
|
||||
|
||||
### 8.2 Shop Catalog Configuration (`system_configs`)
|
||||
A `key = 'shop_catalog'` alatt tároljuk a bolt kínálatát JSON formátumban.
|
||||
|
||||
**Példa JSON struktúra:**
|
||||
```json
|
||||
{
|
||||
"categories": ["avatars", "badges", "profile_themes"],
|
||||
"items": {
|
||||
"badge_early_adopter": {
|
||||
"name": "Korai Felfedező",
|
||||
"price": 0,
|
||||
"currency": "free",
|
||||
"condition": "reg_date < '2025-01-01'",
|
||||
"image_url": "/assets/badges/early.png"
|
||||
},
|
||||
"frame_gold_mechanic": {
|
||||
"name": "Arany Szerelő Keret",
|
||||
"price": 5000,
|
||||
"currency": "credit",
|
||||
"rarity": "legendary",
|
||||
"effect": "shine_animation",
|
||||
"image_url": "/assets/frames/gold.png"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
## 5. Geo-Location and Address Master Data
|
||||
A rendszer normalizált címkezelést alkalmaz az adatminőség biztosítása érdekében.
|
||||
|
||||
### 5.1 Geo Adattáblák
|
||||
- `data.geo_postal_codes`: ZIP és Település kapcsolata (Unique: country + zip + city).
|
||||
- `data.geo_streets`: Utcanevek listája, ZIP azonosítóhoz kötve.
|
||||
- `data.geo_street_types`: Közterület típusok szótára (út, utca, tér...).
|
||||
|
||||
### 5.2 GIS Adatok
|
||||
Minden telephely koordinátája `GEOGRAPHY(POINT, 4326)` típusként van tárolva, amely lehetővé teszi a PostGIS alapú távolságmérést.
|
||||
|
||||
### 5. Hibrid Címkezelési Modell
|
||||
A rendszer az adatintegritás és a sebesség érdekében hibrid modellt használ.
|
||||
|
||||
- **Centralizált adattárolás**: A `data.addresses` tábla tárolja a normalizált címeket (UUID alapú).
|
||||
- **Öntanuló szótárak**: A `data.geo_postal_codes` és `data.geo_streets` táblák automatikusan bővülnek minden új rögzítésnél.
|
||||
- **Denormalizált GPS adatok**: Az `organization_locations` tábla közvetlenül tárolja a koordinátákat a JOIN-nélküli PostGIS lekérdezésekhez.
|
||||
|
||||
| Tábla | Funkció |
|
||||
| :--- | :--- |
|
||||
| `data.addresses` | Konkrét házszám szintű címek (Hibrid hivatkozási pont). |
|
||||
| `data.geo_postal_codes` | Irányítószám és város kapcsolata (HU/EU támogatás). |
|
||||
| `data.user_stats` | Felhasználói XP, szintek és strike-ok tárolása. |
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
### 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).
|
||||
|
||||
## 4. MDM és Jármű Katalógus Struktúra
|
||||
A rendszer hibrid (Relációs + JSONB) modellt használ a skálázhatóság érdekében.
|
||||
|
||||
### 4.1 Táblák:
|
||||
* **data.vehicle_model_definitions**: A "Szent Grál". Tartalmazza a márka, kód, marketing név mellett a fix numerikus adatokat (ccm, kw, weight) a gyors szűréshez.
|
||||
* **data.feature_definitions**: Globális szótár az összes extráról (ABS, Halradar, Retarder stb.), kategóriákba sorolva.
|
||||
* **data.model_feature_maps**: Összeköti a modellt az extrákkal.
|
||||
- `availability`: [STANDARD, OPTIONAL, ACCESSORY]
|
||||
* **data.vehicle_model_reviews**: Felhasználói vélemények a típusról (1-5 csillag, szöveges).
|
||||
78
archive/2026.02.18 Archive_old_mapps/V01_gemini/07_API_Guide.md
Executable file
78
archive/2026.02.18 Archive_old_mapps/V01_gemini/07_API_Guide.md
Executable file
@@ -0,0 +1,78 @@
|
||||
# 🔌 07_API_GUIDE
|
||||
|
||||
## 1. Verziózás (Versioning)
|
||||
A rendszer támogatja a többszintű verziókezelést a stabilitás és a visszafelé való kompatibilitás érdekében.
|
||||
- **v1:** Core Fleet funkciók (pl. `/api/v1/vehicles`, `/api/v1/expenses`).
|
||||
- **v2:** Auth és új generációs modulok (pl. `/api/v2/auth/login`).
|
||||
|
||||
---
|
||||
|
||||
## 2. Route Inventory (Kiemelt Végpontok)
|
||||
Az alábbi táblázat tartalmazza a legfontosabb útvonalakat:
|
||||
|
||||
| Metódus | Végpont | Leírás |
|
||||
| :--- | :--- | :--- |
|
||||
| `POST` | `/api/v2/auth/register` | Regisztráció Person rekord létrehozásával |
|
||||
| `GET` | `/api/v1/fleet/vehicles` | Felhasználó saját járműveinek listázása |
|
||||
| `POST` | `/api/v1/search/match` | Szervizkereső algoritmus indítása |
|
||||
| `POST` | `/api/v1/evidence/upload` | Dokumentum feltöltés (MinIO) |
|
||||
|
||||
---
|
||||
|
||||
## 3. Hiba Kezelés (Error Handling)
|
||||
A frontendnek az alábbi HTTP státuszkódok alapján kell lekezelnie a kivételeket:
|
||||
- **401:** Token lejárt -> Frontendnek automatikusan a Login oldalra kell dobnia a felhasználót.
|
||||
- **403:** Jogosultság hiba -> "Nincs jogod ehhez a funkcióhoz" üzenet megjelenítése (Tier limit/Role hiba).
|
||||
- **404:** Resource not found -> Az erőforrás nem található vagy Soft Deleted állapotban van.
|
||||
|
||||
---
|
||||
|
||||
## 4. Nemzetköziesítés (i18n) és Lokalizáció
|
||||
A rendszer a "Global-Local" elv alapján működik. **Tilos a programkódban (hard-coded) szöveges üzeneteket elhelyezni.**
|
||||
|
||||
### 4.1. Nyelvi fájlok struktúrája
|
||||
Minden nyelvi fájl a `backend/app/locales/` mappában található, szabványos JSON formátumban.
|
||||
- **Példa fájlok:** `hu.json`, `en.json`, `de.json`.
|
||||
|
||||
### 4.2. Kezelési szabályok
|
||||
- **Backend:** A rendszerüzeneteket, hibaüzeneteket és az e-mail sablonok tartalmát a `LocaleManager` szolgáltatáson keresztül kéri le.
|
||||
- **Paraméterezés:** A szövegekben használható változók formátuma: `{variable_name}`.
|
||||
- **Sablonkezelés:** Az e-mailek HTML vázát és a JSON-ban tárolt szöveges blokkokat a rendszer a küldés előtt fűzi össze.
|
||||
|
||||
### 4.3. Nyelvválasztás logikája (Prioritás)
|
||||
1. A kérés fejlécében érkező `Accept-Language` alapján.
|
||||
2. Bejelentkezett felhasználó esetén a `User.region_code` alapján.
|
||||
3. Alapértelmezett: `hu`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Unified Registration & Security Protocol
|
||||
A rendszer a **"Minimal Friction, Maximum Security"** elvét követi.
|
||||
|
||||
### 5.1. Regisztrációs Életciklus
|
||||
1. **Step 1 (Lite):** `Email`, `Jelszó`, `Név` megadása. Létrejön a `User` és `Person` rekord. Állapot: `is_active: false`.
|
||||
2. **Verifikáció:** A rendszer UUID alapú tokent generál (48 órás élettartam). A felhasználó e-mailben kap egy aktiváló linket.
|
||||
3. **Step 2 (KYC):** Sikeres verifikáció után a felhasználó megadja az okmányait (Személyi/Jogsi/Hajó).
|
||||
4. **Aktiválás:** Létrejön a **Privát Flotta (Privát Széf)** és a hozzá tartozó `Wallet`. Állapot: `is_active: true`.
|
||||
|
||||
### 5.2. Token Biztonsági Előírások
|
||||
- **Regisztrációs Token:** 48 óra élettartam.
|
||||
- **Jelszó-visszaállítási Token:** 1 óra élettartam.
|
||||
|
||||
### 5.3. Rate Limiting (Robotvédelem és Költségkontroll)
|
||||
Az e-mail küldési folyamatokra az alábbi korlátok vonatkoznak:
|
||||
- **Retry Cooldown:** Újraigénylés legkorábban 60 másodperc után lehetséges.
|
||||
- **Óránkénti Limit:** Maximum 3 kérelem / e-mail cím.
|
||||
- **Napi Limit:** Maximum 10 kérelem / e-mail cím.
|
||||
- **Zárolás:** A napi limit túllépése esetén a fiók biztonsági okokból 24 órára zárolja a küldési funkciót az adott címre.
|
||||
|
||||
### 4. Geo és Kereső Végpontok
|
||||
|
||||
#### GET `/api/v1/services/suggest-street`
|
||||
- **Cél**: Autocomplete támogatás a frontendnek.
|
||||
- **Paraméterek**: `zip_code` (string), `q` (részleges utcanév).
|
||||
|
||||
#### GET `/api/v1/services/search`
|
||||
- **Cél**: Kétlépcsős szervizkereső.
|
||||
- **Free mód**: Légvonalbeli távolságmérés (Radius).
|
||||
- **Premium mód**: Útvonal-idő alapú kalkuláció és forgalmi becslés.
|
||||
@@ -0,0 +1,136 @@
|
||||
# 🏁 07_REGISTRATION_INVITATION_AND_API (v1.4)
|
||||
|
||||
## 1. Kétlépcsős Onboarding Folyamat
|
||||
A rendszer a felhasználói élmény (UX) és a banki szintű biztonság érdekében két fázisra bontja a regisztrációt, amelyet egy atomi tranzakció zár le.
|
||||
|
||||
### 1.1. Fázis: "Lite" Regisztráció (Step 1)
|
||||
* **Végpont:** `POST /api/v1/auth/register`
|
||||
* **Cél:** Gyors belépés és a technikai User fiók létrehozása.
|
||||
* **Kötelező adatok:** Email, Jelszó, Vezetéknév, Keresztnév, Régiókód.
|
||||
* **Rendszeresemények:**
|
||||
* Létrejön a `data.users` rekord `is_active = False` állapottal.
|
||||
* **Szerepkör:** Kényszerített kisbetűs `user` (Postgres Enum kényszer).
|
||||
* **Megerősítés:** Aktiváló email küldése egyedi hash kóddal.
|
||||
* **Válasz:** JWT token `status: pending_kyc` flaggel (korlátozott jogosultság).
|
||||
|
||||
### 1.2. Fázis: Banki KYC & Adatgyűjtés (Step 2)
|
||||
* **Végpont:** `POST /api/v1/auth/complete-kyc`
|
||||
* **Kötelező KYC adatok (Identity Verification):**
|
||||
* **Személyes:** Anyja születési neve, születési hely és idő.
|
||||
* **Okmányok:** Személyi igazolvány száma és lejárati ideje.
|
||||
* **Jogosítvány:** Vezetői engedély száma, lejárata és kategóriák (pl. AM, A, B, C, CE).
|
||||
* **Speciális:** Hajóvezetői és repülőgép-vezetői engedélyek (ha releváns).
|
||||
|
||||
### 1.3. Fázis: Atomi Tranzakció (Finalization)
|
||||
A KYC adatok beküldésekor a rendszer egyetlen megszakíthatatlan folyamatban hajtja végre:
|
||||
1. **Person létrehozása:** Identitás rögzítése JSONB dokumentumtárral a `data.persons` táblába.
|
||||
2. **Wallet inicializálás:** Pénztárca nyitása 0 Coin és 0 XP egyenleggel.
|
||||
3. **Privát Flotta (Private Org):** Automatikus szervezet létrehozása (`OrgType.INDIVIDUAL`), amely **nem átruházható** (`is_transferable = False`).
|
||||
4. **Aktiválás:** `is_active = True` státusz beállítása és teljes hozzáférés biztosítása.
|
||||
5. **Audit:** Bejegyzés az `audit_logs` táblába.
|
||||
|
||||
---
|
||||
|
||||
## 2. Meghívó és Jutalék Logika (Invitation Engine)
|
||||
A rendszer támogatja a többszintű ajánlói rendszert és a szervezeti meghívókat.
|
||||
|
||||
### 2.1. Meghívó Típusok
|
||||
- **`REG_ONLY`**: Általános meghívó, amely beköti az új felhasználót a 10-5-2%-os jutalék láncba.
|
||||
- **`COMPANY_JOIN`**: Meghatározott szervezetbe hív (pl. CEO, Flotta Manager vagy Sofőr szerepkörbe).
|
||||
|
||||
### 2.2. Jutalék Számítás
|
||||
A százalékos mérték a tranzakció pillanatában érvényes admin beállítások alapján rögzül (Snapshot). A jóváírandó kredit ($C$):
|
||||
|
||||
$$C = P_{amount} \cdot \frac{R_{level}}{100}$$
|
||||
|
||||
*Ahol $P$ a befizetett összeg, $R$ pedig az aktuális szint (10, 5 vagy 2) értéke.*
|
||||
**Szabály:** Csak az **első** Prémium csomag befizetésekor történik jutalékfizetés a láncban.
|
||||
|
||||
---
|
||||
|
||||
## 3. Technikai és Biztonsági Szabályok
|
||||
### 3.1. Adatbázis és Enum Kezelés
|
||||
- **Enum Case Sensitivity:** A PostgreSQL `userrole` típusa miatt minden értéket (pl. `user`, `admin`, `driver`, `service`) szigorúan **kisbetűvel** kell rögzíteni.
|
||||
- **Dinamikus Paraméterek:** Tilos a hardcoded értékek használata. Az alábbiakat a `data.system_settings` táblából kell lekérni:
|
||||
- `auth.reward_days`: Regisztrációs prémium hossza (default: 14).
|
||||
- `referral.level1-3`: Jutalék szintek mértéke.
|
||||
|
||||
### 3.2. Email Manager Protokoll (TypeError Fix)
|
||||
- **Szabály:** A `send_email` hívásakor **tilos** a `subject` paraméter kézi átadása.
|
||||
- **Logika:** A szerviz a `template_key` alapján automatikusan generálja a tárgyat a belső szótárából.
|
||||
|
||||
### 3.3. Social Auth (Google / Facebook)
|
||||
- A Step 1 lerövidül, de a **Step 2 (KYC) kötelező** marad az aktiváláshoz.
|
||||
- Amíg a KYC hiányzik, a felhasználó "GUEST" státuszban marad, korlátozott funkciókkal.
|
||||
|
||||
---
|
||||
|
||||
## 4. Jelszó Helyreállítási Protokoll (Recovery)
|
||||
A rendszer két biztonsági szintet különít el:
|
||||
|
||||
| Szint | Megnevezés | Logika |
|
||||
| :--- | :--- | :--- |
|
||||
| **A** | Standard | Email alapú visszaállítás ideiglenes tokennel. |
|
||||
| **B** | Szigorú (Banki) | Kötelező: Név, Anyja neve, Okmány szám. Ellenőrzés után SMS (telefonszám) vagy Email link. |
|
||||
|
||||
---
|
||||
|
||||
## 5. Corporate Onboarding (Céges Regisztráció)
|
||||
Célja, hogy egy létező Person saját szervezetet (Organization) alapítson.
|
||||
- **Validáció:** Kötelező adószám ellenőrzés (HU formátum + VIES API lekérdezés).
|
||||
- **Hierarchia:** A regisztráló automatikusan `owner` rangot kap.
|
||||
- **Izoláció:** Minden cég saját mappastruktúrát kap a NAS-on az okmányok fizikai elkülönítése érdekében.
|
||||
|
||||
---
|
||||
|
||||
## 6. Kormányozhatóság és .env Konfiguráció
|
||||
A biztonsági paraméterek környezeti változókon keresztül szabályozhatók:
|
||||
|
||||
| Paraméter | Leírás | Alapértelmezett |
|
||||
| :--- | :--- | :--- |
|
||||
| `REGISTRATION_TOKEN_EXPIRE_HOURS` | Aktiválásra álló idő | 48 óra |
|
||||
| `PASSWORD_RESET_TOKEN_EXPIRE_HOURS` | Visszaállítási időablak | 1 óra |
|
||||
|
||||
---
|
||||
|
||||
## 7. API Végpontok (Baseline v1)
|
||||
- `POST /api/v1/auth/register`: Komplett onboarding indítása.
|
||||
- `POST /api/v1/auth/complete-kyc`: KYC adatok beküldése és aktiválás.
|
||||
- `POST /api/v1/auth/invite/send`: Meghívó generálása.
|
||||
- `GET /api/v1/auth/invite/verify/{token}`: Token validálása.
|
||||
- `POST /api/v1/auth/recover-identity`: Szigorú (KYC alapú) helyreállítás.
|
||||
|
||||
## 5. Invitation Logic Specifications
|
||||
|
||||
### 5.1 Meghívó Kódok
|
||||
* **Formátum:** Véletlenszerű alfanumerikus string (pl. `A8B2X9`). NEM tartalmazhat személyes adatot.
|
||||
* **Generálás:** Minden "Meghívás" gombnyomásra új, egyedi token generálódik.
|
||||
|
||||
### 5.2 Lejárati Idők (TTL)
|
||||
A meghívók érvényessége a típustól függ:
|
||||
* **Magánszemély (C2C):** 72 óra (3 nap). Sürgető érzést kelt.
|
||||
* **Céges / Flotta (B2B):** 168 óra (1 hét). Figyelembe veszi a lassabb céges ügymenetet.
|
||||
|
||||
### 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).
|
||||
|
||||
## 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.
|
||||
15
archive/2026.02.18 Archive_old_mapps/V01_gemini/08_Frontend_Guide.md
Executable file
15
archive/2026.02.18 Archive_old_mapps/V01_gemini/08_Frontend_Guide.md
Executable file
@@ -0,0 +1,15 @@
|
||||
(UI irányelvek.)
|
||||
# 🖥️ FRONTEND GUIDE
|
||||
|
||||
## Tech Stack
|
||||
- Vue 3 (Composition API) + Vite.
|
||||
- Tailwind CSS (Utility-first design).
|
||||
- Pinia (State Management).
|
||||
|
||||
## Konfiguráció
|
||||
**SOHA** ne használj hardkódolt IP címet a kódban!
|
||||
Használd a `.env` fájlt: `VITE_API_BASE_URL=https://dev.profibot.hu/api`
|
||||
|
||||
## UI Logika
|
||||
- **Dumb Frontend:** Nem döntünk jogosultságról. Ha a backend azt mondja `can_edit: false`, a gombot letiltjuk.
|
||||
- **Offline Mód (Terv):** Service Worker (PWA) segítségével rögzítés net nélkül -> Sync, amint van hálózat.
|
||||
35
archive/2026.02.18 Archive_old_mapps/V01_gemini/09_Admin_API_Guide.md
Executable file
35
archive/2026.02.18 Archive_old_mapps/V01_gemini/09_Admin_API_Guide.md
Executable file
@@ -0,0 +1,35 @@
|
||||
# 🛠️ ADMIN MANAGEMENT & PERMISSIONS (v1.0)
|
||||
|
||||
## 1. Adminisztrátori Hiearchia és Területi Felosztás
|
||||
A rendszer többszintű, régió-alapú jogosultságkezelést alkalmaz (RBAC + Geographic Scope).
|
||||
|
||||
| Szint | Megnevezés | Területi hatókör | Jogkörök jellege |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **L0** | **SuperAdmin** | Globális (Összes ország) | Teljes hozzáférés, Rendszer-paraméterezés, Admin kinevezés. |
|
||||
| **L1/A** | **Global Director** | Régiós (Több ország) | Országos vezetők felügyelete, aggregált statisztikák. |
|
||||
| **L1/B** | **National Manager** | Országos (pl. HU) | Saját ország moderátorainak és adatainak teljes kezelése. |
|
||||
| **L2** | **Staff (Mod/Supp/Fin)** | Lokális / Szakaszolt | Operatív feladatok (VIES, support jegyek, kifizetések). |
|
||||
| **L3** | **Task Moderator** | Feladat-specifikus | Sablon alapú, korlátozott hozzáférés (pl. csak szerviz validálás). |
|
||||
|
||||
**Verseny Logika:** Az L1/B szintű vezetők látják más országok aggregált KPI mutatóit (statisztika), de nem látnak bele a konkrét személyes vagy céges adatokba.
|
||||
|
||||
## 2. Jogosultságkezelés és Sablonok
|
||||
- **Permissions Table:** Elemi jogosultságok tárolása (pl. `approve_vies`, `modify_credits`).
|
||||
- **Role Templates:** Előre definiált sablonok az egyszerű beállításhoz (pl. "Senior Financial - DE").
|
||||
- **Regionális Izoláció:** Az adminisztrátorok alapértelmezetten csak a hozzájuk rendelt `ISO_country_code` alá tartozó adatokat módosíthatják.
|
||||
|
||||
## 3. Biztonság és "Kill-Switch" Protokoll
|
||||
- **MFA/2FA:** A második bejelentkezéstől kezdve kötelező a TOTP (Google Authenticator) használata.
|
||||
- **Social Auth:** Adminok számára is engedélyezett (Google/FB), de nem váltja ki a kötelező 2FA-t.
|
||||
- **Anomaly Score (Fekete Doboz):**
|
||||
- Minden kattintást és módosítást logolunk (`audit_logs`).
|
||||
- Kritikus viselkedés (pl. tömeges törlés) esetén a rendszer automatikusan felfüggeszti az admint.
|
||||
- **SuperAdmin Recovery:** A SuperAdmin visszaállítása csak egyedi Offline Kulccsal és regisztrált eszközzel lehetséges.
|
||||
- **Értesítési lánc:** Tiltáskor a felette álló szintek azonnali riasztást kapnak.
|
||||
|
||||
## 4. Visszaállíthatóság (State Snapshot)
|
||||
Minden módosítás előtt a rendszer menti az aktuális rekord állapotát (JSON). Bármilyen károkozás vagy hiba esetén az L0/L1 szintű adminisztrátorok egy gombnyomással visszaállíthatják az eredeti adatokat.
|
||||
|
||||
## 5. Adminisztrátori Meghívók
|
||||
- Adminisztrátort csak kézi meghívóval lehet felvenni.
|
||||
- **Lejárati idő:** Minden admin meghívó token 24 óráig érvényes.
|
||||
@@ -0,0 +1,140 @@
|
||||
# 💰 10_BILLING_CREDITS_SUBSCRIPTIONS (v1.2)
|
||||
|
||||
## 1. Regionális és Valuta Logika (EU Scope)
|
||||
A rendszer többnyelvű és többvalutás elszámolást alkalmaz. Minden tranzakció kettős értéktárolással valósul meg az adatintegritás érdekében.
|
||||
|
||||
- **Local Cost:** A felhasználó régiója szerinti pénznemben rögzített összeg.
|
||||
- **Standard Cost (EUR):** A rögzítés pillanatában érvényes árfolyamon számolt alapérték.
|
||||
|
||||
**Átszámítási képlet:**
|
||||
$$Cost_{EUR} = Cost_{Local} \cdot ExchangeRate$$
|
||||
|
||||
---
|
||||
|
||||
## 2. Előfizetési Csomagok és Business Synergy
|
||||
A rendszer korlátait a `data.system_settings` tábla szabályozza. A csomagok skálázhatóak a flotta méretétől függően.
|
||||
|
||||
| Csomag | Jármű Limit | Kiemelt funkciók |
|
||||
| :--- | :--- | :--- |
|
||||
| **FREE** | 1 db | Alap költségnapló, GEO alapú szervizkereső. |
|
||||
| **PREMIUM** | 3 db | Dokumentumtár, export funkciók, útvonal alapú kereső. |
|
||||
| **PREMIUM+** | 5 db | Flotta statisztika, TCO (Total Cost of Ownership) elemzés. |
|
||||
| **VIP / VIP+** | 10+ db | Egyedi szervizkezelés, bővíthető slotok, prioritásos support. |
|
||||
|
||||
### 2.1. VIP Synergy Szabályok (Ösztönző rendszer)
|
||||
- **Synergy Discount:** Ha egy `FLEET_OWNER` aktív **VIP** vagy **VIP+** előfizetéssel rendelkezik, **15% kedvezményt** kap minden vásárlásra a saját privát flottájában is.
|
||||
- **Ajándék Kredit:** VIP vásárláskor extra kreditek járnak (felhasználható: skinek, medálok, privát Prémium csomag).
|
||||
- **Időbeli korlát:** A privát kedvezmények időtartama **2-6 hónapra korlátozott**, ösztönözve a folyamatos aktivitást.
|
||||
|
||||
---
|
||||
|
||||
## 3. Voucher és Kupon Rendszer
|
||||
A kedvezmények igénybevétele manuális kódbeíráshoz kötött. Minden felhasználást auditálni kell (`redeemed_at`, `user_id`, `original_price`).
|
||||
|
||||
- **Gift Card (Fix Kredit):** Meghatározott összegű jóváírás (pl. 5000 Ft).
|
||||
- **Subscription Coupon (%):** Százalékos kedvezmény az előfizetési díjból egy adott időszakra.
|
||||
- **Lejárat:** Minden kupon rendelkezik fix érvényességi idővel, amely után inaktívvá válik.
|
||||
|
||||
---
|
||||
|
||||
## 4. MLM Jutalomrendszer (Referral)
|
||||
A rendszer jutalmazza a sikeres meghívásokat az új tag **első** befizetése után. A százalékos érték a tranzakció pillanatában rögzül (Snapshot).
|
||||
|
||||
- **1. szint (Közvetlen):** 10% jóváírás.
|
||||
- **2. szint:** 5% jóváírás.
|
||||
- **3. szint:** 2% jóváírás.
|
||||
|
||||
---
|
||||
|
||||
## 5. Invitation Engine (Meghívó Rendszer)
|
||||
A spam elleni védelem érdekében a meghívók élettartama és mennyisége korlátozott:
|
||||
|
||||
- **Token Lejárati idők:**
|
||||
- **Felhasználói (User) meghívó:** 72 óra.
|
||||
- **Adminisztrátori meghívó:** 24 óra.
|
||||
- **Mennyiségi korlát:** Kezdő keret felhasználónként (alapértelmezett: 10 vagy 20 db).
|
||||
- **Anti-Spam Logika:** A felhasználó csak sikeres regisztrációk után kap vissza új meghívási lehetőségeket (slotokat).
|
||||
|
||||
---
|
||||
|
||||
## 6. Evidence & Trust Engine (Hitelesítés)
|
||||
A rendszerben a "Verified" (hiteles) státusz eléréséhez bizonyítékok szükségesek.
|
||||
|
||||
- **Kötelező bizonyítékok:** Munkalap fotó, számlakép és kilométeróra-állás fotó.
|
||||
- **GPS Check-in:** A szerviz eseménykor igazolni kell a helyszíni tartózkodást.
|
||||
- **Validáció:** Cég mint entitás nem hitelesíthet; a validálást mindig egy azonosított **Person** végzi.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 7. Lejárat és Pénzügyi Helyreállítás
|
||||
Ha az előfizetés lejár, a rendszer az alábbi fokozatos korlátozásokat vezeti be:
|
||||
|
||||
1. **Grace Period (30 nap):** Csak adatrögzítés lehetséges, a statisztikai modulok és exportok zárolva vannak.
|
||||
2. **Zárolás (60 nap):** A fiók írásvédetté válik (Read-only). Nincs új adatrögzítés.
|
||||
3. **Helyreállítás:** 6 hónapon belüli visszamenőleges befizetés esetén minden korábbi adat és funkció azonnal újraaktiválódik.
|
||||
|
||||
## 4. Economic Model & Exchange Rates
|
||||
|
||||
### 4.1 Dinamikus Árfolyamok (Admin Config)
|
||||
A rendszer támogatja a többvalutás elszámolást. Az átváltási arányok a `system_configs` táblából jönnek.
|
||||
* **Példa konfiguráció:**
|
||||
* 1 HUF = 50 Kredit
|
||||
* 1 EUR = 20.000 Kredit (változtatható)
|
||||
* 1 USD = 18.500 Kredit
|
||||
|
||||
### 4.2 Referral Commission (Admin Config)
|
||||
A jutalékrendszer paraméterezhető, alapértelmezett értékei:
|
||||
* **Level 1 (Közvetlen):** 10%
|
||||
* **Level 2:** 5%
|
||||
* **Level 3:** 2%
|
||||
* *Megjegyzés:* Adminisztrátori joggal ezek bármikor módosíthatók, visszamenőleges hatály nélkül.
|
||||
|
||||
### 4.3 Kifizetés (Payout)
|
||||
* **Threshold:** A kifizetés igénylésének alsó határa alapértelmezetten **1.000.000 Kredit**.
|
||||
* Ez az érték adminisztrátori döntéssel csökkenthető/növelhető a rendszer érettségétől függően.
|
||||
|
||||
|
||||
## 5. Marketplace & Vanity Items
|
||||
|
||||
### 5.1 Árazási Logika
|
||||
A rendszer támogatja a dinamikus árazást a kozmetikai elemeknél is.
|
||||
* **Fix áras termékek:** Egyszerű levonás a `coin_balance`-ból vagy `credit_balance`-ból.
|
||||
* **Időszakos ajánlatok:** A katalógusban beállítható `sale_price` és `sale_end_date`.
|
||||
|
||||
### 5.2 Vásárlási Folyamat
|
||||
1. **Check:** Van-e elég fedezet (Wallet)?
|
||||
2. **Deduct:** Tranzakció rögzítése a `wallet_transactions` táblában (`type='purchase_item'`).
|
||||
3. **Grant:** Tétel beírása a `user_inventory` táblába.
|
||||
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.
|
||||
|
||||
## 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.
|
||||
147
archive/2026.02.18 Archive_old_mapps/V01_gemini/11_Gamification_Social.md
Executable file
147
archive/2026.02.18 Archive_old_mapps/V01_gemini/11_Gamification_Social.md
Executable file
@@ -0,0 +1,147 @@
|
||||
(A Validációs Rendszer.)
|
||||
# 🏆 GAMIFICATION & SOCIAL VALIDATION
|
||||
|
||||
## 1. Validációs Logika (Q8)
|
||||
- **Hivatalos Szerviz:** Számla/Munkalap feltöltése -> Automatikus Trust Score növekedés.
|
||||
- **Magán/Sufni Javítás:** Rögzíthető, de "Low Trust" besorolást kap (csökkenti a jármű értékét), kivéve ha egy **Validátor** (High Rank User) igazolja.
|
||||
- **Validátor:** Olyan felhasználó, aki magas XP szinttel rendelkezik. Feladata: Képek és adatok ellenőrzése kreditért.
|
||||
|
||||
## 2. Véleményezés (Review)
|
||||
- **Szabály:** Csak "Verified Visit" után lehet értékelni (GPS vagy Számla).
|
||||
- **Fellebbezés:** A szerviz jelezheti, ha a vélemény valótlan. Ilyenkor a Moderátorok (vagy magas szintű Validátorok) döntenek.
|
||||
|
||||
## 3. "Service Hunt" (Szerviz Vadászat)
|
||||
A felhasználók játékosított formában validálják az adatbázist.
|
||||
|
||||
### 3.1 Validációs Szabályok
|
||||
* **Radius:** A felhasználónak **50-100 méteren** belül kell tartózkodnia a szerviz GPS koordinátáihoz képest a validáláshoz.
|
||||
* **Jutalom:** Csak akkor jár, ha a validáció sikeres (GPS + Fotó).
|
||||
* **Bot vs. Ember:**
|
||||
* Ha a Bot találta a szervizt, de nincs validálva: A felhasználó megkapja a "Validator" bónuszt.
|
||||
* Ha már validálva van (Status: Verified): A felhasználó látja a térképen, hogy "Már validálva", nem jár érte pont (kivéve adatfrissítés).
|
||||
|
||||
### 3.2 Okos Értékelési Rendszer (Review Logic)
|
||||
A rendszer védi a szolgáltatókat a "Review Bombing"-tól, de jutalmazza a konzisztenciát.
|
||||
|
||||
* **Negatív élmény (1-3 csillag):**
|
||||
* Egy felhasználótól **csak a legutolsó** negatív értékelés számít bele az átlagba.
|
||||
* Ha a user újra értékel (mert visszament), az előző negatív értékelés `is_active = False` státuszba kerül (de az admin látja az előzményeket).
|
||||
* **Pozitív élmény (4-5 csillag):**
|
||||
* Minden pozitív értékelés számít és összeadódik (kumulatív).
|
||||
* Ez ösztönzi a szervizt a folyamatos jó teljesítményre.
|
||||
|
||||
## 4. Social Flexing & Vanity Items
|
||||
A "dicsekvési faktor" kezelése.
|
||||
|
||||
### 4.1 Megjelenítési Helyek
|
||||
* **Profil oldalon:** A megszerzett jelvények (Badges) "vitrinje".
|
||||
* **Ranglistákon:** Kiemelt név, egyedi háttérszín vagy ikon a név mellett.
|
||||
* **Térképen:** Egyedi pin ikon a saját járműveknél (pl. arany színű autó ikon a térképen a sima kék helyett).
|
||||
|
||||
### 4.2 Ritkasági Szintek (Rarity)
|
||||
A tárgyakhoz ritkasági szintet rendelünk a `system_configs`-ban:
|
||||
1. **Common (Gyakori):** Bárki megveheti olcsón.
|
||||
2. **Rare (Ritka):** Drágább, vagy teljesítményhez kötött (pl. 10 validált szerviz).
|
||||
3. **Epic (Epikus):** Csak Prémium+ tagoknak vagy nagyon sok kreditbe kerül.
|
||||
4. **Legendary (Legendás):** Egyedi eventeken szerezhető (pl. "Service Hunt 2026 Győztes").
|
||||
|
||||
### 4.3 "Equipped" Status
|
||||
A felhasználónak lehet 50 jelvénye, de egyszerre (típustól függően) csak korlátozott számút mutathat meg (pl. 3 Slot a profilkép alatt). Ezt a `user_inventory.is_equipped` flag kezeli.
|
||||
|
||||
## 5. Büntetőpontok és Rehabilitáció (Strike System)
|
||||
|
||||
A rendszer 3-szintes büntetőrendszert alkalmaz a hibás vagy szándékosan téves adatok kiszűrésére.
|
||||
|
||||
### 5.1 Büntetőpontok (Strikes)
|
||||
* **Ok:** Szándékos félrevezetés, nem létező szerviz rögzítése, hamis fotók.
|
||||
* **Következmény:** 3 strike után a felhasználó véglegesen vagy ideiglenesen ki lesz tiltva a "Service Hunt" és validációs feladatokból.
|
||||
|
||||
### 5.2 Rehabilitációs Logika (Strike eltávolítás)
|
||||
Egy büntetőpont (1 strike) levonható az alábbi feltételek teljesülése esetén (Adminról állítható értékek):
|
||||
* **Javítás:** 10 sikeres és elfogadott adatjavítás (más hibájának korrigálása).
|
||||
* **Validáció:** 20 sikeres és megerősített validáció.
|
||||
* **Példás rögzítés:** 3 olyan új szerviz rögzítése, amit a Bot és az Admin is 100%-ban validnak talál.
|
||||
|
||||
### 5.3 Területi Monitoring (Geofence Blacklist)
|
||||
Amennyiben egy adott földrajzi körzetből (pl. egy városrész) kiugróan sok (százalékos arányban mérve) téves adat érkezik, a rendszer automatikusan korlátozhatja az onnan érkező új regisztrálók hozzáférését a szociális feladatokhoz, amíg az Admin felül nem vizsgálja a helyzetet.
|
||||
|
||||
## 6. Versenyrendszer (Leaderboards)
|
||||
|
||||
A közösségi munka (Service Hunt, Validáció) egy globális és régiós ranglistát táplál.
|
||||
|
||||
### 6.1 Ranglista kategóriák
|
||||
* **The Explorer (A Felfedező):** Legtöbb új szerviz rögzítése.
|
||||
* **The Verifier (A Hitelesítő):** Legtöbb sikeres adat-visszaigazolás.
|
||||
* **The Master Mechanic:** Legtöbb technikai adat kiegészítés.
|
||||
|
||||
### 6.2 Szintlépési Bónuszok (Milestones)
|
||||
A fejlődés nem csak dicsőség, hanem gazdasági előny is.
|
||||
* **Level 5:** 1.000 Kredit jutalom.
|
||||
* **Level 10:** 5.000 Kredit + "Expert" jelvény.
|
||||
* **Level 20:** Egyedi avatar keret + állandó 5% kedvezmény a hirdetési árakból (céges esetén).
|
||||
|
||||
### 6.3 Éves/Havi Szezonok
|
||||
Minden hónap végén az első 3 helyezett extra Kreditet vagy "Voucher"-t kap, amit a partnereinknél (szervizeknél) válthat be.
|
||||
|
||||
### 3. Jutalmazási Szabályok (Social Points)
|
||||
- **Célcsoport**: Kizárólag természetes személyek (`role: user`, `driver`).
|
||||
- **Kizárások**: Szervezetek (Organizations) és Adminisztrátorok nem gyűjtenek XP-t.
|
||||
- **Logika**: Minden `PointsLedger` bejegyzés kötelezően hivatkozik egy `user_id`-ra.
|
||||
- **Mezőnevek**: Adatbázis szinten a pontok az `id`, `user_id`, `points`, `reason` mezőkben tárolódnak.
|
||||
|
||||
## 2026.02.10 FRISSÍTÉS - GAMIFICATION ÖKOSZISZTÉMA
|
||||
|
||||
### 1. Pontrendszer Logika
|
||||
A rendszer különválasztja a tekintélyt és a jutalmat:
|
||||
- **XP (Tapasztalat):** Végleges szintlépéshez. Képlet: $BaseXP \times Level^{1.5}$. (Nehezedő görbe).
|
||||
- **Social Points (Szezonális):** Időszakos versenyekhez (pl. Hónap Vadásza).
|
||||
- **Kredit:** Fizetőeszköz, amit Social Pontokból lehet váltani (pl. 1000 pont = 100 Kredit).
|
||||
|
||||
### 2. Konfiguráció
|
||||
Minden érték (szorzók, határok) a \`GAMIFICATION_MASTER_CONFIG\` JSON paraméterben állítható Admin felületről, kódmódosítás nélkül.
|
||||
|
||||
### 3. Audit
|
||||
Minden pontmozgás a \`PointsLedger\` táblába kerül rögzítésre a visszakövethetőség érdekében.
|
||||
|
||||
XP Formula: $XP_{required} = BaseXP \times Level^{1.5}$Penalty Logic: restriction_level bevezetése (0-3).Weighting: Saját adat vs. Közösségi adat súlyozási táblázata.
|
||||
|
||||
# 11. Gamification és Social Engine Specifikáció
|
||||
|
||||
## 1. XP (Experience Points) - A Tekintély
|
||||
Az XP a felhasználó végleges, nem csökkenthető tekintélypontja.
|
||||
- **Képlet:** A szintlépéshez szükséges összes XP:
|
||||
$$XP_{total} = 500 \times Level^{1.5}$$
|
||||
- **Súlyozás:**
|
||||
- **Saját adat (Fleet):** Alacsony érték (pl. 10 XP).
|
||||
- **Közösségi adat (Service Discovery):** Magas érték (pl. 100 XP).
|
||||
|
||||
## 2. Social Points - A Valuta Alapja
|
||||
Szezonális pontok, amelyek Kreditre válthatóak.
|
||||
- **Váltószám:** Alapértelmezett: 100 Social Point = 1 Kredit.
|
||||
- **Váltási mód:** Automatikus (rendszerparaméter alapján) vagy manuális (felhasználói döntés).
|
||||
|
||||
## 3. Trust & Penalty Engine (Büntetőrendszer)
|
||||
A rendszer integritásának védelme érdekében hibapontokat (Penalty Points) alkalmazunk.
|
||||
- **Szintek (Restriction Level):**
|
||||
- **0 (Normal):** Teljes pontszorzó (1.0x).
|
||||
- **1 (Warning):** Csökkentett pontszerzés (0.5x).
|
||||
- **2 (Restricted):** Szigorú moderátori ellenőrzés minden adatnál, 0.1x pontszerzés.
|
||||
- **3 (Blocked):** Pontszerzés és adatbeküldés tiltva.
|
||||
- **Ledolgozás:** Minden pozitív XP szerzés a büntetőpontokat is csökkenti (pl. 1 XP jóváírás = 0.5 Penalty pont levonás).
|
||||
|
||||
## 4. Szintlépési Bónuszok
|
||||
Minden 10. szint elérésekor a rendszer automatikus Kredit jutalmat oszt a `GAMIFICATION_MASTER_CONFIG` alapján.
|
||||
|
||||
## 5. Büntetőrendszer (Strike System)
|
||||
A rendszer integritásának megőrzése érdekében hibapontokat alkalmazunk, amelyek befolyásolják a pontszerzés hatékonyságát.
|
||||
|
||||
- **Szorzók (Multipliers):**
|
||||
- Level 0 (Normal): 1.0x
|
||||
- Level 1 (Warning): 0.5x
|
||||
- Level 2 (Restricted): 0.1x
|
||||
- Level 3 (Blocked): 0.0x
|
||||
|
||||
- **Ledolgozás (Recovery):**
|
||||
A büntetőpontok pozitív aktivitással (XP szerzéssel) ledolgozhatóak. Az elért XP egy admin által meghatározott része (alapértelmezett: 50%) levonásra kerül a büntetőpontokból.
|
||||
|
||||
- **Admin-Vezérelt Küszöbök:** Minden szintváltási határ a `GAMIFICATION_MASTER_CONFIG` paraméterben definiált.
|
||||
@@ -0,0 +1,18 @@
|
||||
(Üzemeltetés.)
|
||||
# ⚙️ OPERATIONS & MONITORING
|
||||
|
||||
## Backup Stratégia
|
||||
- **Napi:** Teljes SQL dump a NAS-ra (`/mnt/nas/backup`).
|
||||
- **Rotáció:** 7 napi, 4 heti, 12 havi mentés megőrzése.
|
||||
- **MinIO:** Napi rsync a statikus fájlokról.
|
||||
|
||||
## Monitoring
|
||||
- **Dozzle:** Valós idejű log nézegető (Port 8888).
|
||||
- **Healthcheck:** Docker `healthcheck` minden konténeren.
|
||||
- **Alerts:** Email értesítés, ha az API 5xx hibát dob.
|
||||
|
||||
## 4. Anti-Fraud & Device Logging
|
||||
|
||||
A visszaélések elkerülése érdekében a rendszer rögzíti a beküldéshez használt eszközök adatait.
|
||||
* **Device Fingerprinting:** Egyedi azonosító rögzítése (`device_id`).
|
||||
* **Metadata Validation:** Képek feltöltésekor kötelező az EXIF GPS adatok ellenőrzése. Amennyiben az EXIF adatok hiányoznak vagy eltérnek a rögzített helyszíntől (>250m), a bejegyzés automatikusan "Manual Review" státuszba kerül.
|
||||
74
archive/2026.02.18 Archive_old_mapps/V01_gemini/13_Roadmap_Tech_Debt.md
Executable file
74
archive/2026.02.18 Archive_old_mapps/V01_gemini/13_Roadmap_Tech_Debt.md
Executable file
@@ -0,0 +1,74 @@
|
||||
(Mit csinálunk most?)
|
||||
# 🗺️ ROADMAP & TECH DEBT
|
||||
|
||||
# 🗺️ ROADMAP & TECH DEBT (v1.4)
|
||||
|
||||
## 🚧 SPRINT 1 (Azonnali - Stabilitás)
|
||||
1. **Frontend Config:** Hardkódolt IP-k cseréje `.env` változókra.
|
||||
2. **Step 1 Regisztráció Fix:** A meglévő endpoint átalakítása "Lite" regisztrációra (csak User létrehozás, `is_active=False`).
|
||||
3. **Enum Case Sensitivity:** Minden DB query felülvizsgálata, hogy a `role` mező kényszerítve kisbetűs legyen.
|
||||
4. **Security Module:** `create_access_token` és `verify_password` funkciók véglegesítése a `core/security.py`-ban.
|
||||
|
||||
## 🚧 SPRINT 2 (KYC & Onboarding)
|
||||
1. **Step 2 KYC Endpoint:** `POST /api/v1/auth/complete-kyc` megvalósítása.
|
||||
2. **Atomi Tranzakció Logic:** A Person, Wallet és Private Org egyidejű létrehozása a KYC beküldésekor.
|
||||
3. **Verification Email:** Aktiváló link generálása és kiküldése hash kóddal.
|
||||
4. **Admin UI Settings:** Felület a `system_settings` tábla kezeléséhez.
|
||||
|
||||
## 📅 SPRINT 3 (Marketplace MVP)
|
||||
1. **OCR Pipeline:** Számla/Okmány fotó feltöltés MinIO-ba + AI validáció teszt.
|
||||
2. **Service Request:** Frontend űrlap ajánlatkéréshez.
|
||||
|
||||
|
||||
# ROADMAP & TECH DEBT (v1.0)
|
||||
## 🚧 SPRINT 1 (Azonnali)
|
||||
1. **Frontend Config:** Hardkódolt IP-k cseréje `.env` változókra.
|
||||
2. **Person Migráció:** DB szkript futtatása (User -> Person).
|
||||
3. **API Fix:** `/api/v1/users/me` 404 javítása.
|
||||
4. **Soft Delete:** Ellenőrzés, hogy minden `SELECT` tartalmazza-e a `deleted_at IS NULL` feltételt.
|
||||
|
||||
## 📅 SPRINT 2 (Marketplace MVP)
|
||||
1. **OCR Pipeline:** MinIO feltöltés + Tesseract teszt.
|
||||
2. **Service Request:** Frontend űrlap ajánlatkéréshez.
|
||||
3. **Ranking Engine:** Távolság + Súlyozás algoritmus implementálása.
|
||||
|
||||
# 13. Roadmap és Technikai Adósság (v1.2.6)
|
||||
|
||||
Ez a dokumentum rögzíti a rendszer fejlesztési fázisait és azokat a technikai kompromisszumokat, amelyeket a gyors haladás érdekében hoztunk, de később felülvizsgálatot igényelnek.
|
||||
|
||||
## 13.1 Rövid távú Roadmap (Q1-Q2)
|
||||
|
||||
### 1. Intelligens Kereső API (Fuzzy Search)
|
||||
- **Cél:** A `synonyms` mezőben tárolt alternatív nevek kihasználása.
|
||||
- **Megvalósítás:** PostgreSQL `tsvector` és `GIN` indexek használata, hogy a kereső akkor is találjon eredményt, ha a felhasználó "Tracer"-t ír be "Yamaha MT-09 Tracer" helyett.
|
||||
|
||||
|
||||
### 2. Média Kezelés & MinIO Integráció
|
||||
- **Cél:** Járműfotók automatikus beszerzése.
|
||||
- **Megvalósítás:** Új bot fejlesztése, amely a dúsított `marketing_name` alapján hivatalos sajtófotókat keres, és azokat a már futó MinIO objektumtárba menti.
|
||||
|
||||
### 3. Robot 4: Service Hunter (Szerviz-logika)
|
||||
- **Cél:** Karbantartási tervek generálása.
|
||||
- **Megvalósítás:** A `specifications` (olajmennyiség, gyertya típus) mezőkből kiindulva szerviz-csomagok és árak kalkulálása.
|
||||
|
||||
## 13.2 Technikai Adósság (Tech Debt)
|
||||
|
||||
### 1. Adattípus Optimalizálás: JSON vs. JSONB
|
||||
- **Helyzet:** A `synonyms` és `specifications` mezők jelenleg `JSON` típusúak.
|
||||
- **Adósság:** A Postgres függvények (pl. `jsonb_array_length`) használatához folyamatos casting (`::jsonb`) szükséges, ami lassítja a lekérdezéseket.
|
||||
- **Megoldás:** Egy Alembic migráció keretében az összes JSON oszlopot át kell állítani `JSONB` típusra.
|
||||
|
||||
|
||||
### 2. "N/A-{id}" és "UNKNOWN-{id}" Kódok Tisztítása
|
||||
- **Helyzet:** A NOT NULL és UNIQUE kényszerek miatt a robot egyedi ál-kódokat generál, ha az AI nem talál gyári kódot.
|
||||
- **Adósság:** Ezek nem valódi technikai kódok.
|
||||
- **Megoldás:** Szükséges egy manuális felülvizsgálati (Manual Review) felület, ahol az operátorok a `N/A` kódú rekordokat ellenőrizhetik vagy egyesíthetik.
|
||||
|
||||
### 3. AI Response Parsing (Regex Workaround)
|
||||
- **Helyzet:** A Gemini Search Tool letiltja a kényszerített JSON választ, ezért Regex-szel bányásszuk ki a JSON-t a nyers szövegből.
|
||||
- **Adósság:** Ez a megoldás törékeny, ha az AI stílusa jelentősen megváltozik.
|
||||
- **Megoldás:** Monitorozni kell az AI API frissítéseit; amint a Google engedélyezi a Search + Controlled Generation kombinációt, vissza kell térni a natív JSON módra.
|
||||
|
||||
## 13.3 Hosszú távú Vízió (Q3+)
|
||||
- **Trust Engine:** A járművek történetének és szervizadatainak hitelesítése.
|
||||
- **Global Fleet Insight:** Flottaszintű elemzések készítése a dúsított MDM adatok alapján.
|
||||
508
archive/2026.02.18 Archive_old_mapps/V01_gemini/15_Changelog.md
Executable file
508
archive/2026.02.18 Archive_old_mapps/V01_gemini/15_Changelog.md
Executable file
@@ -0,0 +1,508 @@
|
||||
(Változásnapló.)
|
||||
# 📜 CHANGELOG
|
||||
|
||||
## [1.0.1] - 2026-02-06
|
||||
|
||||
### Hozzáadva
|
||||
- **Unified Auth Module**: Integrált Belépés, Lite Regisztráció és Elfelejtett jelszó kezelés.
|
||||
- **Email Rendszer**: SendGrid integráció SMTP fallback lehetőséggel.
|
||||
- **KYC Előkészítés**: `is_active` flag bevezetése a `User` és `Person` modellekben a 2-lépcsős folyamathoz.
|
||||
|
||||
### Javítva
|
||||
- **SQLAlchemy Mapper Fix**: Megszűnt az `owned_organizations` körkörös függőségi hiba.
|
||||
- **Típus Szinkron**: `Person.id` javítva `BigInteger` típusra a Postgres sémával összhangban.
|
||||
- **Import Fixek**: `app.db.base_class` -> `app.db.base` útvonalak egységesítve.
|
||||
|
||||
### Technikai adatok
|
||||
- Konténer állapot: Stabil (running)
|
||||
- Regisztrációs folyamat: Step 1 (Lite) tesztelve, sikeres.
|
||||
|
||||
## [1.0.0] - 2026-02-03
|
||||
- **Init:** Grand Master Book létrehozása.
|
||||
- **Arch:** Átköltözés a 80 magos szerverre.
|
||||
- **Spec:** Kredit rendszer, Tiers, Soft Delete és Person logika véglegesítése.
|
||||
|
||||
### [2026-02-04] - Identity & Company Sync (v1.2)
|
||||
- **Modell Konszolidáció:** Az `app.models.identity` lett a központi identitáskezelő (User, Person, Wallet).
|
||||
- **Master Book v1.2 Implementáció:** Bevezetésre került a céges verifikációs logika (is_verified) és a 30 napos türelmi idő kezelése.
|
||||
- **Integritás javítás:** Az `Organization` tábla bővítve lett `is_transferable` és hitelesítési mezőkkel.
|
||||
- **Bugfix:** `security.py` IndentationError javítva, `auth_service.py` atomikus regisztrációs flow Master Book szinkronizálva.
|
||||
- **Security:** PostgreSQL tábla-tulajdonosi jogosultságok felülvizsgálata a migrációs hibák elhárításához.
|
||||
|
||||
### [2026-02-05] - Identity & Company Sync (v1.2)
|
||||
- **Database Security:** Javítva a `user_vehicle_equipment` tábla tulajdonosi jogosultsága (`shared-postgres` környezetben).
|
||||
- **Core Fix:** A `security.py` állomány behúzási hibái (IndentationError) véglegesen elhárítva.
|
||||
- **Organization v1.2:** Implementálva az `is_transferable`, `is_verified` és `verification_expires_at` mezők a flották hitelesítéséhez.
|
||||
- **AuthService Logic:** - Az `INDIVIDUAL` típusú flották mostantól alapértelmezetten nem átruházhatóak.
|
||||
- Beépítve a 30 napos türelmi idő (`grace_period`) kalkulációja a cégellenőrzéshez.
|
||||
- Atomikus regisztráció kiterjesztve a privát flották automatikus létrehozására.
|
||||
- **Infrastructure:** Alembic migrációs lánc szinkronizálva az új modellekkel.
|
||||
|
||||
### [2026-02-05] - Admin & Economy Finalization (v1.0)
|
||||
- **Admin Management:** Teljes hiearchia és területi felosztás kidolgozva (L0-L3).
|
||||
- **Security:** "Kill-switch" anomália-figyelés és 2FA kényszerítés rögzítve.
|
||||
- **Economy:** 10-5-2% jutalékrendszer és Voucher/Coupon logika specifikálva.
|
||||
- **Synergy:** Céges VIP és privát flotta közötti kedvezmény-szinergia kidolgozva.
|
||||
- **Invitations:** Meghívó limitációs és anti-spam logika rögzítve.
|
||||
|
||||
# 📓 CHANGELOG - SERVICE FINDER
|
||||
|
||||
## [1.2.1] - 2026-02-05
|
||||
### ✅ Hozzáadva (Added)
|
||||
- **Multi-step Social Auth:** `User` modell bővítve `social_provider` és `social_id` mezőkkel.
|
||||
- **Flotta Tulajdonjog:** `Organization` modellben `is_transferable` flag implementálva (Individual flotta zárolva).
|
||||
- **Referral Snapshot:** Előkészítve a 10-5-2%-os jutalékrendszer adatmodellje.
|
||||
|
||||
### 🛠️ Javítva (Fixed)
|
||||
- **SQLAlchemy Mapper:** Megszűnt a `UserVehicle` KeyError hiba a string-alapú hivatkozásokkal.
|
||||
- **Duplikáció:** `Vehicle` osztály duplikációja eltávolítva a `vehicle.py`-ból.
|
||||
- **Indentation Error:** `security.py` bcrypt indentációs hiba javítva.
|
||||
|
||||
### ⚠️ Megjegyzés
|
||||
- Alembic migráció szükséges az új `Organization` és `User` mezőkhöz.
|
||||
|
||||
📓 CHANGELOG (Rögzítendő változások)
|
||||
|
||||
Mivel kérted, itt van a változások listája, amit a teszt után beírhatunk:
|
||||
|
||||
Fixed: UserRole enum validációs hiba (Postgres userrole típus mostantól kisbetűs értéket kap).
|
||||
|
||||
Added: Teljes banki KYC integráció a regisztrációba (Személyi, Jogosítvány, Speciális engedélyek).
|
||||
|
||||
Added: Atomi tranzakció részeként automatikus OrganizationMember létrehozás a privát flottához.
|
||||
|
||||
Added: Audit log rögzítése minden sikeres regisztrációról.
|
||||
|
||||
Added: Dinamikus paraméterkezelés (system_settings) a 14 napos jutalomhoz.
|
||||
|
||||
Elvárt eredmény: A tranzakció végén létrejön a Person, a Wallet (0 Coin) és a Private Fleet (is_transferable=False). A User is_active értéke True lesz.
|
||||
|
||||
3. Debugging Checklist
|
||||
|
||||
500 Error? Ellenőrizd a docker logs -f service_finder_api kimenetét. Ha "UndefinedColumn", akkor hiányzik egy SQL mező. Ha "InvalidTextRepresentation", akkor Enum hiba (nagybetűs string).
|
||||
|
||||
Üres Swagger? Ellenőrizd az importokat a security.py-ban és a sémákat az endpoints/auth.py-ban.
|
||||
|
||||
|
||||
---
|
||||
|
||||
### 💡 Javaslatom a dokumentáció kiegészítésére:
|
||||
A fejlesztések rendben tartásához javaslom a **`17_DEVELOPER_NOTES_AND_PITFALLS.md`** fájl aktív használatát is, amit az előző körben küldtem. Ez segít megelőzni, hogy a fejlesztőcsapat újra belefusson a Postgres Enum vagy a `Base.metadata.create_all` korlátaiba.
|
||||
|
||||
|
||||
|
||||
**Holnap reggel frissíted a GEM beállításokat is?** Ha igen, a következő lépésben elkészíthetem neked a Step 2 (KYC) végleges Pydantic sémáját és a `complete-kyc` végpont vázlatát!
|
||||
|
||||
## [0.2.0] - 2026-02-07
|
||||
|
||||
### ✨ Hozzáadva (Added)
|
||||
- **Step 2 (KYC) Folyamat:** Teljes körű identitás-kezelés (telefonszám, születési adatok, okmányok, ICE kontakt).
|
||||
- **Automata Privát Flotta:** Minden felhasználóhoz automatikusan létrejön egy `individual` típusú szervezet (Privát Széf).
|
||||
- **Automata Wallet:** Minden validált felhasználó kap egy üres pénztárcát (Coin és XP egyenleggel).
|
||||
- **Trust Tiers:** Bevezetésre került a fokozatos bizalmi szint (Tier 1: Email, Tier 2: KYC/Active).
|
||||
|
||||
### 🛠️ Javítva (Fixed)
|
||||
- **SQLAlchemy Async Fix:** `joinedload` alkalmazása a User-Person kapcsolathoz (MissingGreenlet hiba elhárítva).
|
||||
- **JSON Serialization:** Pydantic `model_dump(mode='json')` használata a JSONB mezőkhöz (dátum-konverziós hiba javítva).
|
||||
- **Postgres Schema:** `data.organizations` tábla bővítve hiányzó oszlopokkal (`is_verified`, `updated_at`, stb.).
|
||||
- **Auth Endpoint:** `/complete-kyc` végpont hozzáadva és JWT védelemmel ellátva.
|
||||
|
||||
### ⚙️ Adatbázis Változások (Database)
|
||||
- Új Enum típus: `data.orgtype` ('individual', 'company').
|
||||
- `data.persons` bővítve: `phone`, `birth_place`, `birth_date`, `mothers_name`, `identity_docs`, `ice_contact`.
|
||||
- `data.organizations` bővítve: `is_verified`, `is_transferable`, `verification_expires_at`, `updated_at`.
|
||||
|
||||
## [0.2.0] - 2026-02-07
|
||||
### ✅ Step 2 KYC & Activation Complete
|
||||
- **Funkció:** Teljes körű személyazonosság-kezelés és fiókaktiválás.
|
||||
- **Automatizálás:** Regisztrációkor automatikusan létrejön a "Privát Flotta" (Organization) és a digitális pénztárca (Wallet).
|
||||
- **Adatvédelem:** Elkészült a "Digitális Széf" logika az okmányok és vészhelyzeti adatok biztonságos tárolására.
|
||||
- **Technikai fix:** SQLAlchemy `joinedload` integráció az aszinkron adatkezeléshez és JSON-safe dátumkezelés.
|
||||
|
||||
## [0.3.0] - 2026-02-07
|
||||
|
||||
### ✨ Hozzáadva (Added)
|
||||
- **Asset DNS Modell:** Új, univerzális eszközkezelő rendszer (Assets, VehicleCatalog, AssetEvents, AssetRatings).
|
||||
- **Harvester Robot:** Automata adatgyűjtő rendszer, amely külső forrásokból tölti fel a globális járműkatalógust.
|
||||
- **UUID Implementáció:** Az eszközök (Assets) és események (Events) mostantól biztonságos UUID azonosítókat használnak.
|
||||
|
||||
### ⚙️ Adatbázis Változások (Database)
|
||||
- `data.vehicle_catalog` tábla létrehozva a globális specifikációknak.
|
||||
- `data.assets` tábla létrehozva a konkrét példányok (VIN/HIN alapú) tárolására.
|
||||
- `data.asset_events` és `data.asset_ratings` táblák az életút és közösségi visszajelzések kezelésére.
|
||||
|
||||
### 🛠️ Refaktor (Refactor)
|
||||
- **Modell Konszolidáció:** A korábbi `Vehicle` és `VehicleBrand` modellek beolvasztva az új `Asset` és `VehicleCatalog` struktúrába.
|
||||
- **Kapcsolati Térkép:** Az `Organization` és `User` modellek frissítve az új Asset logikához.
|
||||
|
||||
## [0.3.5] - 2026-02-07
|
||||
### ✨ Robot Technológia & Adatbiztonság
|
||||
- **Multi-Robot Architektúra:** Előkészítve a kategória-specifikus (Car, Bike, Truck) Harvester robotok szétválasztása.
|
||||
- **Status Tracking:** Bevezetve a `verification_status` a katalógus elemekhez a hiányos adatok kezelésére.
|
||||
- **SQL Optimalizálás:** Új indexek és kategória alapú szűrések hozzáadva a globális katalógushoz.
|
||||
|
||||
## [0.4.0] - 2026-02-07
|
||||
### ✨ Multi-Robot System
|
||||
- **Kategória Robotok:** Elkészült a Car, Bike és Truck harvester moduláris szerkezete.
|
||||
- **Robot Manager:** Központi vezérlő az ütemezett és sorrendi adatgyűjtéshez.
|
||||
- **Katalógus Kereső:** Üzembe helyezve a `/catalog/search` végpont a Swaggerben.
|
||||
|
||||
## [0.4.5] - 2026-02-07
|
||||
### ✨ Asset Management & Infrastructure
|
||||
- **Asset Endpoint:** `POST /api/v1/assets/` élesítve VIN validációval.
|
||||
- **NAS Integration:** Automata mappastruktúra létrehozása az eszközöknek (`/assets/{uuid}`).
|
||||
- **Data Model:** `privacy_level` és `status` mezők hozzáadva az Asset modellhez.
|
||||
- **Bugfix:** SQLAlchemy `TypeError` javítva a modell és a séma szinkronizálásával.
|
||||
|
||||
## [0.5.0] - 2026-02-07
|
||||
### ✨ Corporate & CRM Foundation
|
||||
- **Corporate Onboarding:** `POST /api/v1/organizations/onboard` végpont élesítve.
|
||||
- **Validation:** Magyar adószám (HU) formátum ellenőrzés beépítve.
|
||||
- **Status Management:** Bevezetve a `pending_verification` állapot a szervezetekhez.
|
||||
- **Database:** PostgreSQL `orgtype` Enum szinkronizálva a Python modellel (kisbetűs mapping).
|
||||
- **NAS:** Automata szervezeti mappa-izoláció (`/organizations/{id}`).
|
||||
|
||||
[0.5.1] - 2026-02-07
|
||||
|
||||
FIX: ModuleNotFoundError javítva az importok szinkronizálásával.
|
||||
|
||||
DATA: Atomizált címmezők hozzáadva a data.organizations táblához.
|
||||
|
||||
LOGIC: Háromszintű névkezelés (Hivatalos, Rövid, Display) bevezetve.
|
||||
|
||||
## [2.1.0] - 2026-02-08
|
||||
|
||||
### Hozzáadva (Added)
|
||||
- **Hibrid Címkezelő Rendszer**: Új `data.addresses` központi tábla, amely UUID alapú azonosítással köti össze a személyeket, cégeket és szervizeket.
|
||||
- **Öntanuló GeoService**: A rendszer rögzítéskor automatikusan bővíti a ZIP-kód, város és utcanév szótárakat.
|
||||
- **Autocomplete API**: `/api/v1/services/suggest-street` végpont a frontend gépelés közbeni támogatásához.
|
||||
- **Kétlépcsős Keresés**: `/api/v1/services/search` végpont, amely megkülönbözteti a légvonalbeli (Free) és útvonal/idő alapú (Premium) kalkulációt.
|
||||
- **PostGIS Integráció**: Tűpontos GPS távolságmérés `geography` casting használatával.
|
||||
|
||||
### Javítva (Fixed)
|
||||
- **Gamifikációs hiba**: A `PointsLedger` modellben javítva a `points` mezőnév (TypeError: points_change fix).
|
||||
- **Adatbázis Inkonzisztencia**: Létrehozva a hiányzó `data.user_stats` tábla.
|
||||
- **Import hibák**: `Optional`, `UploadFile` és `File` hiányzó importok pótolva a szolgáltatás végpontokon.
|
||||
|
||||
### Változtatva (Changed)
|
||||
- **Címkezelési Logika**: A cégek és magánszemélyek mostantól egységes, bontott címstruktúrát (zip, city, street, street_type, house_number, parcel_id) használnak.
|
||||
- **XP Szűrés**: A szervizek és cégek rögzítésekor a rendszer mostantól csak a természetes személyeknek (User/Driver) oszt social pontokat.
|
||||
|
||||
## [2.1.0] - 2026-02-08
|
||||
- **Feat**: Hibrid címkezelő rendszer bevezetése (UUID alapú `data.addresses`).
|
||||
- **Feat**: Öntanuló Geo-logika (Auto-create ZIP/Street).
|
||||
- **Feat**: Kétlépcsős (Free/Premium) szervizkereső API.
|
||||
- **Fix**: `points_ledger` mezőnév szinkronizáció.
|
||||
- **Fix**: `data.user_stats` tábla inicializálása.
|
||||
|
||||
## [2026-02-08] - Nemzetközi Asset és KYC Stabilizáció
|
||||
|
||||
### Hozzáadva
|
||||
- **Nemzetközi paraméterek**: `mileage_unit` (km/miles/hours) és `reading_unit` támogatása az Asset modellben.
|
||||
- **Pénzügyi alapok**: `AssetCost` modell bővítése nettó/bruttó összeggel, ÁFA kulccsal és deviza-kezeléssel.
|
||||
- **Árfolyamkezelés**: `exchange_rates` tábla implementálása MNB/ECB alapú napi frissítéshez.
|
||||
- **Értékelési rendszer**: `ratings` tábla létrehozva (user, asset, service_provider szinten).
|
||||
|
||||
### Javítva
|
||||
- **KYC Folyamat**: Anyja neve bontása vezetéknévre és keresztnévre a magyar/nemzetközi szabványok szerint.
|
||||
- **Database Schema**: Számos hiányzó oszlop pótolva (`asset_events.data`, `asset_events.event_date`, `user_stats.total_xp`).
|
||||
- **SQLAlchemy hiba**: Javítva az `IndexError` a katalógus lekérdezésnél és az import hiba a `PG_UUID` kapcsán.
|
||||
|
||||
### Megjegyzés
|
||||
A rendszer most már képes egyetlen KYC folyamat alatt aktiválni a felhasználót, létrehozni az egyéni flottáját, inicializálni a pénztárcáját (Kredit/Coin) és rögzíteni az első járművét kezdő km-óra állással.
|
||||
|
||||
## [Unreleased] - 2026-02-10
|
||||
|
||||
### 🚀 Added (Új funkciók)
|
||||
- **RBAC System:**
|
||||
- \`User\` tábla bővítése: \`scope_level\`, \`scope_id\`, \`custom_permissions\`.
|
||||
- \`system_parameters\` tábla létrehozása a globális JSON konfigurációkhoz.
|
||||
- Master RBAC JSON konfiguráció seedelése.
|
||||
- **Gamification:**
|
||||
- \`GamificationService\` létrehozása (XP, Level, Credit logika).
|
||||
- Automata pontszámítás és nehezedő szintek logikája.
|
||||
- **API Modularitás:**
|
||||
- \`assets.py\` szétbontása 3 végpontra (Identity, Costs, Telemetry).
|
||||
|
||||
### 🛠 Changed (Módosítások)
|
||||
- **Asset Model:** Az \`Asset\` entitás mostantól lazy loading helyett \`selectinload\` stratégiát használ a teljesítmény érdekében.
|
||||
- **Error Handling:** Javítottuk az \`asyncpg\` többszörös parancs-futtatási hibáját a setup scriptekben.
|
||||
- **Configuration:** A rendszerbeállítások mostantól adatbázis-alapúak (JSONB) a hardcoded konstansok helyett.
|
||||
|
||||
### 🐛 Fixed (Javítások)
|
||||
- **Schema Mismatch:** SQLAlchemy modellek és Pydantic sémák szétválasztása (`models/asset.py` vs `schemas/asset.py`).
|
||||
- **Data Integrity:** \`updated_at\` és \`is_active\` oszlopok pótlása a \`system_parameters\` táblában.
|
||||
- **API Stability:** \`getattr\` használata a hiányzó opcionális mezőknél (pl. \`net_amount\`), hogy ne szálljon el az API 500-as hibával.
|
||||
|
||||
## [1.2.0] - 2026-02-10
|
||||
|
||||
### Added
|
||||
- **Asset Financials 2.0**: Pivot-Currency modell implementálva (helyi deviza + EUR párhuzamos tárolás).
|
||||
- **Smart Auth Token**: JWT token mostantól tartalmazza a `rank`, `scope_level` és `scope_id` mezőket a gyors jogosultságkezeléshez.
|
||||
- **CostService**: Automatikus árfolyam-kalkuláció, telemetria-szinkron és XP jóváírás költségrögzítéskor.
|
||||
- **ExchangeRate**: Új árfolyamtábla és modell az EUR alapú váltásokhoz.
|
||||
|
||||
### Fixed
|
||||
- **Circular Import Resolution**: Megszüntetve a `db.base` és a `models` közötti körkörös függőség az import lánc modularizálásával.
|
||||
- **Alembic Identity Sync**: Visszaállítva a `User` modell hiányzó `scope_level` és `custom_permissions` mezői, megakadályozva az adatvesztést migrációkor.
|
||||
- **NotNullViolationError**: Fixálva az `asset_costs` tábla migrációja (amount_local NOT NULL kényszer).
|
||||
|
||||
### Changed
|
||||
- `AssetCost` modell mezőnevek szinkronizálva a pénzügyi standardokhoz (`amount_local`, `amount_eur`).
|
||||
- `SystemParameter` modell elnevezés igazítva a meglévő adatbázis sémához.
|
||||
|
||||
## [1.5.0] - 2026-02-10
|
||||
|
||||
### Added
|
||||
- **Judge & Penalty System**: Bevezetve a `penalty_points` és `restriction_level` mechanizmus a visszaélések kiszűrésére.
|
||||
- **Dynamic Multipliers**: Admin felületről (JSON config) állítható pontszorzók a büntetési szintekhez.
|
||||
- **Social-to-Credit Auto-conversion**: Automatikus Kredit jóváírás a Walletbe meghatározott Social pont elérésekor.
|
||||
- **Level Achievement Bonus**: 10-es szintenkénti automatikus Kredit jutalmazás.
|
||||
|
||||
### Fixed
|
||||
- **Circular Dependency Fix**: A modellek közötti import hurok végleges felszámolva (string-alapú relationship hivatkozások).
|
||||
- **Identity Schema Protection**: Visszaállítva a `User` modell hiányzó `scope_id`, `scope_level` és `custom_permissions` mezői.
|
||||
- **Database Consistency**: A `user_stats` és `asset_costs` táblák sikeresen migráltak a NOT NULL kényszerek és alapértelmezett értékek (server_default) beállításával.
|
||||
|
||||
### Changed
|
||||
- **GamificationService**: Mostantól központi "Bíróként" funkcionál, leválasztva a pontszámítási logikát a többi szervizről.
|
||||
- **Identity Model**: A `Wallet` és `VerificationToken` osztályok integrálva az `identity.py` modulba.
|
||||
|
||||
# Changelog - Service Finder Backend
|
||||
**Verzió:** 1.6.0 (Sentinel & i18n Update)
|
||||
**Dátum:** 2026.02.10.
|
||||
|
||||
## [1.6.0] - 2026-02-10
|
||||
### Hozzáadva
|
||||
- **Sentinel Biztonsági Rendszer:** - `PendingAction` modell bevezetése a "Négy szem elv" (Dual Control) biztosításához.
|
||||
- `SecurityService` implementálása: Adatlopás elleni védelem (Throttling) és automata vészleállító (Emergency Lock).
|
||||
- `AuditLog` bővítése szigorúbb súlyossági szintekkel (`critical`, `emergency`).
|
||||
- **Nyelvi Modul (i18n):**
|
||||
- `Translation` modell a `data` sémában.
|
||||
- `TranslationService`: Adatbázis-alapú fordításkezelés, szerveroldali cache, Fallback (EN) logika és JSON export funkció a Frontend számára.
|
||||
- **Admin Kontroll Panel:**
|
||||
- Új API végpontok a függőben lévő műveletek jóváhagyásához, a rendszerbiztonsági állapot monitorozásához és a nyelvi szinkronizációhoz.
|
||||
|
||||
### Javítva
|
||||
- **Circular Import Fix:** A modellek importálási rendjének optimalizálása a `app.db.base_class` közvetlen használatával, megszüntetve a hurok-importokat.
|
||||
- **Függőségkezelés:** `deps.py` bővítve a `get_current_active_user` függőséggel a biztonsági zárolások érvényesítéséhez.
|
||||
- **Soft-Delete Logika:** A felhasználói fiók törlése mostantól felszabadítja az eredeti e-mail címet a TWINS-elvű újra-regisztrációhoz.
|
||||
|
||||
# 15. Changelog & Version History
|
||||
|
||||
## [v1.2.5] - 2026-02-10 (The "SuperAdmin" Update)
|
||||
### 🚀 New Features
|
||||
- **Admin Bootstrap:** Implementáltuk a "vészhelyzeti" Admin létrehozási folyamatot (Python script alapú hash generálással).
|
||||
- **i18n Sync:** Élesítettük a `/api/v1/admin/translations/sync` végpontot, amely JSON fájlokba exportálja az adatbázis fordításait.
|
||||
- **Identity Expansion:** A `User` modell bővült a `preferred_language` és `region_code` mezőkkel a perszonalizáció érdekében.
|
||||
|
||||
### 🐛 Bug Fixes
|
||||
- **ORM Crash:** Javítva az `AssetAssignment` és `AssetCost` modellek hiányzó `organization` kapcsolatai, amelyek blokkolták a rendszer indulását (`InvalidRequestError`).
|
||||
- **Config Error:** Javítva a `Settings` osztályból hiányzó `STATIC_DIR` definíció, ami 500-as hibát okozott a fordítások szinkronizálásakor.
|
||||
- **Login Crash:** Javítva az `AttributeError` a Login végponton (a hiányzó `region_code` miatt).
|
||||
|
||||
### 🛠 Technical Changes
|
||||
- **Migrations:** Új Alembic migráció (`add_lang_and_region_to_user`) generálva és lefuttatva.
|
||||
- **Environment:** A `static/locales` mappa jogosultságai beállítva a Docker konténer számára.
|
||||
|
||||
[2026.02.12] - Fundamentum és Robot Orchestration
|
||||
|
||||
FIX: Javítva a docker-compose v1/v2 összeférhetetlenség (ContainerConfig hiba).
|
||||
|
||||
FIX: Megszüntetve az ImportError: cannot import name 'FastAPILimiter' hiba a security.py modulban.
|
||||
|
||||
DATABASE: PostGIS Geometry típus implementálva a service_profiles táblában.
|
||||
|
||||
MODEL: Az Asset (Digital Twin) és ServiceProfile közötti kapcsolatok szinkronizálva az ownership_history modulon keresztül.
|
||||
|
||||
WORKERS: Új állapotvezérelt (State-driven) robotlogika bevezetése:
|
||||
|
||||
A szervizek alapértelmezetten ghost státusszal jönnek létre.
|
||||
|
||||
Bevezetve a last_audit_at mező az automatikus kivezetéshez (Soft-delete).
|
||||
|
||||
UX: A keresőmotor számára definiálva a "Nem megerősített szolgáltató" jelzés a bot által talált adatokhoz.
|
||||
📝 Részletes Összefoglaló az Elvégzett Munkáról
|
||||
|
||||
Környezet Stabilizálás: A modern Docker Engine-hez igazítottuk a parancsokat, megoldva a régi Python-alapú compose hibáit.
|
||||
|
||||
Adatmodell Integritás: Visszaállítottuk az összes kritikus mezőt (nettó érték, ÁFA, maradványérték, telemetria), így a rendszer alkalmas komplex flottakezelési feladatokra is.
|
||||
|
||||
Szerviz Életciklus: Kidolgoztunk egy olyan logikát, ahol a botok nem "szemetelik" az adatbázist, hanem egy ghost (árnyék) réteget hoznak létre. Ezek a szervizek csak akkor válnak teljesen hitelessé, ha a felhasználók interakcióba lépnek velük (Gamification) vagy az Admin jóváhagyja őket.
|
||||
|
||||
Robot Koordináció: A robotok immár nem ütköznek. Az egyik a járműkatalógust építi API-kból, a másik a térképi pontokat gyűjti és auditálja.
|
||||
|
||||
# Changelog - 2026-02-13
|
||||
## Service Finder Project - "Dunakeszi Detective" & Docker Infrastructure
|
||||
|
||||
### 🚀 Fejlesztések és Architektúra
|
||||
- **Robot 2.7 (Service Hunter) Implementálása:**
|
||||
- Hibrid adatgyűjtés bevezetése: OSM (OpenStreetMap) + Google Places API + Helyi CSV.
|
||||
- **Geocoding Integráció:** A CSV-ben megadott szöveges címek (pl. "Dunakeszi, Kikerics köz 4") automatikus GPS koordinátára fordítása a Google API segítségével.
|
||||
- **Trust Score alapok:** Különböző források eltérő bizalmi szinttel kerülnek rögzítésre (Manuális > Google > OSM).
|
||||
|
||||
- **Adatbázis és Modellek (ORM) Javítása:**
|
||||
- `Organization` és `Address` modellek szinkronizálása a valós adatbázis sémával.
|
||||
- Hiányzó mezők kezelése (City, Zip átmozgatása Organization szintre).
|
||||
- PostGIS geometria (POINT) kezelésének pontosítása.
|
||||
|
||||
- **Docker Infrastruktúra Stabilizálás:**
|
||||
- Hálózati hiba (`[Errno -2] Name or service not known`) elhárítása.
|
||||
- `shared_db_net` és `bridge` hálózatok megfelelő konfigurálása.
|
||||
- Konténer DNS beállítások fixálása (Google DNS fallback).
|
||||
- Adatbázis hostnév korrekció (`db` -> `shared-postgres`).
|
||||
|
||||
### 🧠 Üzleti Logika és Stratégia (Döntések)
|
||||
1. **Multi-Tenant Kezelés:** Egy címen több cég is létezhet. A rendszer nem vonja össze őket automatikusan, csak ha az adószám/név egyezik.
|
||||
2. **Adatvédelmi Elv (No-Delete):** A robot soha nem töröl adatot fizikailag. Ha egy forrás megszűnik, a rekord "archived" vagy "review_needed" státuszt kap, de az adatbázisban marad.
|
||||
3. **Emberi Felügyelet:** A duplikációk összefűzése vagy a hibás adatok törlése Admin/Moderátor jogkör, nem a robot automatizmusa.
|
||||
4. **Dinamikus Adatfrissítés:** A robot a jövőben frissítheti a manuálisan felvitt adatokat is (pl. ha változik a nyitvatartás a Google-ön), de a prioritási szabályokat még finomítani kell.
|
||||
|
||||
### 🐛 Javított Hibák
|
||||
- `socket.gaierror`: Docker konténer internet elérés és belső névfeloldás javítva.
|
||||
- `AttributeError: 'city'`: SQLAlchemy modell mezőleképezési hiba javítva.
|
||||
- Függőségi hiba (`depends_at` -> `depends_on`) a docker-compose fájlban.
|
||||
|
||||
### 🔜 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.
|
||||
|
||||
|
||||
# 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).
|
||||
|
||||
# Changelog
|
||||
|
||||
## [v1.1.0] - 2026-02-17 "The Awakening"
|
||||
### 🚀 Hozzáadva (New Features)
|
||||
- **AI Service (Gemini Integration):** `app/services/ai_service.py` létrehozva. A rendszer mostantól képes a "Yamaha 4HN" típusú zajos adatokból tiszta marketing neveket és műszaki specifikációkat generálni.
|
||||
- **Robot 2 (Technical Enricher):** `app/workers/technical_enricher.py` frissítve v1.1-re. Hibrid működés: RDW adatbázis + AI kiegészítés.
|
||||
- **Robot 3 (OCR - Előkészület):** `app/workers/ocr_robot.py` váza elkészült a dokumentumok feldolgozásához.
|
||||
- **Reporting:** `app/scripts/morning_report.py` létrehozva a napi robot-tevékenység összefoglalására.
|
||||
- **Logging:** Új `ProcessLog` tábla létrehozva az `audit` sémában a háttérfolyamatok nyomon követésére.
|
||||
|
||||
### 🐛 Javítva (Bug Fixes)
|
||||
- **Docker Infrastructure:** - Javítva a `KeyError: 'ContainerConfig'` hiba a Docker Compose V2-re váltással.
|
||||
- Javítva az "empty database URL" hiba a migrációnál (`.env` változók helyes átadása).
|
||||
- Hálózati beragadások (Gitea/Nginx conflict) feloldva.
|
||||
- **Circular Imports:** Megszüntetve a `SystemParameter` modell duplikációja (`system_config.py` vs `system.py`). Minden szerviz (`Auth`, `Security`, `Cost`, `Gamification`) mostantól a központi `app.models`-ből importál.
|
||||
- **Swagger UI:** Az API sikeresen elindul, a dokumentáció elérhető a `/docs` végponton.
|
||||
|
||||
### ⚙️ Infrastruktúra (Refactor)
|
||||
- **Docker Compose:** Teljes tisztítás. Duplikált környezeti változók törölve, `env_file` használat optimalizálva.
|
||||
- **Services:** A robotok (`enricher`, `catalog`, `hunter`) külön konténerekbe szervezve, `unbuffered` python kimenettel a valós idejű logolásért.
|
||||
|
||||
### 🛡️ Biztonság
|
||||
- `.env` fájl szerkezete egységesítve, duplikációk eltávolítva.
|
||||
@@ -0,0 +1,46 @@
|
||||
# 🧪 TESZTELÉSI ÉS ÉLESÍTÉSI ÚTMUTATÓ (v1.4)
|
||||
|
||||
## 1. Előkészületek és Környezet
|
||||
1. **SQL Patch:** Meglévő adatbázis esetén futtasd a manuális frissítő SQL-t (mothers_name, social_provider, is_transferable oszlopok hozzáadása).
|
||||
2. **Enum Ellenőrzés:** Győződj meg róla, hogy a Postgres `userrole` típus tartalmazza a kisbetűs értékeket.
|
||||
3. **Docker Build:** `docker compose up -d --build` (Kényszeríti az új Python kód betöltését).
|
||||
|
||||
## 2. Regisztrációs Teszt Forgatókönyvek
|
||||
|
||||
### A) Step 1: Lite Regisztráció (Clean Test)
|
||||
- **Endpoint:** `POST /api/v1/auth/register`
|
||||
- **Elvárt eredmény:** 201 Created, `access_token` visszaadva, de a DB-ben a User `is_active = False` és nincs hozzá Person rekord.
|
||||
|
||||
### B) Step 2: KYC Kitöltés (Advanced Test)
|
||||
- **Endpoint:** `POST /api/v1/auth/complete-kyc`
|
||||
- **Adat (JSON):**
|
||||
```json
|
||||
{
|
||||
"mothers_name": "Minta Mária",
|
||||
"id_card_number": "AB123456",
|
||||
"driver_license_categories": ["A", "B"],
|
||||
"boat_license_number": "H-99999"
|
||||
}
|
||||
|
||||
# 🧪 TESZTELÉSI ÉS ÉLESÍTÉSI ÚTMUTATÓ (v1.0)
|
||||
|
||||
## 1. Előkészületek a távoli teszteléshez
|
||||
Mielőtt elindítanád a teszteket, győződj meg róla, hogy a háttérfolyamatok frissültek:
|
||||
1. A `.env` fájl mentve van a helyes jelszavakkal.
|
||||
2. A konténerek újraépítése és indítása:
|
||||
`docker compose up -d --build` (Ez kényszeríti a Python kódot az új verzióra).
|
||||
3. Ellenőrizd a logokat: `docker logs -f service_finder_api` (Itt látod, ha hiba van induláskor).
|
||||
|
||||
## 2. Tesztelési Forgatókönyvek (End-to-End)
|
||||
|
||||
### A) Új Regisztráció Teszt (Clean Registration)
|
||||
- **Endpoint:** `POST /api/v1/auth/register`
|
||||
- **Adat (JSON):**
|
||||
```json
|
||||
{
|
||||
"email": "teszt.felhasznalo@profibot.hu",
|
||||
"password": "nagyonerospassword123",
|
||||
"first_name": "János",
|
||||
"last_name": "Teszt",
|
||||
"region_code": "HU"
|
||||
}
|
||||
@@ -0,0 +1,37 @@
|
||||
# 🛠️ DEVELOPER NOTES & TROUBLESHOOTING
|
||||
|
||||
## 1. ADATBÁZIS ÉS SQL FIXEK
|
||||
### Postgres Enum Case Sensitivity
|
||||
* **Probléma:** Az SQLAlchemy Enum típusa és a Postgres Enum típusa ütközhet, ha a Python kódban nagybetűs stringet (`USER`) küldünk.
|
||||
* **Megoldás:** Mindig használd a `.value` property-t vagy kényszerítsd a kisbetűs stringet: `role="user"`.
|
||||
|
||||
### Tábla oszlopok frissítése
|
||||
* **Probléma:** A `Base.metadata.create_all` nem adja hozzá az új oszlopokat a már meglévő táblákhoz.
|
||||
* **Megoldás:** Új mező esetén (pl. `social_provider`, `mothers_name`) manuális `ALTER TABLE` parancsot kell futtatni vagy Alembic migrációt generálni.
|
||||
|
||||
## 2. BACKEND API HIBÁK
|
||||
### ImportError: create_access_token
|
||||
* **Ok:** A `app.core.security` modulban hiányzott a funkció, vagy elavult volt az import az `endpoints/auth.py`-ban.
|
||||
* **Javítás:** A `security.py`-nak tartalmaznia kell a `jose` könyvtárat használó tokengenerálást.
|
||||
|
||||
### Üres Swagger (OpenAPI) felület
|
||||
* **Ok:** Ha az SQLAlchemy Mapper vagy egy Pydantic séma importja hibás, a FastAPI nem tudja legenerálni a dokumentációt.
|
||||
* **Javítás:** Ellenőrizd a `docker logs` kimenetét indításkor, keresd a `MapperConfigurationError` vagy `ImportError` sorokat.
|
||||
|
||||
# 17. Developer Notes & Pitfalls
|
||||
|
||||
## 17.1. SQLAlchemy & Circular Imports
|
||||
**Hiba:** `InvalidRequestError: Mapper has no property 'organization'`
|
||||
**Ok:** Ha egy modellben definiálsz egy `ForeignKey`-t, de nem adod hozzá a `relationship`-et, a SQLAlchemy mapper inicializáláskor összeomolhat, ha egy másik modell próbál hivatkozni rá (back_populates).
|
||||
**Megoldás:** Mindig párban definiáld a kapcsolatokat (FK + relationship).
|
||||
**Példa javítás (AssetAssignment):**
|
||||
```python
|
||||
organization_id = Column(Integer, ForeignKey("data.organizations.id"))
|
||||
organization = relationship("Organization") # Ez hiányzott!
|
||||
|
||||
17.2. Configuration Missing
|
||||
|
||||
Hiba: AttributeError: 'Settings' object has no attribute 'STATIC_DIR' Tanulság: Ha fájlrendszer műveleteket végzel (pl. JSON export), mindig a core/config.py-ban definiáld az abszolút útvonalakat (BASE_DIR, STATIC_DIR), ne hardkódolj útvonalakat a service fájlokban.
|
||||
17.3. Database Migrations
|
||||
|
||||
Best Practice: Ha mezőt adsz hozzá egy modellhez (pl. User.region_code), azonnal generálj Alembic migrációt (alembic revision --autogenerate), különben az API 500-as hibát dob, mert a Python objektum attribútuma létezik, de az SQL lekérdezés nem adja vissza az oszlopot.
|
||||
@@ -0,0 +1,235 @@
|
||||
# 🏎️ 18_ASSET_AND_FLEET_SPECIFICATION (v1.2)
|
||||
|
||||
Ez a dokumentum írja le a rendszer magját képező "széf" logikát, ahol minden közlekedési eszköz (Asset) egyedi életutat és digitális lenyomatot kap.
|
||||
|
||||
## 1. Az Alapelv: "Mindenki Flottatulajdonos"
|
||||
A rendszerben a technikai réteg nem tesz különbséget magánszemély és cég között.
|
||||
- **Privát Flotta:** A regisztráció során automatikusan létrejövő szervezet (**Organization**).
|
||||
- **Széf (Safe Deposit):** A flotta izolált része, ahol az eszközök (járművek) és azok bizalmas okmányai (Vault) találhatók.
|
||||
|
||||
---
|
||||
|
||||
## 2. Eszköz Típusok és Univerzális Azonosítók (UAI)
|
||||
Minden eszköz rendelkezik egy **Univerzális Állandó Azonosítóval (UAI)**, amely az életútja során soha nem változik.
|
||||
|
||||
| Kategória | Elsődleges Azonosító (UAI) | Speciális Adatpontok |
|
||||
| :--- | :--- | :--- |
|
||||
| **Közúti (Car, Bike, Bus)** | **VIN** (Alvázszám) | Rendszám, Motorkód, Sebességváltó kód |
|
||||
| **Vízi (Boat, Yacht)** | **HIN** (Hull ID) | MMSI kód, IMO szám, Hajó neve |
|
||||
| **Légi (Aircraft)** | **Serial Number** | Lajstromjel (Registration), Típusjelzés |
|
||||
| **Heavy Duty / Agri** | Egyedi sorozatszám | Üzemóra, Teljesítmény, Kanál/Vágóasztal típus |
|
||||
| **Micro-mobility** | Vázszám / UUID | Akkumulátor ciklus, Hatótáv |
|
||||
|
||||
### Kiegészítő mérőszámok:
|
||||
- **Futásteljesítmény (Odometer):** Közúti járműveknél (km/mérföld).
|
||||
- **Üzemóra (Operating Hours):** Hajók, repülők és munkagépek esetén az elsődleges szervizintervallum-mérő.
|
||||
- **VIN Validáció:** Közúti járműveknél kötelező a **VIN Checksum (MOD 11)** ellenőrzése rögzítéskor.
|
||||
|
||||
---
|
||||
|
||||
## 3. A Jármű DNS (Deep Data Structure)
|
||||
A rendszer két rétegben kezeli a jármű adatait a teljes életút követéséhez.
|
||||
|
||||
### 3.1. Gyári Konfiguráció (Factory Specs)
|
||||
- **Trim Level:** Felszereltségi szint (pl. AMG Pack, S-Line).
|
||||
- **Technikai paraméterek:** Motorvariációk, kW/LE, nyomaték, gyári felni/gumi méretek (ET számmal), folyadékmennyiségek.
|
||||
- **Szervizintervallumok:** Gyártói előírások (idő vagy távolság alapú).
|
||||
|
||||
### 3.2. Aktuális Állapot és Módosítások
|
||||
- **Status Quo:** Gyári extrák, utólagos módosítások (Aftermarket - pl. vonóhorog, gázszett) és hiányzó gyári elemek követése.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 4. Digitális Szervizkönyv és Minősítés
|
||||
### 4.1. Eseményalapú Idővonal (Timeline)
|
||||
Minden bejegyzés megváltoztathatatlan (immutable) logként rögzül:
|
||||
- **Típusok:** Karbantartás, Javítás, Műszaki Vizsga, Baleset, Tulajdonosváltás.
|
||||
- **Csatolmányok:** Alkatrész fotók, számlák (OCR), munkalapok.
|
||||
|
||||
### 4.2. Kettős Értékelési Rendszer
|
||||
1. **AI Health Score (Technikai):** Algoritmus alapú pontszám a szerviztörténet és a gyári előírások betartása alapján.
|
||||
2. **Driver Rating (Emocionális):** Szubjektív sofőrértékelés (Komfort, Vezetési élmény, Praktikum).
|
||||
|
||||
---
|
||||
|
||||
## 5. Multi-Robot Harvester Architektúra
|
||||
A katalógus feltöltéséért és frissítéséért kategória-specifikus robotok felelnek (`BaseHarvester` alapokon).
|
||||
|
||||
### 5.1. Robot Típusok:
|
||||
- **Autó / Motor Robot:** Közúti adatokra.
|
||||
- **Heavy Duty / Agri Robot:** Teherautókra és munkagépekre.
|
||||
- **Specialty Robot:** Vízi és légi azonosítókra (MMSI, Lajstrom).
|
||||
|
||||
### 5.2. Adatgyűjtési Szintek:
|
||||
- **Initial Load:** A top 1000 európai típus alapfeltöltése.
|
||||
- **On-Demand Fetch:** Felhasználói "Trigger" hatására indított soron kívüli mélykeresés (Deep Web Scrape).
|
||||
- **Verification Status:** `verified` (teljes), `incomplete` (részleges), `pending` (ellenőrzésre vár).
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 6. OCR és Dokumentum Validációs Stratégia
|
||||
A dokumentumfelismerés (OCR) hibrid technológiát és Tier-alapú prioritást alkalmaz.
|
||||
|
||||
### 6.1. Feldolgozási Sorrend (Failover Logic)
|
||||
1. **Tier 1 (External Cloud):** Google Vision / Azure Form Recognizer (ingyenes keret erejéig).
|
||||
2. **Tier 2 (Saját Fallback):** Helyi szerveren futó **PaddleOCR** modul.
|
||||
|
||||
### 6.2. Üzleti Logika és Monetizáció
|
||||
- **VIP+ / Premium+:** Azonnali (Real-time) OCR feldolgozás (3-5 másodperc).
|
||||
- **Lite:** Háttérfolyamat (sorban állás), korlátozott havi kvóta (pl. 1 scan/hó).
|
||||
- **Kreditalapú túllépés:** A kvóta feletti beolvasások a `Wallet`-ből levont kreditért vásárolhatók meg.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 7. Infrastruktúra és Adatkezelés
|
||||
### 7.1. Dokumentum Tárolás (NAS)
|
||||
- **Elérési út:** `/mnt/nas/app_data/assets/{asset_id}/`
|
||||
- **Típusok:**
|
||||
- **Vault (Tartós):** Kritikus okmányok (Forgalmi, Adásvételi) hash-elt fájlnévvel.
|
||||
- **Ephemeral (Ideiglenes):** Napi bizonylatok (Parkolójegy), melyek OCR után 90 nappal törlődnek.
|
||||
- **Képoptimalizálás:** Automata átméretezés (max 1600px) és WebP konverzió (~80-90% megtakarítás).
|
||||
|
||||
### 7.2. Címkezelési Protokoll (v2.0)
|
||||
Minden címet (székhely, tulajdonos, szerviz) atomizált formában tárolunk a pontos riportáláshoz:
|
||||
- Irányítószám, Település, Közterület neve, Közterület jellege (utca, út stb.), Házszám (emelet/ajtó kiegészítéssel).
|
||||
|
||||
---
|
||||
|
||||
## 8. Kivételkezelés: Ismeretlen Járművek
|
||||
Ha az eszköz nem szerepel a katalógusban:
|
||||
1. **Custom Asset:** Manuális rögzítés kötelező dokumentum-fotóval.
|
||||
2. **AI Verifikáció:** OCR-rel összeveti a fotót a bevitt adatokkal.
|
||||
3. **"Unverified Model" jelzés:** Amíg a Robot vagy egy Admin meg nem erősíti az adatok hitelességét.
|
||||
|
||||
## 3. Document Engine & Optimization
|
||||
- **Processing:** Feltöltéskor automatikus méretoptimalizálás (max 1600px) és WebP konverzió.
|
||||
- **Thumbnails:** Minden képből 300px széles WebP előnézet generálódik a gyors UI eléréshez.
|
||||
- **Supported Formats:** JPG, PNG, WEBP (képek); PDF, DOCX (dokumentumok).
|
||||
- **OCR Integration:** Számlák és munkalapok esetén automata adatkinyerés (alkatrészek, árak, kilométeróra állás).
|
||||
|
||||
## 7.4 Dokumentum Életciklus és Pufferelés (v2.2)
|
||||
|
||||
A rendszer háromlépcsős tárolási és feldolgozási logikát alkalmaz az optimális hálózati és szerver-teljesítmény érdekében:
|
||||
|
||||
1. **Ingestion (TEMP - Helyi SSD):** - Minden feltöltött állomány a `/app/temp/uploads/` mappába érkezik.
|
||||
- Itt történik az AI/OCR elemzés és a képoptimalizálás (Pillow).
|
||||
- A nyers forrásfájl a feldolgozás után **30 percig** marad itt (puffer), hogy a felhasználó azonnal visszanézhesse, mielőtt a NAS-ra kerül.
|
||||
|
||||
2. **Presentation (THUMBNAIL - Helyi SSD):**
|
||||
- A Pillow által generált 300px széles WebP miniképek a szerver lokális `/app/static/previews/` könyvtárába kerülnek.
|
||||
- A UI (web/app) kizárólag ezeket tölti be a listázáskor, elkerülve a NAS terhelését.
|
||||
|
||||
3. **Vault (NAS - Hosszú távú tároló):**
|
||||
- A feldolgozott, nagyfelbontású (max 1600px) WebP állomány átkerül a NAS-ra: `/mnt/nas/app_data/organizations/{id}/vault/`.
|
||||
- A NAS-hoz csak akkor fordul a rendszer, ha a felhasználó kifejezetten a dokumentum nagy változatát kéri.
|
||||
|
||||
## 5. Discovery Bot Strategy
|
||||
|
||||
### 5.1 Prioritási Sorrend
|
||||
A Botok az alábbi sorrendben pásztázzák az adatforrásokat:
|
||||
1. **Land (Földi járművek):**
|
||||
* Személyautók (Car), Motorok (Bike), Teherautók (Truck).
|
||||
* Adatforrás: Márkakereskedői listák, Gyártói API-k.
|
||||
2. **Infrastructure (Infrastruktúra):**
|
||||
* Benzinkutak, Elektromos töltők (OpenChargeMap API).
|
||||
* Ezek könnyen elérhető, statikus adatok.
|
||||
3. **Services (Szervizek):**
|
||||
* Google Maps API, Cégjegyzék adatok.
|
||||
* Ezeket jelöli meg a rendszer "Unverified" (Bot-talált) státusszal.
|
||||
|
||||
### 5.2 Adatgazdagítás
|
||||
A Bot nem csak a nevet keresi. Célzottan gyűjti:
|
||||
* Nyitvatartási idők.
|
||||
* Kapcsolattartói adatok (Email, Weboldal).
|
||||
* Közösségi média linkek.
|
||||
* *Szabály:* A Bot által hozott adat felülírható a "Service Hunt" során a felhasználó által (magasabb megbízhatóság).
|
||||
|
||||
## 6. Multi-Source Consensus Logic
|
||||
A szervizek és szolgáltatók hitelességét nem csak az Admin, hanem a források száma határozza meg.
|
||||
|
||||
### 6.1 Bizalmi szintek (Confidence Score)
|
||||
* **Score 1:** Egyetlen forrás (Bot vagy User). Státusz: `pending`.
|
||||
* **Score 2:** Két független forrás megerősítése.
|
||||
* **Score 3+:** Automatikus hitelesítés (`verified`). Nincs szükség emberi beavatkozásra.
|
||||
|
||||
### 6.2 Bot Adatforrások (Priority: Car & Bike)
|
||||
A Botok az alábbi sorrendben dolgoznak:
|
||||
1. Hivatalos gyártói oldalak (Márkaszervizek).
|
||||
2. Szakmai adatbázisok (pl. Autóklub, Kamarák).
|
||||
3. Google/Social media API-k.
|
||||
|
||||
## 4. Telephelyek (Locations) és Szervizpontok
|
||||
Minden szolgáltató (Organization) több telephelyet tarthat fenn.
|
||||
|
||||
### 4.1 Kötelező Adatstruktúra
|
||||
Minden telephely rögzítésekor az alábbi bontott címadatok kötelezőek:
|
||||
- Irányítószám, Város, Közterület neve, Közterület típusa, Házszám.
|
||||
- Opcionális: Helyrajzi szám (parcel_id) külterületi vagy HRSZ alapú azonosításhoz.
|
||||
|
||||
### 4.2 Validációs Folyamat
|
||||
A rögzített címek automatikusan bekerülnek a Master Geo adatbázisba, építve a rendszer globális címjegyzékét.
|
||||
|
||||
## 5. Járművek és Költségek (MVP)
|
||||
A járműadatok kezelése hibrid módon történik.
|
||||
|
||||
### 5.1 Jármű Katalógus
|
||||
- A rendszer egy központi katalógust (`asset_catalog`) épít.
|
||||
- Új rögzítéskor a rendszer először a katalógusból kínál fel opciókat (Dropdown).
|
||||
- Ha a modell nem létezik, a rendszer automatikusan felveszi (Self-learning catalog).
|
||||
|
||||
### 5.2 Költségkövetés (TCO)
|
||||
- Minden Asset-hez rögzíthető költség (`asset_costs`).
|
||||
- Kötelező adatok: Kategória, Összeg, Dátum.
|
||||
- Opcionális: Km óra állása (az amortizáció és szervizintervallum számításához).
|
||||
|
||||
## 2026.02.10 FRISSÍTÉS - ATOMIZÁLT ADATMODELL ÉS MODULÁRIS API
|
||||
|
||||
### 1. Adatbázis Szerkezet (A 4 Pillér)
|
||||
A járművek kezelése "Single Responsibility" elv alapján 4 modulra bomlott:
|
||||
1. **Identity (Asset):** Alapadatok (VIN, Rendszám, Tulajdonos).
|
||||
2. **Catalog (AssetCatalog):** Gyári statikus adatok (Típus, Motor, Akku). Ezt a Robotok töltik.
|
||||
3. **Telemetry (AssetTelemetry):** Változó állapot (KM óra, VQI minőség index, DBS vezetési stílus).
|
||||
4. **Financials (AssetCost):** Pénzügyi tranzakciók 9 kategóriába sorolva (Fuel, Service, Tax, stb.).
|
||||
|
||||
### 2. Moduláris API Végpontok
|
||||
A teljesítmény optimalizálása érdekében a \`Full Profile\` helyett 3 dedikált végpontot használunk:
|
||||
- \`GET /api/v1/assets/{id}\`: Csak identitás és katalógus (Gyors nézet).
|
||||
- \`GET /api/v1/assets/{id}/costs\`: Csak pénzügyi történet és grafikonok.
|
||||
- \`GET /api/v1/assets/{id}/telemetry\`: Csak élő adatok (Dashboard).
|
||||
|
||||
*A javított AssetAssignment logika dokumentálása.*
|
||||
|
||||
```markdown
|
||||
# 18. Asset & Fleet Management Specification
|
||||
|
||||
## 18.2. Asset Assignment Logic
|
||||
A járművek és eszközök hozzárendelése a rendszer egyik legkritikusabb része.
|
||||
|
||||
### 18.2.1. Assignment Model (`AssetAssignment`)
|
||||
Kapcsolatot teremt egy Jármű (`Asset`) és egy Szervezet (`Organization`) között.
|
||||
- **asset_id**: UUID (Melyik jármű?)
|
||||
- **organization_id**: Integer (Melyik cég használja?)
|
||||
- **status**: Active / Released
|
||||
- **Validáció:** Egy jármű egyszerre csak egy szervezetnél lehet `active` státuszban.
|
||||
|
||||
*(Megjegyzés: A v1.2.5 frissítés javította az ORM kapcsolatokat, így a lekérdezések most már közvetlenül elérik az `assignment.organization` objektumot.)*
|
||||
|
||||
## 4.0 Catalog 2022+ Strategy (Hybrid Mode)
|
||||
A CarQueryAPI korlátai miatt 2022 utáni modelleknél a Robot 1 az alábbi hibrid logikát alkalmazza:
|
||||
1. **API Ninjas & Auto-Data Sync:** Elsődleges technikai forrás.
|
||||
2. **European Scraper Mode:** A mobile.de és autoscout24.hu portálok típusválasztóinak (meta-adatok) aratása a legfrissebb modellek és motorváltozatok rögzítéséhez.
|
||||
|
||||
## 6. Szerviz Logika és Intervallumok
|
||||
A szervizkönyv nem csak eseménynapló, hanem előrejelző rendszer.
|
||||
|
||||
### 6.1 Karbantartási Terv (Maintenance Plan)
|
||||
Az MDM-ben rögzített `specifications` tartalmazza a fődarabok szervizigényét:
|
||||
- **Folyadékok:** Típus, mennyiség, csereperiódus (km/hónap).
|
||||
- **Alkatrészek:** Gyári kódok és alternatívák (cross-reference).
|
||||
- **Biztonság:** Időszakos vizsgák (érintésvédelem, emelőhátfal, hajó szemle).
|
||||
154
archive/2026.02.18 Archive_old_mapps/V01_gemini/19_ADMIN_AND_PERMISSIONS_SPEC.md
Executable file
154
archive/2026.02.18 Archive_old_mapps/V01_gemini/19_ADMIN_AND_PERMISSIONS_SPEC.md
Executable file
@@ -0,0 +1,154 @@
|
||||
# 🛠️ 19_ADMIN_AND_PERMISSIONS_SPEC (v1.0)
|
||||
|
||||
## 1. Adminisztrátori Hierarchia és Területi Felosztás
|
||||
A rendszer többszintű, régió-alapú jogosultságkezelést alkalmaz (**RBAC + Geographic Scope**).
|
||||
|
||||
| Szint | Megnevezés | Területi hatókör | Jogkörök jellege |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **L0** | **SuperAdmin** | Globális (Összes ország) | Teljes hozzáférés, Rendszer-paraméterezés, Admin kinevezés. |
|
||||
| **L1/A** | **Global Director** | Régiós (Több ország) | Országos vezetők felügyelete, aggregált statisztikák. |
|
||||
| **L1/B** | **National Manager** | Országos (pl. HU) | Saját ország moderátorainak és adatainak teljes kezelése. |
|
||||
| **L2** | **Staff (Mod/Supp/Fin)** | Lokális / Szakaszolt | Operatív feladatok (VIES, support jegyek, kifizetések). |
|
||||
| **L3** | **Task Moderator** | Feladat-specifikus | Sablon alapú, korlátozott hozzáférés (pl. csak szerviz validálás). |
|
||||
|
||||
|
||||
|
||||
### Verseny Logika (Privacy Protection)
|
||||
Az L1/B szintű vezetők látják más országok aggregált KPI mutatóit (statisztikai összehasonlítás), de **nincs betekintésük** a konkrét személyes vagy céges adatokba.
|
||||
|
||||
---
|
||||
|
||||
## 2. Jogosultságkezelés és Sablonok
|
||||
- **Permissions Table:** Elemi jogosultságok atomi tárolása (pl. `approve_vies`, `modify_credits`).
|
||||
- **Role Templates:** Előre definiált szerepkör-sablonok (pl. "Senior Financial - DE").
|
||||
- **Regionális Izoláció:** Az adminisztrátorok alapértelmezetten csak a hozzájuk rendelt `ISO_country_code` alá tartozó rekordokat módosíthatják.
|
||||
|
||||
---
|
||||
|
||||
## 3. Biztonság és "Kill-Switch" Protokoll
|
||||
### 3.1. Hitelesítés
|
||||
- **MFA/2FA:** A második bejelentkezéstől kezdve kötelező a **TOTP** (pl. Google Authenticator) használata.
|
||||
- **Social Auth:** Engedélyezett, de nem váltja ki a kötelező 2FA-t.
|
||||
|
||||
### 3.2. Anomaly Score (Fekete Doboz)
|
||||
- **Audit Logs:** Minden kattintást és módosítást JSON formátumban rögzítünk.
|
||||
- **Automatikus Felfüggesztés:** Kritikus viselkedés (pl. tömeges adattörlés) esetén a rendszer automatikusan zárolja az admin fiókot és riasztást küld a felette álló szintnek.
|
||||
- **SuperAdmin Recovery:** Csak egyedi **Offline Kulccsal** és előre regisztrált fizikai eszközzel lehetséges.
|
||||
|
||||
### 3.3. State Snapshot (Visszaállíthatóság)
|
||||
Minden módosítás előtt a rendszer menti a rekord aktuális állapotát. Az L0/L1 szintű adminisztrátorok egy gombnyomással visszaállíthatják az eredeti adatokat károkozás vagy hiba esetén.
|
||||
|
||||
---
|
||||
|
||||
## 4. Értesítési Engine és Lejárati Figyelmeztetések
|
||||
A rendszer proaktív módon értesíti az érintetteket a kritikus dátumok előtt (Push, Email, Mini-CRM).
|
||||
|
||||
### 4.1. Előfizetési Értesítések
|
||||
- **Hatókör:** Lite+, VIP, VIP+, Corporate csomagok.
|
||||
- **Ütemezés:** Automatikus figyelmeztetés **30, 15, 7 és 1** nappal a lejárati dátum előtt.
|
||||
|
||||
### 4.2. Technikai és Jármű Okmányok
|
||||
A rendszer figyeli és jelzi az alábbiak lejáratát:
|
||||
- **Forgalmi engedély:** Műszaki vizsga érvényessége.
|
||||
- **Biztosítás:** KGFB és CASCO fordulónapok.
|
||||
- **Lízing:** Szerződéses futamidő vége.
|
||||
- **Specialty:** Hajólevél, lajstrom, emelőgép vizsga stb.
|
||||
|
||||
---
|
||||
|
||||
## 5. CRM és Szervezeti Kontaktok
|
||||
Minden szervezet (Organization) esetében kötelező legalább egy **Adminisztratív Kontakt** megadása.
|
||||
- **Multi-Role:** Egy Person több szervezetben is lehet `owner` vagy `fleet_manager`.
|
||||
- **CRM Mezők:** Név, beosztás, közvetlen elérhetőség (Pénzügyi felelős / Operatív felelős elkülönítve).
|
||||
|
||||
---
|
||||
|
||||
## 6. Corporate Onboarding és Validáció
|
||||
A cégek hitelesítése három szinten történik:
|
||||
1. **Tier 1 (Automata):** Adószám alapú validáció (VIES / Nemzeti API).
|
||||
2. **Tier 2 (AI/OCR):** Feltöltött dokumentumok (pl. Alapító okirat) intelligens elemzése.
|
||||
3. **Tier 3 (Human):** L2/L3 szintű adminisztrátori jóváhagyás, ha az automatika bizonytalan.
|
||||
|
||||
---
|
||||
|
||||
## 7. B2B Jutalék és MLM Korlátok
|
||||
- **Direct Referral:** Szervezet által meghívott másik szervezet esetén kizárólag az **1. szintű (L1)** jutalék jár.
|
||||
- **MLM Kivétel:** A szervezetek nem építhetnek többszintű hálózatot; a kifizetés minden esetben fix üzleti megállapodás vagy egyedi szerződés alapján történik.
|
||||
- **Adminisztrátori Meghívók:** Csak manuálisan generálhatók, és szigorúan **24 órás** lejárati idővel rendelkeznek.
|
||||
|
||||
## 6. Dinamikus Szabálymotor (Rule Engine)
|
||||
A rendszer minden fontos paramétere a `data.system_settings` táblában tárolt JSON objektumokból származik.
|
||||
|
||||
### 6.1 Módosítási protokoll
|
||||
* Az Admin felületen módosított értékek (pl. Kredit jutalom összege) azonnal érvénybe lépnek.
|
||||
* A módosítás után a Backend Cache-t (`ConfigService`) üríteni kell.
|
||||
|
||||
### 6.2 Paraméterezhető modulok
|
||||
* **Service Hunt:** Távolságok, XP/Kredit szorzók.
|
||||
* **Fraud Protection:** Strike limitek, kitiltási idők.
|
||||
* **Billing:** EUR/HUF/USD váltószámok, csomagárak, jármű-slot árak.
|
||||
|
||||
## 2026.02.10 FRISSÍTÉS - HIERARCHIKUS RBAC RENDSZER
|
||||
|
||||
### 1. Rang-alapú Jogosultság (Rank System)
|
||||
A rendszer a \`system_parameters\` táblában tárolt \`RBAC_MASTER_CONFIG\` JSON alapján működik.
|
||||
- **SUPERADMIN (Rank 100):** Globális hatókör, mindent lát.
|
||||
- **COUNTRY_ADMIN (Rank 80):** Országos felelős.
|
||||
- **REGION_ADMIN (Rank 60):** Területi vezető (Manage Moderators).
|
||||
- **MODERATOR (Rank 40):** Adatvalidátor.
|
||||
- **SALES (Rank 20):** Üzletkötő (Csak saját partnerek).
|
||||
- **USER (Rank 10):** Végfelhasználó.
|
||||
|
||||
### 2. Scope (Hatókör) Védelem
|
||||
Minden műveletnél ellenőrizzük a \`scope_id\` egyezését:
|
||||
- Ha a felhasználó \`scope_level = 'region'\`, akkor csak olyan adatot szerkeszthet, ami ugyanahhoz a régióhoz tartozik.
|
||||
- Kivétel: Impersonation (Megszemélyesítés) - Audit loggal védve.
|
||||
|
||||
|
||||
## 1. Gamification Adminisztráció
|
||||
A `data.system_parameters` táblában a `GAMIFICATION_MASTER_CONFIG` kulcs alatt az alábbiak állíthatóak:
|
||||
- `xp_logic`: `base_xp`, `exponent`.
|
||||
- `penalty_thresholds`: A szintekhez tartozó büntetőpont határok.
|
||||
- `level_up_rewards`: 10-es szintenkénti Kredit jutalom mértéke.
|
||||
- `blocked_roles`: [superadmin, service_bot].
|
||||
- `auto_convert_social`: True/False.
|
||||
|
||||
## 2. Gamification Konfiguráció (JSON Schema)
|
||||
A `GAMIFICATION_MASTER_CONFIG` struktúrája:
|
||||
- `xp_logic`: Alap XP és kitevő a nehezedő szintezéshez.
|
||||
- `penalty_logic`: Küszöbértékek, szorzók és ledolgozási ráta.
|
||||
- `conversion_logic`: Social-to-Credit váltási arány.
|
||||
- `level_rewards`: Szintlépési bónuszok mértéke.
|
||||
|
||||
## 19.1. SuperAdmin Capabilities
|
||||
A `rank: 100` szintű felhasználó (SuperAdmin) az egyetlen, aki:
|
||||
1. **Translation Sync:** Írási joga van a szerver fájlrendszerére a `/api/v1/admin/translations/sync` végponton keresztül.
|
||||
2. **Sentinel Override:** Felülbírálhatja az automatikus biztonsági zárolásokat.
|
||||
|
||||
## 19.2. Admin API Endpoints
|
||||
- `POST /admin/translations/sync`:
|
||||
- **Trigger:** Manuális (Gombnyomás a Dashboardon).
|
||||
- **Action:** `data.translations` -> `static/locales/*.json`.
|
||||
- **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.
|
||||
@@ -0,0 +1,85 @@
|
||||
20. SERVICE FINDER & SPECIALIZED MARKETPLACE (TRUST ENGINE)
|
||||
20.1 Szerviz Identitás és Szpecializációs Taxonómia
|
||||
|
||||
Minden szolgáltatói pont (szerviz, kút, étterem) egy Organization (org_type='service'), de mély szűrési attribútumokkal rendelkezik.
|
||||
|
||||
Fő kategóriák: Repair (Javítás), Fuel (Üzemanyag), Food (Vendéglátás), Safety (Mentés/Vizsga).
|
||||
|
||||
Mély Szpecializáció (Deep Expertise):
|
||||
|
||||
A rendszer ExpertiseTag-eket használ (pl. bmw_gs_adventure_specialist, boat_transport, ev_charging_fast, truck_repair).
|
||||
|
||||
A keresőmotor a jármű típusa (AssetCatalog) és a bejelentett hiba/igény alapján párosítja a specialistákat.
|
||||
|
||||
20.2 Többszintű Validációs Mátrix (Trust Score)
|
||||
|
||||
A szerviz adatlapjának hitelessége egy 0-100% közötti skálán mozog, több forrásból táplálkozva:
|
||||
|
||||
Robot Discovery (30%): A Robot 2 (Service Hunter) találta meg (nyilvános adatok, cégjegyzék).
|
||||
|
||||
First User Entry (50%): Az első felhasználó rögzítette manuálisan.
|
||||
|
||||
Crowd Validation (User 2-5, +10% alkalmanként): További felhasználók megerősítették az adatokat (Gamification XP jár érte).
|
||||
|
||||
Admin Approval (100%): A belső moderátorok manuálisan leellenőrizték és "Verified" státuszba tették.
|
||||
|
||||
AI OCR Validation: Ha egy felhasználó számlát tölt fel egy adott szerviztől, a Robot 2 (OCR) automatikusan validálja a szerviz létezését és adatait (státusz frissítés).
|
||||
|
||||
20.3 Geo-Keresés és Rangsorolási Logika (PostGIS)
|
||||
|
||||
A keresés alapja a felhasználó vagy a jármű aktuális GPS koordinátája.
|
||||
|
||||
Keresési algoritmus:
|
||||
|
||||
Szűrés: PostGIS ST_DWithin (távolság alapú) + Szpecializáció Match.
|
||||
|
||||
Rangsorolás (Szkópolt logika):
|
||||
|
||||
Premium User: 1. Preferált szervizek, 2. Legmagasabb Trust Score, 3. Hirdetők, 4. Útvonaltervezés szerinti valós távolság.
|
||||
|
||||
Free User: 1. Hirdetők, 2. Légvonalbeli távolság, 3. Trust Score.
|
||||
|
||||
Útvonaltervezés (Premium): Külső motor (pl. OSRM vagy GraphHopper) integráció a pontos elérési időhöz.
|
||||
|
||||
## 3.0 Specialization & Filtering (Bentley Logic)
|
||||
A keresőmotor prioritási rendszere:
|
||||
1. **Explicit Specialist:** Specializációs tag-ek alapján (pl. brand: Bentley).
|
||||
2. **General Service:** Univerzális javítók, ahol nincs kizáró ok.
|
||||
3. **Exclusion Logic:** Ha a keresett márka Bentley, de a szerviz specializációja csak "BMW", a találat tiltva van.
|
||||
|
||||
## 4.0 Trust Score Multipliers
|
||||
- **Economic Stability:** 3+ év nyereséges működés (+20 pont).
|
||||
- **Physical Validation:** Google Street View / Robot Photo Verification (+15 pont).
|
||||
- **Verified Staff:** Ha a szerelőregisztrációk száma > 2 (+10 pont).
|
||||
|
||||
# 20. Service Finder & Trust Engine
|
||||
|
||||
## Pre-searching (Silent Service Hunter) Logika
|
||||
A cél a szervizek felderítése API költségek nélkül, kereszt-ellenőrzött forrásokból.
|
||||
|
||||
### 1. Felderítési Fázis (Hunter A)
|
||||
Többmotoros keresés (DuckDuckGo Lite, Bing, Yandex, OSM) segítségével:
|
||||
- **Kulcsszó-dorking:** `site:facebook.com "Dunakeszi" "szerviz"`.
|
||||
- **Informális adatok:** Fórumok, blogok és helyi közösségi posztok elemzése.
|
||||
- **TEAOR Mátrix:** Az e-Cégközlöny napi frissítéseinek szűrése (4520, 4540, 2920 kódok).
|
||||
|
||||
### 2. Validációs Pontrendszer (Trust Engine)
|
||||
Minden talált entitás pontszámot kap:
|
||||
- **+40 pont:** Aktív adószám és megfelelő TEAOR (4520/4540).
|
||||
- **+20 pont:** Friss digitális jelenlét (Facebook/Instagram poszt < 30 nap).
|
||||
- **+20 pont:** Fizikailag validált cím (OSM vagy lakossági megerősítés).
|
||||
- **+10 pont:** Hívható, formátum-helyes telefonszám.
|
||||
|
||||
### 3. Döntési Szintek
|
||||
- **80+ pont:** Ellenőrzött (Verified) - Automatikus publikálás.
|
||||
- **40-79 pont:** Moderációra vár - Manuális adminisztrátori jóváhagyás szükséges.
|
||||
- **<40 pont:** Elutasítva/Inaktív - Marad a Stage táblában.
|
||||
|
||||
## 6. Szerviz Logika és Intervallumok
|
||||
A szervizkönyv nem csak eseménynapló, hanem előrejelző rendszer.
|
||||
|
||||
### 6.1 Karbantartási Terv (Maintenance Plan)
|
||||
Az MDM-ben rögzített `specifications` tartalmazza a fődarabok szervizigényét:
|
||||
- **Folyadékok:** Típus, mennyiség, csereperiódus (km/hónap).
|
||||
- **Alkatrészek:** Gyári kódok és alternatívák (cross-reference).
|
||||
- **Biztonság:** Időszakos vizsgák (érintésvédelem, emelőhátfal, hajó szemle).
|
||||
57
archive/2026.02.18 Archive_old_mapps/V01_gemini/21_DEEP ASSET CATALOG.md
Executable file
57
archive/2026.02.18 Archive_old_mapps/V01_gemini/21_DEEP ASSET CATALOG.md
Executable file
@@ -0,0 +1,57 @@
|
||||
21.1 Adatmélység és Idővonal
|
||||
|
||||
A rendszer célja a teljes EU-s járműpark lefedése a 2000-es évjárattól kezdődően.
|
||||
|
||||
Hierarchia: Make -> Model -> Generation -> Engine Variant -> Trim Level.
|
||||
|
||||
Kezdeti adatok: Az első fázisban a robot a 4 alapszintet tölti (Márka, Típus, Évjárat, Motor), majd iteratívan mélyíti a factory_data JSONB mezőt (olajmennyiség, nyomaték, guminyomás stb.).
|
||||
|
||||
# 21. Deep Asset Catalog (MDM)
|
||||
|
||||
Ez a dokumentum írja le a járművek technikai mélységét kategóriánként.
|
||||
|
||||
## 1. Kategória Specifikus Adatok (JSONB Schemas)
|
||||
- **Személyautó:** Klíma fajták (digit, többzónás), hajtáslánc, ADAS rendszerek.
|
||||
- **Teherautó/Kamion:** Tengelyek száma, fülke típusa, retarder típusok, menetíró.
|
||||
- **Motorkerékpár:** Munkaütem, hűtés módja, táskák/dobozok konfigurációja.
|
||||
- **Hajó:** Merülés, vízkiszorítás, orrsugárkormány, navigációs elektronika.
|
||||
|
||||
## 2. Numerikus Indexelés
|
||||
A gyors keresés érdekében a következő mezők fix oszlopok:
|
||||
- `engine_capacity` (ccm)
|
||||
- `power_kw` (kW)
|
||||
- `weight_kg` (Súly)
|
||||
- `year_from / year_to` (Gyártási időszak)
|
||||
|
||||
# 21. Deep Asset Catalog & Master Data Management (MDM)
|
||||
|
||||
Ez a modul a rendszer "agyát" képezi, ahol a zajos külső forrásokból származó adatok tiszta, dúsított és egyedi járműspecifikációkká alakulnak.
|
||||
|
||||
## 21.1 Adatmodell (vehicle_model_definitions)
|
||||
A katalógus nem egyszerűen rekordokat tárol, hanem egy Master-Slave viszonyrendszert valósít meg a duplikációk elkerülése érdekében.
|
||||
|
||||
### Kulcsfontosságú mezők:
|
||||
- `technical_code`: Egyedi gyári azonosító (pl. PC44, ZX600R). Elsődleges kulcs a deduplikációhoz.
|
||||
- `parent_id`: Önhivatkozás. Ha egy rekord duplikátum, itt mutat a Master (eredeti) rekordra.
|
||||
- `synonyms` (JSONB): Alternatív elnevezések gyűjteménye (pl. "Tracer 9", "MT-09 Tracer") a kereshetőség javítására.
|
||||
- `year_from / year_to`: Gyártási intervallumok a generációk megkülönböztetéséhez.
|
||||
- `specifications` (JSONB): Műszaki adatok (olajmennyiség, gyertya típus, hűtőfolyadék).
|
||||
|
||||
## 21.2 Master-Merge Logika
|
||||
A rendszer az "Igazság Hierarchiáját" követi az adatok mentésekor:
|
||||
1. **Hatósági Adat (RDW):** CCM és teljesítmény (kW) forrása.
|
||||
2. **AI Adatbányászat (Gemini + Google Search):** Technikai kódok, évjáratok és szervizadatok forrása.
|
||||
3. **Manuális felülbírálat:** Legmagasabb prioritású `status = 'manual_check'`.
|
||||
|
||||
### Összefésülési szabály (Deduplikáció):
|
||||
A Robot 2 csak akkor olvaszt össze két rekordot, ha:
|
||||
- A `make` (gyártó) egyezik.
|
||||
- A `technical_code` azonos és nem 'N/A'.
|
||||
- A `engine_capacity` (CCM) megegyezik.
|
||||
|
||||
|
||||
|
||||
## 21.3 Állapotgépek (Status Lifecycle)
|
||||
- `unverified`: Alapállapot, csak nyers adatok.
|
||||
- `ai_enriched`: Sikeresen dúsított, hitelesített Master rekord.
|
||||
- `duplicate`: Felismert másolat, amely egy Master rekordhoz van láncolva.
|
||||
164
archive/2026.02.18 Archive_old_mapps/V01_gemini/22_ROBOT ÖKOSZISZTÉMA.md
Executable file
164
archive/2026.02.18 Archive_old_mapps/V01_gemini/22_ROBOT ÖKOSZISZTÉMA.md
Executable file
@@ -0,0 +1,164 @@
|
||||
22.1 Robot 1: Catalog Scout (The Library)
|
||||
|
||||
Feladat: Folyamatos, háttérben futó adatgyűjtés (EU-szintű járműspecifikációk).
|
||||
|
||||
Működés: Web-crawling és technikai adatbázisok szinkronizációja. Nem áll le, folyamatosan frissíti a vehicle_catalog táblát.
|
||||
|
||||
22.2 Robot 2: Service Hunter & OCR (The Auditor)
|
||||
|
||||
Service Hunting: EU-szintű térképadatok és szaknévsorok (Google, OSM, Yellow Pages) alapján szervizpontok felderítése.
|
||||
|
||||
OCR Validation: Felhasználói dokumentumok (forgalmi, számla) feldolgozása. Ha az OCR szervizadatot talál, keresztellenőrzi a data.organizations táblával.
|
||||
|
||||
22.3 Robot 3: RobotScout (The Detective)
|
||||
|
||||
Feladat: Egyedi jármű (Asset) validáció. VIN alapú lekérdezés és factory_data összevetés a felhasználói adatokkal.
|
||||
|
||||
23. SERVICE ONBOARDING & THREE-STEP FLOW
|
||||
|
||||
A szolgáltatói (szerviz) regisztráció integrálódik az alap onboarding folyamatba:
|
||||
|
||||
Step 1 (Lite): Alap felhasználói fiók létrehozása.
|
||||
|
||||
Step 2 (KYC & Org): Személy azonosítása, Wallet nyitása és az Alapértelmezett Szervezet (Privát flotta) létrehozása.
|
||||
|
||||
Step 3 (Service Setup - Opcionális): Ha a felhasználó szolgáltató is, itt rögzíti a Szerviz Profilját.
|
||||
|
||||
Létrejön egy második Organization rekord (org_type='service').
|
||||
|
||||
Hozzárendelésre kerülnek az ExpertiseTag-ek (Szakmai szempontok).
|
||||
|
||||
GPS koordináták rögzítése (PostGIS).
|
||||
|
||||
24. ROBOT SCOUT & CATALOG STRATEGY (HU -> EU)
|
||||
|
||||
A Robot 1 (Catalog Filler) egy rétegelt feltöltési stratégiát követ:
|
||||
|
||||
Layer 1 (Basic Identity): Márka, Típus, Évjárat, Motor (HU piac fókusz).
|
||||
|
||||
Layer 2 (Technical Depth): Folyadékmennyiségek, kerékméretek, meghúzási nyomatékok.
|
||||
|
||||
Layer 3 (Service Relation): Melyik alkatrész/szerviz igény kapcsolódik az adott típushoz.
|
||||
|
||||
API Strategy
|
||||
|
||||
24. Robot Scout Adatforrások:
|
||||
|
||||
Járművek: A robot a CarQuery API és a NHTSA vPIC API kombinációját használja a 2000 utáni EU-s modellek feltöltéséhez. A ciklusidő: 1 év/5 perc.
|
||||
|
||||
Szervizek: Az OSM Overpass API az elsődleges forrás a lokációkhoz. A validációt a Robot 2 végzi a Google Places adatokkal való összevetéssel (Trust Engine).
|
||||
|
||||
Motorok: Külön prioritást élveznek a prémium márkák (BMW, KTM, Honda) szakszervizei a "Specialization Tag" rendszerben.
|
||||
|
||||
📘 MASTER BOOK KIEGÉSZÍTÉS (v2.4) - 2026.02.13
|
||||
20.4 Szerviz Életciklus és Automatikus Kivezetés (Soft-Delete)
|
||||
|
||||
A Marketplace tisztaságát az automatikus inaktiválási folyamat garantálja:
|
||||
|
||||
Státuszok:
|
||||
|
||||
ghost: Bot által talált, nem hitelesített rekord.
|
||||
|
||||
active: Működő, publikus szerviz.
|
||||
|
||||
flagged: Gyanús (pl. bezártnak jelentett), felülvizsgálatra vár.
|
||||
|
||||
inactive: Megszűnt vagy inaktivált szerviz (Soft-deleted).
|
||||
|
||||
Audit ciklus: A Robot 2 (Auditor) 90 naponta minden active szervizt keresztellenőriz külső forrásokkal (OSM/Google). Ha egy hely "Permanently Closed", a robot átállítja: is_active = False és status = 'inactive'.
|
||||
|
||||
22.4 Robot Orchestration (Koordináció)
|
||||
|
||||
A robotok az adatbázist használják "jelzőtáblának", így elkerülik az ütközéseket:
|
||||
|
||||
Robot 1 (Catalog Scout): Kizárólag a data.vehicle_catalog táblát írja.
|
||||
|
||||
Robot 2 (Hunter/Auditor): * A Hunter csak olyan helyeket rögzít, amik még nincsenek az organizations táblában.
|
||||
|
||||
Az Auditor csak az is_active=True rekordokat vizsgálja felül.
|
||||
|
||||
Robot 3 (OCR/Detective): Dokumentum-alapú validálást végez. Ha az OCR egy inactive szervizt talál egy friss számlán, nem írja felül a robotot, hanem flagged státuszba teszi a szervizt manuális ellenőrzésre ("Lehet, hogy mégis kinyitott?").
|
||||
|
||||
20.4 Szerviz Állapotok és Láthatóság
|
||||
|
||||
ghost (Alapértelmezett): Bot által talált rekord.
|
||||
|
||||
Keresés: Megjelenik, de kötelező "Nem megerősített szolgáltató" jelzéssel ellátni.
|
||||
|
||||
Gamification: Teljesen nyitott. A felhasználók értékelhetik, fotózhatják. Minden ilyen interakció növeli a trust_score-t.
|
||||
|
||||
active: Megerősített szolgáltató (Admin vagy magas Trust Score alapján).
|
||||
|
||||
flagged: Felülvizsgálat alatt (pl. ellentmondásos adatok).
|
||||
|
||||
inactive: Igazoltan megszűnt. Csak ez az állapot rejtett a keresés elől.
|
||||
|
||||
## 2.0 Robot 2 (The Detective)
|
||||
A Robot 2 három fázisban dolgozik:
|
||||
- **Phase 1 (Discovery):** OSM/Overpass alapú koordináta és név rögzítés.
|
||||
- **Phase 2 (Deep Enrichment):** Google Places, Web Scraping (Email, telefon, tulajdonos neve).
|
||||
- **Phase 3 (Financial Audit):** Nyilvános cégadatok (Árbevétel, létszám, adózott eredmény) éves szinkronizálása.
|
||||
|
||||
# 22. ROBOT ÖKOSZISZTÉMA
|
||||
|
||||
## Robot v1.9.2 (Ghost Commander) & n8n
|
||||
A robotok és az n8n szoros együttműködésben dolgoznak.
|
||||
|
||||
### Funkciók
|
||||
- **Auto-Heal:** A járműkatalógus hiányos (null) adatainak automatikus pótlása Holland (RDW) és US (NHTSA) forrásokból.
|
||||
- **Ban-Detection:** Automatikus "Circuit Breaker" logika. Ha a CarQuery vagy más forrás tilt, a robot átvált "Silent Mode"-ba.
|
||||
- **Event Hunter:** n8n workflow figyeli a motoros/autós találkozókat és eseményeket, majd összeköti őket a helyi szervizpartnerekkel.
|
||||
- **Gamification Link:** A robot regisztrálja a felhasználói validálásokat és kiosztja a pontokat/krediteket.
|
||||
|
||||
# 22. Robot Ökoszisztéma
|
||||
|
||||
A rendszer automatizált adatgyűjtő és dúsító ágensei.
|
||||
|
||||
## 1. Model Enrichment Robot (Dúsító)
|
||||
- **Működés:** Hajnali 01:00 - 05:00 között.
|
||||
- **Logika:** 1. Új `unverified` kódok keresése.
|
||||
2. RDW API lekérdezés (Holland alapok).
|
||||
3. AI (Gemini) Deep Scraping: Marketing név, felszereltségi lista, szervizintervallumok kinyerése.
|
||||
4. Validálás a JSON Sémák alapján.
|
||||
5. Master státusz beállítása.
|
||||
|
||||
## 2. Resource Management
|
||||
A robot figyeli a szerver terhelését. Ha a CPU > 70%, az AI lekérdezéseket lassítja (throttle), hogy ne zavarja a hajnali biztonsági mentéseket.
|
||||
|
||||
# 22. Robot Ökoszisztéma Specifikáció
|
||||
|
||||
A rendszer autonóm robotok hálózatából áll, amelyek egymásra épülve tisztítják és dúsítják a flottaszintű adatokat.
|
||||
|
||||
## 22.1 Robot 1: Catalog Scraper (RDW)
|
||||
- **Feladata:** Külső API-k (pl. Holland RDW) folyamatos monitorozása és új járművek importálása.
|
||||
- **Működés:** Nyers adatokat hoz létre `unverified` státusszal.
|
||||
|
||||
## 22.2 Robot 2: Technical Enricher & Master Merge (v1.2.6)
|
||||
Ez a legkomplexebb modul, amely AI-t és webes keresést használ.
|
||||
|
||||
### Főbb képességek:
|
||||
- **Google Search Integration (RAG):** Ha az AI nem ismeri a modellkódot, valós időben keres a gyártói oldalakon.
|
||||
- **Safe-Merge Technológia:** Megakadályozza a technikai kód nélküli rekordok véletlen összevonását (`N/A-{id}` generálásával).
|
||||
- **Atomi tranzakciókezelés:** Minden mentés külön tranzakció, így a hiba nem szakítja meg a tömeges feldolgozást.
|
||||
|
||||
### Működési folyamat:
|
||||
1. Rekord kiválasztása (`status = unverified`).
|
||||
2. RDW kiegészítő adatok lekérése.
|
||||
3. Gemini 2.0 Flash meghívása keresőeszközzel.
|
||||
4. JSON parseolás és kód-validáció.
|
||||
5. Deduplikáció ellenőrzése és mentés.
|
||||
|
||||
|
||||
|
||||
## 22.3 Robot 3: OCR & Document AI
|
||||
- **Feladata:** Feltöltött okmányok, számlák és kilométeróra állások felismerése.
|
||||
- **Technológia:** Multimodális Gemini 2.0 elemzés.
|
||||
- **Kimenet:** Strukturált JSON, amely azonnal validálható a katalógus (R2) adataival.
|
||||
|
||||
## 22.4 Robot 4: Service Hunter (Tervezett)
|
||||
- **Cél:** A dúsított technikai adatok alapján szervizpartnerek és árak keresése.
|
||||
- **Input:** Robot 2 által generált szerviz-specifikációk (olaj típus, mennyiség).
|
||||
|
||||
## 22.5 Robot Monitoring & Operáció
|
||||
A robotok állapotát nem csak SQL-ben, hanem az n8n Dashboardon és a logok szintjén is követjük.
|
||||
- **Hibakezelés:** Automatikus visszalépés és ideiglenes kódgenerálás (`RESET-`, `UNKNOWN-`) az adatbázis kényszerek (Unique, Not Null) betartása érdekében.
|
||||
@@ -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.
|
||||
274
archive/2026.02.18 Archive_old_mapps/V01_gemini/_00_gemini_gem_kód
Executable file
274
archive/2026.02.18 Archive_old_mapps/V01_gemini/_00_gemini_gem_kód
Executable file
@@ -0,0 +1,274 @@
|
||||
# ROLE: Senior Backend Architect & Security Engineer
|
||||
# PROJECT: Service Finder Ecosystem (FastAPI, SQLAlchemy Async, PostgreSQL, Docker)
|
||||
|
||||
## CONTEXT & ARCHITECTURE
|
||||
A rendszer egy magas biztonságú, mikroszolgáltatás-jellegű monolit (Modular Monolith). A biztonsági és üzleti logika szigorúan elkülönül.
|
||||
|
||||
## CORE LOGIC RULES (NON-NEGOTIABLE)
|
||||
|
||||
1. IDENTITY & ONBOARDING (Twin-Model):
|
||||
- **Step 1 (Registration/Social):** Csak `User` és `Person` rekord jön létre.
|
||||
Státusz: `is_active = False`.
|
||||
Folder Slug: `NULL`.
|
||||
Organization/Wallet: NEM jön létre.
|
||||
Service: `SocialAuthService` vagy `AuthService.register_lite`.
|
||||
**Step 2 (KYC/Activation):** Itt történik az üzleti aktiválás.
|
||||
- Státusz váltás: `is_active = True`.
|
||||
- Slug Generálás: `generate_secure_slug(12)` a Usernek és az új Organization-nek.
|
||||
- Shadow Identity: Mindig ellenőrizni kell, létezik-e már a `Person` (név, szül. adat, anyja neve alapján).
|
||||
- Service: `AuthService.complete_kyc`.
|
||||
2. SECURITY & AUTH:
|
||||
- **Dual Token:** Mindig Access és Refresh tokent adunk vissza (`create_tokens`).
|
||||
- **Dynamic Config:** SOHA ne használj hardcoded értékeket rankokra vagy limitekre. Mindig a `config.get_setting` (DB-ből: `data.system_parameters`) használandó.
|
||||
- **RBAC:** A jogosultságot a `deps.check_min_rank` ellenőrzi dinamikusan.
|
||||
- **Resource Access:** Mindig ellenőrizni kell a `scope_id`-t (Slug) a `deps.check_resource_access`-szel.
|
||||
3. DATABASE & MODELS:
|
||||
- Schema: Minden tábla a `data` sémában van (`__table_args__ = {"schema": "data"}`).
|
||||
- Migráció: Adatbázis módosítás CSAK Alembic-kel történhet.
|
||||
## FILE STRUCTURE & RESPONSIBILITIES
|
||||
- `app/api/deps.py`: Auth függőségek, Active User check, Scope check.
|
||||
- `app/services/auth_service.py`: Step 2 logika, Slug generálás, Soft Delete.
|
||||
- `app/services/social_auth_service.py`: Csak Step 1 logika (Google login).
|
||||
- `app/core/config.py`: Dinamikus beállítások olvasása a DB-ből.
|
||||
- `app/models/system_config.py`: A `SystemParameter` modell definíciója.
|
||||
|
||||
## CODING STANDARDS
|
||||
- Minden aszinkron (`async/await`).
|
||||
- SOHA ne rövidíts kódot "..."-al, mindig a teljes, működő fájlt add vissza.
|
||||
- Type hint-ek (typing) kötelezőek.
|
||||
- Logolás (`logger`) minden kritikus ponton kötelező (Security Service hívással).
|
||||
|
||||
## CURRENT STATE (STARTING POINT)
|
||||
A rendszer Security Hardening v2 fázisa kész. A `system_parameters` tábla létezik, a User/Org táblákban ott a `folder_slug`. A kód ezekre a mezőkre támaszkodik.
|
||||
|
||||
🧬 SERVICE FINDER - UNIVERSAL SYSTEM PROMPT (v1.2)
|
||||
|
||||
ROLE: Senior Technical Product Manager & Lead System Architect PROJECT: Service Finder - Traffic Ecosystem SuperApp SOURCE OF TRUTH: Grand Master Book (00–19) + 2026.02.10 System Updates CONTEXT: Monolit-moduláris refaktorálás (FastAPI, Vue3, Postgres 15).
|
||||
1. VÍZIÓ ÉS KONTEXTUS (00, 01)
|
||||
|
||||
Nem egy egyszerű nyilvántartó rendszert építünk, hanem egy Digital Twin (Digitális Iker) alapú ökoszisztémát.
|
||||
|
||||
Core Philosophy: "A jármű örök, a tulajdonos vándor." (Vehicle-Centric Architecture).
|
||||
|
||||
Pillére:
|
||||
|
||||
Core Fleet: Életút és TCO követés.
|
||||
|
||||
Marketplace: Szervizkereső és időpontfoglalás.
|
||||
|
||||
Trust Engine: Bizonyíték alapú előélet (OCR, Fotó).
|
||||
|
||||
Economy: Kredit és Gamification.
|
||||
|
||||
2. TECHNOLÓGIAI STACK ÉS INFRA (02, 03, 04, 08)
|
||||
|
||||
Frontend: Vue 3 (Composition API) + Vite + Tailwind CSS + Pinia. Dumb Frontend elv.
|
||||
|
||||
Backend: Python 3.12 + FastAPI. Szigorú Pydantic validáció.
|
||||
|
||||
Adatbázis: PostgreSQL 15. Két séma: data (üzleti), public (rendszer).
|
||||
|
||||
Storage: MinIO (S3 kompatibilis) titkosított dokumentumokhoz.
|
||||
|
||||
Hálózat: Internal Net (shared_db_net) zárt. Public Net: csak 80/443 (NPM Proxy).
|
||||
|
||||
Config: Minden konfiguráció .env fájlból vagy data.system_parameters táblából jön. Hardkódolás TILOS.
|
||||
|
||||
3. IDENTITÁS ÉS ONBOARDING (05, 07)
|
||||
|
||||
Szétválasztás:
|
||||
|
||||
USER: Technikai fiók (Email/Pass).
|
||||
|
||||
PERSON: Valós jogi személy (Okmányok, KYC). Nem törölhető.
|
||||
|
||||
Folyamat: Kétlépcsős (2-Step) Onboarding.
|
||||
|
||||
Lite: Csak User létrehozása (is_active=False).
|
||||
|
||||
KYC: Okmányok feltöltése -> Person létrehozása -> Wallet nyitása -> Aktiválás (Atomi tranzakció).
|
||||
|
||||
4. ATOMIZÁLT ASSET MODELL (18) [FRISSÍTVE 2026.02.10]
|
||||
|
||||
A járművek kezelése 4 elkülönített modulra bomlott (SRP elv):
|
||||
|
||||
Identity (Asset): VIN, Rendszám, Tulajdonos (AssetAssignment).
|
||||
|
||||
Catalog (AssetCatalog): Gyári statikus adatok. Robot Scout tölti.
|
||||
|
||||
Telemetry (AssetTelemetry): Változó állapot (KM, VQI, DBS).
|
||||
|
||||
Financials (AssetCost): Pénzügyi tranzakciók 9 kategóriában.
|
||||
|
||||
API Design: 3 külön végpont (/assets/{id}, /assets/{id}/costs, /assets/{id}/telemetry).
|
||||
|
||||
5. HIERARCHIKUS JOGOSULTSÁG (RBAC & SCOPE) (09, 19) [FRISSÍTVE 2026.02.10]
|
||||
|
||||
A rendszer egy Rang- és Hatókör-alapú mátrixot használ (RBAC_MASTER_CONFIG JSON).
|
||||
|
||||
Szintek (Rank):
|
||||
|
||||
SUPERADMIN (100): Globális (L0).
|
||||
|
||||
COUNTRY_ADMIN (80): Országos (L1).
|
||||
|
||||
REGION_ADMIN (60): Területi (L1/B).
|
||||
|
||||
MODERATOR (40): Adatvalidátor (L2).
|
||||
|
||||
SALES (20): Üzletkötő (L3).
|
||||
|
||||
USER (10): Végfelhasználó.
|
||||
|
||||
Védelem: Middleware szinten: Token Role >= Required Rank ÉS User Scope == Resource Scope.
|
||||
|
||||
Adattábla: User tábla új mezői: scope_level, scope_id, custom_permissions.
|
||||
|
||||
6. GAMIFICATION ÉS ECONOMY (10, 11) [FRISSÍTVE 2026.02.10]
|
||||
|
||||
XP (Tapasztalat): Végleges szintlépés (BaseXP×Level1.5). Nem csökken.
|
||||
|
||||
Social Points: Szezonális, resetelhető pontok.
|
||||
|
||||
Kredit: Valuta, Social pontokból váltható.
|
||||
|
||||
Service: GamificationService és PointsLedger (auditált naplózás).
|
||||
|
||||
Billing: Többvalutás rendszer (HUF/EUR tárolás).
|
||||
|
||||
7. ÜZEMELTETÉS ÉS ADATINTEGRITÁS (06, 12, 16, 17)
|
||||
|
||||
Soft Delete: Nincs DELETE parancs, csak is_deleted vagy is_active flag.
|
||||
|
||||
Audit: Kritikus műveletek (pl. Impersonation) előtt/után állapotmentés az audit_logs táblába.
|
||||
|
||||
Enum: Postgres Enum típusok mindig kisbetűsek (pl. role='user').
|
||||
|
||||
Migráció: Minden DB módosításhoz SQL script + Alembic migráció kötelező.
|
||||
|
||||
🚀 KÖVETKEZŐ LÉPÉSEK (ACTION PLAN - 2026.02.11)
|
||||
|
||||
A rendszer magja (Asset, RBAC, Gamification) stabil. A következő fejlesztési ciklus célja a biztonsági réteg és az automatizáció bekapcsolása.
|
||||
🔴 PRIORITY 1: SMART AUTH TOKEN (Security)
|
||||
|
||||
Feladat: A Login (/auth/login) folyamat átírása.
|
||||
|
||||
Cél: A generált JWT Token tartalmazza a DB-ből frissen kinyert RBAC adatokat: role, rank, scope_level, scope_id.
|
||||
|
||||
Miért: Hogy a Middleware DB-lekérdezés nélkül tudjon dönteni a jogosultságról.
|
||||
|
||||
File: backend/app/core/security.py, backend/app/api/v1/endpoints/auth.py.
|
||||
|
||||
🟠 PRIORITY 2: IMPERSONATION ENGINE (Ops)
|
||||
|
||||
Feladat: POST /api/v1/admin/impersonate végpont.
|
||||
|
||||
Logika: SuperAdmin token cseréje egy cél-felhasználó tokenjére (időkorlátos).
|
||||
|
||||
Biztonság: Szigorú naplózás az audit_logs táblába (reason kötelező).
|
||||
|
||||
🟡 PRIORITY 3: ROBOT SCOUT (Automation)
|
||||
|
||||
Feladat: Háttérfolyamat (Worker) indítása create_asset után.
|
||||
|
||||
Logika: VIN alapján külső API / Mock adatbázis lekérdezése -> AssetCatalog.factory_data feltöltése.
|
||||
|
||||
# 📘 SERVICE FINDER - MASTER ARCHITECT SYSTEM INSTRUCTIONS
|
||||
|
||||
ROLE: Senior Technical Product Manager & System Architect PROJECT: Service Finder - Traffic Ecosystem SuperApp 2.0 CONTEXT: Monolit-moduláris refaktorálás (FastAPI backend, Vue3 frontend, PostgreSQL 15). SSoT: Grand Master Book (v1.4).
|
||||
🎯 ALAPVETŐ MŰKÖDÉSI PROTOKOLL
|
||||
|
||||
Zéró Találgatás: Tilos feltételezésekre alapozva kódot írni. Ha egy összefüggés (adatbázis-program-fájlrendszer) nem egyértelmű, pontosító kérdéseket kell feltenni.
|
||||
|
||||
Fájlbekérési Kényszer: Minden módosítás vagy hibajavítás előtt kötelező bekérni az érintett fájlok aktuális, teljes tartalmát. Tilos korábbi logikát törölni; a meglévő kódrészeket integrálni kell a tiszta kód elvei szerint.
|
||||
|
||||
Teljes Kódközlés: Mindig a teljes, javított állományt kell visszaadni, nem csak kódrészleteket.
|
||||
|
||||
Gitea & Changelog: Csak működő, tesztelt verziók után generálj Git commit üzenetet és frissítsd a Changelog.md fájlt (.md formátumban).
|
||||
|
||||
🏗️ ARCHITEKTURÁLIS ÉS ÜZLETI LOGIKA
|
||||
|
||||
Identity Strategy: Szigorú elválasztás a technikai User (fiók) és a valós Person (identitás) között. A Person nem törölhető (Soft Delete). Újraregisztrációkor a KYC adatok alapján kötelező a korábbi person_id összekötése.
|
||||
|
||||
Kétlépcsős Onboarding: * Step 1 (Lite): is_active = False, csak technikai User jön létre.
|
||||
|
||||
Step 2 (KYC/Aktiválás): Atomi tranzakcióban: Person rögzítése, Wallet nyitása, Private Org létrehozása, aktiválás.
|
||||
|
||||
Economy & Dynamic Config: * A 10-5-2%-os jutalék és minden üzleti változó (pl. auth.reward_days) kizárólag a data.system_settings táblából jöhet. Tilos beégetett (hardcoded) változók használata.
|
||||
|
||||
Minden költséget helyi pénznemben és EUR-ban is tárolni kell (CostEUR=CostLocal⋅ExchangeRate).
|
||||
|
||||
Admin Hierarchy & Security: L0 (SuperAdmin) -> L3 szintek közötti jogosultságkezelés. Regionális izoláció alkalmazása: az adminok csak a hozzájuk rendelt country_code adatait láthatják.
|
||||
|
||||
🗄️ ADATBÁZIS ÉS SQL IRÁNYELVEK
|
||||
|
||||
Séma: Üzleti logika a data, rendszeradatok a public sémában.
|
||||
|
||||
Enumok: A Postgres Enum típusok miatt minden szerepkört és státuszt kényszerített kisbetűvel kell kezelni (role="user").
|
||||
|
||||
Migráció: Minden adatbázis-módosításhoz pgAdmin felületen futtatható SQL-t és Alembic migrációs szkriptet kell készíteni.
|
||||
|
||||
Audit Trail: Minden módosítás előtt és után State Snapshot (JSON) mentése az audit_logs táblába.
|
||||
|
||||
🛠️ TECHNIKAI STACK SPECIFIKÁCIÓK
|
||||
|
||||
Backend: Python 3.12, FastAPI, SQLAlchemy (Alembic), Pydantic validáció.
|
||||
|
||||
Frontend: Vue 3 (Composition API), Vite, Tailwind CSS, Pinia. Hardkódolt IP tilos, csak .env (VITE_API_BASE_URL).
|
||||
|
||||
Storage: MinIO (S3 kompatibilis) számlákhoz és okmányokhoz.
|
||||
|
||||
Útvonalak: A projekt gyökere: /opt/docker/dev/service_finder. Dokumentációk a /docs/V01_gemini/ mappában.
|
||||
|
||||
💬 KOMMUNIKÁCIÓ ÉS DOKUMENTÁCIÓ
|
||||
|
||||
Ha a Master Book specifikációja és a kérés ütközik, jelezd és tegyél javaslatot a Master Book frissítésére.
|
||||
|
||||
Minden megoldás után frissítsd a megfelelő Master Book fejezetet, ha a rendszerlogika változott.
|
||||
|
||||
Használj technikai angol kifejezéseket a magyar szövegkörnyezetben (pl. refactoring, dependency injection, endpoint).
|
||||
könyvtárszerkezetét Bash tree -I "node_modules|vendor|.git|dist|build|storage" -L 3
|
||||
adatbázis szerkezet Bash docker exec -it shared-postgres pg_dump -U kincses -s service_finder > schema_dump.sq
|
||||
|
||||
|
||||
|
||||
## 🛠️ SERVICE FINDER - SYSTEM ARCHITECT GEM CONFIGURATION
|
||||
|
||||
ROLE: Senior Technical Product Manager & System Architect PROJECT: Service Finder - Flotta Menedzsment Rendszer OBJECTIVE: MVP Refaktorálás (Monolit -> Moduláris) a "Grand Master Book" (v1.0) elvei mentén.
|
||||
🎯 ALAPVETŐ MŰKÖDÉSI PROTOKOLL
|
||||
|
||||
Szigorú Adatgyűjtés: Kódmódosítás vagy javítás előtt kötelező bekérni az érintett fájlok teljes tartalmát. Tilos korábbi logikát törölni vagy módosítani anélkül, hogy tisztáznánk annak összefüggéseit a rendszer többi részével.
|
||||
|
||||
Single Source of Truth (SSoT): Minden válasz alapja a Master Book (00-17.md dokumentumok). Ha a Master Book és a kód ellentmondásban van, vagy a leírás hiányos, állj meg, tegyél javaslatot a kiegészítésre, és csak a tisztázás után folytasd a kódolást.
|
||||
|
||||
Tiszta és Teljes Kód: Mindig a teljes, javított fájltartalmat add vissza. Kerüld a töredékes kódokat. A kódnak tartalmaznia kell a Master Bookban rögzített logikai folyamatokat (clean code thought process).
|
||||
|
||||
Zéró Találgatás: Ha egy összefüggés (adatbázis-program-fájlrendszer) nem egyértelmű, tegyél fel pontosító kérdéseket. Inkább több tisztázó kör, mint hibás kód.
|
||||
|
||||
🏗️ ARCHITEKTÚRA ÉS FEJLESZTÉS
|
||||
|
||||
Modularitás: A fejlesztés iránya a monolitból a moduláris felépítés felé mutat. Minden új kódnak támogatnia kell a skálázhatóságot.
|
||||
|
||||
Adatbázis & SQL: SQL módosításokat pgAdmin felületre optimalizálva készíts. Minden adatbázis-módosításhoz kötelező migrációs szkriptet generálni az egységesség megőrzése érdekében.
|
||||
|
||||
Fájlstruktúra: Tartsd be a projekt meglévő könyvtárszerkezetét. Ne javasolj olyan útvonalakat, amelyek eltérnek a meglévő rendszertől.
|
||||
|
||||
📝 DOKUMENTÁCIÓ ÉS VERZIÓKEZELÉS
|
||||
|
||||
Gitea: Csak a már tesztelt, működő és jóváhagyott javítások után generálj Git commit üzeneteket és instrukciókat.
|
||||
|
||||
Changelog.md: Minden sikeres módosítás után kötelező legenerálni a Changelog.md bejegyzést, amely tartalmazza a változtatások pontos listáját.
|
||||
|
||||
Master Book Frissítés: Ha a fejlesztés során új logika születik, vagy pontosítunk egy meglévőt, generáld le a Master Book megfelelő fejezetének (pl. 07_API_Guide.md vagy 06_Database_Guide.md) frissített szöveges részét is.
|
||||
|
||||
💬 KOMMUNIKÁCIÓS STÍLUS
|
||||
|
||||
Szakmai, tömör és határozott.
|
||||
|
||||
Használj technikai angol szakkifejezéseket a magyar kontextusban (pl. refactoring, dependency injection, migration).
|
||||
|
||||
Minden válasz elején röviden összegezd a megértett problémát, mielőtt a megoldásra térsz.
|
||||
|
||||
könyvtárszerkezetét Bash tree -I "node_modules|vendor|.git|dist|build|storage" -L 3
|
||||
adatbázis szerkezet Bash docker exec -it shared-postgres pg_dump -U kincses -s service_finder > schema_dump.sq
|
||||
|
||||
Reference in New Issue
Block a user