69 lines
5.1 KiB
Markdown
69 lines
5.1 KiB
Markdown
# Behavior Journal
|
||
|
||
Open **Flock → select a bird → Behavior Journal** (calendar tab). Select a behavior or create a custom one, confirm the current date/time, and save. Duration in seconds, intensity from 1–5, and notes are optional. Open a day's occurrence to see its details, edit it, or delete it with confirmation.
|
||
|
||
The bird and behavior selectors filter the journal. The calendar displays one month at a time, daily counts and up to three dots (plus a `+` for additional events). Select a day to review its individual events. The count above the calendar reflects the selected behavior and displayed month.
|
||
|
||
## Storage and access
|
||
|
||
The existing `ensureSchema` startup migration creates `behavior_types` and `behavior_occurrences` and idempotently seeds nine common behaviors. No separate migration command is required. Occurrences reference existing birds and normalized behavior types. They retain `TIMESTAMPTZ` occurrence, created, and updated timestamps; optional duration in seconds; optional intensity; and notes. Indexes support bird/date and bird/behavior/date queries.
|
||
|
||
Custom behavior names are reusable within a flock and unique ignoring case. Default types are explicitly marked so orphaned custom types never become public. A transferred bird retains its occurrences and the types used in those occurrences, even if its old flock is deleted. Other custom types from its former flock remain private.
|
||
|
||
Existing session/integration-token authentication, flock roles, subscription restrictions, memorialized-bird restrictions, and audit logging apply. Owners, assistants, and caregivers can record/edit/delete; viewers can read. Queries and mutations check the bird's current flock. Writes also check flock ownership and memorialization inside the SQL statement.
|
||
|
||
The browser uses its device time zone for entry and calendar grouping, consistently with local date/time controls. Month boundaries are converted to UTC for the API's inclusive `from`, exclusive `to` range. Stored timestamps are not replaced by dates or daily totals. An unchanged edit retains the original timestamp, including sub-second precision. During a daylight-saving repeated hour, a newly entered ambiguous local time uses the browser's earlier offset; an existing event retains its original instant when its time is unchanged.
|
||
|
||
This feature records observations and occurrence timing. It adds no diagnostic interpretation or behavioral analysis.
|
||
|
||
## API
|
||
|
||
The interactive API reference includes these endpoints:
|
||
|
||
| Method | Path | Purpose |
|
||
| --- | --- | --- |
|
||
| GET | `/api/birds/:birdId/behavior-types` | Available default, flock, and transferred-history types |
|
||
| POST | `/api/birds/:birdId/behavior-types` | Create/reuse a custom type (`name`, optional `description`) |
|
||
| GET | `/api/birds/:birdId/behaviors?from=…&to=…&behaviorTypeId=…` | Events in a positive range of at most 32 days; optional type filter |
|
||
| POST | `/api/birds/:birdId/behaviors` | Create an occurrence |
|
||
| PUT | `/api/birds/:birdId/behaviors/:occurrenceId` | Replace the editable fields |
|
||
| DELETE | `/api/birds/:birdId/behaviors/:occurrenceId` | Delete an occurrence |
|
||
|
||
Occurrence input: `behaviorTypeId`, offset-bearing `occurredAt`, optional/null `durationSeconds` (positive, at most one year), `severity` (integer 1–5), and `notes` (at most 10,000 characters). Responses include the behavior name and timestamps, allowing complete details to open without another request.
|
||
|
||
## Isolated verification
|
||
|
||
Use a disposable copy/install when the local dependency or build directories belong to a container. Do not point these scripts at a real flock database. The integration scripts use fixed test-only database settings on port 55439 and API port 55440. They create fixtures with distinct flock IDs and leave them in the disposable database for inspection.
|
||
|
||
```sh
|
||
docker run --detach --rm --name flockpal-behavior-test-db \
|
||
-e POSTGRES_PASSWORD=behavior_test_only -e POSTGRES_DB=behavior_test \
|
||
-p 127.0.0.1:55439:5432 postgres:16-alpine
|
||
cd backend
|
||
npm ci
|
||
npm run build
|
||
npm test
|
||
node test-integration/behaviorJournal.mjs
|
||
```
|
||
|
||
The API integration check covers schema repeatability, seeded/custom types, duplicate custom names, independent events, create/edit/delete, bird/behavior/month filters, timestamp precision, invalid inputs, unauthenticated requests, viewer/read-only/memorialized restrictions, cross-flock access, and transfer history.
|
||
|
||
For the optional browser check, install Playwright in a disposable frontend install (it is not an application dependency), with the built backend alongside it:
|
||
|
||
```sh
|
||
cd ../frontend
|
||
npm ci
|
||
npm run build
|
||
npm install --no-save --package-lock=false playwright
|
||
npx playwright install chromium
|
||
node test-integration/behaviorJournal.mjs
|
||
```
|
||
|
||
The browser check starts and stops its own API and Vite server (port 55441). It covers the complete entry/custom behavior/edit/delete workflow, bird and behavior filters, day selection and daily counts, month navigation, local midnight and daylight-saving boundaries, and a 390px mobile layout. It writes screenshots to `/tmp/flockpal-behavior-mobile.png` and `/tmp/flockpal-behavior-desktop.png`.
|
||
|
||
After verification, stop only the disposable database:
|
||
|
||
```sh
|
||
docker stop flockpal-behavior-test-db
|
||
```
|