chore: Backend codebase cleanup and archiving of legacy scripts
This commit is contained in:
Roo
135
docs/audits/admin_gap_analysis.md
Normal file
135
docs/audits/admin_gap_analysis.md
Normal file
@@ -0,0 +1,135 @@
|
||||
# Admin System Gap Analysis Report
|
||||
*Generated: 2026-03-21 12:14:33*
|
||||
|
||||
## 📊 Executive Summary
|
||||
|
||||
- **Total hardcoded business values found:** 149
|
||||
- **API modules analyzed:** 22
|
||||
- **Modules missing admin endpoints:** 20
|
||||
|
||||
## 🔍 Hardcoded Business Values
|
||||
|
||||
These values should be moved to `system_parameters` table for dynamic configuration.
|
||||
|
||||
| File | Line | Variable | Value | Context |
|
||||
|------|------|----------|-------|---------|
|
||||
| `seed_discovery.py` | 8 | `url` | `"https://opendata.rdw.nl/resource/m9d7-ebf2.json?$s..."` | `url = "https://opendata.rdw.nl/resource/m9d7-ebf2.json?$select=distinct%20merk&$limit=50000"` |
|
||||
| `create_sandbox_user.py` | 28 | `API_BASE` | `"http://localhost:8000..."` | `API_BASE = "http://localhost:8000"` |
|
||||
| `create_sandbox_user.py` | 29 | `MAILPIT_API` | `"http://sf_mailpit:8025/api/v1/messages..."` | `MAILPIT_API = "http://sf_mailpit:8025/api/v1/messages"` |
|
||||
| `create_sandbox_user.py` | 30 | `MAILPIT_DELETE_ALL` | `"http://sf_mailpit:8025/api/v1/messages..."` | `MAILPIT_DELETE_ALL = "http://sf_mailpit:8025/api/v1/messages"` |
|
||||
| `create_sandbox_user.py` | 35 | `SANDBOX_PASSWORD` | `"Sandbox123!..."` | `SANDBOX_PASSWORD = "Sandbox123!"` |
|
||||
| `create_sandbox_user.py` | 138 | `max_attempts` | `5` | `max_attempts = 5` |
|
||||
| `create_sandbox_user.py` | 139 | `wait_seconds` | `3` | `wait_seconds = 3` |
|
||||
| `app/test_billing_engine.py` | 32 | `base_amount` | `100.0` | `base_amount = 100.0` |
|
||||
| `app/test_billing_engine.py` | 133 | `file_path` | `"backend/app/services/billing_engine.py..."` | `file_path = "backend/app/services/billing_engine.py"` |
|
||||
| `app/api/v1/endpoints/providers.py` | 11 | `user_id` | `2` | `user_id = 2` |
|
||||
| `app/api/v1/endpoints/services.py` | 68 | `new_level` | `80` | `new_level = 80` |
|
||||
| `app/api/v1/endpoints/social.py` | 15 | `user_id` | `2` | `user_id = 2` |
|
||||
| `app/models/core_logic.py` | 17 | `__tablename__` | `"subscription_tiers..."` | `__tablename__ = "subscription_tiers"` |
|
||||
| `app/models/core_logic.py` | 29 | `__tablename__` | `"org_subscriptions..."` | `__tablename__ = "org_subscriptions"` |
|
||||
| `app/models/core_logic.py` | 48 | `__tablename__` | `"credit_logs..."` | `__tablename__ = "credit_logs"` |
|
||||
| `app/models/core_logic.py` | 64 | `__tablename__` | `"service_specialties..."` | `__tablename__ = "service_specialties"` |
|
||||
| `app/models/reference_data.py` | 7 | `__tablename__` | `"reference_lookup..."` | `__tablename__ = "reference_lookup"` |
|
||||
| `app/models/identity/identity.py` | 25 | `region_admin` | `"region_admin..."` | `region_admin = "region_admin"` |
|
||||
| `app/models/identity/identity.py` | 26 | `country_admin` | `"country_admin..."` | `country_admin = "country_admin"` |
|
||||
| `app/models/identity/identity.py` | 28 | `sales_agent` | `"sales_agent..."` | `sales_agent = "sales_agent"` |
|
||||
| `app/models/identity/identity.py` | 30 | `service_owner` | `"service_owner..."` | `service_owner = "service_owner"` |
|
||||
| `app/models/identity/identity.py` | 31 | `fleet_manager` | `"fleet_manager..."` | `fleet_manager = "fleet_manager"` |
|
||||
| `app/models/identity/identity.py` | 204 | `__tablename__` | `"verification_tokens..."` | `__tablename__ = "verification_tokens"` |
|
||||
| `app/models/identity/identity.py` | 217 | `__tablename__` | `"social_accounts..."` | `__tablename__ = "social_accounts"` |
|
||||
| `app/models/identity/identity.py` | 235 | `__tablename__` | `"active_vouchers..."` | `__tablename__ = "active_vouchers"` |
|
||||
| `app/models/identity/identity.py` | 249 | `__tablename__` | `"user_trust_profiles..."` | `__tablename__ = "user_trust_profiles"` |
|
||||
| `app/models/identity/address.py` | 14 | `__tablename__` | `"geo_postal_codes..."` | `__tablename__ = "geo_postal_codes"` |
|
||||
| `app/models/identity/address.py` | 24 | `__tablename__` | `"geo_streets..."` | `__tablename__ = "geo_streets"` |
|
||||
| `app/models/identity/address.py` | 33 | `__tablename__` | `"geo_street_types..."` | `__tablename__ = "geo_street_types"` |
|
||||
| `app/models/identity/social.py` | 24 | `__tablename__` | `"service_providers..."` | `__tablename__ = "service_providers"` |
|
||||
| `app/models/identity/social.py` | 61 | `__tablename__` | `"competitions..."` | `__tablename__ = "competitions"` |
|
||||
| `app/models/identity/social.py` | 73 | `__tablename__` | `"user_scores..."` | `__tablename__ = "user_scores"` |
|
||||
| `app/models/identity/social.py` | 91 | `__tablename__` | `"service_reviews..."` | `__tablename__ = "service_reviews"` |
|
||||
| `app/models/identity/security.py` | 24 | `__tablename__` | `"pending_actions..."` | `__tablename__ = "pending_actions"` |
|
||||
| `app/models/vehicle/vehicle.py` | 24 | `__tablename__` | `"cost_categories..."` | `__tablename__ = "cost_categories"` |
|
||||
| `app/models/vehicle/vehicle.py` | 114 | `__tablename__` | `"vehicle_odometer_states..."` | `__tablename__ = "vehicle_odometer_states"` |
|
||||
| `app/models/vehicle/vehicle.py` | 145 | `__tablename__` | `"vehicle_user_ratings..."` | `__tablename__ = "vehicle_user_ratings"` |
|
||||
| `app/models/vehicle/vehicle.py` | 196 | `__tablename__` | `"gb_catalog_discovery..."` | `__tablename__ = "gb_catalog_discovery"` |
|
||||
| `app/models/vehicle/vehicle_definitions.py` | 19 | `__tablename__` | `"vehicle_types..."` | `__tablename__ = "vehicle_types"` |
|
||||
| `app/models/vehicle/vehicle_definitions.py` | 35 | `__tablename__` | `"feature_definitions..."` | `__tablename__ = "feature_definitions"` |
|
||||
| `app/models/vehicle/vehicle_definitions.py` | 53 | `__tablename__` | `"vehicle_model_definitions..."` | `__tablename__ = "vehicle_model_definitions"` |
|
||||
| `app/models/vehicle/vehicle_definitions.py` | 147 | `__tablename__` | `"model_feature_maps..."` | `__tablename__ = "model_feature_maps"` |
|
||||
| `app/models/vehicle/external_reference.py` | 7 | `__tablename__` | `"external_reference_library..."` | `__tablename__ = "external_reference_library"` |
|
||||
| `app/models/vehicle/external_reference_queue.py` | 7 | `__tablename__` | `"auto_data_crawler_queue..."` | `__tablename__ = "auto_data_crawler_queue"` |
|
||||
| `app/models/vehicle/asset.py` | 14 | `__tablename__` | `"vehicle_catalog..."` | `__tablename__ = "vehicle_catalog"` |
|
||||
| `app/models/vehicle/asset.py` | 91 | `__tablename__` | `"asset_financials..."` | `__tablename__ = "asset_financials"` |
|
||||
| `app/models/vehicle/asset.py` | 107 | `__tablename__` | `"asset_costs..."` | `__tablename__ = "asset_costs"` |
|
||||
| `app/models/vehicle/asset.py` | 125 | `__tablename__` | `"vehicle_logbook..."` | `__tablename__ = "vehicle_logbook"` |
|
||||
| `app/models/vehicle/asset.py` | 154 | `__tablename__` | `"asset_inspections..."` | `__tablename__ = "asset_inspections"` |
|
||||
| `app/models/vehicle/asset.py` | 169 | `__tablename__` | `"asset_reviews..."` | `__tablename__ = "asset_reviews"` |
|
||||
|
||||
*... and 99 more findings*
|
||||
|
||||
## 🏗️ Admin Endpoints Analysis
|
||||
|
||||
### Modules with Admin Prefix
|
||||
|
||||
*No modules have `/admin` prefix*
|
||||
|
||||
### Modules with Admin Routes (but no prefix)
|
||||
|
||||
*No mixed admin routes found*
|
||||
|
||||
## ⚠️ Critical Gaps: Missing Admin Endpoints
|
||||
|
||||
These core business modules lack dedicated admin endpoints:
|
||||
|
||||
- **users** - No `/admin` prefix and no admin routes
|
||||
- **vehicles** - No `/admin` prefix and no admin routes
|
||||
- **services** - No `/admin` prefix and no admin routes
|
||||
- **assets** - No `/admin` prefix and no admin routes
|
||||
- **organizations** - No `/admin` prefix and no admin routes
|
||||
- **billing** - No `/admin` prefix and no admin routes
|
||||
- **gamification** - No `/admin` prefix and no admin routes
|
||||
- **analytics** - No `/admin` prefix and no admin routes
|
||||
- **security** - No `/admin` prefix and no admin routes
|
||||
- **documents** - No `/admin` prefix and no admin routes
|
||||
- **evidence** - No `/admin` prefix and no admin routes
|
||||
- **expenses** - No `/admin` prefix and no admin routes
|
||||
- **finance_admin** - No `/admin` prefix and no admin routes
|
||||
- **notifications** - No `/admin` prefix and no admin routes
|
||||
- **reports** - No `/admin` prefix and no admin routes
|
||||
- **catalog** - No `/admin` prefix and no admin routes
|
||||
- **providers** - No `/admin` prefix and no admin routes
|
||||
- **search** - No `/admin` prefix and no admin routes
|
||||
- **social** - No `/admin` prefix and no admin routes
|
||||
- **system_parameters** - No `/admin` prefix and no admin routes
|
||||
|
||||
### Recommended Actions:
|
||||
1. Create `/admin` prefixed routers for each missing module
|
||||
2. Implement CRUD endpoints for administrative operations
|
||||
3. Add audit logging and permission checks
|
||||
|
||||
## 🚀 Recommendations
|
||||
|
||||
### Phase 1: Hardcode Elimination
|
||||
1. Create `system_parameters` migration if not exists
|
||||
2. Move identified hardcoded values to database
|
||||
3. Implement `ConfigService` for dynamic value retrieval
|
||||
|
||||
### Phase 2: Admin Endpoint Expansion
|
||||
1. Prioritize modules with highest business impact:
|
||||
- `users` (user management)
|
||||
- `billing` (financial oversight)
|
||||
- `security` (access control)
|
||||
2. Follow consistent pattern: `/admin/{module}/...`
|
||||
3. Implement RBAC with `admin` and `superadmin` roles
|
||||
|
||||
### Phase 3: Monitoring & Audit
|
||||
1. Add admin action logging to `SecurityAuditLog`
|
||||
2. Implement admin dashboard with real-time metrics
|
||||
3. Create automated health checks for admin endpoints
|
||||
|
||||
## 🔧 Technical Details
|
||||
|
||||
### Scan Parameters
|
||||
- Project root: `/app`
|
||||
- Files scanned: Python files in `/app`
|
||||
- Business patterns: 25
|
||||
- Trivial values excluded: None, False, 0, '', "", True, 1, [], {}
|
||||
60
docs/audits/audit_report_robots.md
Normal file
60
docs/audits/audit_report_robots.md
Normal file
@@ -0,0 +1,60 @@
|
||||
# 🤖 Robot Integrity Audit Report
|
||||
Generated: 2026-03-19T19:40:29.528087
|
||||
Total robots discovered: 40
|
||||
|
||||
## Service Robots
|
||||
**Count:** 6
|
||||
- Import successful: 6/6
|
||||
- Syntax clean: 6/6
|
||||
- Interface OK: 2/6
|
||||
|
||||
**Problematic robots:**
|
||||
- `app.workers.service.service_robot_1_scout_osm`: Interface issues
|
||||
- `app.workers.service.service_robot_2_researcher`: Interface issues
|
||||
- `app.workers.service.service_robot_3_enricher`: Interface issues
|
||||
- `app.workers.service.service_robot_5_auditor`: Interface issues
|
||||
|
||||
## Vehicle General
|
||||
**Count:** 28
|
||||
- Import successful: 28/28
|
||||
- Syntax clean: 28/28
|
||||
- Interface OK: 13/28
|
||||
|
||||
**Problematic robots:**
|
||||
- `app.workers.vehicle.R0_brand_hunter`: Interface issues
|
||||
- `app.workers.vehicle.R1_model_scout`: Interface issues
|
||||
- `app.workers.vehicle.R2_generation_scout`: Interface issues
|
||||
- `app.workers.vehicle.R3_engine_scout`: Interface issues
|
||||
- `app.workers.vehicle.bike.bike_R0_brand_hunter`: Interface issues
|
||||
- `app.workers.vehicle.bike.bike_R1_model_scout`: Interface issues
|
||||
- `app.workers.vehicle.bike.bike_R2_generation_scout`: Interface issues
|
||||
- `app.workers.vehicle.bike.bike_R3_engine_scout`: Interface issues
|
||||
- `app.workers.vehicle.bike.bike_R4_final_extractor`: Interface issues
|
||||
- `app.workers.vehicle.ultimatespecs.vehicle_ultimate_r0_spider`: Interface issues
|
||||
- `app.workers.vehicle.ultimatespecs.vehicle_ultimate_r1_scraper`: Interface issues
|
||||
- `app.workers.vehicle.ultimatespecs.vehicle_ultimate_r2_enricher`: Interface issues
|
||||
- `app.workers.vehicle.ultimatespecs.vehicle_ultimate_r3_finalizer`: Interface issues
|
||||
- `app.workers.vehicle.vehicle_robot_2_auto_data_net`: Interface issues
|
||||
- `app.workers.vehicle.vehicle_robot_2_researcher`: Interface issues
|
||||
|
||||
## System & OCR
|
||||
**Count:** 3
|
||||
- Import successful: 3/3
|
||||
- Syntax clean: 3/3
|
||||
- Interface OK: 3/3
|
||||
|
||||
## Uncategorized
|
||||
**Count:** 3
|
||||
- Import successful: 3/3
|
||||
- Syntax clean: 3/3
|
||||
- Interface OK: 1/3
|
||||
|
||||
**Problematic robots:**
|
||||
- `app.workers.vehicle.r5_test`: Interface issues
|
||||
- `app.workers.vehicle.vehicle_data_loader`: Interface issues
|
||||
|
||||
## 📊 Summary
|
||||
- **Total robots:** 40
|
||||
- **Import successful:** 40/40
|
||||
- **Syntax clean:** 40/40
|
||||
- **Interface OK:** 19/40
|
||||
105
docs/audits/audit_report_vehicle_robots.md
Normal file
105
docs/audits/audit_report_vehicle_robots.md
Normal file
@@ -0,0 +1,105 @@
|
||||
# Vehicle Robot Ecosystem - Teljes technikai audit jelentés
|
||||
|
||||
**Audit dátum:** 2026-03-12
|
||||
**Gitea kártya:** #69
|
||||
**Auditáló:** Főmérnök / Rendszerauditőr
|
||||
|
||||
## 1. Áttekintés
|
||||
A `backend/app/workers/vehicle/` könyvtárban 15 fájl található, melyek egy 5 szintű (0–4) robot‑csővezetéket alkotnak. A pipeline célja a járművek technikai adatainak automatikus felfedezése, gyűjtése, kutatása, AI‑alapú dúsítása és végül a valós eszközök (Asset) VIN‑alapú hitelesítése. A robotok önállóan, aszinkron üzemmódban futnak, és az adatbázis rekordjainak státuszmezőin keresztül kommunikálnak (status‑driven pipeline).
|
||||
|
||||
## 2. Fájllista
|
||||
| Fájl | Szint | Rövid leírás |
|
||||
|------|------|--------------|
|
||||
| `vehicle_robot_0_discovery_engine.py` | 0 | Őrkutya (watchdog), differenciális RDW szinkron, havonta teljes adatbázis letöltés |
|
||||
| `vehicle_robot_0_gb_discovery.py` | 0 | Brit (GB) CSV feldolgozás, `gb_catalog_discovery` tábla feltöltése |
|
||||
| `vehicle_robot_0_strategist.py` | 0 | Piaci priorítás számítása (RDW darabszám alapján) |
|
||||
| `vehicle_robot_1_catalog_hunter.py` | 1 | RDW API‑ból technikai adatok kinyerése, `vehicle_model_definitions` táblába írás |
|
||||
| `vehicle_robot_1_gb_hunter.py` | 1 | DVLA API (GB) lekérdezés, `vehicle_model_definitions` táblába írás |
|
||||
| `vehicle_robot_1_2_nhtsa_fetcher.py` | 1.2 | NHTSA API (USA) – csak EU márkákra szűrve |
|
||||
| `vehicle_robot_1_4_bike_hunter.py` | 1.4 | NHTSA API – motorok |
|
||||
| `vehicle_robot_1_5_heavy_eu.py` | 1.5 | RDW API – nehézgépjárművek (teher, busz, lakóautó) |
|
||||
| `vehicle_robot_2_researcher.py` | 2 | DuckDuckGo keresés, strukturált kontextus előállítása AI számára |
|
||||
| `vehicle_robot_3_alchemist_pro.py` | 3 | AI‑alapú adategyesítés (RDW + AI), validáció, `gold_enriched` státusz |
|
||||
| `vehicle_robot_4_vin_auditor.py` | 4 | Asset VIN hitelesítés AI segítségével |
|
||||
| `mapping_rules.py` | – | Forrásmezők leképezése (jelenleg **nincs használatban**) |
|
||||
| `mapping_dictionary.py` | – | Szinonimák normalizálása (jelenleg **nincs használatban**) |
|
||||
| `vehicle_data_loader.py` | – | Külső JSON források betöltése `vehicle.reference_lookup` táblába |
|
||||
| `robot_report.py` | – | Diagnosztikai dashboard, statisztikák megjelenítése |
|
||||
|
||||
## 3. Állapotgép (State Machine) térkép
|
||||
A következő táblázat a robotok által keresett és beállított státuszokat összegzi. A sorrend a pipeline természetes folyását tükrözi.
|
||||
|
||||
### 3.1. `vehicle.catalog_discovery` tábla
|
||||
| Robot (fájl) | Keresett státusz (`WHERE`) | Beállított státusz (`SET` / `INSERT`) | Megjegyzés |
|
||||
|--------------|----------------------------|---------------------------------------|------------|
|
||||
| `0_discovery_engine` | `processing` | `pending` | Őrkutya: beragadt feladatok visszaállítása |
|
||||
| `0_discovery_engine` | – | `pending` (új rekord) | Differenciális szinkron: csak ha nincs `gold_enriched` a `vehicle_model_definitions`‑ben |
|
||||
| `0_strategist` | `NOT IN ('processed', 'in_progress')` | `pending` (prioritás frissítés) | Csak még nem feldolgozott rekordok |
|
||||
| `1_catalog_hunter` | `pending` | `processing` → `processed` | Atomizált zárolás (`SKIP LOCKED`) |
|
||||
| `1_gb_hunter` | `pending` (gb_catalog_discovery) | `processing` → `processed` / `invalid_vrm` | DVLA API kvótakezeléssel |
|
||||
| `1_2_nhtsa_fetcher` | – | `pending` (új rekord) | Csak EU márkákhoz, `USA_IMPORT` piac |
|
||||
| `1_4_bike_hunter` | – | `pending` (új rekord) | Motorok, `USA_IMPORT` piac |
|
||||
| `1_5_heavy_eu` | – | `pending` (új rekord) | Nehézgépjárművek, `EU` piac |
|
||||
|
||||
### 3.2. `vehicle.vehicle_model_definitions` tábla
|
||||
| Robot (fájl) | Keresett státusz (`WHERE`) | Beállított státusz (`SET` / `INSERT`) | Megjegyzés |
|
||||
|--------------|----------------------------|---------------------------------------|------------|
|
||||
| `0_discovery_engine` | `research_in_progress`, `ai_synthesis_in_progress` (2 órás timeout) | `unverified`, `awaiting_ai_synthesis` | Őrkutya: beragadt AI feladatok visszaállítása |
|
||||
| `1_catalog_hunter` | – | `ACTIVE` (új rekord) | `ON CONFLICT DO NOTHING` (make, normalized_name, variant_code, version_code, fuel_type) |
|
||||
| `1_gb_hunter` | – | `ACTIVE` (új rekord) | `ON CONFLICT DO NOTHING` |
|
||||
| `2_researcher` | `unverified`, `awaiting_research`, `ACTIVE` | `research_in_progress` → `awaiting_ai_synthesis` (siker) / `unverified` (újra) / `suspended_research` (max próbálkozás) | Atomizált zárolás, kvótakezelés (DVLA) |
|
||||
| `3_alchemist_pro` | `awaiting_ai_synthesis`, `ACTIVE` | `ai_synthesis_in_progress` → `gold_enriched` (siker) / `manual_review_needed` (max próbálkozás) / `unverified` (vissza) | AI hívás, hibrid merge (RDW + AI), validáció |
|
||||
| `0_discovery_engine` (diff sync) | `gold_enriched` | – | **Védelem:** a `gold_enriched` rekordok kihagyása a felfedezésből |
|
||||
|
||||
### 3.3. `vehicle.gb_catalog_discovery` tábla
|
||||
| Robot (fájl) | Keresett státusz (`WHERE`) | Beállított státusz (`SET` / `INSERT`) |
|
||||
|--------------|----------------------------|---------------------------------------|
|
||||
| `0_gb_discovery` | – | `pending` (új rekord) – csak ha nincs `gold_enriched` a `vehicle_model_definitions`‑ben |
|
||||
| `1_gb_hunter` | `pending` | `processing` → `processed` / `invalid_vrm` |
|
||||
|
||||
### 3.4. `vehicle.assets` tábla
|
||||
| Robot (fájl) | Keresett állapot (`WHERE`) | Beállított státusz (`SET`) |
|
||||
|--------------|----------------------------|----------------------------|
|
||||
| `4_vin_auditor` | `is_verified = false AND vin IS NOT NULL` | `audit_in_progress` → `active` (siker) / `audit_failed` (hiba) |
|
||||
|
||||
## 4. Logikai összefüggések
|
||||
### 4.1. Orchestráció
|
||||
Nincs központi orchestrator. A robotok **párhuzamosan futnak**, és az adatbázis rekordjainak státuszait **közös munka‑memóriaként** használják. A folyamat láncolata:
|
||||
```
|
||||
catalog_discovery (pending)
|
||||
→ robot 1.x hunter (processed)
|
||||
→ vehicle_model_definitions (ACTIVE)
|
||||
→ robot 2 researcher (awaiting_ai_synthesis)
|
||||
→ robot 3 alchemist (gold_enriched)
|
||||
```
|
||||
A `gold_enriched` státuszú rekordok **védettek**: a `0_discovery_engine` és `0_gb_discovery` nem veszi őket fel újra.
|
||||
|
||||
### 4.2. Mapping réteg
|
||||
A `mapping_rules.py` és `mapping_dictionary.py` fájlok **nincsenek integrálva** a robotokba. A `vehicle_data_loader.py` saját, forrásspecifikus leképezést alkalmaz, de a mapping fájlokat nem importálja. Ez a réteg jelenleg kihasználatlan.
|
||||
|
||||
### 4.3. Atomizált zárolás és kvótakezelés
|
||||
A hunterek és kutatók `FOR UPDATE SKIP LOCKED` zárolást használnak, így elkerülhető a race condition. A külső API‑k (DVLA, DuckDuckGo) kvótakezeléssel rendelkeznek (`QuotaManager` osztály).
|
||||
|
||||
## 5. Biztonsági és integritási ellenőrzés
|
||||
### 5.1. `is_manual` védelem hiánya
|
||||
A **teljes kódbázisban egyetlen fájlban sem** található `is_manual` mezőre vagy „manual” kulcsszóra épülő védelem. A robotok csak a `gold_enriched` státusz alapján kerülik a felülírást. **Kockázat:** manuálisan bevitt adatok (pl. admin által javított technikai specifikációk) felülírhatók, ha a rekord státusza nem `gold_enriched`.
|
||||
|
||||
### 5.2. Egyéb védelmi mechanizmusok
|
||||
- `ON CONFLICT DO NOTHING` / `ON CONFLICT DO UPDATE` csak bizonyos egyedi kulcsokon (pl. make, normalized_name, …).
|
||||
- `0_discovery_engine` differenciális szinkronja kihagyja a `gold_enriched` rekordokat.
|
||||
- `0_strategist` nem módosít `processed` vagy `in_progress` státuszú rekordokat.
|
||||
|
||||
## 6. Következtetések
|
||||
1. **A robot‑ökoszisztéma jól strukturált**, atomizált zárolással, kvótakezeléssel és hibatűréssel.
|
||||
2. **A mapping réteg hiányzik** – a `mapping_rules.py` és `mapping_dictionary.py` fájlok nincsenek használatban.
|
||||
3. **Kritikus biztonsági rés:** nincs `is_manual` védelem. A #27, #28, #29 kártyákhoz kapcsolódó beavatkozásoknál ezt figyelembe kell venni.
|
||||
4. **Állapotgép áttekinthető**, a státuszok logikusan lépnek egymás után. A `gold_enriched` státusz jelenti a végső védelmet.
|
||||
|
||||
## 7. Javaslatok a #27, #28, #29 kártyákhoz
|
||||
- **#27 (Mapping integráció):** Kapcsoljuk be a `mapping_rules.py`‑t a `vehicle_data_loader`‑ben, majd terjeszszük ki a hunterekre.
|
||||
- **#28 (Manual védelem):** Vezessünk be egy `is_manual` (boolean) mezőt a `vehicle_model_definitions` táblában, és a robotok minden írása előtt ellenőrizzük (`WHERE is_manual = false`).
|
||||
- **#29 (Pipeline monitorozás):** A `robot_report.py` kiegészítése valós‑idejű státusz‑átmenetek grafikonjával és riasztásokkal.
|
||||
|
||||
---
|
||||
|
||||
*Jelentés készült a `backend/app/workers/vehicle/` könyvtár 15 fájljának teljes kódauditja alapján. Minden állítás kódrészletekre támaszkodik.*
|
||||
@@ -1,205 +1,234 @@
|
||||
# Epic 10 - Nuxt 3 Mission Control (Admin Dashboard)
|
||||
**Frontend Specification for Service Finder Admin Interface**
|
||||
# Epic 10 - Mission Control (Admin Dashboard)
|
||||
**Frontend Specification for Service Finder Admin Interface - Dual-UI, Gamified, RBAC-protected SaaS System**
|
||||
|
||||
## 📋 Overview
|
||||
This epic defines the development of a modern, reactive admin dashboard built with Nuxt 3 and Vuetify/Tailwind CSS. The dashboard will provide comprehensive control over the Service Finder ecosystem, including service moderation, AI pipeline monitoring, gamification management, and user administration.
|
||||
This epic defines the development of a modular "Launchpad" admin dashboard with strict geographical RBAC isolation. The Mission Control dashboard provides comprehensive oversight over the Service Finder ecosystem through role-based access control, ensuring each user only sees data and functionality relevant to their geographical scope and permissions level.
|
||||
|
||||
## 🎯 Core Concept: Modular Launchpad
|
||||
The admin interface centers around a customizable "Launchpad" home screen with modular tiles that provide at-a-glance insights and quick access to key functions. The Launchpad adapts dynamically based on user role and geographical scope.
|
||||
|
||||
### 🧩 Launchpad Tiles (Role-based Visibility):
|
||||
1. **AI Logs Monitor** - Real-time tracking of AI robot pipelines (GB Discovery, GB Hunter, VIES Validator, OSM Enricher)
|
||||
2. **Financial Dashboard** - Revenue, expenses, ROI metrics with geographical filtering
|
||||
3. **Salesperson Hub** - Performance metrics, leads, conversions for sales teams
|
||||
4. **User Management** - Active users, registration trends, moderation queue
|
||||
5. **Service Moderation Map** - Geographical view of pending/flagged services
|
||||
6. **Gamification Control** - XP levels, badges, penalty system administration
|
||||
7. **System Health** - API status, database metrics, uptime monitoring
|
||||
|
||||
## 👥 Role-Based Access Control (RBAC) - Geographical Isolation
|
||||
**Földrajzi izoláció kötelező!** - Each role has strictly defined geographical boundaries.
|
||||
|
||||
### 1. **Superadmin** (Global Scope)
|
||||
- **Geographical Scope:** Worldwide (no restrictions)
|
||||
- **Permissions:** Full system access, all modules, all geographical regions
|
||||
- **Launchpad Tiles:** All tiles visible and functional
|
||||
- **Critical Function:** Can assign regional admins, override geographical restrictions
|
||||
|
||||
### 2. **Admin** (Területi Mindentudó / Regional Omniscient)
|
||||
- **Geographical Scope:** Assigned region(s) (country/state/province level)
|
||||
- **Permissions:** Full access within assigned region(s), cannot cross regional boundaries
|
||||
- **Launchpad Tiles:** All tiles filtered to show only data from assigned region(s)
|
||||
- **Critical Function:** Manages moderators and salespeople within region
|
||||
|
||||
### 3. **Moderator** (Területi Felügyelő / Regional Supervisor)
|
||||
- **Geographical Scope:** Assigned sub-region(s) (city/district level)
|
||||
- **Permissions:**
|
||||
- Service moderation within assigned sub-region(s)
|
||||
- User management for users registered in assigned sub-region(s)
|
||||
- Access to regional map view (only assigned area)
|
||||
- **Launchpad Tiles:** Service Map, User Management, AI Logs (filtered)
|
||||
- **Restrictions:** Cannot access financial data or salesperson metrics
|
||||
|
||||
### 4. **Salesperson** (Értékesítő)
|
||||
- **Geographical Scope:** Assigned sales territory (may cross multiple sub-regions)
|
||||
- **Permissions:**
|
||||
- View sales metrics and leads for assigned territory
|
||||
- Access customer profiles within territory
|
||||
- Limited service viewing (for sales context)
|
||||
- **Launchpad Tiles:** Salesperson Hub, Customer Profiles, Service Map (read-only)
|
||||
- **Restrictions:** Cannot moderate services or manage users
|
||||
|
||||
## 🎫 Development Tickets (Gitea Issues)
|
||||
|
||||
### Ticket 1: RBAC Implementation & Role Management System
|
||||
**Scope:** Backend/Frontend Core, Authentication, Authorization
|
||||
**Complexity:** High
|
||||
|
||||
#### Requirements:
|
||||
1. **Role & Scope Database Model**
|
||||
- Extend existing User model with role_id and geographical_scope fields
|
||||
- Hierarchical scope system: Global → Country → Region → City
|
||||
- Scope inheritance (Admin sees all subordinate Moderator areas)
|
||||
|
||||
2. **Authentication Middleware**
|
||||
- JWT token enhancement with role and scope claims
|
||||
- Route-level permission validation
|
||||
- Geographical boundary enforcement on all API calls
|
||||
|
||||
3. **Role Management UI**
|
||||
- Admin interface for assigning roles and geographical scopes
|
||||
- Visual geographical selector (map-based or hierarchical tree)
|
||||
- Role permission matrix editor
|
||||
|
||||
4. **Launchpad Tile Visibility Rules**
|
||||
- Dynamic tile filtering based on role and scope
|
||||
- API endpoint for fetching role-appropriate tiles
|
||||
- Client-side tile visibility toggles
|
||||
|
||||
### Ticket 2: Launchpad UI & Modular Tile System
|
||||
**Scope:** Frontend Core, UI/UX, Component Library
|
||||
**Complexity:** Medium-High
|
||||
|
||||
#### Requirements:
|
||||
1. **Launchpad Grid Layout**
|
||||
- Responsive drag-and-drop tile grid (like Windows Start menu)
|
||||
- Tile customization: size (1x1, 2x1, 2x2), position, visibility
|
||||
- Per-user tile arrangement persistence
|
||||
|
||||
2. **Tile Component Framework**
|
||||
- Base tile component with standardized header, content, actions
|
||||
- Tile types: Metric cards, charts, data tables, action buttons
|
||||
- Live data refresh with configurable intervals
|
||||
|
||||
3. **Core Tile Implementations**
|
||||
- AI Logs Monitor: Real-time pipeline status with progress bars
|
||||
- Financial Dashboard: Revenue charts, expense breakdown, ROI calculator
|
||||
- Salesperson Hub: Lead pipeline, conversion rates, performance metrics
|
||||
- User Management: Active users table, registration trends graph
|
||||
|
||||
4. **Tile Configuration & Personalization**
|
||||
- "Add Tile" modal with available tile catalog
|
||||
- Tile settings (data source, refresh rate, display options)
|
||||
- Role-based tile availability restrictions
|
||||
|
||||
### Ticket 3: Geographical Map View with Scope Isolation
|
||||
**Scope:** Frontend Mapping, Geographical Visualization
|
||||
**Complexity:** High
|
||||
|
||||
#### Requirements:
|
||||
1. **Map Integration with Scope Boundaries**
|
||||
- Leaflet/Vue3-leaflet with OpenStreetMap/Mapbox tiles
|
||||
- Visual overlay of user's geographical scope (highlighted regions)
|
||||
- Automatic map centering and zoom to scope boundaries
|
||||
|
||||
2. **Scope-Aware Data Filtering**
|
||||
- Services, users, sales data filtered by geographical scope
|
||||
- Multi-level scope hierarchy support (country → region → city)
|
||||
- "Scope drill-down" ability for Admins (view all subordinate areas)
|
||||
|
||||
3. **Service Moderation Map (Moderator View)**
|
||||
- Service markers color-coded by status within assigned sub-region
|
||||
- Right-click context menu for moderation actions
|
||||
- Bulk selection and status updates
|
||||
|
||||
4. **Sales Territory Visualization (Salesperson View)**
|
||||
- Territory boundaries overlay on map
|
||||
- Customer location markers with sales metrics tooltips
|
||||
- Heatmap of lead density within territory
|
||||
|
||||
### Ticket 4: User Management Interface with Geographical Filtering
|
||||
**Scope:** Frontend User Administration, Data Tables
|
||||
**Complexity:** Medium
|
||||
|
||||
#### Requirements:
|
||||
1. **Geographically Filtered User Tables**
|
||||
- User list automatically filtered by administrator's scope
|
||||
- Scope selector for Admins to switch between regions
|
||||
- Visual indication of current scope filter
|
||||
|
||||
2. **Role Assignment Interface**
|
||||
- Drag-and-drop role assignment with geographical scope picker
|
||||
- Bulk user role updates
|
||||
- Role change history and audit trail
|
||||
|
||||
3. **User Detail View with Scope Context**
|
||||
- Complete user profile with geographical registration data
|
||||
- Activity history filtered by scope
|
||||
- "Impersonate user" function for Superadmins (with scope limitations)
|
||||
|
||||
4. **Moderation Queue for Moderators**
|
||||
- Pending user approvals for assigned sub-region
|
||||
- Flagged user reviews with geographical context
|
||||
- Quick action buttons (approve, reject, require more info)
|
||||
|
||||
### Ticket 5: AI Pipeline & Financial Monitoring Dashboards
|
||||
**Scope:** Frontend Monitoring, Real-time Data, Charts
|
||||
**Complexity:** Medium
|
||||
|
||||
#### Requirements:
|
||||
1. **AI Pipeline Monitor with Scope Filtering**
|
||||
- Real-time status of AI robots (GB Discovery, GB Hunter, etc.)
|
||||
- Progress bars, success/failure rates, last run timestamps
|
||||
- Geographical filtering of pipeline results (which regions were processed)
|
||||
|
||||
2. **Financial Dashboard with RBAC Restrictions**
|
||||
- Revenue/expense charts filtered by geographical scope
|
||||
- Role-based data granularity (Superadmin sees all, Admin sees region, etc.)
|
||||
- Export financial reports with automatic scope filtering
|
||||
|
||||
3. **Sales Performance Metrics**
|
||||
- Salesperson performance compared to territory averages
|
||||
- Lead conversion rates with geographical trends
|
||||
- Commission calculations and payout projections
|
||||
|
||||
4. **System Health & Audit Logs**
|
||||
- API response times, error rates, uptime metrics
|
||||
- Audit log viewer with role-based filtering
|
||||
- Geographical distribution of system usage
|
||||
|
||||
## 🛠️ Technology Stack
|
||||
- **Framework:** Nuxt 3 (SSR/SPA hybrid)
|
||||
- **UI Library:** Vuetify 3 (Material Design) OR Tailwind CSS + Headless UI
|
||||
- **State Management:** Pinia (Vuex 5)
|
||||
- **Mapping:** Leaflet (with Vue3-leaflet wrapper)
|
||||
- **Charts:** Chart.js / Vue-chartjs
|
||||
- **HTTP Client:** Axios / Nuxt $fetch
|
||||
- **Authentication:** JWT tokens with refresh mechanism
|
||||
- **Form Validation:** Vee-Validate / Zod
|
||||
- **Framework:** Nuxt 3 (SSR/SPA hybrid) or Vue 3 with Vite
|
||||
- **UI Library:** Vuetify 3 (Material Design) for consistency with existing design system
|
||||
- **State Management:** Pinia with role/scope persistence
|
||||
- **Mapping:** Leaflet with Vue3-leaflet wrapper
|
||||
- **Charts:** Chart.js with Vue-chartjs wrapper
|
||||
- **HTTP Client:** Axios with interceptors for scope headers
|
||||
- **Authentication:** JWT tokens with role/scope claims
|
||||
- **Form Validation:** Vee-Validate with Zod schemas
|
||||
- **Internationalization:** Nuxt i18n (hu/en)
|
||||
- **Build Tool:** Vite
|
||||
- **Package Manager:** npm / yarn
|
||||
|
||||
## 🎯 Functional Requirements
|
||||
|
||||
### Jegy 1: Alapstruktúra, Auth & JWT Login Felület
|
||||
**Ticket ID:** #TBD (to be assigned in Gitea)
|
||||
**Scope:** Frontend Core, Authentication
|
||||
**Estimated Complexity:** Medium
|
||||
|
||||
#### Requirements:
|
||||
1. **Project Scaffolding**
|
||||
- Nuxt 3 project initialization with TypeScript
|
||||
- Vuetify 3/Tailwind CSS integration
|
||||
- Layout system with admin sidebar, header, and main content area
|
||||
- Responsive design (mobile/tablet/desktop)
|
||||
|
||||
2. **Authentication System**
|
||||
- JWT login page with email/password form
|
||||
- Token storage in secure HTTP-only cookies
|
||||
- Auto-refresh token mechanism
|
||||
- Protected route middleware (Nuxt middleware)
|
||||
- Login/logout flow with redirects
|
||||
|
||||
3. **Admin Layout Components**
|
||||
- Sidebar navigation with collapsible menu
|
||||
- Header with user profile dropdown and notifications
|
||||
- Breadcrumb navigation
|
||||
- Dark/light theme toggle
|
||||
|
||||
4. **API Integration**
|
||||
- Axios instance with interceptors for auth headers
|
||||
- Centralized error handling (401 redirect to login, 403/404 displays)
|
||||
- Loading states and progress indicators
|
||||
|
||||
5. **Initial Pages**
|
||||
- Dashboard overview (placeholder)
|
||||
- Login page
|
||||
- 404/error pages
|
||||
|
||||
### Jegy 2: Térképes Szerviz Moderátor (Leaflet integráció)
|
||||
**Ticket ID:** #TBD
|
||||
**Scope:** Frontend Mapping, Service Moderation
|
||||
**Estimated Complexity:** High
|
||||
|
||||
#### Requirements:
|
||||
1. **Leaflet Map Integration**
|
||||
- Vue3-leaflet wrapper setup
|
||||
- Hungarian map tiles (OpenStreetMap/Mapbox)
|
||||
- Cluster markers for service locations
|
||||
- Zoom/pan controls with bounds restriction
|
||||
|
||||
2. **Service Visualization**
|
||||
- Different marker colors/icons for service statuses:
|
||||
- Ghost (gray) - robot-discovered, unverified
|
||||
- Active (green) - verified, public services
|
||||
- Flagged (orange) - suspicious, needs manual review
|
||||
- Suspended (red) - banned services
|
||||
- Marker popups with service summary
|
||||
- Filter controls by status/city/rating
|
||||
|
||||
3. **Moderation Actions**
|
||||
- Right-click context menu on markers
|
||||
- Change status (ghost→active, active→flagged, etc.)
|
||||
- Bulk selection and status updates
|
||||
- Service details modal with full information
|
||||
- Edit service profile (contact info, hours, tags)
|
||||
|
||||
4. **Geospatial Features**
|
||||
- Drag-and-drop marker relocation for ghost services
|
||||
- Address search with geocoding (Nominatim API)
|
||||
- Radius search around a point
|
||||
- Export selected services as CSV/GeoJSON
|
||||
|
||||
5. **Real-time Updates**
|
||||
- WebSocket connection for live service status changes
|
||||
- Notification when new ghost services appear
|
||||
|
||||
### Jegy 3: AI Pipeline Monitor (Progress barok, manuális újrafuttatás)
|
||||
**Ticket ID:** #TBD
|
||||
**Scope:** Frontend Monitoring, AI Integration
|
||||
**Estimated Complexity:** Medium-High
|
||||
|
||||
#### Requirements:
|
||||
1. **Pipeline Dashboard**
|
||||
- Overview of all AI robots (GB Discovery, GB Hunter, VIES Validator, OSM Enricher)
|
||||
- Current status (idle, running, failed, completed)
|
||||
- Last run timestamps and durations
|
||||
- Success/failure statistics (charts)
|
||||
|
||||
2. **Progress Visualization**
|
||||
- Real-time progress bars for active pipelines
|
||||
- Step-by-step breakdown (fetching, processing, saving)
|
||||
- Live log stream with auto-scroll
|
||||
- Color-coded log levels (INFO, WARN, ERROR)
|
||||
|
||||
3. **Manual Control**
|
||||
- "Run Now" buttons for each robot (with confirmation)
|
||||
- Stop/abort running pipelines
|
||||
- Configuration parameter editing
|
||||
- Schedule management (cron expression editor)
|
||||
|
||||
4. **Log Management**
|
||||
- Filterable log table with search
|
||||
- Export logs as text file
|
||||
- Log detail modal with stack traces
|
||||
- Automatic log rotation display
|
||||
|
||||
5. **VIES/OSM Integration**
|
||||
- Dedicated panels for VIES validation results
|
||||
- OSM enrichment statistics
|
||||
- Side-by-side comparison of raw vs enriched data
|
||||
- Manual validation override controls
|
||||
|
||||
### Jegy 4: Gamification Vezérlő & User Menedzsment
|
||||
**Ticket ID:** #TBD
|
||||
**Scope:** Frontend Gamification, User Administration
|
||||
**Estimated Complexity:** Medium
|
||||
|
||||
#### Requirements:
|
||||
1. **User Management Interface**
|
||||
- User table with pagination and sorting
|
||||
- Filter by level, status, registration date
|
||||
- Quick actions (ban, promote to admin, reset password)
|
||||
- User detail view with activity history
|
||||
|
||||
2. **Gamification Control Panel**
|
||||
- Level configuration editor (-3 to +10 levels)
|
||||
- Edit rank names, point thresholds, penalty flags
|
||||
- Real-time preview of level progression
|
||||
- Bulk level adjustments for user groups
|
||||
|
||||
3. **Penalty System Management**
|
||||
- Assign penalty levels (-1, -2, -3) to users
|
||||
- View penalty quota usage
|
||||
- Manual penalty point addition/removal
|
||||
- Ban user temporarily/permanently
|
||||
|
||||
4. **Point Administration**
|
||||
- Manual XP/point adjustment interface
|
||||
- Transaction ledger with filters
|
||||
- Revert mistaken point allocations
|
||||
- Export user stats as CSV
|
||||
|
||||
5. **Badge & Achievement System**
|
||||
- Badge creation/editing interface
|
||||
- Assign badges to users
|
||||
- Badge gallery with unlock conditions
|
||||
- Seasonal competition management
|
||||
- **Package Manager:** npm
|
||||
|
||||
## 🎨 Design Requirements
|
||||
- **Design System:** Follow Material Design 3 guidelines
|
||||
- **Color Palette:** Service Finder brand colors (primary: #3B82F6, secondary: #10B981)
|
||||
- **Accessibility:** WCAG 2.1 AA compliant
|
||||
- **Responsive:** Mobile-first approach, breakpoints at 640px, 768px, 1024px, 1280px
|
||||
- **Icons:** Material Design Icons (mdi-vue)
|
||||
- **Design System:** Material Design 3 with Service Finder brand colors
|
||||
- **Color Coding by Role:** Superadmin (purple), Admin (blue), Moderator (green), Salesperson (orange)
|
||||
- **Geographical Visualizations:** Clear boundary indications, scope-aware color schemes
|
||||
- **Accessibility:** WCAG 2.1 AA compliant, screen reader support for all tiles
|
||||
- **Responsive:** Mobile-first, with Launchpad adapting to tablet/desktop layouts
|
||||
|
||||
## 🔧 Technical Specifications
|
||||
- **Code Quality:** ESLint, Prettier, TypeScript strict mode
|
||||
- **Testing:** Vitest for unit tests, Cypress for E2E
|
||||
- **Performance:** Lazy loading routes, code splitting, image optimization
|
||||
- **Security:** CSP headers, XSS protection, sanitized inputs
|
||||
- **Code Quality:** TypeScript strict mode, ESLint, Prettier
|
||||
- **Testing:** Vitest for unit tests, Cypress for E2E with role-based test scenarios
|
||||
- **Performance:** Lazy loading of tile components, virtual scrolling for data tables
|
||||
- **Security:** Role validation on both client and server, scope injection prevention
|
||||
- **Browser Support:** Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
|
||||
|
||||
## 📊 Success Metrics
|
||||
- Page load time < 2 seconds
|
||||
- Time to interactive < 3 seconds
|
||||
- Page load time < 2 seconds with role/scope determination
|
||||
- Tile loading < 1 second after initial page load
|
||||
- Geographical filtering response time < 500ms
|
||||
- Lighthouse score > 90
|
||||
- Zero critical security vulnerabilities
|
||||
- 100% test coverage for critical paths
|
||||
- Zero role escalation or scope bypass vulnerabilities
|
||||
|
||||
## 🔗 Dependencies
|
||||
- **Backend:** Requires completed seed_v2_0.py for mock data
|
||||
- **APIs:** Authentication API, Service Profile API, Gamification API, AI Pipeline API
|
||||
- **External:** OpenStreetMap tiles, Nominatim geocoding
|
||||
- **Backend:** Completed RBAC API endpoints with geographical scope support
|
||||
- **APIs:** Role management API, Geographical scope API, Tile data APIs
|
||||
- **External:** OpenStreetMap tiles, Mapbox for enhanced visualizations
|
||||
- **Data:** Geographical boundary datasets for countries/regions/cities
|
||||
|
||||
## 📅 Implementation Phases
|
||||
1. **Phase 1 (Week 1-2):** Core setup, authentication, basic layout
|
||||
2. **Phase 2 (Week 3-4):** Map integration, service moderation
|
||||
3. **Phase 3 (Week 5-6):** AI pipeline monitoring
|
||||
4. **Phase 4 (Week 7-8):** Gamification controls, polish, testing
|
||||
1. **Phase 1 (Week 1-3):** RBAC foundation, authentication enhancements, role middleware
|
||||
2. **Phase 2 (Week 4-6):** Launchpad UI framework, core tile components
|
||||
3. **Phase 3 (Week 7-8):** Geographical map integration, scope visualization
|
||||
4. **Phase 4 (Week 9-10):** User management, financial dashboards, polish
|
||||
5. **Phase 5 (Week 11-12):** Testing, security audit, performance optimization
|
||||
|
||||
## 🚀 Deployment Strategy
|
||||
- **Development:** Local Nuxt dev server
|
||||
- **Staging:** Docker container with Nginx
|
||||
- **Production:** Cloudflare Pages / Vercel / Self-hosted Nginx
|
||||
- **Development:** Feature flags for role-based UI elements
|
||||
- **Staging:** Test with realistic geographical data and role scenarios
|
||||
- **Production:** Gradual rollout with role groups (Superadmins first, then Admins, etc.)
|
||||
|
||||
---
|
||||
*This specification serves as the foundation for Gitea ticket creation and frontend development planning. Each "Jegy" section corresponds to a separate development ticket.*
|
||||
|
||||
*This specification serves as the foundation for Gitea ticket creation and frontend development planning. Each "Ticket" section corresponds to a separate development ticket that will be created in the Gitea project management system.*
|
||||
310
docs/epic_11_public_frontend_spec.md
Normal file
310
docs/epic_11_public_frontend_spec.md
Normal file
@@ -0,0 +1,310 @@
|
||||
# Epic 11 - The Smart Garage (User Frontend)
|
||||
**Frontend Specification for Service Finder Public Interface - Dual-UI, Gamified, Brand-Aware Vehicle Management**
|
||||
|
||||
## 📋 Overview
|
||||
This epic defines the development of a dual-interface public frontend for Service Finder end-users (B2C and B2B). The "Smart Garage" offers two distinct experiences: a youthful, gamified "Private Garage" for individual vehicle owners and a clean, analytical "Corporate Fleet" interface for business users. Upon login, users choose their preferred interface, which then tailors the entire experience to their needs.
|
||||
|
||||
## 🎯 Core Concept: Dual-UI Architecture
|
||||
**Kétarcú UI** - One system, two completely different visual and functional experiences based on user type.
|
||||
|
||||
### 🏠 **Private Garage** (Privát Garázs)
|
||||
- **Target Audience:** Individual vehicle owners, enthusiasts, young drivers
|
||||
- **Design Aesthetic:** Youthful, energetic, gamified, themeable
|
||||
- **Color Scheme:** Vibrant colors, gradients, dynamic animations
|
||||
- **Key Focus:** Fun, engagement, community, personal achievement
|
||||
- **Gamification:** Heavy emphasis on points, levels, badges, daily challenges
|
||||
|
||||
### 🏢 **Corporate Fleet** (Céges Flotta)
|
||||
- **Target Audience:** Fleet managers, business owners, logistics companies
|
||||
- **Design Aesthetic:** Professional, clean, data-driven, minimalist
|
||||
- **Color Scheme:** Corporate blues/grays, clean lines, subtle accents
|
||||
- **Key Focus:** ROI, TCO (Total Cost of Ownership), analytics, efficiency
|
||||
- **Gamification:** Light - focuses on efficiency metrics and cost savings
|
||||
|
||||
## 🚪 Entry Point: Profile Selector Screen
|
||||
Upon successful authentication, users are presented with a choice screen before entering the main application.
|
||||
|
||||
### Profile Selector Requirements:
|
||||
1. **Visual Choice Interface**
|
||||
- Two large, visually distinct cards: "Private Garage" and "Corporate Fleet"
|
||||
- Animated previews showing each interface's style
|
||||
- Brief description of each mode's benefits
|
||||
|
||||
2. **Smart Default & Memory**
|
||||
- Remember user's last choice (cookie/localStorage)
|
||||
- Allow switching modes later via settings
|
||||
- "Not sure? Try Private Garage" for new users
|
||||
|
||||
3. **Role Enforcement**
|
||||
- B2B accounts (company-associated) default to Fleet but can choose Garage
|
||||
- B2C accounts default to Garage but can request Fleet access
|
||||
|
||||
## 🧩 Core Features (Both Interfaces)
|
||||
|
||||
### 1. **Daily Quiz** (Napi Kvíz)
|
||||
- **Purpose:** Engage users daily, educate about vehicle maintenance, reward participation
|
||||
- **Implementation:** Dismissible pop-up appearing once per 24 hours
|
||||
- **Functionality:**
|
||||
- Multiple-choice questions about vehicle care, safety, Service Finder features
|
||||
- Immediate feedback with explanations
|
||||
- Points awarded for correct answers (scaling with difficulty)
|
||||
- Streak counter for consecutive days of participation
|
||||
- **Future Expansion:** Foundation for full educational module
|
||||
|
||||
### 2. **Garage Display** (Garázs Csempék)
|
||||
- **Core Requirement:** Display user's vehicles with **real brand logos and country flags**
|
||||
- **Implementation:**
|
||||
- Vehicle cards/tiles showing make, model, year, license plate
|
||||
- High-quality SVG brand logos (downloaded from brand repositories)
|
||||
- Country flag based on vehicle origin/registration
|
||||
- Quick status indicators (service due, expenses this month, fuel level if connected)
|
||||
- **Visual Design:**
|
||||
- Private Garage: Animated cards, hover effects, themeable backgrounds
|
||||
- Corporate Fleet: Compact table view, sortable columns, export options
|
||||
|
||||
### 3. **Quick Action Buttons** (Gyors-akció Gombok)
|
||||
- **Primary Actions:**
|
||||
1. **[Költség felvitele]** - Quick expense entry
|
||||
2. **[Szerviz keresése]** - Service finder launch
|
||||
3. **[Üzemanyag]** - Fuel tracking (if enabled)
|
||||
4. **[Jármű hozzáadása]** - Add new vehicle
|
||||
- **Implementation:**
|
||||
- Floating action button (FAB) or fixed toolbar
|
||||
- Context-sensitive actions (e.g., if vehicle selected, actions apply to that vehicle)
|
||||
- One-tap modals for quick data entry
|
||||
|
||||
### 4. **Trophy Showcase** (Vitrin - Gamification Kupák és Díjak)
|
||||
- **Purpose:** Visual display of user achievements
|
||||
- **Implementation:**
|
||||
- Trophy cabinet/shelf metaphor
|
||||
- 3D-rendered or high-quality 2D trophy graphics
|
||||
- Categories: Participation, Knowledge, Savings, Community
|
||||
- Empty slots for future achievements (creates goals)
|
||||
- **Private Garage:** Prominent display, celebration animations when earned
|
||||
- **Corporate Fleet:** Subtle badge system, efficiency achievement markers
|
||||
|
||||
### 5. **Vehicle Detail & Analytics**
|
||||
- **Private Garage:** Fun stats (km driven equivalent to moon distance, CO2 saved vs trees)
|
||||
- **Corporate Fleet:** Serious analytics (TCO per km, maintenance cost trends, ROI calculations)
|
||||
- **Shared Features:**
|
||||
- Service history timeline
|
||||
- Expense categorization charts
|
||||
- Fuel efficiency graphs
|
||||
- Predictive maintenance alerts
|
||||
|
||||
## 🎫 Development Tickets (Gitea Issues)
|
||||
|
||||
### Ticket 1: Dual-UI Profile Selector & Mode Switching System
|
||||
**Scope:** Frontend Core, Authentication Flow, User Preferences
|
||||
**Complexity:** Medium
|
||||
|
||||
#### Requirements:
|
||||
1. **Profile Selector Component**
|
||||
- Two large interactive cards with animated previews
|
||||
- Visual distinction between Private Garage and Corporate Fleet styles
|
||||
- Responsive design (mobile/tablet/desktop)
|
||||
|
||||
2. **User Preference Management**
|
||||
- API integration for saving/retrieving interface preference
|
||||
- Local storage fallback for offline usage
|
||||
- Preference change auditing
|
||||
|
||||
3. **Authentication Flow Integration**
|
||||
- Redirect to selector after successful login
|
||||
- Skip selector if preference already set (configurable)
|
||||
- "Remember my choice" option with expiration
|
||||
|
||||
4. **Mode Switching Mechanism**
|
||||
- Settings page option to switch between interfaces
|
||||
- Confirmation modal explaining implications
|
||||
- Session restart or dynamic theme switching
|
||||
|
||||
### Ticket 2: Daily Quiz System with Dismissible Pop-up
|
||||
**Scope:** Frontend Engagement, Education, Gamification
|
||||
**Complexity:** Medium
|
||||
|
||||
#### Requirements:
|
||||
1. **Quiz Pop-up Component**
|
||||
- Dismissible modal that appears once per 24 hours per user
|
||||
- Configurable appearance delay (e.g., 30 seconds after page load)
|
||||
- "Remind me later" and "Don't show again today" options
|
||||
|
||||
2. **Question Management**
|
||||
- Dynamic question loading from API/content management system
|
||||
- Multiple-choice format with 4 options
|
||||
- Question categories (Maintenance, Safety, Service Finder Features, Vehicle Knowledge)
|
||||
|
||||
3. **Scoring & Rewards**
|
||||
- Points awarded based on question difficulty
|
||||
- Streak counter for consecutive days of participation
|
||||
- Visual feedback (confetti for correct, gentle correction for wrong)
|
||||
|
||||
4. **Quiz Administration**
|
||||
- Admin interface for adding/editing questions
|
||||
- Question scheduling (seasonal questions, promotional content)
|
||||
- Analytics dashboard for quiz participation rates
|
||||
|
||||
### Ticket 3: Garage Tile System with Real Brand Logos & Country Flags
|
||||
**Scope:** Frontend UI, Asset Management, Vehicle Display
|
||||
**Complexity:** High
|
||||
|
||||
#### Requirements:
|
||||
1. **Brand Logo Integration**
|
||||
- SVG logo library for all major vehicle brands (200+ brands)
|
||||
- Logo licensing verification and compliance
|
||||
- Fallback generic vehicle icon for unknown brands
|
||||
- Logo optimization and lazy loading
|
||||
|
||||
2. **Vehicle Card/Tile Components**
|
||||
- Two display modes: Card view (Private Garage) and Table row (Corporate Fleet)
|
||||
- Vehicle image placeholder with brand logo overlay
|
||||
- Country flag based on vehicle registration/origin
|
||||
- Quick status indicators (service due, insurance expiry, etc.)
|
||||
|
||||
3. **Garage Layout Management**
|
||||
- Grid layout for Private Garage (themable, rearrangeable)
|
||||
- Sortable table for Corporate Fleet (by cost, mileage, age, etc.)
|
||||
- Filtering by vehicle type, status, location
|
||||
|
||||
4. **Asset Management System**
|
||||
- Centralized asset service for logos and flags
|
||||
- CDN integration for fast delivery
|
||||
- Cache management and version control
|
||||
|
||||
### Ticket 4: Quick Action Buttons & Contextual Shortcuts
|
||||
**Scope:** Frontend UX, Productivity, User Flows
|
||||
**Complexity:** Medium
|
||||
|
||||
#### Requirements:
|
||||
1. **Quick Action System**
|
||||
- Floating Action Button (FAB) that expands to show actions
|
||||
- Context-aware actions (different actions if vehicle is selected)
|
||||
- Keyboard shortcuts for power users
|
||||
|
||||
2. **Core Action Implementations**
|
||||
- **Expense Entry:** Modal form with smart categorization (fuel, maintenance, insurance, etc.)
|
||||
- **Service Finder:** Launch service search with pre-filled vehicle details
|
||||
- **Fuel Tracking:** Quick fuel entry with odometer, amount, price per liter
|
||||
- **Vehicle Add:** Streamlined vehicle addition form
|
||||
|
||||
3. **Action Customization**
|
||||
- User-configurable quick actions (choose which 4 appear)
|
||||
- Role-based action availability (fleet managers see different actions)
|
||||
- Usage analytics to suggest most relevant actions
|
||||
|
||||
4. **Mobile Optimization**
|
||||
- Bottom navigation bar for mobile devices
|
||||
- Swipe gestures for quick access
|
||||
- Haptic feedback on action completion
|
||||
|
||||
### Ticket 5: Trophy Showcase & Gamification Display
|
||||
**Scope:** Frontend Gamification, Visual Design, Animation
|
||||
**Complexity:** Medium-High
|
||||
|
||||
#### Requirements:
|
||||
1. **Trophy Cabinet Component**
|
||||
- 3D shelf or grid display of earned trophies
|
||||
- Trophy categories with distinct visual styles
|
||||
- Empty trophy slots with "locked" visual state
|
||||
|
||||
2. **Trophy System Integration**
|
||||
- API integration with backend gamification system
|
||||
- Real-time trophy unlock notifications
|
||||
- Trophy detail views (unlock criteria, rarity statistics)
|
||||
|
||||
3. **Achievement Animations**
|
||||
- Celebration sequence when trophy earned
|
||||
- Subtle glow/pulse for newly earned trophies
|
||||
- Share functionality (social media integration)
|
||||
|
||||
4. **Corporate Fleet Achievement System**
|
||||
- Professional badge system for efficiency milestones
|
||||
- Cost-saving achievement markers
|
||||
- Team/company-wide achievement boards
|
||||
|
||||
### Ticket 6: Vehicle Analytics & TCO Dashboard
|
||||
**Scope:** Frontend Data Visualization, Analytics, Business Intelligence
|
||||
**Complexity:** High
|
||||
|
||||
#### Requirements:
|
||||
1. **Dual-Interface Analytics**
|
||||
- Private Garage: Fun, engaging visualizations (km to moon, CO2 to trees)
|
||||
- Corporate Fleet: Professional business intelligence (TCO, ROI, depreciation)
|
||||
|
||||
2. **TCO Calculation Dashboard**
|
||||
- Total Cost of Ownership breakdown (acquisition, fuel, maintenance, insurance, tax)
|
||||
- Cost per kilometer/mile calculations
|
||||
- Comparison against vehicle class averages
|
||||
|
||||
3. **Predictive Analytics**
|
||||
- Maintenance cost forecasting based on mileage/age
|
||||
- Fuel price trend analysis
|
||||
- Optimal replacement timing suggestions
|
||||
|
||||
4. **Report Generation**
|
||||
- Export analytics as PDF/Excel
|
||||
- Scheduled report delivery (email)
|
||||
- Shareable dashboard links for team collaboration
|
||||
|
||||
## 🛠️ Technology Stack
|
||||
- **Framework:** Vue 3 with Composition API (consistent with admin interface)
|
||||
- **UI Library:** Vuetify 3 for Corporate Fleet, custom themed components for Private Garage
|
||||
- **State Management:** Pinia with separate stores for Garage/Fleet modes
|
||||
- **Charts:** Chart.js for analytics, D3.js for advanced visualizations
|
||||
- **Maps:** Leaflet for service finder integration
|
||||
- **Animation:** GSAP for smooth transitions and trophy animations
|
||||
- **HTTP Client:** Axios with interceptors for mode-specific API routing
|
||||
- **Authentication:** JWT tokens with mode preference claim
|
||||
- **Build Tool:** Vite with separate build configurations for optimization
|
||||
- **Package Manager:** npm
|
||||
|
||||
## 🎨 Design Requirements
|
||||
- **Private Garage Design System:**
|
||||
- Vibrant color palette with gradients
|
||||
- Rounded corners, soft shadows, playful typography
|
||||
- Interactive elements with hover/focus animations
|
||||
- Theme support (light/dark/seasonal themes)
|
||||
|
||||
- **Corporate Fleet Design System:**
|
||||
- Material Design 3 with corporate refinement
|
||||
- Clean lines, ample white space, professional typography
|
||||
- Subtle animations for transitions only
|
||||
- Accessibility-focused (WCAG 2.1 AA compliant)
|
||||
|
||||
- **Brand Logo Integration:** High-quality SVG logos with consistent sizing and coloring
|
||||
- **Country Flags:** Standardized flag library with proper aspect ratios
|
||||
|
||||
## 🔧 Technical Specifications
|
||||
- **Code Quality:** TypeScript strict mode, component-based architecture
|
||||
- **Testing:** Vitest for unit tests, Cypress for E2E with mode-switching scenarios
|
||||
- **Performance:** Lazy loading of mode-specific bundles, image optimization
|
||||
- **Security:** Content Security Policy for SVG assets, XSS protection
|
||||
- **Browser Support:** Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
|
||||
|
||||
## 📊 Success Metrics
|
||||
- **User Engagement:** Daily quiz participation > 40% of active users
|
||||
- **Performance:** Mode switching < 500ms, page load < 2 seconds
|
||||
- **Satisfaction:** User preference retention > 80% (users don't switch back)
|
||||
- **Business:** Fleet users report time savings > 2 hours/week on vehicle management
|
||||
|
||||
## 🔗 Dependencies
|
||||
- **Backend:** Vehicle API with brand/origin data, Gamification API for trophies
|
||||
- **APIs:** Quiz content API, Expense tracking API, Service finder API
|
||||
- **External:** Brand logo SVG repository, Country flag library
|
||||
- **Design:** Complete design systems for both interfaces
|
||||
|
||||
## 📅 Implementation Phases
|
||||
1. **Phase 1 (Week 1-3):** Foundation - Profile selector, mode switching, basic layout
|
||||
2. **Phase 2 (Week 4-6):** Core features - Garage tiles, quick actions, basic analytics
|
||||
3. **Phase 3 (Week 7-9):** Gamification - Daily quiz, trophy system, animations
|
||||
4. **Phase 4 (Week 10-12):** Advanced analytics - TCO dashboard, predictive features
|
||||
5. **Phase 5 (Week 13-14):** Polish - Performance optimization, accessibility, testing
|
||||
|
||||
## 🚀 Deployment Strategy
|
||||
- **Development:** Feature flags for dual-UI components
|
||||
- **Staging:** A/B testing of interface preferences with test users
|
||||
- **Production:** Gradual rollout starting with Private Garage, then Corporate Fleet
|
||||
|
||||
---
|
||||
|
||||
*This specification serves as the foundation for Gitea ticket creation and frontend development planning. Each "Ticket" section corresponds to a separate development ticket that will be created in the Gitea project management system.*
|
||||
Reference in New Issue
Block a user