feat(notification): carry the whole deep-link target on every notification

[aquie00t]

Closes findings 1-5 of the notification audit. Findings 6-7 (unread-count endpoint, per-notification read) follow in a second PR.

Problem

Tapping a notification could not reliably open what it was about.

1. No referenceId on two types. like-post.usecase.ts and like-comment.usecase.ts called Notification.create without a fourth argument, so the stored row had referenceId = null. The realtime event carried the right ids, the persisted notification did not — a link that worked live and broke once the user opened the list.
2. LIKE did not distinguish post from article. Both used the same type; the client could not tell what the uuid it received pointed at.
3. Comment notifications stored only the comment id. Opening a comment means opening the post or article it lives under, which the row did not know.
4. Articles are read by slug (GET /articles/:slug), but notifications only knew the article uuid, and no endpoint resolves one into the other.
5. The notification id was never mapped, so a single notification could not be addressed — no per-item read, no stable list key.

Change

Notification now stores postId / articleId / commentId alongside referenceId, and Notification.create takes a NotificationTarget instead of a bare reference:

Notification.create(recipientId, issuerId, NotificationType.COMMENT_LIKE, {
    commentId: comment.id,
    postId: comment.postId ?? undefined,
    articleId: comment.articleId ?? undefined,
});

referenceId is derived from that target — the comment, else the article, else the post — so it is populated consistently and every old client keeps working unchanged.

• Article slugs are resolved on read, not denormalised: the repository includes article: { select: { slug: true } }, so articleSlug is always current even after a title change.
• The target columns are real foreign keys with ON DELETE CASCADE. A notification can no longer outlive the content it points at, so a tap never lands on a 404. This also covers part of finding 8.
• The response exposes id, unblocking the per-notification read endpoint in the follow-up PR.
• The realtime payload gained articleSlug, so the live event and the REST row build the same URL.

Client rule after this change: commentId → open the post/article and scroll to the comment; articleId → /articles/{articleSlug}; postId → the post; none of them → the issuer's profile via username.

Migration

20260826233221_notification_deep_link_targets adds three nullable columns, their indexes and their cascading foreign keys. Existing rows keep their referenceId and get NULL targets — they render as before and simply are not deep-linkable.

Verification

• pnpm test:unit — 785 passed
• pnpm test:integration — 104 passed (new cases: post target round-trip, article slug resolution, cascade on target delete)
• pnpm test:e2e — 317 passed (new tests/e2e/notification/deep-links.test.ts drives a real post like, comment and comment like, then asserts the payload)
• tsc -p tsconfig.build.json --noEmit, pnpm lint, prettier — clean

The test database was reset with the user's explicit consent to apply and verify the migration.

Not in this PR

Findings 6-14 of the audit, notably: unread-count endpoint and per-notification read (6-7, next PR), notification cleanup on unlike/unfollow (8), realtime emit inside the transaction (9), one socket per user in WebSocketManager (11), and the wrong default-avatar.png fallback in the mapper (12).

🤖 Generated with Claude Code

https://claude.ai/code/session_01PwzkQ5YGFXSB9jWCZKzX4H

[github-actions]

🎉 This PR is included in version 1.8.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