From 5dd5692d83891817166fcf3f770eba02e9f1657e Mon Sep 17 00:00:00 2001 From: Kincses Date: Wed, 4 Feb 2026 00:08:35 +0000 Subject: [PATCH] =?UTF-8?q?DOCS:=20Grand=20Master=20Book=20v1.0=20(Gemini?= =?UTF-8?q?=20V01)=20hozz=C3=A1ad=C3=A1sa?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/V01_gemini/00_README.md | 17 +++++++++++++ docs/V01_gemini/01_Project_Overview.md | 19 ++++++++++++++ .../02_Architecture_System_Context.md | 12 +++++++++ docs/V01_gemini/03_Dev_Environment_Runbook.md | 24 ++++++++++++++++++ .../04_Infrastructure_Docker_Stack.md | 13 ++++++++++ docs/V01_gemini/05_Security_Model.md | 17 +++++++++++++ docs/V01_gemini/06_Database_Guide.md | 17 +++++++++++++ docs/V01_gemini/07_API_Guide.md | 17 +++++++++++++ docs/V01_gemini/08_Frontend_Guide.md | 15 +++++++++++ .../10_Billing_Credits_Subscriptions.md | 25 +++++++++++++++++++ docs/V01_gemini/11_Gamification_Social.md | 11 ++++++++ .../12_Operations_Backup_Monitoring.md | 12 +++++++++ docs/V01_gemini/13_Roadmap_Tech_Debt.md | 13 ++++++++++ docs/V01_gemini/15_Changelog.md | 7 ++++++ 14 files changed, 219 insertions(+) create mode 100644 docs/V01_gemini/00_README.md create mode 100644 docs/V01_gemini/01_Project_Overview.md create mode 100644 docs/V01_gemini/02_Architecture_System_Context.md create mode 100644 docs/V01_gemini/03_Dev_Environment_Runbook.md create mode 100644 docs/V01_gemini/04_Infrastructure_Docker_Stack.md create mode 100644 docs/V01_gemini/05_Security_Model.md create mode 100644 docs/V01_gemini/06_Database_Guide.md create mode 100644 docs/V01_gemini/07_API_Guide.md create mode 100644 docs/V01_gemini/08_Frontend_Guide.md create mode 100644 docs/V01_gemini/10_Billing_Credits_Subscriptions.md create mode 100644 docs/V01_gemini/11_Gamification_Social.md create mode 100644 docs/V01_gemini/12_Operations_Backup_Monitoring.md create mode 100644 docs/V01_gemini/13_Roadmap_Tech_Debt.md create mode 100644 docs/V01_gemini/15_Changelog.md diff --git a/docs/V01_gemini/00_README.md b/docs/V01_gemini/00_README.md new file mode 100644 index 0000000..0647e53 --- /dev/null +++ b/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). \ No newline at end of file diff --git a/docs/V01_gemini/01_Project_Overview.md b/docs/V01_gemini/01_Project_Overview.md new file mode 100644 index 0000000..4dcb96f --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/V01_gemini/02_Architecture_System_Context.md b/docs/V01_gemini/02_Architecture_System_Context.md new file mode 100644 index 0000000..403228f --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/V01_gemini/03_Dev_Environment_Runbook.md b/docs/V01_gemini/03_Dev_Environment_Runbook.md new file mode 100644 index 0000000..fa66869 --- /dev/null +++ b/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. + diff --git a/docs/V01_gemini/04_Infrastructure_Docker_Stack.md b/docs/V01_gemini/04_Infrastructure_Docker_Stack.md new file mode 100644 index 0000000..55cbdf2 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/V01_gemini/05_Security_Model.md b/docs/V01_gemini/05_Security_Model.md new file mode 100644 index 0000000..41cc9cc --- /dev/null +++ b/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). \ No newline at end of file diff --git a/docs/V01_gemini/06_Database_Guide.md b/docs/V01_gemini/06_Database_Guide.md new file mode 100644 index 0000000..37fae90 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/V01_gemini/07_API_Guide.md b/docs/V01_gemini/07_API_Guide.md new file mode 100644 index 0000000..9225cbc --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/V01_gemini/08_Frontend_Guide.md b/docs/V01_gemini/08_Frontend_Guide.md new file mode 100644 index 0000000..f88361c --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/V01_gemini/10_Billing_Credits_Subscriptions.md b/docs/V01_gemini/10_Billing_Credits_Subscriptions.md new file mode 100644 index 0000000..c930070 --- /dev/null +++ b/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). \ No newline at end of file diff --git a/docs/V01_gemini/11_Gamification_Social.md b/docs/V01_gemini/11_Gamification_Social.md new file mode 100644 index 0000000..9146c13 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/V01_gemini/12_Operations_Backup_Monitoring.md b/docs/V01_gemini/12_Operations_Backup_Monitoring.md new file mode 100644 index 0000000..8bc301a --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/V01_gemini/13_Roadmap_Tech_Debt.md b/docs/V01_gemini/13_Roadmap_Tech_Debt.md new file mode 100644 index 0000000..3b46fd9 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/V01_gemini/15_Changelog.md b/docs/V01_gemini/15_Changelog.md new file mode 100644 index 0000000..de5367a --- /dev/null +++ b/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.