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

51 lines
3.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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](BEHAVIOR_JOURNAL.md#isolated-verification), then run:
```sh
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:
```sh
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.