71 lines
5.7 KiB
Markdown
71 lines
5.7 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.
|
||
|
||
Each flock member has their own journal, which automatically uses the bird whose profile is open. The behavior selector filters that member’s entries. 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.
|
||
|
||
Choose **Date range** in the View selector to review entries across months. Start and end dates are inclusive in your local time zone, with ranges up to 366 days. Matching entries appear newest first and still support behavior filtering, editing, and deletion. Switch back to **Monthly calendar** for daily counts. Saving an entry outside the selected range moves the range to its date so the saved entry is visible.
|
||
|
||
## 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 366 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, switching between member journals, 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
|
||
```
|