DOCS: Grand Master Book v1.0 (Gemini V01) hozzáadása

docs/V01_gemini/00_README.md

@@ -0,0 +1,17 @@
+# 📘 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).

docs/V01_gemini/01_Project_Overview.md

@@ -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.

docs/V01_gemini/02_Architecture_System_Context.md

@@ -0,0 +1,12 @@
+# 🏗️ 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.

docs/V01_gemini/03_Dev_Environment_Runbook.md

@@ -0,0 +1,24 @@
+(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.
+

docs/V01_gemini/04_Infrastructure_Docker_Stack.md

@@ -0,0 +1,13 @@
+# 🐳 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

docs/V01_gemini/05_Security_Model.md

@@ -0,0 +1,17 @@
+(Biztonság és Identitás.)
+# 🔐 SECURITY & IDENTITY MODEL
+
+## 1. Identitás Kezelés (Person vs User)
+- **Person:** Természetes személy (GDPR alany). `deleted_at` esetén nem töröljük, csak minden személyes adatmezőt (név, email, tel) hashelünk/anonimizálunk, de a statisztikai ID megmarad.
+- **User:** Belépési fiók. Egy Person-höz több User tartozhat.
+- **Company:** Céges entitás. Tulajdonosa egy Person.
+
+## 2. Authentication
+- **Token:** JWT (JSON Web Token) HS256.
+- **Password:** Argon2 hash.
+- **Anti-Enumeration:** "Ha létezik ilyen email cím, küldtünk egy levelet" (nem áruljuk el, hogy regisztrált-e).
+
+## 3. Soft Delete Logika
+Minden táblában (`users`, `vehicles`, `events`) kötelező a `deleted_at`.
+- **API szinten:** Minden lekérdezéshez automatikusan hozzáadódik a `WHERE deleted_at IS NULL`.
+- **Admin szinten:** Láthatóak a törölt elemek is (Audit célból).

docs/V01_gemini/06_Database_Guide.md

@@ -0,0 +1,17 @@
+(Az Adatbázis Bibliája.)
+# 🗄️ DATABASE GUIDE
+
+## Sémák
+- `public`: Csak technikai táblák (pl. Alembic version).
+- `data`: Az üzleti logika 55 táblája.
+
+## 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`.
+
+## Migrációs Állapot
+- **Eszköz:** Alembic.
+- **Current Head:** `10b73fee8967`.
+- **Hiányzó láncszem:** A `persons` tábla létrehozása és a meglévő `users` tábla migrációja (Ba

docs/V01_gemini/07_API_Guide.md

@@ -0,0 +1,17 @@
+(API specifikáció.)
+# 🔌 API GUIDE
+
+## Verziózás
+- **v1:** Core Fleet funkciók (`/api/v1/vehicles`, `/api/v1/expenses`).
+- **v2:** Auth és új modulok (`/api/v2/auth/login`).
+
+## Route Inventory (Kiemelt)
+- `POST /api/v2/auth/register` (Regisztráció Person létrehozással)
+- `GET /api/v1/fleet/vehicles` (Saját járművek listája)
+- `POST /api/v1/search/match` (Szervizkereső algoritmus)
+- `POST /api/v1/evidence/upload` (MinIO feltöltés)
+
+## Hiba Kezelés
+- **401:** Token lejárt -> Frontend dobjon Loginra.
+- **403:** Jogosultság hiba -> "Nincs jogod ehhez a funkcióhoz" (Tier limit).
+- **404:** Resource not found OR Soft Deleted.

docs/V01_gemini/08_Frontend_Guide.md

@@ -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.

docs/V01_gemini/10_Billing_Credits_Subscriptions.md

@@ -0,0 +1,25 @@
+(Az Üzleti Modell - A legfontosabb frissítés.)
+# 💰 BILLING, CREDITS & SUBSCRIPTIONS
+
+## 1. Előfizetési Csomagok (SaaS)
+
+| Csomag | Ár (Havi) | Jármű | User | Funkciók |
+| :--- | :--- | :--- | :--- | :--- |
+| **FREE** | 0 Ft | 1 db | 1 | Geo Keresés (Sugár), Reklám, Nincs Export. |
+| **PREMIUM** | ~1.490 Ft | 3 db | 1 | Útvonal Keresés, Nincs Reklám, Excel Export, Dokumentum Tár. |
+| **PREMIUM+** | ~2.990 Ft | 5 db | 4 (Család) | Családi megosztás, Trust Score részletek. |
+| **VIP** | Egyedi | 10+ | 5+ | Flotta funkciók, API, Sofőr App. |
+
+## 2. A "Free -> Premium" Szabály (Q10 Solution)
+- A Free időszakban rögzített adatok **láthatóak maradnak**, de **nem képezik részét** a Prémium Elemzéseknek (TCO, Trendek).
+- **Feloldás:** Visszamenőleges elemzéshez "Retroaktív Csomag" vagy folyamatos előfizetés szükséges.
+
+## 3. Kredit Ökonómia (Coin)
+- **Szerzés:** Adatfeltöltés (50 Coin), Meghívás (200 Coin), Validálás (5 Coin).
+- **Költés:** Prémium előfizetés vásárlása, Skin-ek, Extra lekérdezések.
+- **Kifizetés:** Nincs automatikus kifizetés. Nagy mennyiség esetén (pl. Üzletkötő) egyedi szerződés (Megbízási/Számlás) alapján, vagy jövőben Blokklánc (Stablecoin).
+
+## 4. Befizetési Technológiák
+- **Stripe:** Nemzetközi kártyás fizetés.
+- **Barion / SimplePay:** Magyar specifikus fizetés.
+- **Coin Pack:** Mikrotanzakciók (pl. 500 Coin = 1000 Ft).

docs/V01_gemini/11_Gamification_Social.md

@@ -0,0 +1,11 @@
+(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.

docs/V01_gemini/12_Operations_Backup_Monitoring.md

@@ -0,0 +1,12 @@
+(Ü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.

docs/V01_gemini/13_Roadmap_Tech_Debt.md

@@ -0,0 +1,13 @@
+(Mit csinálunk most?)
+# 🗺️ ROADMAP & TECH DEBT
+
+## 🚧 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.

docs/V01_gemini/15_Changelog.md

@@ -0,0 +1,7 @@
+(Változásnapló.)
+# 📜 CHANGELOG
+
+## [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.