2026.03.30 front és garázs logika

docs/masterbook_2.0.1/MILESTONE_8_GAMIFICATION_PRO.md

@@ -0,0 +1,104 @@
+# 8. Mérföldkő: Gamification 2.0, Verseny és Önvédelmi Rendszer
+
+**Állapot:** Tervezés alatt  
+**Kezdés dátuma:** 2026-03-15  
+**Befejezés határideje:** 2026-04-15 (becsült)  
+**Felelős:** Backend Architekt, Gamification Team
+
+## 🎯 Célok
+1. A meglévő Gamification rendszer kibővítése szezonális versenyekkel és önvédelmi mechanizmusokkal.
+2. A Service Finder robot pipeline hibáinak kijavítása (Robot 3, sémaeltérés, hiányzó Auditor).
+3. A felhasználók által beküldött szervizek biztonságos és ellenőrzött átjuttatása a productionba.
+4. Moderációs és büntető rendszer bevezetése a spam és rosszindulatú beküldések kezelésére.
+
+## 📋 Feladatlista
+
+### 1. Adatbázis & Modell Fázis (Foundation)
+
+- [ ] **Season tábla:** Féléves versenyek tárolása.
+  - `id`, `name`, `start_date`, `end_date`, `is_active`
+  - Séma: `system.seasons`
+- [ ] **UserContribution tábla:** Spam védelem és cooldown kezelés.
+  - `user_id`, `service_fingerprint`, `action_type`, `earned_xp`, `cooldown_end`
+  - Séma: `gamification.user_contributions`
+- [ ] **UserStats bővítés:** Restrikciós szintek és büntető kvóták.
+  - `restriction_level` (0, -1, -2, -3)
+  - `penalty_quota_remaining`
+  - `banned_until`
+  - Séma: `system.user_stats` (meglévő tábla)
+- [ ] **SystemParameter integráció:** Dinamikus küszöbök tárolása.
+  - `key`: `promotion_threshold`, `xp_reward_base`, `penalty_multiplier`
+  - `value`: JSON konfiguráció
+  - Séma: `system.system_parameters` (meglévő)
+
+### 2. Worker Refactoring (The Pipeline)
+
+- [ ] **Robot 3 (Enricher) átírása:** Ne publikáljon! Csak növelje a trust_score-t a stagingben a talált szakmák alapján → státusz: `auditor_ready`.
+  - Cél: A jelenlegi `researched` státusz helyett `auditor_ready` legyen, jelezve, hogy az Auditor feldolgozhatja.
+  - Függőség: Hiányzó Auditor robot (lásd alább).
+- [ ] **Robot 2 (Auditor) implementálása:** Staging → Production átemelés.
+  - Olvassa ki a küszöböt a `system_parameters`-ből.
+  - Ha a trust_score elég magas:
+    - Organization létrehozása (Digital Twin).
+    - ServiceProfile létrehozása a staging adatok alapján.
+    - Státusz átállítás `active` vagy `pending_validation`.
+  - Ha nem igazolható az adat: InternalNotification a moderátoroknak.
+  - Audit log rögzítése.
+- [ ] **Séma bővítés:** A `service_staging` táblához hiányzó mezők hozzáadása.
+  - `contact_phone`, `website`, `external_id`, `contact_email`
+  - Migráció: Alembic szkript.
+
+### 3. Gamification API & Verseny (Logic)
+
+- [ ] **POST /submit-service:** User szint ellenőrzés, 90 napos cooldown check, büntetési szorzók.
+  - Ellenőrzés: `restriction_level` alapján XP szorzó (-1 szint = 50% XP, -2 szint = 20% XP).
+  - Cooldown: `UserContribution` tábla alapján, ugyanazon fingerprint esetén.
+  - XP jutalom: `SystemParameter` alapján, korrigálva a büntetési szorzóval.
+- [ ] **GET /leaderboard:** Szezonális toplista.
+  - Szezon kiválasztása (`is_active = TRUE`).
+  - Rangsorolás: Szezonális XP alapján.
+  - Adatvédelem: Maszkolt e-mail címek (`a***@domain.com`).
+- [ ] **POST /claim-business:** Tulajdonosi igénylés indítása.
+  - Feltétel: `trust_score ≥ 100` és `is_verified = TRUE`.
+  - Moderátori jóváhagyás szükséges.
+  - Jogosultság átadása a kérvényező felhasználónak.
+
+### 4. Moderáció & Admin (Protection)
+
+- [ ] **Büntető mechanizmus:** Ha a Robot 4 vagy moderátor hibás adatot talál → User strike → `restriction_level` csökkentés.
+  - Strikes tárolása: `gamification.user_strikes`.
+  - Automatikus szintcsökkentés: 3 strikes → `restriction_level -1`.
+- [ ] **Admin funkció:** Büntetési kvóták és XP értékek állítása a `SystemParameter` táblán keresztül.
+  - Admin UI: Paraméterek szerkesztése (küszöbértékek, szorzók, cooldown idő).
+- [ ] **Moderátori értesítések:** InternalNotification rendszer bővítése.
+  - Értesítési csatornák: email, in-app, push (opcionális).
+
+## 🗺️ Kapcsolódó Gitea Kártyák
+- #76: Hibás Robot 3 (Enricher) – közvetlen publikálás a service_profiles táblába (LEZÁRVA)
+- #77: Service Staging tábla hiányzó mezői (contact_phone, website, external_id) (LEZÁRVA)
+- #78: Hiányzó Auditor robot a staging -> production átvitelhez (LEZÁRVA)
+
+## 🔗 Függőségek
+- **Meglévő rendszer:** Gamification API (`/my-stats`, `/leaderboard`, `/submit-service`), Service robot pipeline (0–4), SystemParameter tábla.
+- **Külső rendszerek:** Google Places API (Robot 4), Docker környezet, PostgreSQL adatbázis.
+
+## 🚀 Megvalósítási Lépések
+1. **Adatbázis migrációk** (Alembic) – Season, UserContribution, UserStats bővítés, service_staging mezők.
+2. **Robot refactoring** – Robot 3 logika finomhangolása, Robot 2 (Auditor) implementálása.
+3. **API bővítés** – Új végpontok, meglévők módosítása (submit-service, leaderboard, claim-business).
+4. **Moderációs rendszer** – Strikes kezelés, admin felület integráció.
+5. **Tesztelés** – Egységtesztek, integrációs tesztek, teljes pipeline teszt.
+6. **Dokumentáció** – API dokumentáció, robot leírások, admin útmutató.
+
+## ⚠️ Kockázatok
+- **Adatbázis séma változás:** Meglévő adatok migrálása szükséges lehet.
+- **Robot függőségek:** Ha az Auditor robot hibás, a staging adatok felhalmozódnak.
+- **Teljesítmény:** A leaderboard lekérdezés nagy adatmennyiség esetén lassú lehet (indexelés, gyorsítótárazás).
+
+## ✅ Sikeresség Mérésére
+- A staging → production átvitel sikeresen működik (napi X szerviz publikálása).
+- A spam beküldések száma csökken (strikes rendszer hatékonysága).
+- A felhasználói engagement növekszik (XP, ranglétrák, versenyek).
+
+---
+*Ez a dokumentum a projekt gyökerében található, és a 8. mérföldkő tervezési fázisát rögzíti. A tényleges megvalósítás előtt az Architect és a Code csapat felülvizsgálja.*

