Plan: User Notifications¶
Overview¶
Status: Approved Author: nguyenhuuca Date: 2026-10-02 Related PRD: PRD-user-notifications Related ADR: ADR-0017 User Notifications (accepted)
Objective¶
Implement ADR-0017: notifications table, Spring events after commit, owner-only REST API, SSE stream (header auth, in-memory publisher), FE bell with real-time badge + polling fallback, deep link to comment, email digest within the email budget, retention job.
Verified Facts (exploration 2026-10-02)¶
| Area | Fact | Impact on plan |
|---|---|---|
| Async | @EnableAsync + @EnableScheduling on FunnyApp; no custom executor; spring.threads.virtual.enabled=true |
Verify applicationTaskExecutor is virtual-thread based (Boot ≥ 3.2 does this); otherwise add one @Bean |
| Events | No ApplicationEventPublisher / @EventListener anywhere |
First event-driven code — keep it small and documented |
| Scheduler | jobs/AppScheduler uses @Scheduled cron/fixedRate, try/catch per job, no ShedLock (single instance) |
Add digest + retention jobs in the same style |
MailService (sendSimpleMail, @Async sendInvitation), EmailCacheLimiterImpl daily counter, app.email-setting.max-daily-emails: 200 |
Digest must check/increment the same limiter and use ≤ 50% of the budget | |
| Users | UserRepo.findAllByUserName(email) returns User (status ACTIVE/DEACTIVATED); UserSettingsRepository has no finder by user |
Add findByUserId |
| JWT | JwtProvider.verifyToken checks exp but does not expose it; TTL 30 days; filter writes 401 JSON |
Stream does not close on expiry; emitter timeout 30 min forces re-auth on reconnect |
| CORS | origins *.canh-labs.com, localhost:*; all headers allowed |
fetch with Authorization to the stream works cross-origin |
| Metrics | Micrometer + /actuator/prometheus; no custom meters yet |
First custom gauge |
| FE header | AppShell.jsx right section: search, login/profile/logout, theme toggle |
Bell goes before the theme toggle (logged-in only), also in mobile header |
| FE auth | AuthContext exposes jwt, isLoggedIn, logout; client.js exports getBaseUrl-style base + createHeaders() |
Reuse for the stream fetch |
| FE queries | retry: 1, refetchOnWindowFocus: false globally |
Unread-count query overrides refetchOnWindowFocus: true |
| Deep link | AppShell reads ?v={id} on mount → jumpIndex; comment panel opened via onShowComments(video) |
Extend to ?v={id}&c={commentId} → open panel + highlight |
| FE tests | Only window.matchMedia mocked; client.test.js mocks fetch |
Stream tests need a ReadableStream helper |
Implementation Steps¶
Phase 1 — Data layer (0.5 d) — NT-1¶
- [ ] Migration
api/src/main/resources/db/changelog/sql/202610030001-create-notifications.sql(schema from ADR-0017: table,idx_notifications_user_unread, partial uniqueuq_notifications_unread_group,idx_notifications_digest) - [ ]
enums/NotificationType(COMMENT_REPLY,COMMENT_REMOVED) - [ ]
entity/Notification(payloadas@JdbcTypeCode(SqlTypes.JSON) Map<String,Object>) - [ ]
repo/NotificationRepositoryPage<Notification> findByUserIdOrderByUpdatedAtDesc(Long, Pageable)long countByUserIdAndReadAtIsNull(Long)Optional<Notification> findByIdAndUserId(UUID, Long)(owner-scoped)@Modifying int markAllRead(Long userId, Instant now)- native
upsertGrouped(...)—INSERT … ON CONFLICT (user_id, group_key) WHERE read_at IS NULL DO UPDATE SET actor_count = notifications.actor_count + 1, actor_display = EXCLUDED.actor_display, payload = EXCLUDED.payload, comment_id = EXCLUDED.comment_id, updated_at = now(), emailed_at = NULL @Modifying int deleteReadOlderThan(Instant)
- [ ]
UserSettingsRepository.findByUserId(Long)
AC: migration applies; repo methods covered by unit tests (Mockito) — native SQL reviewed manually.
Phase 2 — Producers (1 d) — NT-2 (after NT-1)¶
- [ ] Events (records):
CommentRepliedEvent(videoId, rootId, parentId, commentId, actorEmail, snippet),CommentRemovedEvent(List<RemovedComment(commentId, videoId, authorEmail)>, reason) - [ ] Publish from
VideoCommentServiceImpl.createComment(only whenparentIdpresent; capture original parent before root normalization) andAdminCommentServiceImpl.moderate/bulkModerate(only comments that actually changed to REMOVED) - [ ]
NotificationEventListener—@TransactionalEventListener(AFTER_COMMIT)+@Async- Reply recipients = {root author, original-parent author} − actor − guests (
userIdblank) − unknown/deactivated users group_key = "REPLY:" + rootId;REMOVED:+ commentIdactor_display= email local part; snippet ≤ 140 chars, whitespace-collapsed- After write →
NotificationPublisher.unreadChanged(userId) - All exceptions caught and logged (never propagate)
- Reply recipients = {root author, original-parent author} − actor − guests (
- [ ] Verify async executor uses virtual threads (log
Thread.currentThread().isVirtual()in a test or add@Bean(name = "applicationTaskExecutor")withExecutors.newVirtualThreadPerTaskExecutor()) - [ ] Tests: recipients (actor excluded, guest excluded, same person root+parent → one row), grouping calls upsert with same key, removed event per changed comment only, listener swallows errors, nothing published when reply validation fails
AC: posting a reply/moderating never fails because of notifications; correct recipients.
Phase 3 — REST API (0.5 d) — NT-3 (after NT-1)¶
- [ ]
dto/notification/NotificationDto(fields per ADR),UnreadCountDto - [ ]
service/NotificationService+ impl (list,unreadCount,markRead,markAllRead) — current user fromAppUtils.getCurrentUser();markRead/markAllRead→publisher.unreadChanged - [ ]
web/NotificationControlleratBASE_URL + "/notifications"— authenticated route (not inALLOW_ALL_METHOD/OPTIONAL_AUTH_PATH) - [ ] Tests:
@WebMvcTest401 without JWT; another user's id → 404; paging; read-all
Phase 4 — SSE (1 d) — NT-4 (after NT-3)¶
- [ ]
service/notification/NotificationPublisherinterface;InMemorySsePublisher(ConcurrentHashMap<Long, CopyOnWriteArrayList<SseEmitter>>, nosynchronized)register(userId): newSseEmitter(30 min); cap 5 per user (complete oldest); remove on completion/timeout/errorunreadChanged(userId): compute count once, sendevent: unreaddata: {"unread": n}to each emitter; drop failed emitters- Heartbeat
@Scheduled(fixedRate = 25 s): send commentpingto all emitters - Gauge
notifications_sse_active_connections
- [ ]
GET /notifications/stream(produces = text/event-stream), headersCache-Control: no-cache,X-Accel-Buffering: no; sends current unread on connect - [ ] Tests: register/send/remove-on-error, cap 5, heartbeat, gauge value, controller returns 401 without header (via real
JWTAuthenticationFilter, likeVideoReactionControllerTest)
AC: curl -N -H "Authorization: <jwt>" …/notifications/stream prints event: unread then pings; reply from another account pushes a new count within 3 s.
Phase 5 — Email digest & retention (0.5 d) — NT-5 (after NT-1)¶
- [ ]
AppScheduler.notificationDigest@Scheduled(cron = "0 */15 * * * *"): users withnotify_emailand unreademailed_at IS NULL→ one plain-text email each (list ≤ 5 items + "và N thông báo khác", link to app, footer "Tắt email trong Cài đặt") → setemailed_at - [ ] Budget: before each email check
EmailCacheLimiterdaily count< max-daily-emails * 0.5; stop the run otherwise; increment after send - [ ]
AppScheduler.notificationRetentiondaily 03:30 Asia/Ho_Chi_Minh →deleteReadOlderThan(now − 90 d) - [ ] Tests: opted-out user skipped, budget stop,
emailed_atset, retention cutoff
Phase 6 — Frontend (1.5 d) — NT-6 (contract-first; integrate after NT-3/NT-4)¶
- [ ]
src/api/notifications.js:list(page),unreadCount(),markRead(id),markAllRead() - [ ]
src/api/sseStream.js:openStream({ path, headers, onEvent, signal })—fetch+TextDecoderStream, buffer split on blank line, parseevent:/data:, ignore:comments; returns on end; throws{status}on non-2xx - [ ]
src/hooks/useNotifications.jsuseUnreadCount()— key['notifications','unread'],refetchOnWindowFocus: true,refetchInterval30 s when stream down / 120 s when upuseNotificationList(page),useMarkRead(),useMarkAllRead()(optimistic badge decrement)useNotificationStream()— mounted once inAppShellwhen logged in;AbortControlleron logout/unmount; backoff 1 s → 30 s + 1–5 s jitter; stop on 401; onunread→setQueryData+ invalidate list
- [ ]
components/notifications/NotificationBell.jsx(badge, 9+ cap,aria-label),NotificationDropdown.jsx(latest 10, empty state, mark all, Esc/outside click closes), item text per type:COMMENT_REPLY: "bob đã trả lời bình luận của bạn" / "bob và N người khác đã trả lời…" + snippetCOMMENT_REMOVED: "Bình luận của bạn đã bị gỡ: {reason label}"
- [ ] Deep link: item click →
markRead→ navigate?v={videoId}&c={commentId};AppShellreadsc→ opensCommentPanel→ scroll to + highlight comment (data-comment-id), expand its thread - [ ] Styles in
styles/index.css(.notif-bell,.notif-badge,.notif-dropdown,.notif-item.unread,.comment-highlight) - [ ] Tests: SSE parser (event split across chunks, multiple events in one chunk, comments ignored), stream hook reconnect + stop on 401 (fake timers), bell badge from stream event, dropdown render + mark all, deep link opens panel and highlights
- [ ]
npm run lint && npx vitest run && npm run build
Phase 7 — Ops & verification (0.5 d) — NT-7¶
- [ ] (Optional) nginx stream location with
proxy_read_timeout 1h(ADR-0017 Operations) — manual on VM, only with owner approval - [ ] Prod E2E with two accounts: B replies to A → A's badge updates < 3 s without reload; click → opens comment; mark all; admin removes A's comment → A notified with reason; restart backend (deploy) → stream reconnects; digest email received only when
notify_emailon - [ ] Check
/actuator/prometheusgauge; updatedocs/tracking.md
Dependency Graph¶
Suggested swarm: Builder A NT-1 → NT-2 → NT-5; Builder B NT-3 → NT-4 (after NT-1 lands); Builder C NT-6 in parallel. In practice NT-1..NT-5 share packages → one BE builder sequentially + one FE builder is safer.
Estimate: ≈ 5.5 days (≈ 3 days on the critical path with BE/FE in parallel).
Risks¶
| Risk | Mitigation |
|---|---|
@Async not on virtual threads → platform pool saturation |
NT-2 verification step / explicit executor bean |
| Event published inside a rolled-back tx | AFTER_COMMIT phase only |
| SSE parser bugs (chunk boundaries) | Dedicated unit tests with split chunks |
| Email budget shared with magic links | 50% cap + stop run |
| Native upsert with partial unique index syntax | Manual review + prod E2E; ON CONFLICT (user_id, group_key) WHERE read_at IS NULL must match the index predicate exactly |