Aller au contenu principal

Epic 3: RBAC-Enhanced User Experience & Interface

⚡ URGENT: Story 3.3 Fast-Tracked (2025-11-09)​

Course Correction Applied: Story 3.3 (Context-Aware Forms and Data Entry) has been fast-tracked ahead of Epic 2 to enable user acceptance testing. The application requires CRUD forms to validate Epic 1's completed backend security features (Stories 1.3 & 1.4).

Revised Story Sequence:

  1. ✅ Story 3.3 - Context-Aware Forms (CURRENT PRIORITY - Started 2025-11-09)
  2. Story 3.1 - Navigation & Menu System
  3. Story 3.2 - Role-Based Dashboards
  4. Story 3.4 - Search & Filtering
  5. Story 3.5 - Notifications
  6. Story 3.6 - Mobile Responsive

Rationale: Forms enable UAT 4-5 sprints earlier. Epic 2 (backend) proceeds in parallel.

Reference: Sprint Change Proposal | Story 3.3 Implementation

Epic Goal​

Transform the EMTB frontend user experience to fully leverage the implemented RBAC infrastructure, providing role-based dashboards, personalized workflows, and intuitive interfaces that respect user permissions while enhancing productivity for both EMTB staff and client users.

Epic Description​

Foundation Context:

  • Epic 1 Completed: JWT authentication, role-based guards, tenant isolation, secure APIs (Stories 1.0-1.4 complete)
  • Epic 2 Status: Planned - Will proceed in parallel with frontend forms
  • Current State: Backend RBAC infrastructure operational and tested, frontend forms needed for UAT
  • Technology Stack: Vite + React + shadcn/ui + established API security infrastructure

Epic Focus:

This epic transforms the user experience by implementing role-aware interfaces, personalized dashboards, and streamlined workflows that leverage the security foundation to provide enterprise-grade usability.

Stories​

Story 3.1: Role-Based Navigation and Menu System​

Priority: High - Core User Experience

As an EMTB user (any role), I want the navigation menu to show only features and sections I have access to, So that I can focus on my work without confusion about unavailable functionality.

Acceptance Criteria:

  1. Implement role-aware navigation components that hide unauthorized sections
  2. Create dynamic menu generation based on user permissions
  3. Add role-based route guards that redirect unauthorized access gracefully
  4. Implement breadcrumb navigation with permission-aware links
  5. Create responsive navigation that adapts to different screen sizes and roles

Role-Based Navigation Structure:

EMTB-ADMIN:
├── Dashboard (Multi-client overview)
├── Clients (All clients management)
├── Sites & Cadastres (Cross-client view)
├── Tax Claims (All reclamations)
├── Financial (Invoicing & billing)
├── Partners (Business relationships)
├── Reports (System-wide analytics)
└── Administration (User & system management)

EMTB-LIMITED:
├── Dashboard (Assigned clients)
├── Clients (Assigned only)
├── Sites & Cadastres (Assigned only)
├── Tax Claims (Assigned only)
└── Reports (Limited scope)

CLIENT-USER:
├── Dashboard (Own company)
├── Properties (Own sites)
├── Tax Claims (Own reclamations)
├── Documents (Own files)
└── Reports (Own data)

Story 3.2: Personalized Role-Based Dashboards​

Priority: High - Productivity Enhancement

As an EMTB user in any role, I want a dashboard tailored to my responsibilities and permissions, So that I can quickly access relevant information and complete my tasks efficiently.

Acceptance Criteria:

  1. Create role-specific dashboard layouts with relevant widgets
  2. Implement permission-aware data visualization components
  3. Add customizable dashboard elements within role boundaries
  4. Create real-time updates for dashboard metrics and alerts
  5. Implement responsive dashboard design for mobile and desktop

Dashboard Specifications:

EMTB-ADMIN Dashboard:

  • Multi-client performance metrics
  • System-wide reclamation status overview
  • Financial summary across all clients
  • Recent activity feed (all clients)
  • Quick access to critical tasks
  • System health and performance indicators

EMTB-LIMITED Dashboard:

  • Assigned client performance metrics
  • Task queue for assigned reclamations
  • Pending document reviews
  • Recent client activity
  • Performance KPIs for assigned portfolio

CLIENT-USER Dashboard:

  • Company property overview
  • Active tax claim status
  • Document status and requirements
  • Recent activity timeline
  • Key financial metrics and projections

Story 3.3: Context-Aware Forms and Data Entry​

Priority: Medium - Data Integrity

As an EMTB user entering data, I want forms that respect my role permissions and tenant context, So that I can only create and modify data appropriate to my access level.

Acceptance Criteria:

  1. Implement role-based form field visibility and editability
  2. Create tenant-aware dropdown options and data selections
  3. Add automatic context injection (tenant, user) in form submissions
  4. Implement conditional form validation based on user permissions
  5. Create form templates optimized for each role's common workflows

Form Behavior Examples:

// Client form for EMTB-ADMIN
<ClientForm
  showAllFields={true}
  canAssignToAnyPartner={true}
  canChangeStatus={true}
  tenantScope="all"
/>

// Same form for CLIENT-USER
<ClientForm
  showAllFields={false}
  canAssignToAnyPartner={false}
  canChangeStatus={false}
  tenantScope="own"
  readOnlyMode={true}
/>

Story 3.4: Advanced Role-Based Search and Filtering​

Priority: Medium - Data Discovery

As an EMTB user searching for information, I want search results filtered to my access permissions and enhanced with role-appropriate options, So that I can find relevant data quickly without seeing unauthorized information.

