kincses/service-finder
1
0
Fork 0
Code Issues 7 Pull Requests Packages Projects 2 Releases Wiki Activity

chore: Backend codebase cleanup and archiving of legacy scripts

Browse Source
This commit is contained in:
Roo
2026-03-22 20:07:37 +00:00
parent 5d96b00f81
commit 309a72cc0b
19 changed files with 530 additions and 184 deletions
Download Patch File Download Diff File Expand all files Collapse all files

395
docs/epic_10_admin_frontend_spec.md
View File

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