brief sprint C2: introduce billboard.Brief notification model + view_post marks-read on GET — TDD

Brief is the slide-down-banner record that connects an event (a Line freshly appended to a Post) to a user who needs to see it. It's the C3 attachment point for note-unlock + share-invite + future event sources; the banner JS (C3) reads the Brief shape to render kind-specific affordances. C2 lays the schema + the FYI-read contract; C3 hooks the senders.

Schema (billboard.Brief):
- owner FK→lyric.User (related_name='briefs') — required; whose attention this is for
- post  FK→billboard.Post (related_name='briefs') — required; where FYI navigates
- line  FK→billboard.Line (related_name='briefs', null=True) — the appended Line that triggered the Brief; nullable for share-invite-style flows where the Line write races behind the Brief
- is_unread BooleanField default=True — flips on view_post GET
- kind CharField (note_unlock | user_post | share_invite, default=user_post) — drives banner-side affordances
- title CharField (blank=True) — banner display title
- created_at DateTimeField (default=timezone.now) — Meta.ordering='-created_at'

view_post (the post-detail GET) now bulk-updates is_unread=False on every Brief where owner == request.user AND post == our_post AND is_unread=True. POST (the compose-a-new-Line path) intentionally does NOT mark read — the user is authoring, not reviewing.

Tests: BriefModelTest (7) covers defaults, kind choices include all three values, line nullability, owner+post requiredness, title field, __str__ shape. ViewPostMarksReadTest (5) covers the GET flips owner's unread Brief to read; doesn't flip other users' Briefs on the same post; doesn't flip Briefs on unrelated posts; idempotent for already-read; POST request does NOT mark read.

Auto migration billboard/0002_brief creates the table. 801-test IT regression green (789 + 12 new).

Code architected by Disco DeDisco <discodedisco@outlook.com>
Git commit message Co-Authored-By:
Claude Sonnet 4.6 <noreply@anthropic.com>

src/apps/billboard/migrations/0002_brief.py

@@ -0,0 +1,34 @@
+# Generated by Django 6.0 on 2026-05-08 21:34
+
+import django.db.models.deletion
+import django.utils.timezone
+import uuid
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('billboard', '0001_initial'),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='Brief',
+            fields=[
+                ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+                ('is_unread', models.BooleanField(default=True)),
+                ('kind', models.CharField(choices=[('note_unlock', 'Note unlock'), ('user_post', 'User post'), ('share_invite', 'Share invite')], default='user_post', max_length=32)),
+                ('title', models.CharField(blank=True, max_length=255)),
+                ('created_at', models.DateTimeField(default=django.utils.timezone.now)),
+                ('line', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.CASCADE, related_name='briefs', to='billboard.line')),
+                ('owner', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='briefs', to=settings.AUTH_USER_MODEL)),
+                ('post', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='briefs', to='billboard.post')),
+            ],
+            options={
+                'ordering': ['-created_at'],
+            },
+        ),
+    ]

src/apps/billboard/models.py

@@ -2,6 +2,7 @@ import uuid
 
 from django.db import models
 from django.urls import reverse
+from django.utils import timezone
 
 
 class Post(models.Model):
@@ -38,3 +39,64 @@ class Line(models.Model):
 
     def __str__(self):
         return self.text