Acceptance Criteria:

  1. Implement tenant-scoped search functionality
  2. Create role-based filter options and search categories
  3. Add intelligent search suggestions based on user permissions
  4. Implement saved searches and search history per role
  5. Create advanced filtering with permission-aware field options

Search Capabilities by Role:

EMTB-ADMIN:

  • Global search across all clients and data
  • Advanced filtering by any field
  • Cross-client comparative searches
  • System-wide data export capabilities

EMTB-LIMITED:

  • Search within assigned client scope
  • Filtering by assigned properties and claims
  • Limited export to assigned data only

CLIENT-USER:

  • Search within own company data only
  • Basic filtering by property and claim status
  • Export limited to own data

Story 3.5: Role-Based Notification and Alert System​

Priority: Medium - Communication Enhancement

As an EMTB user, I want to receive notifications relevant to my role and responsibilities, So that I stay informed about important updates without information overload.

Acceptance Criteria:

  1. Implement role-based notification routing and delivery
  2. Create tenant-aware alert generation and distribution
  3. Add notification preferences customizable within role boundaries
  4. Implement real-time notifications with proper permission checks
  5. Create notification history and management interface

Notification Categories by Role:

EMTB-ADMIN:

  • System-wide alerts and performance issues
  • Critical business metrics and thresholds
  • User access and security notifications
  • Financial and billing alerts across all clients

EMTB-LIMITED:

  • Task assignments and deadlines for assigned clients
  • Document submission requirements
  • Status change notifications for assigned portfolio
  • Performance alerts for assigned responsibilities

CLIENT-USER:

  • Document requests and requirements
  • Tax claim status updates
  • Important deadline reminders
  • System updates affecting their access

Story 3.6: Mobile-Responsive Role-Based Interface​

Priority: Low - Accessibility Enhancement

As an EMTB user working on mobile devices, I want a responsive interface that maintains role-based functionality, So that I can access appropriate features regardless of device.

Acceptance Criteria:

  1. Create mobile-optimized layouts for each role type
  2. Implement touch-friendly navigation with role-based menus
  3. Add mobile-specific workflows for common tasks
  4. Create offline capability for essential role-based functions
  5. Implement mobile push notifications with permission awareness

Technical Implementation​

Frontend Architecture​

Auth0 Context → Role Extraction → Permission Mapping → Component Rendering

Role-Based Component Pattern​

const RoleAwareComponent = ({ userRole, permissions, children }) => {
  const allowedFeatures = getPermissionsForRole(userRole);

  return (
    <PermissionProvider permissions={allowedFeatures}>
      {children}
    </PermissionProvider>
  );
};

// Usage
<RoleAwareComponent userRole="EMTB-ADMIN">
  <ClientManagement />
  <SystemAdministration />
</RoleAwareComponent>

Permission Checking Hooks​

const usePermissions = () => {
  const { user } = useAuth();

  return {
    canViewAllClients: hasPermission(user, "VIEW_ALL_CLIENTS"),
    canEditClient: hasPermission(user, "EDIT_CLIENT"),
    canDeleteClaim: hasPermission(user, "DELETE_CLAIM"),
    // ... other permissions
  };
};

Integration Points​

With Epic 1 (RBAC Foundation)​

  • Leverages JWT role extraction
  • Uses established permission patterns
  • Builds on security testing framework

With Epic 2 (Tenant Isolation)​

  • Respects tenant boundaries in UI
  • Uses tenant context for data scoping
  • Implements tenant-aware user experiences

With Backend APIs​

  • Consumes role-based API endpoints
  • Handles permission-based error responses
  • Implements graceful degradation for unauthorized access

Performance Considerations​

Optimization Strategies​

  1. Lazy Loading: Load role-specific components only when needed
  2. Permission Caching: Cache user permissions client-side with refresh logic
  3. Component Memoization: Prevent unnecessary re-renders of permission-aware components
  4. Route Prefetching: Intelligently prefetch accessible routes only

Performance Targets​

  • Initial Load: < 3 seconds for role-specific dashboard
  • Navigation: < 500ms between role-appropriate sections
  • Search: < 1 second for permission-filtered results
  • Responsiveness: 60fps animations and interactions

Accessibility & Usability​

WCAG Compliance​

  • Role-based interfaces maintain AA accessibility standards
  • Screen reader compatibility with permission-aware navigation
  • Keyboard navigation support for all role-specific features

User Experience Principles​

  • Discoverability: Users can easily find features they have access to
  • Feedback: Clear indication of permission boundaries and restrictions
  • Consistency: Similar patterns across all role-based interfaces
  • Error Handling: Graceful handling of permission-related errors

Definition of Done​

  • Navigation menu dynamically adapts to user roles with proper hiding of unauthorized sections
  • Role-specific dashboards operational with real-time data and customization options
  • Forms enforce permission boundaries with appropriate field visibility and validation
  • Search and filtering respect tenant boundaries and role permissions
  • Notification system delivers role-appropriate alerts with proper routing
  • Mobile-responsive interface maintains role-based functionality across devices
  • Performance targets met for all role-based interface interactions
  • Accessibility standards maintained across all role-specific features
  • E2E testing covers all role-based user journeys and permission scenarios
  • User acceptance testing passed for all roles (admin, limited, client)

Epic Owner: Frontend & UX Team
Dependencies: Epic 1 (RBAC) complete, Epic 2 (Tenant Isolation) in progress
Target Timeline: 3-4 sprints
Critical Path: Navigation → Dashboards → Forms → Search → Notifications → Mobile