Files
FireworksApp/FIELD_NOTES.md
T
2026-10-14 18:17:27 +02:00

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:

  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.