516 lines
No EOL
20 KiB
Markdown
516 lines
No EOL
20 KiB
Markdown
# User Routes Frontend Documentation
|
|
|
|
This document describes customer journeys for managing users through the frontend, focusing on how administrators interact with user management and how the backend routes support these experiences. All UI components are dynamically generated from backend metadata—no hardcoding required.
|
|
|
|
**IMPORTANT:** All user management pages are **admin-only**. Non-admin users should not see navigation links or be able to access these pages. The frontend must check user privileges before rendering user management UI.
|
|
|
|
## Table of Contents
|
|
|
|
1. [Overview](#overview)
|
|
2. [Customer Journey 1: Discovering and Browsing Users](#customer-journey-1-discovering-and-browsing-users)
|
|
3. [Customer Journey 2: Viewing User Details](#customer-journey-2-viewing-user-details)
|
|
4. [Customer Journey 3: Creating New Users](#customer-journey-3-creating-new-users)
|
|
5. [Customer Journey 4: Editing User Properties](#customer-journey-4-editing-user-properties)
|
|
6. [Customer Journey 5: Enabling and Disabling Users](#customer-journey-5-enabling-and-disabling-users)
|
|
7. [Customer Journey 6: Resetting User Passwords](#customer-journey-6-resetting-user-passwords)
|
|
8. [Customer Journey 7: Revoking User Sessions](#customer-journey-7-revoking-user-sessions)
|
|
9. [Customer Journey 8: Deleting Users](#customer-journey-8-deleting-users)
|
|
9. [Backend Metadata System](#backend-metadata-system)
|
|
10. [Implementation Patterns](#implementation-patterns)
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
The user routes (`/api/users`) enable administrators to manage users within their mandate. These routes focus on **user administration** including creation, editing, password management, and deletion.
|
|
|
|
**Key Principles:**
|
|
- **Admin-Only**: All user management functionality is restricted to administrators
|
|
- **User-Centric**: Documentation organized around what administrators want to accomplish
|
|
- **Backend-Driven**: All forms, tables, and UI components generated from backend metadata
|
|
- **No Hardcoding**: Field definitions, labels, validation rules, and options come from the backend
|
|
- **Permission-Aware**: Backend enforces permissions; frontend handles gracefully
|
|
- **Mandate-Scoped**: Users are managed within the context of mandates
|
|
|
|
---
|
|
|
|
## Customer Journey 1: Discovering and Browsing Users
|
|
|
|
### User Goal
|
|
"As an administrator, I want to see all users in my mandate and find the one I'm looking for."
|
|
|
|
### User Story
|
|
As an administrator, I want to browse users, search for specific users, filter by any field, sort them by different criteria, and quickly identify which users are enabled, their privilege levels, and their authentication methods.
|
|
|
|
### User Story Flow
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Admin
|
|
participant Frontend
|
|
participant Backend
|
|
|
|
Admin->>Frontend: Navigate to /users (admin only)
|
|
Frontend->>Frontend: Check if user is admin
|
|
alt User is not admin
|
|
Frontend-->>Admin: Redirect to unauthorized page or hide navigation
|
|
else User is admin
|
|
Frontend->>Backend: GET /api/attributes/User
|
|
Backend-->>Frontend: Attribute definitions (fields, labels, types)
|
|
Frontend->>Backend: GET /api/users/?pagination=...
|
|
Backend-->>Frontend: Paginated users list
|
|
Frontend->>Frontend: Generate table columns from attributes
|
|
Frontend->>Frontend: Generate filter controls from attributes
|
|
Frontend->>Frontend: Render users table + search + filters
|
|
Frontend-->>Admin: Display user list with search/filter UI
|
|
end
|
|
|
|
alt Admin performs general search
|
|
Admin->>Frontend: Type in search box (e.g., "john")
|
|
Frontend->>Frontend: Update search query
|
|
Frontend->>Backend: GET /api/users/?pagination=...filters:{"search":"john"}
|
|
Backend-->>Frontend: Filtered users list
|
|
Frontend-->>Admin: Display matching users
|
|
end
|
|
|
|
alt Admin applies field filter
|
|
Admin->>Frontend: Select filter field (e.g., "Privilege")
|
|
Frontend->>Frontend: Show filter options from attribute metadata
|
|
Admin->>Frontend: Select filter value (e.g., "admin")
|
|
Frontend->>Frontend: Update filter parameters
|
|
Frontend->>Backend: GET /api/users/?pagination=...filters:{"privilege":"admin"}
|
|
Backend-->>Frontend: Filtered users list
|
|
Frontend-->>Admin: Display filtered users
|
|
end
|
|
|
|
alt Admin combines search + filter + sort
|
|
Admin->>Frontend: Apply search + filter + sort
|
|
Frontend->>Frontend: Combine all parameters
|
|
Frontend->>Backend: GET /api/users/?pagination=...filters:{"search":"john","privilege":"admin"}...sort:desc
|
|
Backend-->>Frontend: Filtered, sorted users list
|
|
Frontend-->>Admin: Display results
|
|
end
|
|
|
|
Admin->>Frontend: Click column header (e.g., "Email")
|
|
Frontend->>Frontend: Update sort parameters
|
|
Frontend->>Backend: GET /api/users/?pagination=...sort:desc
|
|
Backend-->>Frontend: Sorted users list
|
|
Frontend-->>Admin: Display sorted users
|
|
|
|
Admin->>Frontend: Click user row
|
|
Frontend->>Frontend: Navigate to /users/userId
|
|
Frontend-->>Admin: Show user detail page
|
|
```
|
|
|
|
---
|
|
|
|
## Customer Journey 2: Viewing User Details
|
|
|
|
### User Goal
|
|
"As an administrator, I want to see everything about a specific user—their account information, privilege level, and status."
|
|
|
|
### User Story
|
|
As an administrator, I want to open a user and see their complete information, including username, email, full name, language preference, enabled status, privilege level, authentication authority, and mandate association.
|
|
|
|
### User Story Flow
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Admin
|
|
participant Frontend
|
|
participant Backend
|
|
|
|
Admin->>Frontend: Click user from list
|
|
Frontend->>Backend: GET /api/users/userId
|
|
Backend-->>Frontend: User object
|
|
|
|
Frontend->>Backend: GET /api/attributes/User
|
|
Backend-->>Frontend: Field definitions
|
|
|
|
Frontend->>Frontend: Generate UI from metadata
|
|
Frontend->>Frontend: Render user info section
|
|
Frontend->>Frontend: Separate editable vs read-only fields
|
|
Frontend-->>Admin: Display complete user view
|
|
|
|
alt User has editable fields and admin has permission
|
|
Frontend->>Frontend: Show "Edit User" button
|
|
end
|
|
|
|
alt Admin has permission
|
|
Frontend->>Frontend: Show "Reset Password" button
|
|
Frontend->>Frontend: Show "Revoke Sessions" button
|
|
Frontend->>Frontend: Show "Delete User" button
|
|
end
|
|
|
|
alt Admin clicks "Revoke Sessions"
|
|
Admin->>Frontend: Click "Revoke Sessions" button
|
|
Frontend->>Frontend: Show revocation dialog
|
|
Admin->>Frontend: Select authority filter (optional)
|
|
Admin->>Frontend: Enter reason (optional)
|
|
Admin->>Frontend: Click "Revoke"
|
|
Frontend->>Frontend: Optimistic update: Show loading state
|
|
Frontend->>Backend: POST /api/admin/tokens/revoke/user
|
|
alt Success
|
|
Backend-->>Frontend: {"revoked": count}
|
|
Frontend->>Frontend: Keep optimistic update
|
|
Frontend->>Backend: GET /api/users/userId (refetch)
|
|
Backend-->>Frontend: Updated user object
|
|
Frontend->>Frontend: Update UI with fresh data
|
|
Frontend-->>Admin: Show success message
|
|
else Error (403/400/500)
|
|
Backend-->>Frontend: Error response
|
|
Frontend->>Frontend: Revert optimistic update
|
|
Frontend-->>Admin: Show error message
|
|
end
|
|
end
|
|
|
|
alt Admin clicks "Reset Password"
|
|
Admin->>Frontend: Click "Reset Password" button
|
|
Frontend->>Frontend: Show password reset dialog
|
|
Admin->>Frontend: Enter new password
|
|
Admin->>Frontend: Confirm password
|
|
Admin->>Frontend: Click "Reset"
|
|
Frontend->>Frontend: Optimistic update: Show loading state
|
|
Frontend->>Backend: POST /api/users/userId/reset-password
|
|
alt Success
|
|
Backend-->>Frontend: Success response
|
|
Frontend->>Frontend: Keep optimistic update
|
|
Frontend->>Backend: GET /api/users/userId (refetch)
|
|
Backend-->>Frontend: Updated user object
|
|
Frontend->>Frontend: Update UI with fresh data
|
|
Frontend-->>Admin: Show success message
|
|
else Error (403/400/500)
|
|
Backend-->>Frontend: Error response
|
|
Frontend->>Frontend: Revert optimistic update
|
|
Frontend-->>Admin: Show error message
|
|
end
|
|
end
|
|
|
|
alt Admin clicks "Delete User"
|
|
Admin->>Frontend: Click "Delete User" button
|
|
Frontend->>Backend: GET /api/users/userId
|
|
Backend-->>Frontend: User data (for name)
|
|
Frontend->>Frontend: Show confirmation dialog
|
|
Admin->>Frontend: Confirm deletion
|
|
Frontend->>Frontend: Optimistic update: Remove user from UI
|
|
Frontend->>Backend: DELETE /api/users/userId
|
|
alt Success
|
|
Backend-->>Frontend: Success response
|
|
Frontend->>Frontend: Keep optimistic update
|
|
Frontend->>Frontend: Navigate to /users
|
|
Frontend-->>Admin: Show success message
|
|
else Error (403/404/500)
|
|
Backend-->>Frontend: Error response
|
|
Frontend->>Frontend: Revert optimistic update
|
|
Frontend-->>Admin: Show error message
|
|
end
|
|
end
|
|
```
|
|
|
|
|
|
## Customer Journey 3: Creating New Users
|
|
|
|
### User Goal
|
|
"As an administrator, I want to create new users for my mandate."
|
|
|
|
### User Story
|
|
As an administrator, I want to create a new user by filling out a form with their username, email, full name, language preference, privilege level, and initial password. The form should validate all required fields and show clear error messages.
|
|
|
|
### User Story Flow
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Admin
|
|
participant Frontend
|
|
participant Backend
|
|
|
|
Admin->>Frontend: Click "Create User" button
|
|
Frontend->>Frontend: Navigate to /users/create
|
|
|
|
Frontend->>Backend: GET /api/attributes/User
|
|
Backend-->>Frontend: Field definitions (editable fields)
|
|
|
|
Frontend->>Frontend: Filter editable fields
|
|
Frontend->>Frontend: Generate form from attributes
|
|
Frontend->>Frontend: Add password field (special case)
|
|
Frontend-->>Admin: Display create user form
|
|
|
|
Admin->>Frontend: Fill in form fields
|
|
Admin->>Frontend: Enter password
|
|
Admin->>Frontend: Click "Create"
|
|
|
|
Frontend->>Frontend: Validate form (required fields, types, email format)
|
|
alt Validation fails
|
|
Frontend-->>Admin: Show validation errors
|
|
else Validation passes
|
|
Frontend->>Backend: POST /api/users + form data + password
|
|
alt Permission denied (403)
|
|
Backend-->>Frontend: 403 Forbidden
|
|
Frontend-->>Admin: Show permission error
|
|
else Validation error (400)
|
|
Backend-->>Frontend: 400 Bad Request + error details
|
|
Frontend-->>Admin: Show backend validation errors
|
|
else Success (200)
|
|
Backend-->>Frontend: Created user object
|
|
Frontend->>Frontend: Navigate to user detail page
|
|
Frontend-->>Admin: Show created user
|
|
end
|
|
end
|
|
```
|
|
|
|
## Customer Journey 4: Editing User Properties
|
|
|
|
### User Goal
|
|
"As an administrator, I want to change user settings like their name, email, privilege level, or enabled status."
|
|
|
|
### User Story
|
|
As an administrator, I want to edit a user's properties through a form that only shows fields I'm allowed to edit, with validation and clear error messages.
|
|
|
|
### User Story Flow
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Admin
|
|
participant Frontend
|
|
participant Backend
|
|
|
|
Admin->>Frontend: Click "Edit" button
|
|
Frontend->>Frontend: Navigate to /users/id/edit
|
|
|
|
Frontend->>Backend: GET /api/users/userId
|
|
Backend-->>Frontend: Current user data
|
|
|
|
Frontend->>Backend: GET /api/attributes/User
|
|
Backend-->>Frontend: Field definitions (editable fields)
|
|
|
|
Frontend->>Frontend: Filter editable fields
|
|
Frontend->>Frontend: Generate form from attributes
|
|
Frontend->>Frontend: Pre-populate form with user data
|
|
Frontend-->>Admin: Display edit form
|
|
|
|
Admin->>Frontend: Modify form fields
|
|
Admin->>Frontend: Click "Save"
|
|
|
|
Frontend->>Frontend: Validate form (required fields, types)
|
|
alt Validation fails
|
|
Frontend-->>Admin: Show validation errors
|
|
else Validation passes
|
|
Frontend->>Frontend: Optimistic update: Apply changes to UI immediately
|
|
Frontend->>Backend: PUT /api/users/userId + form data
|
|
alt Permission denied (403)
|
|
Backend-->>Frontend: 403 Forbidden
|
|
Frontend->>Frontend: Revert optimistic update
|
|
Frontend-->>Admin: Show permission error
|
|
else Validation error (400)
|
|
Backend-->>Frontend: 400 Bad Request + error details
|
|
Frontend->>Frontend: Revert optimistic update
|
|
Frontend-->>Admin: Show backend validation errors
|
|
else Success (200)
|
|
Backend-->>Frontend: Updated user
|
|
Frontend->>Frontend: Keep optimistic update (or refresh from response)
|
|
Frontend->>Frontend: Navigate to detail page
|
|
Frontend-->>Admin: Show updated user
|
|
end
|
|
end
|
|
```
|
|
|
|
---
|
|
|
|
## Customer Journey 5: Enabling and Disabling Users
|
|
|
|
### User Goal
|
|
"As an administrator, I want to quickly enable or disable users directly from the user list without navigating to their detail page."
|
|
|
|
### User Story
|
|
As an administrator, I want to toggle a user's enabled status directly in the user list table. When I click the toggle, it should immediately update the user's status in the backend with an optimistic update, so the UI feels responsive and confident.
|
|
|
|
### User Story Flow
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Admin
|
|
participant Frontend
|
|
participant Backend
|
|
|
|
Admin->>Frontend: View user list table
|
|
Frontend->>Backend: GET /api/users/?pagination=...
|
|
Backend-->>Frontend: Paginated users list
|
|
Frontend->>Frontend: Render table with enabled toggle column
|
|
Frontend-->>Admin: Display user list with enabled toggles
|
|
|
|
Admin->>Frontend: Click enabled toggle for user
|
|
Frontend->>Frontend: Optimistic update: Toggle switch immediately<br/>(enabled: true → false or false → true)
|
|
Frontend->>Backend: PUT /api/users/userId + {enabled: newValue}
|
|
alt Success (200)
|
|
Backend->>Backend: Update user enabled status
|
|
Backend-->>Frontend: Updated user object
|
|
Frontend->>Frontend: Keep optimistic update (toggle already changed)
|
|
Frontend->>Backend: GET /api/users/?pagination=... (refetch list)
|
|
Backend-->>Frontend: Updated users list
|
|
Frontend->>Frontend: Update table with fresh data
|
|
Frontend-->>Admin: Show subtle success indicator (optional)
|
|
else Error (403/400/404/500)
|
|
Backend-->>Frontend: Error response
|
|
Frontend->>Frontend: Revert optimistic update: Toggle back to original state
|
|
Frontend-->>Admin: Show error message
|
|
end
|
|
```
|
|
|
|
## Customer Journey 6: Resetting User Passwords
|
|
|
|
### User Goal
|
|
"As an administrator, I want to reset a user's password when they forget it or need a new one."
|
|
|
|
### User Story
|
|
As an administrator, I want to reset a user's password by entering a new password. The system should validate password strength and automatically revoke all existing tokens for security.
|
|
|
|
### User Story Flow
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Admin
|
|
participant Frontend
|
|
participant Backend
|
|
|
|
Admin->>Frontend: Click "Reset Password" button
|
|
Frontend->>Frontend: Show password reset dialog
|
|
|
|
Admin->>Frontend: Enter new password
|
|
Admin->>Frontend: Confirm new password
|
|
Admin->>Frontend: Click "Reset"
|
|
|
|
Frontend->>Frontend: Validate password (min 8 characters)
|
|
Frontend->>Frontend: Validate passwords match
|
|
alt Validation fails
|
|
Frontend-->>Admin: Show validation errors
|
|
else Validation passes
|
|
Frontend->>Backend: POST /api/users/userId/reset-password + newPassword
|
|
alt Permission denied (403)
|
|
Backend-->>Frontend: 403 Forbidden
|
|
Frontend-->>Admin: Show permission error
|
|
else Validation error (400)
|
|
Backend-->>Frontend: 400 Bad Request (password too short)
|
|
Frontend-->>Admin: Show validation error
|
|
else Success (200)
|
|
Backend->>Backend: Reset password
|
|
Backend->>Backend: Revoke all user tokens
|
|
Backend-->>Frontend: Success response
|
|
Frontend-->>Admin: Show success message
|
|
end
|
|
end
|
|
```
|
|
|
|
### Frontend Requirements
|
|
|
|
> **📋 Complete frontend requirements for this journey are documented in [User Page Requirements](./user-page-requirements.md#customer-journey-6-resetting-user-passwords)**
|
|
|
|
The frontend must implement a password reset dialog with password strength validation. This is an admin-only action.
|
|
|
|
```typescript
|
|
const handleResetPassword = async (userId: string, newPassword: string) => {
|
|
// Validate password strength
|
|
if (newPassword.length < 8) {
|
|
showError('Password must be at least 8 characters long');
|
|
return;
|
|
}
|
|
|
|
const response = await fetch(`/api/users/${userId}/reset-password`, {
|
|
method: 'POST',
|
|
headers: { 'Content-Type': 'application/json' },
|
|
body: JSON.stringify({ newPassword })
|
|
});
|
|
|
|
if (response.ok) {
|
|
showSuccess('Password reset successfully. All user sessions have been revoked.');
|
|
} else {
|
|
const error = await response.json();
|
|
showError(error.detail || 'Failed to reset password');
|
|
}
|
|
};
|
|
```
|
|
|
|
---
|
|
|
|
## Customer Journey 7: Revoking User Sessions
|
|
|
|
### User Goal
|
|
"As an administrator, I want to revoke all active sessions for a user to force them to log in again."
|
|
|
|
### User Story
|
|
As an administrator, I want to revoke all active tokens/sessions for a user, optionally filtered by authentication authority (local, Google, Microsoft). This is useful for security purposes, such as when a user's account may have been compromised or when they need to be logged out of all devices.
|
|
|
|
### User Story Flow
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Admin
|
|
participant Frontend
|
|
participant Backend
|
|
|
|
Admin->>Frontend: Click "Revoke Sessions" button
|
|
Frontend->>Frontend: Show session revocation dialog
|
|
|
|
Admin->>Frontend: Optionally select authority filter (local/Google/Microsoft)
|
|
Admin->>Frontend: Optionally enter reason
|
|
Admin->>Frontend: Click "Revoke Sessions"
|
|
|
|
Frontend->>Backend: POST /api/admin/tokens/revoke/user + {userId, authority?, reason?}
|
|
alt Permission denied (403)
|
|
Backend-->>Frontend: 403 Forbidden
|
|
Frontend-->>Admin: Show permission error
|
|
else Success (200)
|
|
Backend->>Backend: Revoke all active tokens for user
|
|
Backend-->>Frontend: {"revoked": count}
|
|
Frontend-->>Admin: Show success message with count
|
|
end
|
|
```
|
|
|
|
---
|
|
|
|
## Customer Journey 8: Deleting Users
|
|
|
|
### User Goal
|
|
"As an administrator, I want to delete users that are no longer needed."
|
|
|
|
### User Story
|
|
As an administrator, I want to delete users with a clear confirmation to prevent accidental deletion.
|
|
|
|
### User Story Flow
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Admin
|
|
participant Frontend
|
|
participant Backend
|
|
|
|
Admin->>Frontend: Click "Delete" button
|
|
Frontend->>Backend: GET /api/users/userId
|
|
Backend-->>Frontend: User data (for name)
|
|
Frontend->>Frontend: Show confirmation dialog<br/>"Delete 'User Name'?"
|
|
Admin->>Frontend: Cancel deletion
|
|
Frontend-->>Admin: Dialog closed, no action
|
|
|
|
Admin->>Frontend: Click "Delete" button again
|
|
Frontend->>Backend: GET /api/users/userId
|
|
Backend-->>Frontend: User data
|
|
Frontend->>Frontend: Show confirmation dialog
|
|
Admin->>Frontend: Confirm deletion
|
|
Frontend->>Frontend: Optimistic update: Remove user from UI immediately
|
|
Frontend->>Backend: DELETE /api/users/userId
|
|
|
|
alt Permission denied (403)
|
|
Backend-->>Frontend: 403 Forbidden
|
|
Frontend->>Frontend: Revert optimistic update: Restore user in UI
|
|
Frontend-->>Admin: Show permission error
|
|
else Not found (404)
|
|
Backend-->>Frontend: 404 Not Found
|
|
Frontend->>Frontend: Revert optimistic update: Restore user in UI
|
|
Frontend-->>Admin: Show not found error
|
|
else Success (200)
|
|
Backend-->>Frontend: Success response
|
|
Frontend->>Frontend: Keep optimistic update (user already removed)
|
|
Frontend->>Frontend: Show success message
|
|
Frontend->>Frontend: Navigate to /users (if on detail page)
|
|
Frontend-->>Admin: Display user list (without deleted user)
|
|
end
|
|
``` |