docs/masterbook_2.0.1/cleanup_audit_root.md

@@ -0,0 +1,61 @@
+# Gyökérkönyvtár Audit és Tisztítási Terv (Root Directory Cleanup Audit)
+
+A "Spring Cleaning" első fázisa keretében átvizsgáltuk a projekt gyökérkönyvtárában található összes fájlt. Az alábbi lista a fájlok kategorizálását tartalmazza. Még semmilyen törlés vagy áthelyezés nem történt. Kérjük, hagyd jóvá a lenti felosztást a végrehajtás előtt.
+
+## 🟢 Helyén marad és kell (Keep in place)
+- `.env`: A projekt fő környezeti változóit és titkos konfigurációit tartalmazza.
+- `.gitignore`: A Git verziókövetésből kizárandó fájlok és mappák listája.
+- `.roomodes`: A Roo kódoló AI asszisztens egyedi profiljainak és eszközeinek definíciója.
+- `docker-compose.yml`: A teljes mikroszolgáltatásos architektúra (Docker) leírása.
+- `readme.md`: A projekt alapvető leírását és telepítési/indítási útmutatóját tartalmazza.
+- `service_finder.code-workspace`: A VS Code projekt munkaterületének beállítási fájlja.
+- `sf_gitea.sh`: A beépített Gitea projektmenedzsment-eszköz indítását és menedzselését végző shell script.
+- `sf_run.sh`: A projekt Docker-alapú szolgáltatásainak elindítását leegyszerűsítő szkript.
+
+## 🟡 Kell, de át kell helyezni (Keep but move)
+- `backup_manager.sh`: Biztonsági mentéseket kezelő szkript. Át kell helyezni a `.roo/scripts/` vagy `/scripts/` mappába a többi operációs szkript mellé.
+- `MILESTONE_8_GAMIFICATION_PRO.md`: Gamifikációs projektterv. Át kell helyezni a `docs/masterbook_2.0.1/` mappába a többi dokumentációhoz.
+- `Roo code_utasitas.md`: Magyar nyelvű Roo AI utasítások. A `docs/` vagy `.roo/` mappába való a gyökér helyett.
+
+## 🔴 Nem kell, mehet az archívumba (Archive/Delete)
+- `=`: Véletlenül generált, értelmetlen nevű output fájl.
+- `0`: Szintén egy véletlenül létrejött fájl, valószínűleg egy teszt kimenete.
+- `add_categories.py`: Egyszeri adatbázis-feltöltő szkript a kategóriák inicializálásához.
+- `audit_report_robots_local.md`: Régi, már elavult robot-audit jelentés.
+- `audit_report_vehicle_robots.md`: Korábbi, feleslegessé vált járműrobot audit napló.
+- `classify_workers.py`: Ideiglenes szkript a teszt-munkások kategorizálására.
+- `complete_ailogs.py`: Az AI logok kiegészítésére szolgáló eldobható script.
+- `create_diff.py`: Kód-összehasonlításhoz használt, egyszeri segédszkript.
+- `create_integration_session.py`: Integrációs tesztek munkamenetének gyors legenerálására használt script.
+- `create_sandbox_user.py`: Egyszeri, eldobható homokozó-felhasználót generáló kód.
+- `create_test_identity.py`: A "Dual Entity" identity modell tesztelésére szánt egyszeri script.
+- `create_test_user_simple.py`: Gyors, lokális tesztfelhasználót létrehozó segédkód.
+- `database_check_test.txt`: Adatbázis-kapcsolat tesztjének szöveges eredményfájlja.
+- `db_audit_report.csv`: Korábbi adatbázis-elemzésből származó táblázatos export.
+- `fix_classification.py`: Egy korábbi adatbázis hibát javító, ma már felesleges migrációs szkript.
+- `fix_schema_refs.py`: Séma-hivatkozások javítását végző, lejárt szükségességű script.
+- `full_schema_backup_2026-02-14.sql`: Régi, februári adatbázis biztonsági mentés.
+- `git init`: Egy véletlenül fájlként létrehozott "git init" parancs eredménye.
+- `gitea_audit_report.md`: Elavult, régebbi Gitea állapotjelentés.
+- `gitea_body.md`: Valószínűleg egy Gitea API hívás tesztelésénél hátramaradt body payload fájl.
+- `manual_migration_summary.md`: Egy régi kézi adatbázis módosítás dokumentációja.
+- `rdw_probe.py`: A holland rendszám API (RDW) működését vizsgáló kísérleti script.
+- `reset_test_user_password.py`: Tesztfelhasználó jelszavának nullázására használt segédkód.
+- `schema_dump.sql`: Adatbázis sémájának ideiglenes mentése.
+- `seed_discovery.py`: A GB Discovery táblák adatokkal való feltöltésére írt egyszeri script.
+- `test_catalog_simple.py`: A járműkatalógust lokálisan, terminálból tesztelő fájl.
+- `test_catalog_verification_v2.py`: A jármű-ellenőrzési folyamat második verziójának ideiglenes tesztje.
+- `test_catalog_verification.py`: A katalógus validációt vizsgáló korábbi tesztkód.
+- `test_draft_vehicle.py`: A `DRAFT` járműstátusz logikáját kipróbáló szkript.
+- `test_final_verification.py`: A jármű-katalógus végső jóváhagyási lépését ellenőrző kód.
+- `test_integration.py`: Egy átfogó integrációs teszt kísérleti fájlja.
+- `test_mailpit.py`: A Mailpit e-mail elfogó szolgáltatást vizsgáló teszt.
+- `test_r0_spider.py`: A 0-s adatgyűjtő robot (Spider) működésének teszt szkriptje.
+- `test_registration_smtp.py`: E-mail alapú regisztrációs folyamat validálására írt fájl.
+- `tree.txt`: Egy korábbi mappa-struktúra listázásának (tree) kimenete.
+- `update_env.py`: Az `.env` fájl módosítására írt ideiglenes script.
+- `update_ledger.awk`: Főkönyvi vagy log fájl manipulációra szolgáló AWK script.
+- `update_ledger.py`: A pénzügyi főkönyvi folyamatot tesztelő Python kód.
+- `vehicle.modelfile`: Ollama AI modell beállítási fájl a járműfelismeréshez.
+- `verify_financial_truth_simple.py`: Pénzügyi modul működését validáló eldobható script.
+- `verify_financial_truth.py`: A Triple Wallet gazdasági motor mélyebb lokális tesztje.

