6.7 KiB
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:
- Bursts are Event/PendingEvent records with occurrences >= 3, not separate
incidents. The live browser listener has no server-side event until submission.
FieldNoteContextis 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. - 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.
- The frontend uses custom SCSS, HTMX and existing theme tokens, not Bootstrap. These conventions are reused; no second CSS framework is introduced.
- 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.
- 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.
- 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_pendingeventpermission. view_all_fieldnotesexplicitly allows reading other authors' private notes. Staff status alone does not. Django superusers have this permission.export_reportable_fieldnotesexplicitly 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 thanvisible_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 orQuerySet.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_eventandview_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.