+
+
+class Brief(models.Model):
+    """A slide-down notification record. Owner = whose attention; post = where
+    FYI navigates (and where mark-read happens on GET); line = the specific
+    appended Line that triggered it (so the banner can surface its text).
+
+    `kind` discriminates the affordances the banner renders. NOTE_UNLOCK
+    Briefs get a clickable square that jumps direct to my_notes.html;
+    SHARE_INVITE Briefs render the invitation copy; USER_POST is the legacy
+    user-authored compose flow.
+
+    Magic-link confirmation + invalid-link banners use the same Gaussian-glass
+    visual styling but ride no Brief row (transient one-shot).
+    """
+    KIND_NOTE_UNLOCK   = "note_unlock"
+    KIND_USER_POST     = "user_post"
+    KIND_SHARE_INVITE  = "share_invite"
+    KIND_CHOICES = [
+        (KIND_NOTE_UNLOCK,  "Note unlock"),
+        (KIND_USER_POST,    "User post"),
+        (KIND_SHARE_INVITE, "Share invite"),
+    ]
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    owner = models.ForeignKey(
+        "lyric.User",
+        related_name="briefs",
+        on_delete=models.CASCADE,
+    )
+    post = models.ForeignKey(
+        Post,
+        related_name="briefs",
+        on_delete=models.CASCADE,
+    )
+    # Line is nullable because a share_invite-style Brief can race ahead of its
+    # async-appended Line write; the post FK alone is enough to navigate.
+    line = models.ForeignKey(
+        Line,
+        related_name="briefs",
+        on_delete=models.CASCADE,
+        null=True,
+        blank=True,
+    )
+    is_unread = models.BooleanField(default=True)
+    kind = models.CharField(
+        max_length=32,
+        choices=KIND_CHOICES,
+        default=KIND_USER_POST,
+    )
+    title = models.CharField(max_length=255, blank=True)
+    created_at = models.DateTimeField(default=timezone.now)
+
+    class Meta:
+        ordering = ["-created_at"]
+
+    def __str__(self):
+        return (
+            f"Brief({self.kind}, {self.owner.email}, "
+            f"unread={self.is_unread})"
+        )

src/apps/billboard/tests/integrated/test_brief.py