docs/masterbook_2.0.1/cleanup_audit_subdirs.md

@@ -0,0 +1,35 @@
+# Alkönyvtárak Audit és Tisztítási Terv (Subdirectory Cleanup Audit)
+
+A "Spring Cleaning" második fázisa keretében átvizsgáltuk a `/backend` és `/frontend` könyvtárakat, különös tekintettel az ideiglenes fájlokra, tesztszkriptekre és nem használt komponensekre. Az alábbi lista a fájlok kategorizálását tartalmazza. Még semmilyen törlés vagy áthelyezés nem történt. Kérjük, hagyd jóvá a lenti felosztást a végrehajtás előtt.
+
+## 🟢 Helyén marad és kell (Keep in place)
+
+### Backend
+- `/backend/app/tests/e2e/*`: Az End-to-End integrációs tesztek mappája. Ezek a kódok szükségesek a CI/CD pipeline-hoz és a rendszeres ellenőrzésekhez (pl. `test_robot.py`, `test_organization_flow.py`).
+- `/backend/app/tests/test_admin_audit_gitea.py` és variánsai: A Gitea és adminisztrációs audit logikát validáló tesztek.
+
+### Frontend
+- `/frontend/tests/e2e/frontend-flow.spec.js`: A Playwright alapú e2e tesztelés specifikációja, szükséges a UI automatizált teszteléséhez.
+
+## 🟡 Kell, de át kell helyezni (Keep but move)
+
+### Backend
+- `/backend/test_registration.py`, `/backend/test_registration2.py`, `/backend/sendgrid_live_test.py`: Gyökérmappában lévő (backend/) tesztfájlok, amiket be kell mozgatni a `/backend/app/tests/` könyvtárba.
+- `/backend/test_catalog_verification.py`, `/backend/test_catalog_verification_v2.py`, `/backend/test_catalog_simple.py`, `/backend/test_final_verification.py`: Katalógus ellenőrző tesztek, amiknek szintén a `/backend/app/tests/` alatt a helyük.
+- `/backend/create_test_user.py`, `/backend/create_test_user_fixed.py`, `/backend/create_test_user_final.py`: Ezeket a segédszkripteket egy új `/backend/scripts/` vagy `/backend/app/scripts/` mappába kell helyezni.
+- `/backend/reset_test_user_password.py`: Tesztadatokat manipuláló script, helye a `/backend/scripts/` mappában van.
+
+## 🔴 Nem kell, mehet az archívumba (Archive/Delete)
+
+### Backend
+- `/backend/app/test_billing_engine.py`: Valószínűleg elavult, ideiglenes tesztfájl, ami nem a hivatalos tesztmappában van.
+- `/backend/app/test_hierarchical.py`: Szintén egy eldobható, ideiglenes tesztszkript.
+- `/backend/archive_v1_scripts/test_config_service.py`: V1-es archív script, már nem releváns.
+- `/backend/test_asset_schema.py`: Ideiglenes sématesztelő script a backend gyökerében.
+- `/backend/temp`: Üres vagy átmeneti fájlokat tartalmazó mappa, törölhető.
+
+### Frontend
+- `/frontend/tests/automated_flow_test.js`: Régi vagy kísérleti tesztfájl, a Playwright vette át a helyét (`frontend-flow.spec.js`).
+- `/frontend/admin/test-structure.sh`: Adminisztrációs felülethez tartozó eldobható vagy ideiglenes tesztszkript.
+- `/frontend/admin/.nuxt/`: Átmeneti build és cache mappák, amiket a fejlesztői szerver generál. Nem kell verziókövetni, és törölhetők (újragenerálódnak).
+- `/frontend/test-results/`: Tesztfuttatások kimeneti mappája (pl. Playwright riportok), nem szükséges megtartani a forráskódban.

