From 7f9ff36d1d6825c33d4d8745f23abd0e7a3ba3ed Mon Sep 17 00:00:00 2001 From: Disco DeDisco Date: Fri, 8 May 2026 17:35:46 -0400 Subject: [PATCH] =?UTF-8?q?brief=20sprint=20C2:=20introduce=20billboard.Br?= =?UTF-8?q?ief=20notification=20model=20+=20view=5Fpost=20marks-read=20on?= =?UTF-8?q?=20GET=20=E2=80=94=20TDD?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Git commit message Co-Authored-By: Claude Sonnet 4.6 --- src/apps/billboard/migrations/0002_brief.py | 34 +++++ src/apps/billboard/models.py | 62 +++++++++ .../billboard/tests/integrated/test_brief.py | 121 ++++++++++++++++++ src/apps/billboard/views.py | 10 +- 4 files changed, 226 insertions(+), 1 deletion(-) create mode 100644 src/apps/billboard/migrations/0002_brief.py create mode 100644 src/apps/billboard/tests/integrated/test_brief.py diff --git a/src/apps/billboard/migrations/0002_brief.py b/src/apps/billboard/migrations/0002_brief.py new file mode 100644 index 0000000..2783711 --- /dev/null +++ b/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'], + }, + ), + ] diff --git a/src/apps/billboard/models.py b/src/apps/billboard/models.py index ffd8ec8..69dc5ff 100644 --- a/src/apps/billboard/models.py +++ b/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})" + ) diff --git a/src/apps/billboard/tests/integrated/test_brief.py b/src/apps/billboard/tests/integrated/test_brief.py new file mode 100644 index 0000000..567ac25 --- /dev/null +++ b/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// 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) diff --git a/src/apps/billboard/views.py b/src/apps/billboard/views.py index d7e5ba6..112be83 100644 --- a/src/apps/billboard/views.py +++ b/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})