User Settings
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: User-specific display preferences including timezone, date/time format, and display name Domain: USERSET
Statement
The system shall allow authenticated users to configure and persist personal display preferences that control the presentation of temporal data and user identity throughout the application.
Users can select their preferred timezone, date format, and time format, as well as set a unique display name. The system enforces display name uniqueness and length constraints, applies saved preferences to all temporal data displays, and provides access to settings from any application context.
Behavior Overview (Illustrative)
This diagram illustrates the high-level behavior. It does not specify UI layout, styling, or interaction details.
Definitions
| Term | Definition |
|---|---|
| Display Name | A user-configurable identifier shown throughout the application to represent the user |
| Timezone | A geographic region's standard time offset used to localize temporal data display |
| Date Format | The pattern used to render date values (e.g., MM/DD/YYYY, DD/MM/YYYY) |
| Time Format | The pattern used to render time values (e.g., 12-hour, 24-hour) |
Functional Requirements
Preference Management (REQ-USERSET-001)
FR-USERSET-001 Manage User Display Preferences
The system shall allow authenticated users to configure and persist personal display preferences that control the presentation of temporal data and user identity throughout the application.
Acceptance Criteria:
Preference Selection:
- The system shall allow users to select a timezone from available options
- The system shall allow users to select a date format from available options
- The system shall allow users to select a time format from available options
- The system shall allow users to set a display name
Persistence & Application:
- The system shall persist user preference changes upon user confirmation
- The system shall apply saved preferences to all temporal data displayed in the application
- The system shall apply the user's selected timezone to all date/time values displayed in the application UI
Accessibility:
- The system shall provide access to preference configuration from any application context
Constraints:
- The system shall enforce a maximum display name length of 40 characters
- The system shall provide 'Eastern Time (ET)' as an additional timezone option for Super Admin users
Error Handling:
- Save operation fails: The system shall display an error message and retain unsaved changes for retry
Trace: Source: 3.0.0-User Settings (Rows 1-6, 9-11) | Jira: BT-3089, BT-3029, BT-3711 | Tests: [BT-605](#test-req-userset-001)
Display Name Validation (REQ-USERSET-002)
FR-USERSET-002 Validate Display Name Uniqueness
The system shall validate that a user's display name is unique across all users before persisting the value.
Acceptance Criteria:
Validation Rules:
- The system shall reject display names that are already in use by another user
- The system shall perform uniqueness validation before submission is attempted
User Feedback:
- The system shall display a validation error when a duplicate display name is detected
- The system shall prevent preference submission when display name validation fails
Error Handling:
- Display name already in use: The system shall display "Display Name has already taken"
Trace: Source: 3.0.0-User Settings (Row 8) | Jira: BT-3958 | Tests: [BT-3856](#test-req-userset-002)
Non-Functional Requirements (REQ-USERSET-NFR-001)
FR-USERSET-NFR-001 Performance Standards
The system shall conform to global NFR performance standards for all user settings operations.
Acceptance Criteria:
Performance Thresholds:
- Settings page loading shall meet global performance thresholds
- Settings save operations shall meet global performance thresholds
Trace: Source: 3.0.0-User Settings (Non functional Requirements section) | Related: Global NFR Performance Standards
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
| supported_timezones | See list below | Available timezone selections | REQ-USERSET-001 |
| display_name_max_length | 40 | Maximum characters for display name | REQ-USERSET-001 |
Supported Timezones:
| Display Name | IANA Identifier |
|---|---|
| Eastern Time (ET) | America/New_York |
| Central Time (CT) | America/Chicago |
| Mountain Time (MT) | America/Denver |
| Pacific Time (PT) | America/Los_Angeles |
| Alaska Time (AKT) | America/Anchorage |
| Hawaii-Aleutian Time (HAT) | Pacific/Honolulu |
| Coordinated Universal Time (UTC) | UTC |
| GMT/BST | Europe/London |
| CET/CEST | Europe/Berlin |
| India Standard Time (IST) | Asia/Colombo |
Assumptions
The following assumptions were verified against the codebase implementation:
- Users are authenticated before accessing settings functionality (verified:
AuthUserControllerrequires auth middleware viaroutes/api.php) - At least one timezone option is available in the system (verified:
User::defaultSettings()provides 'America/Chicago' as default timezone) - Display name character limit (40 characters) is enforced at the application level (verified:
UpdateAuthUserRequestenforces'display_name' => 'nullable|max:40'validation rule)
UI Notes (Illustrative)
FR-USERSET-001 UI Specifications
Navigation:
- Settings access via cog icon in top right corner of application header
- Cog icon consistently positioned across all screens
Form Controls:
- Timezone: Dropdown list
- Date format: Radio button group
- Time format: Radio button group
- Display name: Text input field
- Save: Button to confirm changes
FR-USERSET-002 UI Specifications
Validation Feedback:
- Validation error displayed inline with display name field
- Error text: "Display Name has already taken"
Implementation (Illustrative)
| Component | Type | Location | Notes |
|---|---|---|---|
| AuthUserController | Controller | code/app/Http/Controllers/AuthUserController.php | Current user profile retrieval and update |
| UpdateAuthUserAction | Action | code/app/Actions/Users/UpdateAuthUserAction.php | Persists settings and display_name to user record |
| UpdateAuthUserRequest | Request | code/app/Http/Requests/UpdateAuthUserRequest.php | Validates settings array and enforces max:40 on display_name |
| Settings.vue | View | views/Settings.vue | Frontend settings interface |
Implementation Notes
REQ-USERSET-001 Coverage:
- AC-01 through AC-06: Implemented via
AuthUserController::update()which delegates toUpdateAuthUserAction - AC-07: Settings accessible via user profile endpoint
- AC-08: Display name max length enforced by
UpdateAuthUserRequestvalidation rule (max:40) - AC-09: Eastern Time timezone - Configuration-level, not code-enforced
- AC-10: Timezone application - Frontend applies stored timezone preference
REQ-USERSET-002 Gap:
Display name uniqueness validation is not implemented in the current codebase. The UpdateAuthUserRequest validates format (nullable|max:40) but does not include a unique:users,display_name rule. This represents a gap between requirements and implementation that should be addressed.
REQ-USERSET-NFR-001 Coverage:
Performance standards apply at the global infrastructure level (see sdd-architecture.md).
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-USERSET-001 | Manage User Display Preferences | Test | AuthUserController, UpdateAuthUserAction, UpdateAuthUserRequest | BT-605 | Draft |
| REQ-USERSET-002 | Validate Display Name Uniqueness | Test | Not implemented (see Implementation Notes) | BT-3856 | Draft |
| REQ-USERSET-NFR-001 | Performance Standards | Test | Global NFR standards apply | [Pending] | Draft |
Notes
- Notification preferences are managed separately; see Comment tagging documentation for related user notification settings
- Eastern Time (ET) timezone option is restricted to Super Admin users only
Open Questions
| ID | Question | Source | Owner | Date Raised |
|---|---|---|---|---|
| OQ-001 | Display name uniqueness validation not implemented - should this be added? | Implementation Review | @DEV-TBD | TBD |
Acceptance Tests
Test: REQ-USERSET-001
Test: Access settings from any context
Given: User is logged into the application
And: User is on any application screen
When: User requests to access settings
Then: The system shall display the settings configuration interface
Test: Select timezone
Given: User is viewing the settings configuration
When: User selects a timezone from available options
And: User confirms the selection
Then: The system shall persist the timezone preference
And: The system shall apply the selected timezone to all temporal data displays
Test: Select date format
Given: User is viewing the settings configuration
When: User selects a date format option
And: User confirms the selection
Then: The system shall apply the selected date format throughout the application
Test: Select time format
Given: User is viewing the settings configuration
When: User selects a time format option
And: User confirms the selection
Then: The system shall apply the selected time format throughout the application
Test: Set display name
Given: User is viewing the settings configuration
When: User enters a display name within the character limit
And: User confirms the selection
Then: The system shall persist the display name
And: The system shall display the name where user identification is shown
Test: Eastern Time timezone (Super Admin)
Given: User is authenticated with Super Admin role
When: User views timezone options
Then: Eastern Time (ET) option shall be available
When: User selects Eastern Time (ET) timezone
And: User confirms the selection
Then: The system shall apply Eastern Time to all temporal data displays
Test: REQ-USERSET-002
Test: Duplicate display name rejected
Given: A user exists with display name "Example One"
And: A different user is viewing the settings configuration
When: The user attempts to set display name to "Example One"
Then: The system shall display "Display Name has already taken"
And: The system shall prevent the preference submission
Test: Unique display name accepted
Given: No user has display name "Unique Name"
And: User is viewing the settings configuration
When: User sets display name to "Unique Name"
And: User confirms the selection
Then: The system shall accept and persist the display name
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| SDD Architecture | User Authentication, Session Management |
Appendix: Process Artifacts
Completion Checklist
- All requirements are capability-level (describe behavior, not UI)
- Requirement variants consolidated (no requirement explosion)
- UI details are fully demoted to Illustrative section
- Configuration options are not encoded as requirements
- Acceptance criteria describe behavior, not UI mechanics
- Every requirement has acceptance criteria and source traceability
- Error handling addressed for I/O, validation, and external system requirements
- Open questions documented with owners assigned
- Consolidations documented in Reviewer Notes with reversibility info
- Module can survive a full UI redesign unchanged
- Refinements folded into Acceptance Criteria
- Traceability matrix is complete
Reviewer Notes
Consolidation: REQ-USERSET-001
The following items from the source were consolidated into a single capability-level requirement:
| Original Item | Source Reference | Disposition |
|---|---|---|
| REQ-USERSET-001 (Access Settings) | 3.0.0-User Settings Row 1 | Merged -> REQ-USERSET-001 AC (Accessibility) |
| REQ-USERSET-002 (Configure preferences) | 3.0.0-User Settings Rows 2-6, 9-11 | Merged -> REQ-USERSET-001 Statement, ACs |
Rationale: The original REQ-USERSET-001 (access settings from any screen) described navigation to a capability, not a distinct system responsibility. It has been demoted to an acceptance criterion of the preference management requirement. The core functionality is the ability to configure and persist preferences, not the navigation mechanism.
Reversibility: To restore original structure, reference:
- Source:
output/pilot/restructured/user-settings.md - Confluence: 3.0.0-User Settings (Rows 1-11)
Preserved Requirements
| Original Item | Source Reference | Disposition |
|---|---|---|
| REQ-USERSET-003 (Display name validation) | 3.0.0-User Settings Row 8 | Preserved as REQ-USERSET-002 (renumbered) |
| NFR-USERSET-001 (Performance) | 3.0.0-User Settings NFR section | Preserved as REQ-USERSET-NFR-001 |
Rationale: Display name uniqueness validation is a distinct system responsibility with independent testability. It requires specific error handling and represents a data integrity constraint beyond simple preference storage.
AC Transformations
| Original (UI-Centric) | Transformed (Behavior-Centric) |
|---|---|
| "User can select a time zone from a dropdown list" | "The system shall allow users to select a timezone from available options" |
| "User can save changes using a Save button" | "The system shall persist user preference changes upon user confirmation" |
| "Clicking the settings icon opens the Settings page" | "The system shall provide access to preference configuration from any application context" |