docs/masterbook_2.0.1/deep_analysis_v201.md

@@ -0,0 +1,45 @@
+# Masterbook 2.0.1: Backend - Frontend UI Szakadék Elemzés
+
+**Dátum:** 2026. március 29.
+**Készítette:** Enterprise Solutions Architect
+**Referencia:** Issue #172 Mélyelemzés
+
+## 1. Vezetői Összefoglaló (A Brutális Valóság)
+
+A mai nap folyamán a Backend rendszermag (SQLAlchemy + Database + API) sikeresen megkapta a Masterbook 2.0.1 legfejlettebb vállalati funkcióit:
+1. **`data_status` oszlop** a `vehicle.assets` táblában (DRAFT, ACTIVE, stb. státuszokhoz).
+2. **`vehicle_transfer_requests` tábla** a tulajdonosváltási (Owner transfer) forgatókönyvekhez (rendszám igénylés/átvétel/elutasítás).
+3. **`system_data_completion_weights` tábla és dinamikus `completion_percentage`** a profil kitöltöttség mérésére (Gamification és Trust score alapja).
+
+**A Frontend azonban jelenleg "vak" és teljesen leválasztott ezekről a mély, vállalati szintű (Enterprise) funkciókról.** 
+A Vue.js komponensek, mint a `Dashboard.vue`, `VehicleCard.vue`, `VehicleShowcase.vue` vagy `AddVehicle.vue` vagy hardkódolt értékekkel (vagy egyszerű fallbacks-ekkel) dolgoznak, vagy egyáltalán nem is jelenítik meg a Backend által szolgáltatott adatokat. Ráadásul az alapvető navigációt biztosító profilt váltó rendszerek (Profile/Organization Switcher) 500-as Internal Server Errort dobnak bizonyos esetekben, ami blokkolja a Garage funkciók rendes tesztelését.
+
+## 2. Részletes Elemzés (Mélyfúrás a kódban)
+
+### 2.1. A Dinamikus Profil Kitöltöttség (Completion Percentage) és Data Status Hiánya
+**A Backend oldalon:** 
+A rendszer a `system_data_completion_weights` alapján súlyozza a megadott adatokat, és API válaszban küldené a dinamikusan kalkulált `completion_percentage` értéket és az adat minőségét/státuszát (`data_status`).
+**A Frontend oldalon:**
+- A `frontend/src/components/garage/VehicleCard.vue` fájlban jelenleg egy hardkódolt vagy hiányos fall-back szerepel:
+  ```vue
+  <div class="text-xs text-gray-600 mb-1">Profile: {{ vehicle.profile_completion_percentage || 0 }}% Complete</div>
+  <div class="w-full bg-gray-200 rounded-full h-2">
+    <div class="bg-yellow-500 h-2 rounded-full" :style="{ width: (vehicle.profile_completion_percentage || 0) + '%' }"></div>
+  </div>
+  ```
+- A `vehicle.status` ugyan ki van vezetve (pl. `'draft'`), de az új `data_status` szintű bontás (enum: DRAFT, DISCOVERED, ENRICHED, ACTIVE, ARCHIVED stb.) vizualizálása nem teljes körű vagy nincs a helyes backend mezőre drótozva.
+
+### 2.2. A Jármű Átruházás (Vehicle Transfer Requests) teljes hiánya a UI-on
+**A Backend oldalon:**
+Teljes életciklus kezelés (Scenario A, B, C) készült a rendszám alapján történő igénylésre, konfliktuskezelésre (ha már valakié az autó), és tulajdonosváltás lebonyolítására.
+**A Frontend oldalon:**
+- A `frontend/src/views/AddVehicle.vue` csak egy egyszerű form (`model_name`, `plate`, `vin`, `current_odo`), amely a `POST /assets/vehicles` endpointot hívja.
+- Nincs UI ág arra az esetre, ha a API 409 Conflict-ot adna vissza (már létezik a jármű).
+- Nincs "Transfer Request" nézet, ahol a felhasználó láthatná a bejövő és kimenő jármű igényléseit, és ahol jóváhagyhatná/elutasíthatná azokat.
+
+### 2.3. A Blokkoló Hiba: 500-as hiba a Profile/Organization Switcher-ben
+Ahhoz, hogy a B2B és B2C (Private Garage vs. Corporate Fleet) nézeteket és járműveket érdemben tesztelni lehessen, a fiókváltás kritikus. Jelenleg a Profile Select / Org Switcher backend/frontend integrációja bizonyos API hívásoknál 500-as Internal Server Errorra fut, ami lehetetlenné teszi a különböző szerepkörök (Owner vs. Member, Private vs. Corporate) tiszta elkülönítését és tesztelését a Garage nézetben. 
+
+## 3. Következtetés
+
+Jelenleg egy "Ferrari motoros Trabantot" építettünk. A Backend enterprise szinten kezeli az állapottérgépet (State Machine), a minőségi pontozást és az eszköztulajdonosi konfliktusokat, míg a Frontend egy v1-es, "MVP" (Minimum Viable Product) szintű UI-t használ. Ezt a szakadékot azonnal, három célzott Issue (Gitea jegy) formájában kell áthidalnunk.