@@ -0,0 +1,121 @@
+"""ITs for the Brief model & view_post's mark-read behavior.
+
+Brief is a notification record — owner + post FK + line FK + is_unread + kind.
+It rides on a Post (one-Post-per-category, Lines accumulate). Clicking FYI on
+a Brief banner navigates to billboard:view_post for the underlying Post; that
+GET is the contract that flips is_unread → False.
+"""
+
+from django.test import TestCase
+from django.urls import reverse
+
+from apps.billboard.models import Brief, Line, Post
+from apps.lyric.models import User
+
+
+class BriefModelTest(TestCase):
+    def setUp(self):
+        self.user = User.objects.create(email="brief@test.io")
+        self.post = Post.objects.create(owner=self.user)
+        self.line = Line.objects.create(post=self.post, text="Stargazer, 5:21pm")
+
+    def test_brief_defaults_unread(self):
+        b = Brief.objects.create(owner=self.user, post=self.post, line=self.line)
+        self.assertTrue(b.is_unread)
+
+    def test_brief_default_kind_is_user_post(self):
+        b = Brief.objects.create(owner=self.user, post=self.post, line=self.line)
+        self.assertEqual(b.kind, Brief.KIND_USER_POST)
+
+    def test_brief_kind_choices_include_note_unlock_and_share_invite(self):
+        choices = dict(Brief._meta.get_field("kind").choices)
+        self.assertIn(Brief.KIND_NOTE_UNLOCK, choices)
+        self.assertIn(Brief.KIND_USER_POST, choices)
+        self.assertIn(Brief.KIND_SHARE_INVITE, choices)
+
+    def test_brief_line_can_be_null(self):
+        """A Brief may pre-date its Line (e.g. share-invite spawns the Line
+        async — the Brief should still be persistable while the Line write
+        is pending). Doesn't break the post FK."""
+        b = Brief.objects.create(owner=self.user, post=self.post)
+        self.assertIsNone(b.line)
+
+    def test_brief_owner_post_required(self):
+        """Brief without owner OR post is invalid; both are the load-bearing
+        FKs (owner = whose attention; post = where FYI navigates)."""
+        from django.db import IntegrityError, transaction
+        with transaction.atomic(), self.assertRaises(IntegrityError):
+            Brief.objects.create(post=self.post, line=self.line)
+        with transaction.atomic(), self.assertRaises(IntegrityError):
+            Brief.objects.create(owner=self.user, line=self.line)
+
+    def test_brief_carries_title(self):
+        b = Brief.objects.create(
+            owner=self.user, post=self.post, line=self.line,
+            title="Look! — new Note unlocked",
+        )
+        self.assertEqual(b.title, "Look! — new Note unlocked")
+
+    def test_brief_str_includes_owner_kind_unread(self):
+        b = Brief.objects.create(owner=self.user, post=self.post, kind=Brief.KIND_NOTE_UNLOCK)
+        s = str(b)
+        self.assertIn("brief@test.io", s)
+        self.assertIn("note_unlock", s)
+
+
+class ViewPostMarksReadTest(TestCase):
+    """GET /billboard/post/<uuid>/ flips every unread Brief on that post for
+    the requesting user to is_unread=False. NVM (banner dismiss client-side
+    without nav) leaves Briefs untouched — that path doesn't hit this view."""
+
+    def setUp(self):
+        self.user = User.objects.create(email="reader@test.io")
+        self.client.force_login(self.user)
+        self.post = Post.objects.create(owner=self.user)
+        self.line = Line.objects.create(post=self.post, text="entry one")
+
+    def test_get_view_post_flips_owner_unread_brief_to_read(self):
+        b = Brief.objects.create(owner=self.user, post=self.post, line=self.line)
+        self.assertTrue(b.is_unread)
+        self.client.get(reverse("billboard:view_post", args=[self.post.id]))
+        b.refresh_from_db()
+        self.assertFalse(b.is_unread)
+
+    def test_get_does_not_flip_other_users_briefs(self):
+        other = User.objects.create(email="other@test.io")
+        # Both users have a Brief on this post; only the requesting user's flips
+        mine = Brief.objects.create(owner=self.user, post=self.post, line=self.line)
+        theirs = Brief.objects.create(owner=other, post=self.post, line=self.line)
+        self.client.get(reverse("billboard:view_post", args=[self.post.id]))
+        mine.refresh_from_db()
+        theirs.refresh_from_db()
+        self.assertFalse(mine.is_unread)
+        self.assertTrue(theirs.is_unread)
+
+    def test_get_does_not_flip_briefs_on_other_posts(self):
+        other_post = Post.objects.create(owner=self.user)
+        other_line = Line.objects.create(post=other_post, text="other")
+        unrelated = Brief.objects.create(owner=self.user, post=other_post, line=other_line)
+        self.client.get(reverse("billboard:view_post", args=[self.post.id]))
+        unrelated.refresh_from_db()
+        self.assertTrue(unrelated.is_unread)
+
+    def test_get_idempotent_for_already_read_brief(self):
+        already_read = Brief.objects.create(
+            owner=self.user, post=self.post, line=self.line, is_unread=False,
+        )
+        self.client.get(reverse("billboard:view_post", args=[self.post.id]))
+        already_read.refresh_from_db()
+        self.assertFalse(already_read.is_unread)
+
+    def test_post_request_does_not_mark_read(self):
+        """Posting a new Line to view_post (the legacy compose flow) is not
+        the FYI-read contract — the user is composing, not reviewing. Mark-
+        read happens only on a GET render of post.html."""
+        b = Brief.objects.create(owner=self.user, post=self.post, line=self.line)
+        self.client.post(
+            reverse("billboard:view_post", args=[self.post.id]),
+            data={"text": "appended via POST"},
+        )
+        b.refresh_from_db()
+        self.assertTrue(b.is_unread)

src/apps/billboard/views.py

@@ -9,7 +9,7 @@ from django.shortcuts import redirect, render
 
 from apps.applets.utils import applet_context, apply_applet_toggle
 from apps.billboard.forms import ExistingPostLineForm, LineForm
-from apps.billboard.models import Post
+from apps.billboard.models import Brief, Post
 from apps.dashboard.views import _PALETTE_DEFS
 from apps.drama.models import GameEvent, Note, ScrollPosition
 from apps.epic.models import Room
@@ -253,6 +253,14 @@ def view_post(request, post_id):
         if form.is_valid():
             form.save()
             return redirect(our_post)
+
+    # GET render is the FYI-read contract — flip every unread Brief on this
+    # post for the requesting user. POST (compose) is intentionally excluded
+    # because the user is authoring, not reviewing the new Line.
+    if request.user.is_authenticated:
+        Brief.objects.filter(
+            owner=request.user, post=our_post, is_unread=True,
+        ).update(is_unread=False)
     return render(request, "apps/billboard/post.html", {"post": our_post, "form": form})