201 előtti mentés
This commit is contained in:
Roo
234
docs/sf/epic_10_admin_frontend_spec.md
Normal file
234
docs/sf/epic_10_admin_frontend_spec.md
Normal file
@@ -0,0 +1,234 @@
|
||||
# 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 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) 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
|
||||
|
||||
## 🎨 Design Requirements
|
||||
- **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:** 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 with role/scope determination
|
||||
- Tile loading < 1 second after initial page load
|
||||
- Geographical filtering response time < 500ms
|
||||
- Lighthouse score > 90
|
||||
- Zero role escalation or scope bypass vulnerabilities
|
||||
|
||||
## 🔗 Dependencies
|
||||
- **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-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:** 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 "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