User Management — Building Blocks Integration Requirements

Requirements specification for integrating 3 building blocks into the user-management module.

Overview

1. Workflow Engine — User Status Transitions

Goal

Replace the static status badge in UserDetailComponent with <lib-status-transition>, enabling formal workflow-based status transitions with permission checks, confirmations, and history tracking.

Functional Requirements

FR-1.1: Workflow Definition

Define a WorkflowDefinition for user status with entity type 'user':

States:

Transitions:

FR-1.2: Workflow Registration

• Register the workflow definition on module initialization (e.g., in routes config or a dedicated initializer)
• Use WorkflowEngineService.registerWorkflow()

FR-1.3: Status Transition Component

• In UserDetailComponent, replace the static <ggs-badge> for status with <lib-status-transition>
• Pass entityType="user", [entity]="entity()" (must include status as current state identifier)
• Handle (transitionCompleted) to refresh user data
• Handle (transitionFailed) to show error feedback

FR-1.4: Post-Transition Hooks

• Each transition emits a WorkflowTransitionEvent (already built into the engine)
• Add a post-hook that emits a UserStatusChangedEvent (already defined in user-management events)
• Mock notification: log a message simulating "Notification sent to user about status change"

FR-1.5: Transition History

• In UserDetailComponent, add a section showing status change history using WorkflowHistoryService.getHistory('user', userId)
• Display as a simple timeline/list: date, from → to, performed by

Non-Functional Requirements

• NFR-1.1: All transitions must respect existing RBAC — only users with users:status permission see transition buttons
• NFR-1.2: The workflow definition must be registered once and shared across all instances
• NFR-1.3: Status transition must be reactive — UI updates immediately after successful transition

User Stories

• US-1.1: As an admin, I can approve a pending user by clicking "Approve" on their detail page, so the user becomes active
• US-1.2: As an admin, I can suspend an active user with a confirmation dialog, so the user loses access
• US-1.3: As an admin, I can see the history of status changes for a user

Acceptance Criteria

• <lib-status-transition> renders in UserDetailComponent with correct current state
• Available transitions match the user's current status
• Destructive transitions (suspend, deactivate) show confirmation dialog
• Non-destructive transitions (approve, reactivate) execute immediately
• After successful transition, the user entity reloads with new status
• Status change history displays in the detail view
• Transitions respect users:status permission

2. Media System — Avatar Management

Goal

Replace the text URL input for avatar with a proper image upload experience using <lib-entity-media-section>, allowing users to upload/change profile photos in both the form and detail views.

Functional Requirements

FR-2.1: Avatar Upload in UserFormComponent

• Replace the current <input type="text"> for avatar URL with <lib-entity-media-section>
• Configuration:
  • entityType="user-avatar"
  • [entityId]="userId" (from route params in edit mode; generated/temp in create mode)
  • accept="image/jpeg,image/png,image/webp"
  • [maxSize]="2" (2 MB)
  • [multiple]="false" (single file only)
  • [allowDelete]="true"
• On successful upload, the component emits MediaUploadedEvent — the form should capture the new URL
• The actual avatar field update depends on the backend (the form sends the uploaded media reference)

FR-2.2: Avatar Change in UserDetailComponent

• Add a "Change Photo" section or overlay on the avatar area in UserDetailComponent
• Use <lib-entity-media-section> with same configuration as form
• Only visible to users with users:update permission
• After upload, refresh user data to show new avatar

FR-2.3: File Validation

• Accept only: image/jpeg, image/png, image/webp
• Max file size: 2 MB
• Single file only — new upload replaces the existing avatar
• Show validation errors for wrong type or size

Non-Functional Requirements

• NFR-2.1: Upload shows progress indicator
• NFR-2.2: Image preview available after upload
• NFR-2.3: Permission-gated — only users with users:update see the upload control

User Stories

• US-2.1: As an admin editing a user, I can upload a profile photo instead of manually entering a URL
• US-2.2: As an admin viewing a user's detail page, I can change their photo directly
• US-2.3: As an admin, I see a preview of the uploaded image before saving

