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

106 lines
6.7 KiB
Markdown

# 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.