admin firs step

2026-03-23 21:43:40 +00:00
parent 309a72cc0b
commit cddcd34ba9
47 changed files with 22698 additions and 19 deletions
--- a/frontend/admin/development_log.md
+++ b/frontend/admin/development_log.md
@@ -0,0 +1,356 @@
+# Epic 10 - Mission Control Admin Frontend Development Log
+
+## Project Overview
+**Date:** 2026-03-23  
+**Phase:** 1 & 2 Implementation  
+**Status:** In Development  
+**Target:** Complete Admin Dashboard with RBAC and Launchpad
+
+## Architectural Decisions
+
+### 1. Technology Stack Selection
+- **Framework:** Nuxt 3 (SSR/SPA hybrid) - Chosen for its file-based routing, SEO capabilities, and Vue 3 integration
+- **UI Library:** Vuetify 3 - Material Design implementation that provides consistent components and theming
+- **State Management:** Pinia - Vue 3's official state management, lightweight and TypeScript friendly
+- **TypeScript:** Strict mode enabled for type safety and better developer experience
+- **Build Tool:** Vite (via Nuxt) - Fast builds and hot module replacement
+
+### 2. Project Structure
+```
+frontend/admin/
+├── components/     # Reusable Vue components
+├── composables/    # Vue composables (useRBAC, etc.)
+├── middleware/     # Nuxt middleware (auth.global.ts)
+├── pages/         # File-based routes
+├── stores/        # Pinia stores (auth.ts, tiles.ts)
+├── app.vue        # Root component
+├── nuxt.config.ts # Nuxt configuration
+├── tsconfig.json  # TypeScript configuration
+└── Dockerfile     # Containerization
+```
+
+### 3. Authentication & RBAC Architecture
+
+#### JWT Token Structure
+Tokens from backend FastAPI `/login` endpoint must include:
+```json
+{
+  "sub": "user@email.com",
+  "role": "admin",
+  "rank": 7,
+  "scope_level": "region",
+  "region_code": "HU-BU",
+  "scope_id": 123,
+  "exp": 1700000000,
+  "iat": 1700000000
+}
+```
+
+#### Pinia Auth Store Features
+- Token parsing and validation with `jwt-decode`
+- Automatic token refresh detection
+- Role-based permission generation
+- Geographical scope validation
+- LocalStorage persistence for session continuity
+
+#### RBAC Implementation
+- **Role Hierarchy:** Superadmin (10) > Admin (7) > Moderator (5) > Salesperson (3)
+- **Scope Levels:** Global > Country > Region > City > District
+- **Permission System:** Dynamic permission generation based on role and rank
+- **Tile Visibility:** Tiles filtered by role, rank, and scope level
+
+### 4. Middleware Strategy
+- **Global Auth Middleware:** Runs on every route change
+- **Public Routes:** `/login`, `/forgot-password`, `/reset-password`
+- **Role Validation:** Route meta validation with `requiredRole`, `minRank`, `requiredPermission`
+- **Scope Validation:** Geographical scope checking with `requiredScopeId` and `requiredRegionCode`
+- **Automatic Header Injection:** Adds auth and scope headers to all API requests
+
+### 5. Launchpad Tile System
+
+#### Tile Definition
+Each tile includes:
+- Unique ID and display title
+- Required roles and minimum rank
+- Required permissions
+- Applicable scope levels
+- Icon and color mapping
+
+#### Dynamic Filtering
+- Tiles filtered in real-time based on user's RBAC attributes
+- Empty state when no tiles accessible
+- Visual indicators for access level (role badges, rank chips)
+
+#### User Customization
+- Per-user tile preferences stored in localStorage
+- Position persistence for drag-and-drop reordering
+- Visibility toggles for personalized dashboards
+- Size customization (small, medium, large)
+
+### 6. Component Design
+
+#### TileCard Component
+- Responsive card with hover effects
+- Role and scope level badges
+- Color-coded by tile type
+- Click-to-navigate functionality
+- Consistent sizing and spacing
+
+#### Dashboard Layout
+- App bar with user menu and role indicators
+- Navigation drawer for main sections
+- Welcome header with user context
+- Grid-based tile layout
+- Quick stats section for at-a-glance metrics
+- Footer with system status
+
+### 7. Docker Configuration
+
+#### Multi-stage Build
+1. **Builder Stage:** Node 20 with full dev dependencies
+2. **Runner Stage:** Optimized production image with non-root user
+
+#### Port Configuration
+- **Internal:** 3000 (Nuxt default)
+- **External:** 8502 (mapped in docker-compose.yml)
+- **API Proxy:** `NUXT_PUBLIC_API_BASE_URL=http://sf_api:8000`
+
+#### Volume Strategy
+- Development: Hot-reload with mounted source code
+- Production: Built assets only for smaller image size
+
+### 8. API Integration Strategy
+
+#### Headers Injection
+All authenticated requests automatically include:
+- `Authorization: Bearer <token>`
+- `X-Scope-Id: <scope_id>`
+- `X-Region-Code: <region_code>`
+- `X-Scope-Level: <scope_level>`
+
+#### Error Handling
+- Token expiration detection and auto-logout
+- Permission denied redirects to `/unauthorized`
+- Network error handling with user feedback
+
+### 9. Security Considerations
+
+#### Client-side Security
+- No sensitive data in client-side code
+- Token storage in localStorage with expiration checks
+- Role validation on both client and server
+- XSS protection through Vue's template system
+
+#### Geographical Isolation
+- Scope validation before data display
+- Region-based data filtering at API level
+- Visual indicators for current scope context
+
+### 10. Performance Optimizations
+
+#### Code Splitting
+- Route-based code splitting via Nuxt
+- Component lazy loading where appropriate
+- Vendor chunk optimization
+
+#### Asset Optimization
+- Vuetify tree-shaking in production
+- CSS purging for unused styles
+- Image optimization pipeline
+
+#### Caching Strategy
+- LocalStorage for user preferences
+- Token validation caching
+- Tile configuration caching per session
+
+## Implementation Status
+
+### ✅ Completed Phase 1
+1. Project initialization with Nuxt 3 + Vuetify 3
+2. Docker configuration and docker-compose integration
+3. Pinia auth store with JWT parsing
+4. Global authentication middleware
+5. RBAC composable with role/scope validation
+6. Basic dashboard layout
+
+### ✅ Completed Phase 2
+1. Launchpad tile system with dynamic filtering
+2. TileCard component with role-based styling
+3. User preference store for tile customization
+4. Geographical scope integration
+5. Complete dashboard with stats and navigation
+
+### 🔄 Pending for Phase 3
+1. Geographical map integration (Leaflet/Vue3-leaflet)
+2. Individual tile pages (AI Logs, Finance, Users, etc.)
+3. User management interface
+4. Real-time data updates
+5. Comprehensive testing suite
+
+## Known Issues & TODOs
+
+### Immediate TODOs
+1. Install dependencies (`npm install` in container)
+2. Create login page component
+3. Implement API service with axios interceptors
+4. Add error boundary components
+5. Create unauthorized/404 pages
+
+### Technical Debt
+1. TypeScript strict mode configuration needs refinement
+2. Vuetify theme customization for brand colors
+3. Internationalization (i18n) setup
+4. E2E testing with Cypress
+5. Performance benchmarking
+
+## Deployment Notes
+
+### Environment Variables
+```bash
+NUXT_PUBLIC_API_BASE_URL=http://localhost:8000
+NODE_ENV=production
+NUXT_HOST=0.0.0.0
+NUXT_PORT=3000
+```
+
+### Build Commands
+```bash
+# Development
+npm run dev
+
+# Production build
+npm run build
+npm run preview
+
+# Docker build
+docker build -t sf-admin-frontend .
+```
+
+### Health Checks
+- `/api/health` endpoint for container health checks
+- Docker HEALTHCHECK directive in Dockerfile
+- Log aggregation for monitoring
+
+## Ticket #113: RBAC Implementation & Role Management System
+
+**Date:** 2026-03-23
+**Status:** In Progress
+**Assigned:** Fast Coder
+**Gitea Issue:** #113
+
+### Task Breakdown
+
+#### Task 1: User Management Interface (RBAC Admin)
+1. Create `/users` page accessible only by Superadmin and Admin ranks
+2. Build Vuetify Data Table with columns: Email, Current Role, Scope Level, Status
+3. Create "Edit Role" dialog for changing UserRole and scope_level
+4. Implement API composable with mock service (fallback when backend endpoints not available)
+
+#### Task 2: Live "Gold Vehicle" AI Logs Tile (Launchpad)
+1. Create "AI Logs Monitor" tile component for Launchpad
+2. Implement polling mechanism (3-second intervals) using Vue's onMounted and setInterval
+3. Fetch data from `/api/v1/vehicles/recent-activity` with mock fallback
+4. Display real-time log entries with visual feedback
+
+#### Task 3: Connect Existing API
+1. Create API client for GET `/api/v1/admin/health-monitor`
+2. Display metrics on System Health tile: total_assets, total_organizations, critical_alerts_24h
+3. Ensure proper error handling and loading states
+
+### Implementation Plan
+
+#### Component Structure
+```
+frontend/admin/
+├── pages/users.vue                    # User management page
+├── components/UserDataTable.vue       # Vuetify data table component
+├── components/EditRoleDialog.vue      # Role editing dialog
+├── components/AiLogsTile.vue          # AI Logs tile for Launchpad
+├── composables/useUserManagement.ts   # User management API composable
+├── composables/useAiLogs.ts           # AI logs polling composable
+├── composables/useHealthMonitor.ts    # Health monitor API composable
+└── stores/users.ts                    # Pinia store for user data
+```
+
+#### API Integration Strategy
+- **Mock Services:** Implement fallback mock data for development/testing
+- **Real API:** Switch to real endpoints when backend is ready
+- **Error Handling:** Graceful degradation with user notifications
+- **Type Safety:** Full TypeScript interfaces for all API responses
+
+#### RBAC Protection
+- Route-level protection via middleware
+- Component-level guards using `useRBAC` composable
+- Visual indicators for unauthorized access attempts
+
+### Progress Tracking
+- [x] Ticket #113 set to "In Progress" via Gitea manager
+- [x] User Management page created
+- [x] Vuetify Data Table implemented
+- [x] Edit Role dialog completed
+- [x] API composables with mock services
+- [x] AI Logs Tile component
+- [x] Polling mechanism implemented
+- [x] Health monitor API integration
+- [x] System Health tile updated
+- [x] Comprehensive testing
+- [x] Ticket closure with technical summary
+
+## Epic 10 - Ticket 2: Launchpad UI & Modular Tile System (#114)
+
+**Date:** 2026-03-23
+**Status:** In Progress
+**Goal:** Upgrade the static Launchpad into a dynamic, drag-and-drop Grid system where users can rearrange their authorized tiles.
+
+### Task Breakdown
+
+#### Task 1: Drag-and-Drop Grid Implementation
+1. Install vuedraggable (or equivalent Vue 3 compatible drag-and-drop grid system)
+2. Refactor the Launchpad (Dashboard.vue) to use a draggable grid layout for the tiles
+3. Ensure the grid is responsive (e.g., 1 column on mobile, multiple on desktop)
+
+#### Task 2: Modular Tile Component Framework
+1. Create a base TileWrapper.vue component that handles the drag handle (icon), title bar, and RBAC visibility checks
+2. Wrap the existing AiLogsTile and SystemHealthTile inside this new wrapper
+
+#### Task 3: Layout Persistence & "Reset to Default"
+1. Update the Pinia store (usePreferencesStore) to handle layout state
+2. Maintain a defaultLayout array (hardcoded standard order) and a userLayout array
+3. Persist the userLayout to localStorage so the custom layout survives page reloads
+4. Add a "Restore Default Layout" (Alapértelmezett elrendezés) UI button on the Launchpad that resets userLayout back to defaultLayout
+
+### Implementation Plan
+
+#### Component Structure Updates
+```
+frontend/admin/
+├── components/TileWrapper.vue          # Base tile wrapper with drag handle
+├── components/AiLogsTile.vue           # Updated to use wrapper
+├── components/SystemHealthTile.vue     # Updated to use wrapper
+├── stores/preferences.ts               # New store for layout preferences
+└── pages/dashboard.vue                 # Updated with draggable grid
+```
+
+#### Technical Specifications
+- **Drag & Drop Library:** `vuedraggable@next` (Vue 3 compatible)
+- **Grid System:** CSS Grid with responsive breakpoints
+- **State Persistence:** localStorage with fallback to default
+- **RBAC Integration:** Tile visibility controlled via `useRBAC` composable
+- **Default Layout:** Hardcoded array of tile IDs in order of appearance
+
+### Progress Tracking
+- [x] Ticket #114 set to "In Progress" via Gitea manager
+- [x] TODO lista létrehozása development_log.md fájlban
+- [x] vuedraggable csomag telepítése (v4.1.0 for Vue 3)
+- [x] Dashboard.vue átalakítása draggable grid-re (Draggable component integration)
+- [x] TileWrapper.vue alapkomponens létrehozása (with drag handle, RBAC badges, visibility toggle)
+- [x] Meglévő tile-ok becsomagolása TileWrapper-be (TileCard wrapped in TileWrapper)
+- [x] Pinia store frissítése layout kezeléshez (added defaultLayout and isLayoutModified computed properties)
+- [x] Layout persistencia localStorage-ban (existing loadPreferences/savePreferences enhanced)
+- [x] "Restore Default Layout" gomb implementálása (button with conditional display based on isLayoutModified)
+- [x] Tesztelés és finomhangolás
+- [x] Gitea Ticket #114 lezárása (Ticket closed with technical summary)
+
+## Conclusion
+
+The Epic 10 Admin Frontend Phase 1 & 2 implementation establishes a solid foundation for the Mission Control dashboard. The architecture supports the core requirements of geographical RBAC isolation, modular launchpad tiles, and role-based access control. The system is ready for integration with the backend FastAPI services and can be extended with additional tiles and features as specified in the epic specification.