Acceptance Criteria

• Avatar text input replaced with <lib-entity-media-section> in UserFormComponent
• Avatar upload available in UserDetailComponent (permission-gated)
• Only image files (jpeg/png/webp) accepted, max 2 MB
• Single file mode — replaces existing avatar
• Upload progress shown during upload
• Uploaded image previews correctly in the gallery
• MediaUploadedEvent emitted on successful upload

3. Entity Lookup — Role Assignment

Goal

Replace the checkbox-based role selection in UserFormComponent with a searchable <ggs-entity-lookup> in a multi-select "tag input" pattern, providing a more scalable role assignment experience.

Functional Requirements

FR-3.1: Multi-Role Lookup Component

Since GgsEntityLookupComponent is single-select, implement a multi-select wrapper pattern:

• Use <ggs-entity-lookup> to search and select one role at a time
• On selection, add the role to a "selected roles" list displayed as chips/tags
• After each selection, clear the lookup input for the next pick
• Filter out already-selected roles from search results
• Show all available roles on focus (before the user types) using the initialItems input bound to a computed() signal that loads all roles once and excludes already-selected ones. This provides immediate discoverability of available options

FR-3.2: Replace in UserFormComponent

• Create mode: Replace the current <select multiple> with the multi-role lookup
• Edit mode: Replace the embedded UserRoleManagerComponent with the same multi-role lookup, pre-populated with the user's current roles
• The lookup calls RoleApiService to load available roles
• loadFn: searches roles by name (filter from available roles minus already selected)
• displayFn: shows role name + description

FR-3.3: Selected Roles Display

• Show selected roles as removable chips/tags below the lookup input
• Each chip shows: role name, remove button (×)
• Removing a chip removes the role from the selection
• Minimum 1 role required (validation)

FR-3.4: Role Data Flow

• The component outputs the selected role names/IDs
• On form submit, the selected roles are included in the save payload
• In edit mode, initialize the selected roles from user.roles

FR-3.5: Removal of UserRoleManagerComponent from Form

• UserRoleManagerComponent is NO longer used in UserFormComponent
• UserRoleManagerComponent remains in UserDetailComponent (readonly mode) — unchanged
• Remove the pendingRoles signal pattern; the form directly manages role selection

Non-Functional Requirements

• NFR-3.1: Role search must be debounced (300ms default from entity-lookup)
• NFR-3.2: Keyboard accessible — lookup supports arrow keys, Enter, Escape
• NFR-3.3: Form validation — at least 1 role must be selected
• NFR-3.4: Role descriptions visible in dropdown results for informed selection

User Stories

• US-3.1: As an admin creating a user, I can search for roles by name and add them one by one
• US-3.2: As an admin editing a user, I see their current roles as chips and can add/remove roles
• US-3.3: As an admin, I see role descriptions in the search results to make informed choices
• US-3.4: As an admin, I cannot save a user with zero roles assigned

Acceptance Criteria

• Checkbox role selection removed from UserFormComponent
• <ggs-entity-lookup> renders with role search functionality
• Selected roles displayed as removable chips
• Already-selected roles excluded from search results
• Lookup clears after each selection
• Pre-populated with existing roles in edit mode
• Form validation prevents saving with 0 roles
• UserRoleManagerComponent still works in UserDetailComponent (readonly, unchanged)
• On focus, all available roles are shown immediately (via initialItems bound to a reactive computed() signal)

Dependencies

Out of Scope

• Backend API changes — all integrations work with existing mock API structure
• UserRoleManagerComponent refactoring — it stays as-is for readonly use in detail views
• Role hierarchy visualization — remains in UserRoleManagerComponent (detail view only)
• User preferences or security settings changes
• New permissions — uses existing users:status and users:update

Status: Implemented Implementation Date: 2026-02-25 Validated: 2026-02-26 — 301 tests passing (257 user-management, 32 workflow-engine, 12 media), build green Commit: feat(user-management): integrate workflow engine, media system, and entity lookup building blocks Component Usage Guide: COMPONENT_USAGE.md