F 13 Notifications

Status: 🟢 ready to test Owner: Adilet Last updated: 2026-05-08 Last verified on production: —

Goal

Every user has an in-app bell that surfaces unread notifications, links each to the source resource (issue / cycle), and supports "mark all read". The bell fires for 11 distinct event types across the QA platform.

Actors

• Primary — Any signed-in user
• Secondary — Whatever upstream system fired the event (triage, payouts, run-batch, comment thread, role assignment)

Preconditions

• The user is signed in.
• An upstream event has fired that should notify this user (e.g. an admin triaged their issue, they were added to a cycle, etc.)

Trigger

The user clicks the bell icon in the sidebar.

Notification event types

Happy path — read + mark read

Notification creation pattern

Every upstream API handler calls createNotification(...) or createNotificationsBulk(...) from src/lib/notifications.ts after the primary write succeeds. Failures are swallowed and logged — a notification table outage cannot block the primary action.

Self-notify is suppressed: actions an actor takes on their own resources do not generate a row addressed to themselves.

The bulk helper deduplicates by (user_id, type, issue_id, cycle_id) so the same person never gets two copies of one event (e.g. an admin who is also a cycle lead).

Acceptance criteria

• AC-1 — Given a tester files an issue, when the POST returns, then leads + admins of the cycle (excluding the reporter) each have a new notifications row with type='issue_filed', cycle_id + issue_id set.
• AC-2 — Given the reporter replies on an info_requested issue, then leads + admins are notified via issue_info_provided, and the reporter is not in the audience list.
• AC-3 — Given the user opens the bell dropdown, when there are 0 unread, then the bell badge is hidden.
• AC-4 — Given a user has 5 unread notifications, when they click "Mark all read", then all 5 rows have read_at set and the badge disappears.
• AC-5 — Given a notification has cycle_id + issue_id, when the user clicks the row, then they navigate to /app/test-cycles/:cycleId/issues/:issueId.
• AC-6 — Given the upstream notification insert fails (DB error), when the primary action succeeded, then the user still sees the primary success path; the failure is console.warn'd.
• AC-7 — Given an admin runs a period batch and pays 10 issues from 3 testers, then exactly 10 issue_paid rows are inserted, distributed across the 3 reporters; no admin gets a row for issues they paid themselves.

Test data / fixtures

• Baseline seed
• Two users: an admin and a tester member of an active cycle

Negative paths

Manual QA checklist

• As tester, file an issue (F-08)
• As admin, sign in → bell badge shows "1"; dropdown shows "Issue filed"
• Click the row → navigate to issue detail
• Refresh bell → that row is now "read" (not bold)
• As admin, approve the issue → reporter's bell badge shows "1"
• As reporter, click "Issue approved" notification → land on issue detail
• As admin, run a period batch (F-11)
• As reporter, bell shows "Paid: " with method + reference body
• In bell dropdown, click "Mark all read" → badge clears, all rows greyed
• Verify notifications table: read_at populated for all the user's rows

Automated test outline

test.describe("F-13 notifications", () => {
  test("issue.filed → leads+admins notified, not reporter", async ({ request }) => { … });
  test("self-notify suppressed", async ({ request }) => { … });
  test("dedup across multi-role users", async ({ request }) => { … });
  test("mark-all-read clears badge", async ({ page }) => { … });
  test("graceful insert failure", async ({ request }) => { /* simulate DB issue */ });
});

Code references

• UI: sidebar bell button + dropdown (find via useNotifications hook usage; lives in the QA section sidebar)
• API:
  • src/app/api/me/notifications/route.ts (GET list, POST/DELETE bulk?)
  • src/app/api/me/notifications/[id]/route.ts (PATCH read)
  • src/app/api/me/notifications/mark-all-read/route.ts
• Hooks: src/hooks/test-cycles/notifications.ts
• Lib: src/lib/notifications.ts (createNotification, createNotificationsBulk, leadAndAdminAudience, cycleMemberAudience)
• Schema: notifications, NOTIFICATION_TYPES

Events emitted (proposed)

• notification.created — fired implicitly inside each upstream flow (via the createNotification(s)* helpers). Telemetry can hook the helper itself once we wire a track().
• notification.viewed — { user_id, unread_count } (when dropdown opens)
• notification.opened — { user_id, notification_id, type } (when row clicked)
• notification.mark_all_read — { user_id, marked_count }

Open questions / known gaps

• No real-time push (no WebSocket / SSE) — bell refreshes on tab focus / poll. Verify the polling interval; if 0, only refreshes on navigation.
• No email delivery (deferred — feature-matrix.md §3.7).
• No Telegram delivery (deferred).
• issue_awaiting_verification exists in the enum but isn't wired — could fire when an issue is approved + gate active so the reporter knows their bug is queued for fix re-test.