docs/masterbook_2.0.1/garage_hierarchy.md

@@ -0,0 +1,200 @@
+# 🏢 Garage-Centric Hierarchy Audit Report
+
+**Audit Date**: 2026-03-29  
+**Issue**: #179 - SYSTEM ARCHITECT - CODE & SCHEMA AUDIT  
+**Auditor**: Fast Coder (Core Developer)
+
+## 📋 Executive Summary
+
+This audit verifies the implementation of the "Masterbook 2.0.1 Hierarchy": **User → Org (Private/Corp) → Branch → Garage → Vehicle**. The audit reveals that the core hierarchy is partially implemented with some gaps that need to be addressed.
+
+## 🔍 Current Implementation Status
+
+### ✅ **IMPLEMENTED CORRECTLY**
+
+#### 1. Registration Step 2 - Private Organization Creation
+- **Location**: `backend/app/services/auth_service.py` - `complete_kyc()` method
+- **Status**: ✅ **FULLY IMPLEMENTED**
+- **Details**: When a user completes KYC (Registration Step 2), the system:
+  - Creates an `Organization` with `OrgType.individual`
+  - Sets `user.scope_id = str(new_org.id)` 
+  - Creates a default `Branch` with `name="Home Base"` and `is_main=True`
+  - Creates `OrganizationMember` with `role="OWNER"`
+- **Code Reference**: Lines 159-191 in `auth_service.py`
+
+#### 2. Organization Model
+- **Location**: `backend/app/models/marketplace/organization.py`
+- **Status**: ✅ **COMPLETE**
+- **Schema**: `fleet.organizations`
+- **Key Fields**: `id`, `full_name`, `org_type`, `owner_id`, `status`, `is_active`
+- **Relationships**: Has `branches` relationship to `Branch` model
+
+#### 3. Branch Model (Acting as Garage)
+- **Location**: `backend/app/models/marketplace/organization.py` - `Branch` class
+- **Status**: ✅ **COMPLETE**
+- **Schema**: `fleet.branches`
+- **Key Fields**: `id` (UUID), `organization_id`, `name`, `is_main`, `address_id`
+- **Note**: No dedicated "Garage" model exists - Branch serves as the Garage container
+
+#### 4. Asset Model
+- **Location**: `backend/app/models/vehicle/asset.py` - `Asset` class
+- **Status**: ✅ **COMPLETE**
+- **Schema**: `vehicle.assets`
+- **Key Fields**: `id` (UUID), `vin`, `license_plate`, `current_organization_id`, `owner_org_id`
+
+### ⚠️ **PARTIALLY IMPLEMENTED / GAPS IDENTIFIED**
+
+#### 1. Asset to Branch/Garage Linkage
+- **Status**: ❌ **MISSING**
+- **Issue**: Assets are linked to Organizations via `current_organization_id` and `owner_org_id`, but there's no direct `branch_id` or `garage_id` field to specify which Branch/Garage the asset belongs to.
+- **Current**: Assets use `AssetAssignment` model for many-to-many relationship with Organizations
+- **Required**: Add `branch_id` field to Asset model
+
+#### 2. Verified Purchase Date Field
+- **Status**: ⚠️ **PARTIAL**
+- **Current Fields**:
+  - `first_registration_date` in Asset model (line 48)
+  - `activation_date` in AssetFinancials model (line 146)
+- **Missing**: Explicit `verified_purchase_date` field for cost cut-off logic
+- **Required**: Add `verified_purchase_date` to AssetFinancials model
+
+#### 3. Relocation Performed Flag
+- **Status**: ❌ **MISSING**
+- **Issue**: No `relocation_performed` flag for one-time relocation logic
+- **Required**: Add boolean `relocation_performed` field to Asset model
+
+## 🗺️ Hierarchy Mapping
+
+```
+User (identity.users)
+    ↓
+Organization (fleet.organizations) ← Private Org created during KYC
+    ↓
+Branch (fleet.branches) ← Acts as "Garage" container
+    ↓
+Asset (vehicle.assets) ← Missing direct branch_id linkage
+```
+
+## 📊 Database Schema Analysis
+
+### Current Asset-Organization Relationship
+```sql
+-- Current linkage (via AssetAssignment)
+asset_assignments (fleet schema)
+    asset_id → vehicle.assets.id
+    organization_id → fleet.organizations.id
+
+-- Direct fields in Asset
+assets (vehicle schema)
+    current_organization_id → fleet.organizations.id
+    owner_org_id → fleet.organizations.id
+```
+
+### Missing Branch Linkage
+```sql
+-- PROPOSED ADDITION to Asset model
+ALTER TABLE vehicle.assets 
+ADD COLUMN branch_id UUID REFERENCES fleet.branches(id);
+```
+
+## 🔧 Required Code Modifications
+
+### 1. Asset Model Updates (`backend/app/models/vehicle/asset.py`)
+
+```python
+# Add to Asset class (around line 64):
+branch_id: Mapped[Optional[uuid.UUID]] = mapped_column(
+    PG_UUID(as_uuid=True), 
+    ForeignKey("fleet.branches.id"),
+    nullable=True
+)
+relocation_performed: Mapped[bool] = mapped_column(
+    Boolean, 
+    default=False, 
+    server_default=text("false")
+)
+
+# Add relationship:
+branch: Mapped[Optional["Branch"]] = relationship("Branch")
+```
+
+### 2. AssetFinancials Model Updates
+
+```python
+# Add to AssetFinancials class:
+verified_purchase_date: Mapped[Optional[datetime]] = mapped_column(
+    DateTime(timezone=True),
+    nullable=True
+)
+```
+
+### 3. Schema Updates Required
+- Run `sync_engine.py` after model changes
+- **DO NOT** use Alembic migrations directly per project rules
+
+## 🧪 Test Script for Hierarchy Verification
+
+A test script has been prepared to verify the separation logic:
+
+```python
+# Test: Create 1 Private Garage car and 1 Corporate Branch car
+# Verify GET /vehicles (with active scope_id) only shows cars belonging to specific context
+```
+
+**Test Logic**:
+1. Create User A with Private Organization (Org A)
+2. Create User B with Corporate Organization (Org B)  
+3. Add Vehicle 1 to Org A's Branch
+4. Add Vehicle 2 to Org B's Branch
+5. Verify User A only sees Vehicle 1 when calling GET /vehicles
+6. Verify User B only sees Vehicle 2 when calling GET /vehicles
+
+## 🚨 Critical Findings
+
+### 1. **Scope Isolation Works**
+The `user.scope_id` mechanism correctly isolates data at the Organization level. When a user queries `/vehicles`, the API filters by `current_organization_id = user.scope_id`.
+
+### 2. **Branch-Level Isolation Missing**
+While Organization-level isolation exists, there's no Branch-level filtering. All assets in an Organization are visible regardless of which Branch they belong to.
+
+### 3. **Cost Cut-off Logic Incomplete**
+Without `verified_purchase_date` and `relocation_performed` fields, the historical cost tracking and one-time relocation logic cannot be properly implemented.
+
+## 📝 Recommendations
+
+### **HIGH PRIORITY**
+1. **Add `branch_id` to Asset model** - Enable Branch/Garage level asset management
+2. **Add `verified_purchase_date` to AssetFinancials** - Support cost cut-off logic
+3. **Add `relocation_performed` flag to Asset** - Enable one-time relocation tracking
+
+### **MEDIUM PRIORITY**
+4. Update API endpoints to respect `branch_id` in queries
+5. Enhance admin interface to show Branch assignment for assets
+6. Add Branch filtering to vehicle listing endpoints
+
+### **LOW PRIORITY**
+7. Consider creating dedicated `Garage` model if Branch semantics differ significantly
+8. Add Branch-level permissions for fleet managers
+
+## 🔄 Synchronization Process
+
+**STRICT RULE**: Apply changes ONLY via `sync_engine.py`:
+
+```bash
+docker compose exec roo-helper python3 /app/backend/app/scripts/sync_engine.py
+```
+
+**DO NOT** use Alembic migrations directly. The sync engine is the primary source of truth for schema generation in Masterbook 2.0.1 architecture.
+
+## 📈 Next Steps
+
+1. **User Approval**: Present this "Gap Report" for approval before implementing changes
+2. **Implementation**: Apply the three high-priority model modifications
+3. **Sync**: Run `sync_engine.py` to update database schema
+4. **Testing**: Execute the hierarchy verification test script
+5. **Validation**: Confirm GET /vehicles endpoint respects scope isolation
+
+---
+
+**Audit Completed**: 2026-03-29  
+**Next Review**: After gap implementation approval