Files
FlockPal/docs/BIRD_MEMBERSHIP.md
Corey Blais 3237cd7601
Deploy / deploy-prod (push) Skipped
Deploy / deploy-dev (push) Successful in 4m18s
Added behavior journal, adjusted layout, and added some colors
2026-10-05 15:20:00 -04:00

3.9 KiB
Raw Permalink Blame History

Removing and re-adding a bird

Remove from flock now unassigns the bird. It does not delete the bird profile, photo, weights, vet visits, medication/dose records, Behavior Journal, timeline, or bird-specific notes.

The bird disappears from the old flock's lists and care-record access. Its public profile is disabled, open transfer codes are revoked, and pending transfers are cancelled. Existing reminders find birds through their current flock, so unassigned birds do not enter future reminder selections. Removal is recorded in the bird timeline and the old flock's audit log.

Bird-specific notes follow the bird. Flock-wide notes and workspace audit history stay with the original flock. Removal and claiming keep the bird's ID, so care history is preserved without copying or combining records.

Adding an existing unassigned bird

In Add bird, enter the band ID. FlockPal checks for an unassigned, non-memorialized match after typing pauses. Matching follows the existing global band-ID convention: ignore surrounding whitespace and letter case, but otherwise require the entire ID. Blank/unknown placeholders and partial IDs cannot recover a bird.

A match displays a notice that the saved profile, photo, notes, and care history will be brought in, with an Add bird with existing history button. Confirmation is required. Saved profile details are used rather than overwriting them with draft fields. No new name or species is required for this path. Before confirmation, the lookup returns only availability, not the previous profile or flock details.

A bird already assigned to a flock cannot be claimed this way; use the existing transfer flow. Claims use a database row lock so simultaneous requests from different flocks cannot both succeed. Memorialized birds remain read-only.

Birds without band IDs can still be removed and retained, but they cannot be automatically recovered through the band-ID workflow. The removal confirmation explains this. Previously hard-deleted records cannot be restored by this change.

Schema and API

The startup ensureSchema migration allows birds.workspace_id and bird-specific flock_notes.workspace_id to be null. Removal, note reassignment, transfer revocation, and timeline recording run in a transaction. Claiming and its note/timeline changes also run in a transaction. A failure rolls the entire change back.

The existing DELETE /api/birds/:birdId now removes flock membership and still returns 204. New endpoints:

  • GET /api/birds/unassigned-match?tagId=… returns { "available": true | false }.
  • POST /api/birds/claim accepts { "tagId": "…", "confirmHistory": true } and returns the existing bird plus historyImported: true.

Both require authenticated owner, assistant, or caregiver membership. Claiming also requires write access. Creating a new profile with an unassigned band's ID returns 409 / bird_history_available; it never overwrites history.

Verification

Use the disposable PostgreSQL/API setup in Behavior Journal testing, then run:

cd backend
npm run build
npm test
node test-integration/birdMembership.mjs

The integration check covers repeated schema startup, retained profile/photo/history, notes separation, source access removal, disabled sharing, transfer revocation, exact/case-insensitive band matching, explicit confirmation, role/billing restrictions, transaction rollback, and competing claims.

With Playwright installed in the disposable frontend install as described in that guide:

cd frontend
node test-integration/birdMembership.mjs

The browser check exercises desktop removal, the mobile match notice, cancellation, confirmed recovery without replacement profile fields, and restored notes/timeline. It uses ports 55439–55441 and writes a notice screenshot to /tmp/flockpal-existing-history-notice.png. No real flock data is used.