106 lines
6.7 KiB
Markdown
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.
|