diff --git a/FIELD_NOTES.md b/FIELD_NOTES.md
new file mode 100644
index 0000000..af014ce
--- /dev/null
+++ b/FIELD_NOTES.md
@@ -0,0 +1,105 @@
+# Field notes: specification review and implementation
+
+## Review decisions
+
+The requested separation between recorded evidence and human context fits the
+application. Inspection found these differences from the illustrative spec:
+
+1. **Bursts are Event/PendingEvent records with occurrences >= 3**, not separate
+ incidents. The live browser listener has no server-side event until submission.
+ `FieldNoteContext` is a small, author-owned association record, with no incident
+ timestamps, count, audio or classification of its own. It holds a draft UUID and
+ later references the existing PendingEvent or Event. Multiple notes attach once
+ to that report rather than being copied across individual bangs.
+2. **Pending manual ownership was session-based.** Note contexts preserve author
+ attribution across sessions without inventing ownership for old reports. New
+ draft tokens are signed, author-bound and expire after seven days. A submitted
+ token cannot be reused for another report; the UI rotates it on success. Late
+ note saves still follow the original report through moderation.
+3. **The frontend uses custom SCSS, HTMX and existing theme tokens**, not Bootstrap.
+ These conventions are reused; no second CSS framework is introduced.
+4. **There was no incident export pipeline or event merge UI.** Added CSV/JSON
+ note exports through one permission-filtered service. PDF export and event
+ regrouping interfaces remain outside this pass. A tested regrouping service
+ preserves note provenance for future merge operations.
+5. **Corrections are new notes.** No edit/delete route or editable admin form is
+ provided. This keeps original text and entry timestamps unchanged. Verification
+ labels describe the author's stated assessment, not automated validation.
+6. **Timezone follows Django's active timezone**, currently Europe/Amsterdam;
+ there is no per-user timezone setting. Datetimes are stored timezone-aware,
+ with the timezone shown beside entry/observation times. Adding a user timezone
+ preference later can use the same fields.
+
+## Privacy and permissions
+
+- Notes default to private, unknown source and unverified. Only content is required.
+- An authenticated author can read/create their own notes. Reportable notes are
+ still not public and do not become verified.
+- Approved events are already public; authenticated users may add their own notes
+ to them. Pending targets require existing session ownership, sensor ownership,
+ a note context owned by that user, or staff `view_pendingevent` permission.
+- `view_all_fieldnotes` explicitly allows reading other authors' private notes.
+ Staff status alone does not. Django superusers have this permission.
+- `export_reportable_fieldnotes` explicitly allows exporting other authors'
+ reportable notes. Without it, exports contain only the caller's reportable notes.
+ **Private notes are excluded even for superusers.** Read-all permission does not
+ imply export-all permission.
+- Every export starts with `field_notes.reportable_notes(user)`. Future PDF/API
+ reporting must use this service, rather than `visible_to()` or raw relations.
+- CSV escapes formula-like user values; HTML renders escaped plain text and keeps
+ line breaks. Public event/map responses do not serialize note data.
+- Link operations are author-only, POST/CSRF-protected, and only accept an existing
+ approved event. Existing linked notes cannot be silently reparented through the
+ user endpoint. Each standalone observation context can hold several live notes;
+ linking it moves that observation's notes together.
+- Admin is read-only and uses the same visibility boundary. Association history
+ is similarly scoped. ORM `save()` rejects note/history edits; direct SQL or
+ `QuerySet.update()` is not an application editing interface and must not be used
+ to bypass this policy.
+
+## Lifecycle and interfaces
+
+- The dashboard's Add field note form is adjacent to quick reporting and updates
+ only its own HTMX region, leaving listener/audio controls mounted and running.
+- Submission binds the draft context to Pending Review. Approval atomically moves
+ contexts to the approved Event and records the moderator (or system/null actor
+ for non-request approvals). Notes retain their original entry timestamps.
+- Denial/deletion clears the foreign key but preserves the note and its historical
+ target ID. The observation remains available in My field notes.
+- `regroup_event_notes(actor, source, target)` requires staff, `change_event` and
+ `view_all_fieldnotes`. Existing or future merge code must call it inside its
+ transaction before deleting the source. It moves associations without copying
+ notes and records previous/current event IDs. No automatic grouping is added.
+- Historical event details show only visible notes and counts. Direct event pages
+ and the archive now have normal links for no-JavaScript access.
+- `/fireworks/notes/` creates standalone observations and lists accessible notes;
+ event/pending filters provide contextual forms. `/fireworks/notes/export/json/`
+ and `/fireworks/notes/export/csv/` export authorised reportable notes, optionally
+ filtered by approved event ID.
+- Standard POST forms redirect after saving. HTMX forms return their own updated
+ region; validation responses intentionally use HTTP 200 so HTMX renders errors.
+- Occurrence and entry dates are displayed separately. New information is appended
+ chronologically; author-supplied observed time does not reorder entry history.
+
+## Validation and deployment
+
+Migration `0014` adds three tables, constraints and an author/time index. It does
+not rewrite existing event data. Apply with `python manage.py migrate` after
+updating the application; build assets with the existing `npm run build` command.
+No firmware changes or version bump are needed for this Django-only feature.
+
+Automated tests cover defaults, escaping, anonymous/cross-user access, explicit
+staff permissions, private export exclusion (including superuser), source and
+uncertainty preservation, observed/entry timestamps, append-only saves, invalid
+forms, active draft binding, approval, late saves, stale-token rejection,
+standalone linking, regrouping and denied-report retention.
+
+Browser verification uses the actual Django application with an isolated SQLite
+DB under `/tmp`. It covers HTMX note saves during a **synthetic browser audio
+stream**, listener continuity, report binding/token rotation, historical notes,
+mobile/desktop layouts, dark/light appearance, accessibility labels, exports and
+standard form submission in a JavaScript-disabled browser context. This is not a
+microphone/hardware validation and does not claim classification accuracy.
+
+Out of scope: attachments, CCTV files, witness identity management, PDF generation,
+new incident/merge interfaces, full timeline redesign, or changing detection logic.
diff --git a/fireworks_detect/__pycache__/admin.cpython-312.pyc b/fireworks_detect/__pycache__/admin.cpython-312.pyc
index 7a9ba43..862dd98 100644
Binary files a/fireworks_detect/__pycache__/admin.cpython-312.pyc and b/fireworks_detect/__pycache__/admin.cpython-312.pyc differ
diff --git a/fireworks_detect/__pycache__/admin.cpython-313.pyc b/fireworks_detect/__pycache__/admin.cpython-313.pyc
index 9a95c3f..571cc12 100644
Binary files a/fireworks_detect/__pycache__/admin.cpython-313.pyc and b/fireworks_detect/__pycache__/admin.cpython-313.pyc differ
diff --git a/fireworks_detect/__pycache__/field_notes.cpython-312.pyc b/fireworks_detect/__pycache__/field_notes.cpython-312.pyc
new file mode 100644
index 0000000..ca74b3e
Binary files /dev/null and b/fireworks_detect/__pycache__/field_notes.cpython-312.pyc differ
diff --git a/fireworks_detect/__pycache__/field_notes.cpython-313.pyc b/fireworks_detect/__pycache__/field_notes.cpython-313.pyc
new file mode 100644
index 0000000..1fe1450
Binary files /dev/null and b/fireworks_detect/__pycache__/field_notes.cpython-313.pyc differ
diff --git a/fireworks_detect/__pycache__/forms.cpython-312.pyc b/fireworks_detect/__pycache__/forms.cpython-312.pyc
new file mode 100644
index 0000000..ce62538
Binary files /dev/null and b/fireworks_detect/__pycache__/forms.cpython-312.pyc differ
diff --git a/fireworks_detect/__pycache__/forms.cpython-313.pyc b/fireworks_detect/__pycache__/forms.cpython-313.pyc
new file mode 100644
index 0000000..a79d3da
Binary files /dev/null and b/fireworks_detect/__pycache__/forms.cpython-313.pyc differ
diff --git a/fireworks_detect/__pycache__/models.cpython-312.pyc b/fireworks_detect/__pycache__/models.cpython-312.pyc
index d53d28a..f6e0f57 100644
Binary files a/fireworks_detect/__pycache__/models.cpython-312.pyc and b/fireworks_detect/__pycache__/models.cpython-312.pyc differ
diff --git a/fireworks_detect/__pycache__/models.cpython-313.pyc b/fireworks_detect/__pycache__/models.cpython-313.pyc
index c446bb7..7e9c35c 100644
Binary files a/fireworks_detect/__pycache__/models.cpython-313.pyc and b/fireworks_detect/__pycache__/models.cpython-313.pyc differ
diff --git a/fireworks_detect/__pycache__/note_views.cpython-312.pyc b/fireworks_detect/__pycache__/note_views.cpython-312.pyc
new file mode 100644
index 0000000..9cff4e2
Binary files /dev/null and b/fireworks_detect/__pycache__/note_views.cpython-312.pyc differ
diff --git a/fireworks_detect/__pycache__/note_views.cpython-313.pyc b/fireworks_detect/__pycache__/note_views.cpython-313.pyc
new file mode 100644
index 0000000..0cf937c
Binary files /dev/null and b/fireworks_detect/__pycache__/note_views.cpython-313.pyc differ
diff --git a/fireworks_detect/__pycache__/test_field_notes.cpython-313.pyc b/fireworks_detect/__pycache__/test_field_notes.cpython-313.pyc
new file mode 100644
index 0000000..909491d
Binary files /dev/null and b/fireworks_detect/__pycache__/test_field_notes.cpython-313.pyc differ
diff --git a/fireworks_detect/__pycache__/urls.cpython-312.pyc b/fireworks_detect/__pycache__/urls.cpython-312.pyc
index 5a2f055..f7d2c50 100644
Binary files a/fireworks_detect/__pycache__/urls.cpython-312.pyc and b/fireworks_detect/__pycache__/urls.cpython-312.pyc differ
diff --git a/fireworks_detect/__pycache__/urls.cpython-313.pyc b/fireworks_detect/__pycache__/urls.cpython-313.pyc
index 798a095..27cb2a7 100644
Binary files a/fireworks_detect/__pycache__/urls.cpython-313.pyc and b/fireworks_detect/__pycache__/urls.cpython-313.pyc differ
diff --git a/fireworks_detect/__pycache__/views.cpython-312.pyc b/fireworks_detect/__pycache__/views.cpython-312.pyc
index fec4f31..b6bc7e0 100644
Binary files a/fireworks_detect/__pycache__/views.cpython-312.pyc and b/fireworks_detect/__pycache__/views.cpython-312.pyc differ
diff --git a/fireworks_detect/__pycache__/views.cpython-313.pyc b/fireworks_detect/__pycache__/views.cpython-313.pyc
index 1debce5..3352251 100644
Binary files a/fireworks_detect/__pycache__/views.cpython-313.pyc and b/fireworks_detect/__pycache__/views.cpython-313.pyc differ
diff --git a/fireworks_detect/admin.py b/fireworks_detect/admin.py
index 8057b62..5fe0bf8 100644
--- a/fireworks_detect/admin.py
+++ b/fireworks_detect/admin.py
@@ -134,7 +134,7 @@ class PendingEventAdmin(ClassificationAdmin):
def approve_selected(self, request, queryset):
approved = 0
for pending in queryset:
- pending.approve()
+ pending.approve(actor=request.user)
approved += 1
self.message_user(request, ngettext("%(count)d sample approved and moved to Events.", "%(count)d samples approved and moved to Events.", approved) % {"count": approved}, messages.SUCCESS)
@@ -198,3 +198,47 @@ class SensorAdmin(admin.ModelAdmin):
sensor = queryset.get()
token = sensor.issue_token()
self.message_user(request, format_html(_("Copy this token now; it is not stored and will not be shown again: {}"), token), messages.WARNING)
+
+
+from .models import FieldNote, FieldNoteAssociation
+
+
+@admin.register(FieldNote)
+class FieldNoteAdmin(admin.ModelAdmin):
+ list_display = ("id", "author", "category", "source_type", "verification_status", "visibility", "created_at")
+ list_filter = ("visibility", "category", "source_type", "verification_status")
+ readonly_fields = tuple(f.name for f in FieldNote._meta.fields)
+ search_fields = ("content",)
+
+ def get_queryset(self, request):
+ return super().get_queryset(request).visible_to(request.user).select_related("author", "context")
+
+ def has_add_permission(self, request):
+ return False
+
+ def has_change_permission(self, request, obj=None):
+ return False
+
+ def has_delete_permission(self, request, obj=None):
+ return False
+
+
+@admin.register(FieldNoteAssociation)
+class FieldNoteAssociationAdmin(admin.ModelAdmin):
+ list_display = ("context", "actor", "reason", "created_at")
+ readonly_fields = tuple(f.name for f in FieldNoteAssociation._meta.fields)
+
+ def get_queryset(self, request):
+ qs = super().get_queryset(request)
+ if request.user.has_perm("fireworks_detect.view_all_fieldnotes"):
+ return qs
+ return qs.filter(context__author=request.user)
+
+ def has_add_permission(self, request):
+ return False
+
+ def has_change_permission(self, request, obj=None):
+ return False
+
+ def has_delete_permission(self, request, obj=None):
+ return False
diff --git a/fireworks_detect/field_notes.py b/fireworks_detect/field_notes.py
new file mode 100644
index 0000000..8af38d8
--- /dev/null
+++ b/fireworks_detect/field_notes.py
@@ -0,0 +1,100 @@
+"""Central access checks and association/reporting services for field notes."""
+import uuid
+
+from django.contrib.auth import get_user_model
+from django.core import signing
+from django.core.exceptions import PermissionDenied
+from django.db import transaction
+from django.db.models import Q
+from django.http import Http404
+
+from .models import Event, PendingEvent, FieldNote, FieldNoteContext, FieldNoteAssociation
+
+
+def draft_token(user):
+ if not user.is_authenticated:
+ return ""
+ return signing.dumps({"author": user.pk, "id": str(uuid.uuid4())}, salt="field-notes")
+
+
+def token_id(user, token):
+ try:
+ data = signing.loads(token, salt="field-notes", max_age=7 * 86400)
+ if data["author"] != user.pk:
+ raise ValueError
+ return uuid.UUID(data["id"])
+ except (signing.BadSignature, ValueError, KeyError, TypeError):
+ raise PermissionDenied("Invalid or expired note context. Reload the reporting page.")
+
+
+def accessible_pending(user, session_ids=()):
+ if not user.is_authenticated:
+ return PendingEvent.objects.none()
+ if user.is_staff and user.has_perm("fireworks_detect.view_pendingevent"):
+ return PendingEvent.objects.all()
+ return PendingEvent.objects.filter(Q(note_contexts__author=user) | Q(sensor__owner=user) | Q(pk__in=session_ids)).distinct()
+
+
+def target_snapshot(context):
+ if context.event_id:
+ return {"kind": "event", "id": context.event_id}
+ if context.pending_event_id:
+ return {"kind": "pending", "id": context.pending_event_id}
+ return {}
+
+
+def associate(context, *, event=None, pending=None, actor=None, reason):
+ previous = target_snapshot(context)
+ context.event = event
+ context.pending_event = pending
+ context.full_clean()
+ context.save(update_fields=["event", "pending_event"])
+ FieldNoteAssociation.objects.create(context=context, actor=actor, previous=previous,
+ target=target_snapshot(context), reason=reason)
+
+
+@transaction.atomic
+def context_for_token(user, token):
+ # Serialize draft-note creation and report binding for the same author.
+ get_user_model().objects.select_for_update().get(pk=user.pk)
+ context, _ = FieldNoteContext.objects.get_or_create(id=token_id(user, token), defaults={"author": user})
+ if context.author_id != user.pk:
+ raise PermissionDenied
+ return context
+
+
+@transaction.atomic
+def bind_report(user, token, pending):
+ if not user.is_authenticated or not token:
+ return
+ context = context_for_token(user, token)
+ if context.event_id or context.pending_event_id:
+ raise PermissionDenied("This note context already belongs to a report. Reload before reporting again.")
+ associate(context, pending=pending, actor=user, reason="submission")
+
+
+@transaction.atomic
+def link_standalone(user, context_id, event):
+ # Approved events are publicly accessible in the existing application.
+ context = FieldNoteContext.objects.select_for_update().filter(pk=context_id, author=user).first()
+ if not context or context.event_id or context.pending_event_id:
+ raise Http404
+ associate(context, event=event, actor=user, reason="linked")
+ return context
+
+
+@transaction.atomic
+def regroup_event_notes(user, source, target):
+ """Hook for future event-merging code; does not modify detection records."""
+ if not (user.is_staff and user.has_perm("fireworks_detect.change_event") and
+ user.has_perm("fireworks_detect.view_all_fieldnotes")):
+ raise PermissionDenied
+ if source.pk == target.pk:
+ return
+ for context in FieldNoteContext.objects.select_for_update().filter(event=source):
+ associate(context, event=target, actor=user, reason="regrouped")
+
+
+def reportable_notes(user):
+ """All exports, including future PDF reports, must start with this queryset."""
+ return FieldNote.objects.reportable_to(user).select_related("author", "context")
diff --git a/fireworks_detect/forms.py b/fireworks_detect/forms.py
new file mode 100644
index 0000000..65f3025
--- /dev/null
+++ b/fireworks_detect/forms.py
@@ -0,0 +1,33 @@
+from django import forms
+from django.utils.translation import gettext_lazy as _
+from .models import FieldNote
+
+
+class FieldNoteForm(forms.ModelForm):
+ class Meta:
+ model = FieldNote
+ fields = ["content", "category", "source_type", "verification_status", "visibility", "observed_at"]
+ widgets = {
+ "content": forms.Textarea(attrs={"rows": 3, "placeholder": _("What did you observe or learn?")}),
+ "observed_at": forms.DateTimeInput(format="%Y-%m-%dT%H:%M", attrs={"type": "datetime-local"}),
+ }
+ labels = {"content": _("Note"), "observed_at": _("Observed at (optional)"),
+ "category": _("Category"), "source_type": _("Source"),
+ "verification_status": _("Verification status"), "visibility": _("Visibility")}
+ help_texts = {
+ "visibility": _("Private by default. Reportable permits authorised export; it does not mean verified or public."),
+ "observed_at": _("Local time (Europe/Amsterdam). The entry time is recorded separately."),
+ }
+
+ def __init__(self, *args, **kwargs):
+ super().__init__(*args, **kwargs)
+ for name in self.fields:
+ if name != "content":
+ self.fields[name].required = False
+
+ def clean(self):
+ data = super().clean()
+ for name in ("category", "source_type", "verification_status", "visibility"):
+ if not data.get(name):
+ data[name] = FieldNote._meta.get_field(name).get_default()
+ return data
diff --git a/fireworks_detect/migrations/0014_fieldnotecontext_fieldnoteassociation_fieldnote_and_more.py b/fireworks_detect/migrations/0014_fieldnotecontext_fieldnoteassociation_fieldnote_and_more.py
new file mode 100644
index 0000000..c22d071
--- /dev/null
+++ b/fireworks_detect/migrations/0014_fieldnotecontext_fieldnoteassociation_fieldnote_and_more.py
@@ -0,0 +1,86 @@
+# Generated by Django 6.1.1 on 2026-10-13 07:57
+
+import django.db.models.deletion
+import uuid
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+ dependencies = [
+ ('fireworks_detect', '0013_event_submitted_at'),
+ migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+ ]
+
+ operations = [
+ migrations.CreateModel(
+ name='FieldNoteContext',
+ fields=[
+ ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+ ('created_at', models.DateTimeField(auto_now_add=True)),
+ ('author', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, to=settings.AUTH_USER_MODEL)),
+ ('event', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='note_contexts', to='fireworks_detect.event')),
+ ('pending_event', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='note_contexts', to='fireworks_detect.pendingevent')),
+ ],
+ ),
+ migrations.CreateModel(
+ name='FieldNoteAssociation',
+ fields=[
+ ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+ ('previous', models.JSONField(default=dict)),
+ ('target', models.JSONField(default=dict)),
+ ('reason', models.CharField(max_length=32)),
+ ('created_at', models.DateTimeField(auto_now_add=True)),
+ ('actor', models.ForeignKey(null=True, on_delete=django.db.models.deletion.SET_NULL, to=settings.AUTH_USER_MODEL)),
+ ('context', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='associations', to='fireworks_detect.fieldnotecontext')),
+ ],
+ options={
+ 'ordering': ['created_at', 'pk'],
+ },
+ ),
+ migrations.CreateModel(
+ name='FieldNote',
+ fields=[
+ ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+ ('content', models.TextField(max_length=10000)),
+ ('category', models.CharField(choices=[('general', 'General'), ('witness', 'Witness'), ('people_vehicles', 'People / vehicles'), ('cctv', 'CCTV'), ('location_direction', 'Location / direction'), ('follow_up', 'Follow-up'), ('other', 'Other')], default='general', max_length=32)),
+ ('source_type', models.CharField(choices=[('first_hand', 'First-hand'), ('second_hand', 'Second-hand'), ('unknown', 'Other / unknown')], default='unknown', max_length=24)),
+ ('verification_status', models.CharField(choices=[('unverified', 'Unverified'), ('corroborated', 'Corroborated'), ('disputed', 'Disputed')], default='unverified', max_length=24)),
+ ('visibility', models.CharField(choices=[('private', 'Private'), ('reportable', 'Reportable')], default='private', max_length=16)),
+ ('observed_at', models.DateTimeField(blank=True, null=True)),
+ ('created_at', models.DateTimeField(auto_now_add=True)),
+ ('updated_at', models.DateTimeField(auto_now=True)),
+ ('author', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='field_notes', to=settings.AUTH_USER_MODEL)),
+ ('context', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='notes', to='fireworks_detect.fieldnotecontext')),
+ ],
+ options={
+ 'ordering': ['created_at', 'pk'],
+ 'permissions': [('view_all_fieldnotes', 'Read all private field notes'), ('export_reportable_fieldnotes', 'Export reportable field notes from all authors')],
+ },
+ ),
+ migrations.AddConstraint(
+ model_name='fieldnotecontext',
+ constraint=models.CheckConstraint(condition=models.Q(('event__isnull', False), ('pending_event__isnull', False), _negated=True), name='note_context_one_target'),
+ ),
+ migrations.AddIndex(
+ model_name='fieldnote',
+ index=models.Index(fields=['author', 'created_at'], name='fieldnote_author_time'),
+ ),
+ migrations.AddConstraint(
+ model_name='fieldnote',
+ constraint=models.CheckConstraint(condition=models.Q(('content', ''), _negated=True), name='fieldnote_nonempty'),
+ ),
+ migrations.AddConstraint(
+ model_name='fieldnote',
+ constraint=models.CheckConstraint(condition=models.Q(('visibility__in', ['private', 'reportable'])), name='fieldnote_visibility'),
+ ),
+ migrations.AddConstraint(
+ model_name='fieldnote',
+ constraint=models.CheckConstraint(condition=models.Q(('source_type__in', ['first_hand', 'second_hand', 'unknown'])), name='fieldnote_source'),
+ ),
+ migrations.AddConstraint(
+ model_name='fieldnote',
+ constraint=models.CheckConstraint(condition=models.Q(('verification_status__in', ['unverified', 'corroborated', 'disputed'])), name='fieldnote_verification'),
+ ),
+ ]
diff --git a/fireworks_detect/migrations/__pycache__/0014_fieldnotecontext_fieldnoteassociation_fieldnote_and_more.cpython-313.pyc b/fireworks_detect/migrations/__pycache__/0014_fieldnotecontext_fieldnoteassociation_fieldnote_and_more.cpython-313.pyc
new file mode 100644
index 0000000..5e0cac6
Binary files /dev/null and b/fireworks_detect/migrations/__pycache__/0014_fieldnotecontext_fieldnoteassociation_fieldnote_and_more.cpython-313.pyc differ
diff --git a/fireworks_detect/models.py b/fireworks_detect/models.py
index 9ae03dd..983db32 100644
--- a/fireworks_detect/models.py
+++ b/fireworks_detect/models.py
@@ -265,7 +265,7 @@ class PendingEvent(ClassifiedAudio):
verbose_name_plural = _("Pending")
@transaction.atomic
- def approve(self):
+ def approve(self, actor=None):
event = Event.objects.create(
submitted_at=self.created_at,
audio_file=self.audio_file.name,
@@ -289,6 +289,9 @@ class PendingEvent(ClassifiedAudio):
direction_accuracy_degrees=self.direction_accuracy_degrees,
direction_source=self.direction_source,
)
+ from .field_notes import associate
+ for context in self.note_contexts.select_for_update():
+ associate(context, event=event, actor=actor, reason="approved")
self.delete()
return event
@@ -334,3 +337,117 @@ class SensorSubmission(models.Model):
class Meta:
constraints = [models.UniqueConstraint(fields=["sensor", "event_id"], name="unique_sensor_event_id")]
+
+
+class FieldNoteContext(models.Model):
+ """An author's note association, including drafts before a report exists.
+
+ This stores no detection/incident data; Event/PendingEvent remain canonical.
+ """
+ id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+ author = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.PROTECT)
+ event = models.ForeignKey(Event, null=True, blank=True, on_delete=models.SET_NULL, related_name="note_contexts")
+ pending_event = models.ForeignKey(PendingEvent, null=True, blank=True, on_delete=models.SET_NULL, related_name="note_contexts")
+ created_at = models.DateTimeField(auto_now_add=True)
+
+ class Meta:
+ constraints = [models.CheckConstraint(condition=~(models.Q(event__isnull=False) & models.Q(pending_event__isnull=False)), name="note_context_one_target")]
+
+
+class FieldNoteQuerySet(models.QuerySet):
+ def visible_to(self, user):
+ if not user.is_authenticated or not user.is_active:
+ return self.none()
+ if user.is_active and user.has_perm("fireworks_detect.view_all_fieldnotes"):
+ return self
+ return self.filter(author=user)
+
+ def reportable_to(self, user):
+ if not user.is_authenticated or not user.is_active:
+ return self.none()
+ notes = self.filter(visibility="reportable")
+ if user.is_active and user.has_perm("fireworks_detect.export_reportable_fieldnotes"):
+ return notes
+ return notes.filter(author=user)
+
+
+class FieldNote(models.Model):
+ class Category(models.TextChoices):
+ GENERAL = "general", _("General")
+ WITNESS = "witness", _("Witness")
+ PEOPLE = "people_vehicles", _("People / vehicles")
+ CCTV = "cctv", _("CCTV")
+ LOCATION = "location_direction", _("Location / direction")
+ FOLLOW_UP = "follow_up", _("Follow-up")
+ OTHER = "other", _("Other")
+
+ class Source(models.TextChoices):
+ FIRST_HAND = "first_hand", _("First-hand")
+ SECOND_HAND = "second_hand", _("Second-hand")
+ UNKNOWN = "unknown", _("Other / unknown")
+
+ class Verification(models.TextChoices):
+ UNVERIFIED = "unverified", _("Unverified")
+ CORROBORATED = "corroborated", _("Corroborated")
+ DISPUTED = "disputed", _("Disputed")
+
+ class Visibility(models.TextChoices):
+ PRIVATE = "private", _("Private")
+ REPORTABLE = "reportable", _("Reportable")
+
+ author = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.PROTECT, related_name="field_notes")
+ context = models.ForeignKey(FieldNoteContext, on_delete=models.PROTECT, related_name="notes")
+ content = models.TextField(max_length=10000)
+ category = models.CharField(max_length=32, choices=Category.choices, default=Category.GENERAL)
+ source_type = models.CharField(max_length=24, choices=Source.choices, default=Source.UNKNOWN)
+ verification_status = models.CharField(max_length=24, choices=Verification.choices, default=Verification.UNVERIFIED)
+ visibility = models.CharField(max_length=16, choices=Visibility.choices, default=Visibility.PRIVATE)
+ observed_at = models.DateTimeField(null=True, blank=True)
+ created_at = models.DateTimeField(auto_now_add=True)
+ updated_at = models.DateTimeField(auto_now=True)
+ objects = FieldNoteQuerySet.as_manager()
+
+ class Meta:
+ ordering = ["created_at", "pk"]
+ indexes = [models.Index(fields=["author", "created_at"], name="fieldnote_author_time")]
+ permissions = [
+ ("view_all_fieldnotes", "Read all private field notes"),
+ ("export_reportable_fieldnotes", "Export reportable field notes from all authors"),
+ ]
+ constraints = [
+ models.CheckConstraint(condition=~models.Q(content=""), name="fieldnote_nonempty"),
+ models.CheckConstraint(condition=models.Q(visibility__in=["private", "reportable"]), name="fieldnote_visibility"),
+ models.CheckConstraint(condition=models.Q(source_type__in=["first_hand", "second_hand", "unknown"]), name="fieldnote_source"),
+ models.CheckConstraint(condition=models.Q(verification_status__in=["unverified", "corroborated", "disputed"]), name="fieldnote_verification"),
+ ]
+
+ def clean(self):
+ super().clean()
+ if not self.content.strip():
+ raise ValidationError({"content": _("Enter a note.")})
+ if self.context_id and self.author_id != self.context.author_id:
+ raise ValidationError(_("The note and its context must have the same author."))
+
+ def save(self, *args, **kwargs):
+ if not self._state.adding:
+ raise ValidationError(_("Field notes are append-only. Add a follow-up to correct an earlier note."))
+ self.full_clean()
+ return super().save(*args, **kwargs)
+
+
+class FieldNoteAssociation(models.Model):
+ """Immutable provenance retained even when the original event is deleted."""
+ context = models.ForeignKey(FieldNoteContext, on_delete=models.PROTECT, related_name="associations")
+ actor = models.ForeignKey(settings.AUTH_USER_MODEL, null=True, on_delete=models.SET_NULL)
+ previous = models.JSONField(default=dict)
+ target = models.JSONField(default=dict)
+ reason = models.CharField(max_length=32)
+ created_at = models.DateTimeField(auto_now_add=True)
+
+ class Meta:
+ ordering = ["created_at", "pk"]
+
+ def save(self, *args, **kwargs):
+ if not self._state.adding:
+ raise ValidationError("Association history is append-only.")
+ return super().save(*args, **kwargs)
diff --git a/fireworks_detect/note_views.py b/fireworks_detect/note_views.py
new file mode 100644
index 0000000..edaea15
--- /dev/null
+++ b/fireworks_detect/note_views.py
@@ -0,0 +1,126 @@
+import csv
+import json
+from urllib.parse import urlencode
+
+from django.contrib.auth.decorators import login_required
+from django.db import transaction
+from django.http import Http404, HttpResponse, JsonResponse
+from django.shortcuts import get_object_or_404, redirect, render
+from django.urls import reverse
+from django.views.decorators.cache import never_cache
+from django.views.decorators.http import require_http_methods
+
+from .field_notes import accessible_pending, associate, context_for_token, link_standalone, reportable_notes, token_id
+from .forms import FieldNoteForm
+from .models import Event, FieldNote, FieldNoteContext
+
+
+def panel_context(request, params=None):
+ params = params if params is not None else request.GET
+ selected = [(k, params.get(k)) for k in ("event", "pending", "token") if params.get(k)]
+ if len(selected) > 1:
+ raise Http404
+ notes = FieldNote.objects.visible_to(request.user).select_related("author", "context__event", "context__pending_event").prefetch_related("context__associations")
+ target = None
+ kind, value = selected[0] if selected else ("", "")
+ try:
+ if kind == "event":
+ target = get_object_or_404(Event, pk=int(value))
+ notes = notes.filter(context__event=target)
+ elif kind == "pending":
+ target = get_object_or_404(accessible_pending(request.user, request.session.get("manual_pending_ids", [])), pk=int(value))
+ notes = notes.filter(context__pending_event=target)
+ elif kind == "token":
+ key = token_id(request.user, value)
+ notes = notes.filter(context_id=key)
+ except (ValueError, TypeError):
+ raise Http404
+ return {"field_notes": notes, "note_count": notes.count(), "note_form": FieldNoteForm(),
+ "note_kind": kind, "note_value": value, "note_target": target,
+ "note_panel_id": "live-field-notes" if kind == "token" else "field-notes",
+ "note_query": urlencode({kind: value}) if kind else "",
+ "note_events": Event.objects.all() if not kind else (),
+ "note_token": value if kind == "token" else ""}
+
+
+@login_required
+@never_cache
+@require_http_methods(["GET", "POST"])
+def notes(request):
+ params = request.POST if request.method == "POST" else request.GET
+ context = panel_context(request, params)
+ if request.method == "POST":
+ form = FieldNoteForm(request.POST)
+ if form.is_valid():
+ with transaction.atomic():
+ kind = context["note_kind"]
+ if kind == "token":
+ owner_context = context_for_token(request.user, context["note_value"])
+ else:
+ owner_context = FieldNoteContext.objects.create(author=request.user)
+ if kind:
+ associate(owner_context, event=context["note_target"] if kind == "event" else None,
+ pending=context["note_target"] if kind == "pending" else None,
+ actor=request.user, reason="created")
+ note = form.save(commit=False)
+ note.author = request.user
+ note.context = owner_context
+ note.save()
+ if request.headers.get("HX-Request") != "true":
+ return redirect(reverse("fireworks_detect:field_notes") + ("?" + context["note_query"] if context["note_query"] else ""))
+ context = panel_context(request, params)
+ context["note_saved"] = True
+ else:
+ context["note_form"] = form
+ # Invalid HTMX forms deliberately return 200 so HTMX renders field errors.
+ template = "fireworks_detect/notes/panel.html" if request.headers.get("HX-Request") == "true" else "fireworks_detect/notes/page.html"
+ return render(request, template, context)
+
+
+@login_required
+@never_cache
+@require_http_methods(["POST"])
+def link_note(request, context_id):
+ try:
+ event = get_object_or_404(Event, pk=int(request.POST.get("event", "")))
+ except (ValueError, TypeError):
+ raise Http404
+ link_standalone(request.user, context_id, event)
+ return redirect("fireworks_detect:field_notes")
+
+
+@login_required
+@never_cache
+@require_http_methods(["GET"])
+def export_notes(request, format):
+ notes = reportable_notes(request.user).prefetch_related("context__associations")
+ if request.GET.get("event"):
+ try:
+ event = get_object_or_404(Event, pk=int(request.GET["event"]))
+ except (ValueError, TypeError):
+ raise Http404
+ notes = notes.filter(context__event=event)
+ rows = [{"id": n.pk, "author": n.author.get_username(), "event_id": n.context.event_id,
+ "pending_event_id": n.context.pending_event_id, "content": n.content,
+ "category": n.category, "source_type": n.source_type,
+ "verification_status": n.verification_status, "visibility": n.visibility,
+ "observed_at": n.observed_at.isoformat() if n.observed_at else None,
+ "created_at": n.created_at.isoformat(), "updated_at": n.updated_at.isoformat(),
+ "association_history": [{"previous": a.previous, "target": a.target, "reason": a.reason,
+ "created_at": a.created_at.isoformat()} for a in n.context.associations.all()]}
+ for n in notes]
+ if format == "json":
+ response = JsonResponse({"notes": rows})
+ elif format == "csv":
+ response = HttpResponse(content_type="text/csv; charset=utf-8")
+ fields = ["id", "author", "event_id", "pending_event_id", "content", "category", "source_type", "verification_status", "visibility", "observed_at", "created_at", "updated_at", "association_history"]
+ writer = csv.DictWriter(response, fieldnames=fields)
+ writer.writeheader()
+ for row in rows:
+ row["association_history"] = json.dumps(row["association_history"])
+ # Prevent spreadsheet formula execution from user-authored text.
+ writer.writerow({k: "'" + v if isinstance(v, str) and v.lstrip().startswith(("=", "+", "-", "@")) else v for k, v in row.items()})
+ else:
+ raise Http404
+ response["Content-Disposition"] = f'attachment; filename="boomcast-field-notes.{format}"'
+ return response
diff --git a/fireworks_detect/templates/fireworks_detect/dashboard.html b/fireworks_detect/templates/fireworks_detect/dashboard.html
index d17542c..3c9f915 100644
--- a/fireworks_detect/templates/fireworks_detect/dashboard.html
+++ b/fireworks_detect/templates/fireworks_detect/dashboard.html
@@ -25,6 +25,7 @@
{% trans "No peak events returned." %}
{% endfor %} {% endif %} + +{% if request.user.is_authenticated %}{% include "fireworks_detect/notes/panel.html" %}{% else %}{% trans "Sign in to add private field notes" %}
{% endif %} diff --git a/fireworks_detect/templates/fireworks_detect/event_page.html b/fireworks_detect/templates/fireworks_detect/event_page.html new file mode 100644 index 0000000..dce77db --- /dev/null +++ b/fireworks_detect/templates/fireworks_detect/event_page.html @@ -0,0 +1,2 @@ +{% load i18n vite %} +{% trans "Reviewed signal archive" %}
{% trans "This feed refreshes automatically every three seconds after a pending sample is approved in admin." %}
{% trans "Loading events…" %}
{% trans "Choose an approved event to inspect its classification details." %}
{% trans "Reviewed signal archive" %}
{% trans "This feed refreshes automatically every three seconds after a pending sample is approved in admin." %}
{% trans "Choose an approved event to inspect its classification details." %}
{% trans "No approved events yet. Submit a classification, then approve it from the Pending page in admin." %}
diff --git a/fireworks_detect/templates/fireworks_detect/includes/manual_report_form.html b/fireworks_detect/templates/fireworks_detect/includes/manual_report_form.html index bde7f6c..28caeb1 100644 --- a/fireworks_detect/templates/fireworks_detect/includes/manual_report_form.html +++ b/fireworks_detect/templates/fireworks_detect/includes/manual_report_form.html @@ -10,22 +10,32 @@ - +