From 309a72cc0bed18a212283d5c1cd396cf0f712cde Mon Sep 17 00:00:00 2001 From: Roo Date: Sun, 22 Mar 2026 20:07:37 +0000 Subject: [PATCH] chore: Backend codebase cleanup and archiving of legacy scripts --- .roo/history.md | 6 + .roo/mcp.json | 3 +- .../create_sandbox_user.py | 0 .../create_tco_tables.py | 0 .../debug_metadata.py | 0 .../discovery_bot.py.old | 0 .../force_create_tables.py | 0 backend/{ => archive_v1_scripts}/seed_data.py | 0 .../seed_discovery.py | 0 .../{ => archive_v1_scripts}/seed_models.py | 0 .../seed_passenger_cars.py | 0 .../{ => archive_v1_scripts}/seed_vehicles.py | 0 .../test_config_service.py | 0 .../verify_financial_truth.py | 0 .../audits}/admin_gap_analysis.md | 0 .../audits}/audit_report_robots.md | 0 .../audits}/audit_report_vehicle_robots.md | 0 docs/epic_10_admin_frontend_spec.md | 395 ++++++++++-------- docs/epic_11_public_frontend_spec.md | 310 ++++++++++++++ 19 files changed, 530 insertions(+), 184 deletions(-) rename backend/{ => archive_v1_scripts}/create_sandbox_user.py (100%) rename backend/{ => archive_v1_scripts}/create_tco_tables.py (100%) rename backend/{ => archive_v1_scripts}/debug_metadata.py (100%) rename backend/{ => archive_v1_scripts}/discovery_bot.py.old (100%) rename backend/{ => archive_v1_scripts}/force_create_tables.py (100%) rename backend/{ => archive_v1_scripts}/seed_data.py (100%) rename backend/{ => archive_v1_scripts}/seed_discovery.py (100%) rename backend/{ => archive_v1_scripts}/seed_models.py (100%) rename backend/{ => archive_v1_scripts}/seed_passenger_cars.py (100%) rename backend/{ => archive_v1_scripts}/seed_vehicles.py (100%) rename backend/{ => archive_v1_scripts}/test_config_service.py (100%) rename backend/{ => archive_v1_scripts}/verify_financial_truth.py (100%) rename {backend => docs/audits}/admin_gap_analysis.md (100%) rename {backend => docs/audits}/audit_report_robots.md (100%) rename {backend => docs/audits}/audit_report_vehicle_robots.md (100%) create mode 100644 docs/epic_11_public_frontend_spec.md diff --git a/.roo/history.md b/.roo/history.md index d0410b3..4411609 100644 --- a/.roo/history.md +++ b/.roo/history.md @@ -297,3 +297,9 @@ A módosítások nem befolyásolják a meglévő funkcionalitást, mivel csak v ### 2026-03-22 - Epic 10 Előkészítés (#113) - **Esemény:** A legfontosabb Admin API végpontok (AI trigger, Térkép lokáció frissítés, Büntető szintek kiosztása) sikeresen implementálva a Nuxt 3 dashboard számára. + +### 2026-03-22 - Frontend Sprint Indítása +- **Esemény:** Az Epic 10 és Epic 11 Gitea jegyei (összesen kb. 10-12 db) sikeresen legenerálva és felvéve a Kanban táblára a specifikációk alapján. + +### 2026-03-22 - Backend Nagytakarítás +- **Esemény:** A backend gyökérkönyvtára megtisztítva. A régi seederek, audit fájlok és ideiglenes szkriptek archiválva lettek a tiszta kódbázis érdekében. diff --git a/.roo/mcp.json b/.roo/mcp.json index f4aefba..ff15372 100644 --- a/.roo/mcp.json +++ b/.roo/mcp.json @@ -27,7 +27,8 @@ "read_text_file", "list_directory", "search_files", - "write_file" + "write_file", + "list_allowed_directories" ] } } diff --git a/backend/create_sandbox_user.py b/backend/archive_v1_scripts/create_sandbox_user.py similarity index 100% rename from backend/create_sandbox_user.py rename to backend/archive_v1_scripts/create_sandbox_user.py diff --git a/backend/create_tco_tables.py b/backend/archive_v1_scripts/create_tco_tables.py similarity index 100% rename from backend/create_tco_tables.py rename to backend/archive_v1_scripts/create_tco_tables.py diff --git a/backend/debug_metadata.py b/backend/archive_v1_scripts/debug_metadata.py similarity index 100% rename from backend/debug_metadata.py rename to backend/archive_v1_scripts/debug_metadata.py diff --git a/backend/discovery_bot.py.old b/backend/archive_v1_scripts/discovery_bot.py.old similarity index 100% rename from backend/discovery_bot.py.old rename to backend/archive_v1_scripts/discovery_bot.py.old diff --git a/backend/force_create_tables.py b/backend/archive_v1_scripts/force_create_tables.py similarity index 100% rename from backend/force_create_tables.py rename to backend/archive_v1_scripts/force_create_tables.py diff --git a/backend/seed_data.py b/backend/archive_v1_scripts/seed_data.py similarity index 100% rename from backend/seed_data.py rename to backend/archive_v1_scripts/seed_data.py diff --git a/backend/seed_discovery.py b/backend/archive_v1_scripts/seed_discovery.py similarity index 100% rename from backend/seed_discovery.py rename to backend/archive_v1_scripts/seed_discovery.py diff --git a/backend/seed_models.py b/backend/archive_v1_scripts/seed_models.py similarity index 100% rename from backend/seed_models.py rename to backend/archive_v1_scripts/seed_models.py diff --git a/backend/seed_passenger_cars.py b/backend/archive_v1_scripts/seed_passenger_cars.py similarity index 100% rename from backend/seed_passenger_cars.py rename to backend/archive_v1_scripts/seed_passenger_cars.py diff --git a/backend/seed_vehicles.py b/backend/archive_v1_scripts/seed_vehicles.py similarity index 100% rename from backend/seed_vehicles.py rename to backend/archive_v1_scripts/seed_vehicles.py diff --git a/backend/test_config_service.py b/backend/archive_v1_scripts/test_config_service.py similarity index 100% rename from backend/test_config_service.py rename to backend/archive_v1_scripts/test_config_service.py diff --git a/backend/verify_financial_truth.py b/backend/archive_v1_scripts/verify_financial_truth.py similarity index 100% rename from backend/verify_financial_truth.py rename to backend/archive_v1_scripts/verify_financial_truth.py diff --git a/backend/admin_gap_analysis.md b/docs/audits/admin_gap_analysis.md similarity index 100% rename from backend/admin_gap_analysis.md rename to docs/audits/admin_gap_analysis.md diff --git a/backend/audit_report_robots.md b/docs/audits/audit_report_robots.md similarity index 100% rename from backend/audit_report_robots.md rename to docs/audits/audit_report_robots.md diff --git a/backend/audit_report_vehicle_robots.md b/docs/audits/audit_report_vehicle_robots.md similarity index 100% rename from backend/audit_report_vehicle_robots.md rename to docs/audits/audit_report_vehicle_robots.md diff --git a/docs/epic_10_admin_frontend_spec.md b/docs/epic_10_admin_frontend_spec.md index a1ac80b..b0eb35b 100644 --- a/docs/epic_10_admin_frontend_spec.md +++ b/docs/epic_10_admin_frontend_spec.md @@ -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.* \ No newline at end of file + +*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.* \ No newline at end of file diff --git a/docs/epic_11_public_frontend_spec.md b/docs/epic_11_public_frontend_spec.md new file mode 100644 index 0000000..b46377e --- /dev/null +++ b/docs/epic_11_public_frontend_spec.md @@ -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.* \ No newline at end of file