From d4c9e73e1b9a2d9cbdc38ed420b946a7694c52a4 Mon Sep 17 00:00:00 2001 From: Echo Date: Wed, 29 Apr 2026 01:35:08 +0000 Subject: [PATCH] docs: add Navigation and Frontend Error Handling specs to SPEC.md - Added Navigation subsection under User Interface: - Layout structure: AppBar + 240px sidebar + main content - Menu groups: Overview, Fleet, Operations, Administration - RBAC visibility rules for admin-only items - Mobile responsive behavior (collapsible drawer) - User menu with avatar, role display, and sign out - Dark theme specification (Primary: #42A5F5, Secondary: #26C6DA) - Added Frontend Error Handling subsection: - Login error messages for network, rate limit, auth, MFA, server errors - Dismissible MUI Alert components (no blank error pages) - Auth token expiry handling via Zustand store (no hard redirects) - React Router RequireAuth guard behavior --- SPEC.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/SPEC.md b/SPEC.md index 2919a5b..42acf1e 100644 --- a/SPEC.md +++ b/SPEC.md @@ -153,6 +153,50 @@ Management plane web application communicating with Linux Patch API agents on ea - Web UI TLS certificate strategy (internal CA vs. operator-supplied) - IP whitelist management +### Navigation + +All authenticated pages share a persistent sidebar navigation layout: + +**Layout Structure:** +- **AppBar** (top): Page title, user avatar with role display, dropdown menu (profile info, sign out) +- **Sidebar** (left, 240px): Grouped navigation menu with icons, version label at bottom +- **Main content** (center): Routed page content with padding and scroll + +**Menu Groups:** + +| Group | Items | RBAC | +|-------|-------|------| +| Overview | Dashboard | All users | +| Fleet | Hosts, Groups, Deploy | All users | +| Operations | Jobs, Maintenance | All users | +| Administration | Users, Certificates, Settings | Admin only | +| Administration | Reports | All users | + +**Behavior:** +- Active page highlighted with primary color background on sidebar item +- Admin-only items hidden from operators (entire group hidden if all items are admin-only) +- Mobile responsive: collapsible drawer with hamburger toggle on small screens, permanent drawer on desktop +- User menu: avatar shows first letter of display name, dropdown shows display name + role, sign out action clears tokens and navigates to login via React Router +- Login page renders without sidebar (standalone layout) + +**Theme:** Dark mode (MUI dark palette). Primary: #42A5F5, Secondary: #26C6DA. + +### Frontend Error Handling + +**Login Errors:** +- Network errors (server unreachable): "Unable to connect to the server. Please check your network connection and try again." +- Rate limiting (HTTP 429): "Too many login attempts. Please wait a moment and try again." +- Invalid credentials (HTTP 401): "Invalid username or password." +- Account disabled: "This account has been disabled. Contact your administrator." +- MFA required: Show TOTP input field with info alert +- Server errors (5xx): "A server error occurred. Please try again later." +- All errors displayed as dismissible MUI Alert components (no blank error pages) + +**Auth Token Expiry:** +- 401 responses trigger automatic token refresh using stored refresh token +- If refresh fails, auth state is cleared via Zustand store (no `window.location` hard redirects) +- React Router `` guard redirects unauthenticated users to `/login` + ## Error Handling **Agent Communication Failures:**