Comment Tagging
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: User mentions, notifications, and comment management within comments Domain: COMMENTS
Statement
The system shall enable users to mention other system users within comments using @ syntax, triggering notifications through configurable delivery channels (in-app and/or email).
Users can tag internal users by name or invite external reviewers by email. The notification system tracks read/unread status, provides navigation to referenced comments, and enforces role-based access control for mentionable users.
Behavior Overview (Illustrative)
This diagram illustrates the high-level behavior. It does not specify UI layout, styling, or interaction details.
Definitions
| Term | Definition |
|---|---|
| Tag | A reference to a user within a comment using @ syntax that triggers notification |
| Mention | Synonymous with tag; the act of referencing another user in a comment |
| In-app notification | A notification delivered within the application via the notification bell/pane |
| External reviewer | A person not registered in the system who is invited to review via email |
Functional Requirements
User Tagging (REQ-COMMENTS-001, REQ-COMMENTS-002)
FR-COMMENTS-001 Tag Internal Users in Comments
The system shall allow users to mention other system users by name within comments, triggering notifications per the tagged user's preferences.
Acceptance Criteria:
User Selection Interface:
- The system shall provide a user selection interface when @ symbol is entered in a comment field
- The system shall display all mentionable users matching typed characters
- The system shall filter the user selection list dynamically as characters are typed after @
Selection Methods:
- The system shall support keyboard navigation (up/down arrows) and selection (Enter key)
- The system shall support mouse selection of users
Notification:
- The system shall trigger notification delivery to the tagged user upon comment submission
Supported Locations:
- The system shall provide user tagging in: Manage Results (reason for selection), Edit Wells (reason for edit), Re-export (run level), Re-export (well level), Comment action, Assay Summary (Run Notes)
Trace: Source: 3.0.0-Comment tagging for other users (Rows 1-6) | Jira: BT-2319 (Epic), BT-2365 | Tests: BT-2668, BT-2669, BT-2670, BT-2634, BT-3321, BT-3347, BT-3361
FR-COMMENTS-002 Tag External Users by Email
The system shall allow users to invite external reviewers by email when the intended recipient is not a registered system user.
Acceptance Criteria:
Email Invitation:
- The system shall provide an option to send invitation by email from the user selection interface
- The system shall accept one email address per invitation
- The system shall send email notification upon user confirmation
Validation:
- The system shall validate email address format before allowing submission
Error Handling
- Invalid email format: The system shall disable submission until a valid email is entered
Trace: Source: 3.0.0-Comment tagging for other users (Rows 7-11) | Jira: BT-2365 | Tests: BT-2671
Notification Delivery (REQ-COMMENTS-003, REQ-COMMENTS-004)
FR-COMMENTS-003 Send Email Notifications for Tags
The system shall deliver email notifications to tagged users containing comment details and a direct link to the relevant content.
Acceptance Criteria:
Email Content:
- Email shall identify the requesting user in the subject line
- Email shall include run identifier
- Email shall include well identifier when comment is at well level
- Email shall include the comment text
- Email shall include a link that navigates directly to the comment location
Error Handling
- Email delivery failure: Log the failure (no retry, no user alert)
Trace: Source: 3.0.0-Comment tagging for other users (Rows 12-13) | Jira: BT-2365 | Tests: [Pending]
FR-COMMENTS-004 Configure Notification Preferences
The system shall allow users to configure their preferred notification delivery method for comment tags.
Acceptance Criteria:
Preference Options:
- The system shall support In-app notification preference
- The system shall support Email notification preference
- The system shall support combined (Both) notification preference
- Default preference shall be Both
Preference Enforcement:
- Tags sent via "send by email" shall always deliver email regardless of recipient preference
- Tags sent via name mention shall respect recipient's notification preference
Trace: Source: 3.0.0-Comment tagging for other users (Rows 14-17) | Jira: BT-2365 | Tests: BT-2672
Notification Display (REQ-COMMENTS-005, REQ-COMMENTS-006)
FR-COMMENTS-005 Display Notification Indicator
The system shall display a persistent indicator showing the count of unread notifications.
Acceptance Criteria:
Display Behavior:
- The system shall display unread notification count
- The indicator shall not be displayed when unread count is zero
Persistence:
- The count shall persist until notifications are explicitly marked as read
- The count shall update immediately when notifications are marked as read
Trace: Source: 3.0.0-Comment tagging for other users (Rows 18, 30, 32) | Jira: BT-2365 | Tests: [Pending]
FR-COMMENTS-006 Display Notifications List
The system shall provide access to view all notifications with summary information and navigation capability.
Acceptance Criteria:
Notification Details:
- Each notification shall display the requesting user's identity
- Each notification shall display the timestamp
- Each notification shall display run and well identifiers (when applicable)
- Each notification shall display a preview of the comment text
Access and Navigation:
- The system shall provide access to all notifications (not limited to recent)
- The system shall support pagination for large notification sets
- Each notification shall provide navigation to the source comment
Trace: Source: 3.0.0-Comment tagging for other users (Rows 19-24, 31) | Jira: BT-2365 | Tests: [Pending]
Notification Management (REQ-COMMENTS-007, REQ-COMMENTS-008)
FR-COMMENTS-007 Manage Notification Read Status
The system shall allow users to track and toggle the read/unread status of individual notifications.
Acceptance Criteria:
Automatic Status Change:
- Navigating to a notification's linked content shall mark it as read
Manual Status Management:
- Each notification shall display its current read/unread status
- Users shall be able to toggle notification status between read and unread
Trace: Source: 3.0.0-Comment tagging for other users (Rows 26-29) | Jira: BT-2365 | Tests: [Pending]
FR-COMMENTS-008 Mark All Notifications as Read
The system shall allow users to mark all notifications as read in a single action.
Acceptance Criteria:
- The action shall mark all current notifications as read
- The unread count shall update to zero after the action
Trace: Source: 3.0.0-Comment tagging for other users (Row 33) | Jira: BT-2742 | Tests: [Pending]
Navigation (REQ-COMMENTS-009)
FR-COMMENTS-009 Navigate to Tagged Comments
The system shall navigate users to the specific location of a tagged comment when selected from a notification.
Acceptance Criteria:
Navigation Behavior:
- Navigation shall position the referenced comment in the visible area
- The comments section shall be expanded/visible after navigation
- Navigation shall work for comments from all supported locations
Deleted Comments:
- Navigation to deleted comments shall show the deleted comment with deletion indicator
- Deleted comments shall remain visible with strikethrough formatting
Location-Specific Behavior:
- For Run Notes comments, navigation shall open the Assay Summary widget and position to the comment
- For run-level re-export, navigation shall open the Runfile Report page without positioning to a specific comment
Trace: Source: 3.0.0-Comment tagging for other users (Rows 34-37) | Jira: [Not specified] | Tests: [Pending]
Access Control (REQ-COMMENTS-010)
FR-COMMENTS-010 Filter Mentionable Users by Role
The system shall restrict the set of users available for mention based on the current user's role.
Acceptance Criteria:
Consistency:
- Role-based filtering shall be applied consistently across all tagging locations
Role Permissions:
- JUNIOR role shall be able to mention MANAGER, SENIOR, and JUNIOR users
- SENIOR role shall be able to mention MANAGER, SENIOR, and JUNIOR users
- MANAGER role shall be able to mention MANAGER, SENIOR, and JUNIOR users
- CLIENT_ADMIN role shall not be able to mention any users
- SUPER_ADMIN role shall be able to mention all user roles
Trace: Source: 3.0.0-Well Comment - Filter users by user type, 3.0.0-Run re-export reason - Filter users by user type, 3.0.0-Well re-export reason - Filter users by user type, 3.0.0-Assay summary - Filter users by user type, 3.0.0-Reason for edit - Filter users by user type, 3.0.0-Reason for selection - Filter users by user type | Jira: BT-4826 | Tests: [Pending]
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
default_notification_preference | Both | Default notification delivery method for new users | REQ-COMMENTS-004 |
comment_preview_length | 200 | Number of characters shown in notification comment preview | REQ-COMMENTS-006 |
Assumptions
- Users accessing comment functionality have at minimum Junior User role permissions
- Email delivery infrastructure is available and configured
- Users have valid email addresses associated with their accounts
- Comment fields are available in designated locations (Manage Results, Edit Wells, Re-export, Comment action, Assay Summary)
[REVIEW REQUIRED: Assumptions inferred from context, not explicitly stated in source. Confirm accuracy with SME.]
UI Notes (Illustrative)
FR-COMMENTS-001 UI Specifications
- @ symbol triggers dropdown menu display
- Dropdown shows user display names with email icon option at bottom
- Arrow key navigation supported within dropdown
FR-COMMENTS-002 UI Specifications
- Email dialog title: "Email teammate to review"
- Dialog subtitle explains recipient will receive email with link to comment
- Input field labeled "Add one teammate"
- "Add teammate" button disabled until valid email entered
- Dialog closes on Cancel, clicking outside, or successful submission
FR-COMMENTS-003 UI Specifications
- Email subject format: "Review request by {Username requesting} in pcr.ai"
FR-COMMENTS-004 UI Specifications
- Settings page contains "Notifications" section
- Three radio button options: In-app, Email, Both
FR-COMMENTS-005 UI Specifications
- Bell icon positioned in header between user's name and settings icon
- Red circle badge shows unread count
- Badge hidden when count is zero
FR-COMMENTS-006 UI Specifications
- Pane appears as overlay above current screen
- Each notification row displays: link, username + timestamp (top line), run/well info (second line), comment preview in grey text box
- Comment preview truncated with "..." if exceeds 2 lines
- Auto-pagination on scroll to bottom
- Clicking outside pane closes it
- Row hover: grey highlight
- Text box hover within row: darker grey highlight
FR-COMMENTS-007 UI Specifications
- Circular status indicator on each notification
- Color indicates read/unread state (e.g., blue for unread)
- Tooltip on hover shows available action ("Mark as Read" or "Mark as Unread")
FR-COMMENTS-009 UI Specifications
- "Click to jump" button/link on notification rows
Implementation (Illustrative)
| Component | Type | Path | Requirements |
|---|---|---|---|
| Comment | Model | code/app/Comment.php | REQ-COMMENTS-001, REQ-COMMENTS-002, REQ-COMMENTS-009 |
| CommentCollection | Collection | code/app/CommentCollection.php | REQ-COMMENTS-009 |
| Notification | Model | code/app/Notification.php | REQ-COMMENTS-005, REQ-COMMENTS-006, REQ-COMMENTS-007, REQ-COMMENTS-008 |
| NotificationBuilder | QueryBuilder | code/app/QueryBuilders/NotificationBuilder.php | REQ-COMMENTS-005, REQ-COMMENTS-006, REQ-COMMENTS-007 |
| CommentsController | Controller | code/app/Http/Controllers/CommentsController.php | REQ-COMMENTS-001, REQ-COMMENTS-002, REQ-COMMENTS-003 |
| RunCommentsController | Controller | code/app/Http/Controllers/RunCommentsController.php | REQ-COMMENTS-001, REQ-COMMENTS-003, REQ-COMMENTS-009 |
| WellCommentsController | Controller | code/app/Http/Controllers/WellCommentsController.php | REQ-COMMENTS-001, REQ-COMMENTS-003, REQ-COMMENTS-009 |
| NotificationsController | Controller | code/app/Http/Controllers/NotificationsController.php | REQ-COMMENTS-007, REQ-COMMENTS-008 |
| PaginateNotificationsController | Controller | code/app/Http/Controllers/Notifications/PaginateNotificationsController.php | REQ-COMMENTS-006 |
| ReadNotificationsController | Controller | code/app/Http/Controllers/Notifications/ReadNotificationsController.php | REQ-COMMENTS-007 |
| UnreadNotificationsCountController | Controller | code/app/Http/Controllers/Notifications/UnreadNotificationsCountController.php | REQ-COMMENTS-005 |
| StoreWellCommentsAction | Action | code/app/Actions/Comments/StoreWellCommentsAction.php | REQ-COMMENTS-001, REQ-COMMENTS-003 |
| NotifyMentionedUsers | Trait | code/app/Actions/Notifications/NotifyMentionedUsers.php | REQ-COMMENTS-001, REQ-COMMENTS-003, REQ-COMMENTS-004 |
| NotifyNonExistingMentionedEmails | Trait | code/app/Actions/Notifications/NotifyNonExistingMentionedEmails.php | REQ-COMMENTS-002 |
| NotifyWellCommentMentionedUsersAction | Action | code/app/Actions/Notifications/NotifyWellCommentMentionedUsersAction.php | REQ-COMMENTS-001, REQ-COMMENTS-002, REQ-COMMENTS-003 |
| NotifyRunCommentMentionedUsersAction | Action | code/app/Actions/Notifications/NotifyRunCommentMentionedUsersAction.php | REQ-COMMENTS-001, REQ-COMMENTS-002, REQ-COMMENTS-003 |
| NotifyManageResultsMentionedUsersAction | Action | code/app/Actions/Notifications/NotifyManageResultsMentionedUsersAction.php | REQ-COMMENTS-001, REQ-COMMENTS-003 |
| GetUnreadNotificationsCountAction | Action | code/app/Actions/Notifications/GetUnreadNotificationsCountAction.php | REQ-COMMENTS-005 |
| GetPaginateNotificationsAction | Action | code/app/Actions/Notifications/GetPaginateNotificationsAction.php | REQ-COMMENTS-006 |
| MarkNotificationAsReadAction | Action | code/app/Actions/Notifications/MarkNotificationAsReadAction.php | REQ-COMMENTS-007 |
| MarkNotificationAsUnreadAction | Action | code/app/Actions/Notifications/MarkNotificationAsUnreadAction.php | REQ-COMMENTS-007 |
| UserHasNotified | Notification | code/app/Notifications/UserHasNotified.php | REQ-COMMENTS-001, REQ-COMMENTS-003, REQ-COMMENTS-004, REQ-COMMENTS-009 |
| UserHasNotifiedMail | code/app/Mail/UserHasNotifiedMail.php | REQ-COMMENTS-003 | |
| NotificationRead | Event | code/app/Events/NotificationRead.php | REQ-COMMENTS-007 |
Frontend Implementation (Illustrative)
| Component Type | Location |
|---|---|
| View | views/RunView.vue |
| Components | components/ (MentionableTextbox usage cross-cutting) |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-COMMENTS-001 | Tag Internal Users in Comments | Test | Comment, CommentsController, RunCommentsController, WellCommentsController, NotifyMentionedUsers, NotifyWellCommentMentionedUsersAction, NotifyRunCommentMentionedUsersAction, UserHasNotified | BT-2668, BT-2669, BT-2670, BT-2634, BT-3321, BT-3347, BT-3361 | Draft |
| REQ-COMMENTS-002 | Tag External Users by Email | Test | CommentsController, NotifyNonExistingMentionedEmails, NotifyWellCommentMentionedUsersAction, NotifyRunCommentMentionedUsersAction | BT-2671 | Draft |
| REQ-COMMENTS-003 | Send Email Notifications for Tags | Test | NotifyMentionedUsers, NotifyNonExistingMentionedEmails, UserHasNotifiedMail, UserHasNotified | [Pending] | Draft |
| REQ-COMMENTS-004 | Configure Notification Preferences | Test | User.notificationMethods(), NotifyMentionedUsers, UserHasNotified | BT-2672 | Draft |
| REQ-COMMENTS-005 | Display Notification Indicator | Test | Notification, NotificationBuilder, UnreadNotificationsCountController, GetUnreadNotificationsCountAction | [Pending] | Draft |
| REQ-COMMENTS-006 | Display Notifications List | Test | Notification, NotificationBuilder, PaginateNotificationsController, GetPaginateNotificationsAction | [Pending] | Draft |
| REQ-COMMENTS-007 | Manage Notification Read Status | Test | Notification, NotificationsController, ReadNotificationsController, MarkNotificationAsReadAction, MarkNotificationAsUnreadAction, NotificationRead | [Pending] | Draft |
| REQ-COMMENTS-008 | Mark All Notifications as Read | Test | NotificationsController | [Pending] | Draft |
| REQ-COMMENTS-009 | Navigate to Tagged Comments | Test | Comment, CommentCollection, UserHasNotified (URL generation) | [Pending] | Draft |
| REQ-COMMENTS-010 | Filter Mentionable Users by Role | Test | Frontend implementation (MentionableTextbox.vue) | [Pending] | Draft |
Notes
- Notification counter behavior differs from Confluence: counter persists until notifications are marked as read (Confluence removes counter on modal close)
- Does not include Confluence-style "Direct, Watching" functionality
Open Questions
| ID | Question | Source | Owner | Date Raised | Resolution |
|---|---|---|---|---|---|
| OQ-01 | Error handling for email delivery failure not specified | REQ-COMMENTS-003 | - | - | Resolved: Log the failure (no retry, no user alert) |
| OQ-02 | Comment preview length configuration value not specified | REQ-COMMENTS-006 | - | - | Resolved: 200 characters |
Acceptance Tests
Test: REQ-COMMENTS-001
Test: Trigger user selection interface
Given: User is in a comment field (any supported location)
When: User types '@'
Then: A user selection interface shall appear showing mentionable user display names
And: An option to send by email shall be available
Test: Filter user list
Given: User selection interface is open
When: User types characters after '@'
Then: List shall filter to show only names starting with typed characters
Test: Select user via keyboard
Given: User selection interface is open with users listed
When: User navigates with arrow keys and presses Enter
Then: Selected user shall be tagged in the comment
Test: Select user via mouse
Given: User selection interface is open with users listed
When: User clicks on a name in the list
Then: Selected user shall be tagged in the comment
Test: REQ-COMMENTS-002
Test: Open email invitation interface
Given: User selection interface is open
When: User selects "send by email" option
Then: Email invitation interface shall open
And: Submission shall be disabled
Test: Validate email format
Given: Email invitation interface is open
When: User enters invalid email format
Then: Submission shall remain disabled
When: User enters valid email format
Then: Submission shall become enabled
Test: Send email invitation
Given: Valid email entered and submission enabled
When: User confirms submission
Then: Email shall be sent to the address
And: Interface shall close
Test: REQ-COMMENTS-003
Test: Verify email content
Given: User tags another user who has email notifications enabled
When: Email notification is sent
Then: Subject shall identify the requesting user
And: Body shall contain run identifier
And: Body shall contain well identifier (if applicable)
And: Body shall contain comment text
And: Body shall contain link to comment location
Test: REQ-COMMENTS-004
Test: View preference options
Given: User navigates to Settings
When: User views Notifications section
Then: Three options shall be available: In-app, Email, Both
And: "Both" shall be selected by default
Test: In-app only preference
Given: User A has notification preference set to "In-app"
When: User B tags User A by name
Then: User A shall receive in-app notification
And: User A shall not receive email notification
Test: Email only preference
Given: User A has notification preference set to "Email"
When: User B tags User A by name
Then: User A shall receive email notification
And: User A shall not receive in-app notification
Test: REQ-COMMENTS-005
Test: Indicator visibility
Given: User has unread notifications
When: User views the application
Then: Notification indicator shall be visible
And: Indicator shall show count of unread notifications
Test: Indicator updates
Given: User has 5 unread notifications
When: User marks 2 as read
Then: Indicator shall show 3
Test: Indicator hidden when zero
Given: User has no unread notifications
When: User views the application
Then: Notification indicator shall not be displayed
Test: REQ-COMMENTS-006
Test: View notifications
Given: User is on any page
When: User accesses notifications
Then: Notification list shall appear
And: Each notification shall show: requesting user, timestamp, run/well info, comment preview
Test: Pagination
Given: User has more notifications than fit in one view
When: User scrolls to bottom
Then: Additional notifications shall be loaded
Test: REQ-COMMENTS-007
Test: Navigation marks as read
Given: Notification is unread
When: User navigates to the notification's linked content
Then: Notification shall be marked as read
Test: Toggle read status
Given: Notification is unread
When: User toggles the notification status
Then: Notification shall be marked as read
Given: Notification is read
When: User toggles the notification status
Then: Notification shall be marked as unread
Test: REQ-COMMENTS-008
Test: Mark all
Given: User has 5 unread notifications
When: User invokes mark all as read
Then: All notifications shall be marked as read
And: Unread count shall be zero
Test: REQ-COMMENTS-009
Test: Navigate to well comment
Given: Notification references a comment on a well
When: User navigates from the notification
Then: System shall position the referenced comment in view
And: Comments section shall be visible/expanded
Test: Navigate to deleted comment
Given: Notification references a comment that was deleted
When: User navigates from the notification
Then: System shall position the deleted comment in view
And: Deleted comment shall be visible with deletion indicator
Test: Navigate to Run Notes comment
Given: Notification references a comment in Assay Summary Run Notes
When: User navigates from the notification
Then: Assay Summary shall be open
And: Run Notes section shall be visible
And: Specific comment shall be positioned in view
Test: REQ-COMMENTS-010
Test: SUPER_ADMIN mentions
Given: User logged in as SUPER_ADMIN
When: User accesses user selection for mentions
Then: All user roles shall be available (SUPER_ADMIN, CLIENT_ADMIN, MANAGER, SENIOR, JUNIOR)
Test: JUNIOR mentions
Given: User logged in as JUNIOR
When: User accesses user selection for mentions
Then: Only MANAGER, SENIOR, and JUNIOR users shall be available
And: SUPER_ADMIN and CLIENT_ADMIN shall not be available
Test: CLIENT_ADMIN mentions
Given: User logged in as CLIENT_ADMIN
When: User accesses user selection for mentions
Then: No users shall be available for mention
Test: Filter consistency across locations
Given: User logged in as SENIOR
When: User accesses mentions in Well Comment
Then: MANAGER, SENIOR, JUNIOR users shall be available
When: User accesses mentions in Manage Results reason
Then: Same users (MANAGER, SENIOR, JUNIOR) shall be available
When: User accesses mentions in Edit Wells reason
Then: Same users (MANAGER, SENIOR, JUNIOR) shall be available
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| SDD Architecture | Email Integration, Notification Services |
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 incorporated into acceptance criteria
- Traceability matrix is complete
Reviewer Notes
Conversion Notes
This conversion preserves the original 10 requirements as distinct capabilities. No consolidation was performed because each requirement represents a genuinely separate system capability:
| Original ID | Assessment | Disposition |
|---|---|---|
| REQ-COMMENTS-001 | Distinct: User mention by name | Preserved as FR-COMMENTS-001 |
| REQ-COMMENTS-002 | Distinct: External user invitation | Preserved as FR-COMMENTS-002 |
| REQ-COMMENTS-003 | Distinct: Email notification delivery | Preserved as FR-COMMENTS-003 |
| REQ-COMMENTS-004 | Distinct: Preference configuration | Preserved as FR-COMMENTS-004 |
| REQ-COMMENTS-005 | Distinct: Notification indicator | Preserved as FR-COMMENTS-005 |
| REQ-COMMENTS-006 | Distinct: Notification list display | Preserved as FR-COMMENTS-006 |
| REQ-COMMENTS-007 | Distinct: Individual read status | Preserved as FR-COMMENTS-007 |
| REQ-COMMENTS-008 | Distinct: Bulk read status | Preserved as FR-COMMENTS-008 |
| REQ-COMMENTS-009 | Distinct: Comment navigation | Preserved as FR-COMMENTS-009 |
| REQ-COMMENTS-010 | Distinct: Role-based access control | Preserved as FR-COMMENTS-010 |
Rationale: These requirements do not exhibit the "requirement explosion" pattern. They represent genuinely different user actions and system capabilities rather than variants of a single capability.
AC Transformations
UI-centric acceptance criteria were transformed to behavior-centric:
| Original | Transformed |
|---|---|
| "Dropdown menu appears" | "User selection interface is provided" |
| "Clicking bell icon opens pane" | "Provide access to view all notifications" |
| "Circle changes color" | "Display current read/unread status" |
| "Scrolls to specific comment" | "Position referenced comment in visible area" |
Reversibility: To review original structure, reference:
- Source:
output/pilot/restructured/comments.md - Confluence: 3.0.0-Comment tagging for other users