generated from john/python-template
104 lines
4.5 KiB
Markdown
104 lines
4.5 KiB
Markdown
# People Page Contract
|
|
|
|
## Purpose
|
|
|
|
People manages reusable historical-person records. A Person may appear in many Documents under different relationship roles and may optionally carry one or more photos plus a FamilySearch identifier.
|
|
|
|
## Routes
|
|
|
|
| Route | Purpose |
|
|
| --- | --- |
|
|
| `/people` | Searchable People list. |
|
|
| `/people/new` | Create a Person. |
|
|
| `/people/{person_id}` | View one Person and linked Documents. |
|
|
| `/people/{person_id}/photos` | Manage Person photos. |
|
|
| `/people/{person_id}/edit` | Edit the Person. |
|
|
| `/people/{person_id}/delete` | Confirm permanent deletion. |
|
|
|
|
## List Behavior
|
|
|
|
- The title is **Archival Entities: People**.
|
|
- **Create new person** opens the create route.
|
|
- The table defaults to Full Name order and supports search and column sorting.
|
|
- Columns are Full Name, FamilySearch ID, Birth Date, Death Date, and # Documents.
|
|
- Full Name is left-aligned; FamilySearch ID, date columns, and # Documents are centered.
|
|
- # Documents reflects how many linked Documents each Person is connected to.
|
|
- Birth and death values independently prefer exact date, then approximate date, then `Unknown`.
|
|
- Selecting a row opens Person Detail.
|
|
- No records displays `No person records found in repository.`
|
|
|
|
## Create and Edit Behavior
|
|
|
|
Required:
|
|
|
|
- Full name.
|
|
|
|
Optional:
|
|
|
|
- Display name and maiden name.
|
|
- Exact and approximate birth/death dates.
|
|
- Birth/death places.
|
|
- Biography.
|
|
- FamilySearch ID.
|
|
|
|
Rules:
|
|
|
|
- Missing Full name blocks save with a warning.
|
|
- Exact date inputs are native browser date inputs.
|
|
- FamilySearch IDs are normalized and validated by `PeopleService`.
|
|
- Photos are managed on Person Detail (not in create/edit form fields).
|
|
- Metadata JSON remains hidden.
|
|
- Save success returns to Person Detail.
|
|
|
|
## Detail Behavior
|
|
|
|
- The header provides **New Document**, **Edit Person**, and **Delete**.
|
|
- **New Document** opens Document creation with this Person requested for author preselection.
|
|
- Person Detail shows a single-photo viewer with **Previous/Next** navigation; the page-level **Edit Photo(s)** header action opens photo management.
|
|
- Photo management (upload, description edit, set-primary, delete) is intentionally moved to `/people/{person_id}/photos`.
|
|
- Biographical Record shows names, compact birth/death dates, and places.
|
|
- Birth and death place values are clickable links to Google Maps when present.
|
|
- FamilySearch ID is shown as a metadata value and is clickable to the FamilySearch person details route when present.
|
|
- Maiden Name is only shown in Biographical Record when a value exists.
|
|
- Biography has an explicit empty value.
|
|
- Linked Documents render as a table with **Document Name**, **Role**, and **Number of Pages**; selecting a row opens Document Detail.
|
|
- No links shows both an empty state and guidance to link from a Document workflow.
|
|
- System Logistics shows created and updated timestamps.
|
|
|
|
## Delete Behavior
|
|
|
|
- The page warns when linked Document relationships exist.
|
|
- Delete is blocked when related Photos exist.
|
|
- Confirmed deletion removes the Person and its relationship links; it does not delete Documents.
|
|
- Success returns to the People list.
|
|
- Missing or already-deleted records return to a safe list state.
|
|
|
|
## Photo Gallery Behavior (`/people/{person_id}/photos`)
|
|
|
|
- Upload is triggered from a header-level **Upload Photo(s)** control beside **Back to Person**.
|
|
- The gallery renders all photos in a responsive grid (3-4 tiles wide on larger screens).
|
|
- Description text is shown as an overlay at the bottom of each image for quick context.
|
|
- The editor provides **Save Description**, **Set Primary** (when applicable), and **Delete Photo** actions.
|
|
|
|
## Acceptance Checklist
|
|
|
|
- List fields, alignment, date fallback, search, sorting, and navigation match this contract.
|
|
- Full name is enforced on create and edit.
|
|
- FamilySearch ID validation and link generation use the fixed supported identifier format.
|
|
- Photo upload and rendering remain constrained to supported media paths.
|
|
- New Document carries the Person context.
|
|
- Linked Documents show the correct role and target.
|
|
- Delete wording distinguishes removal of relationship links from deletion of Documents.
|
|
|
|
## Implementation Anchors
|
|
|
|
- `src/transcription/ui/pages/people_page.py`
|
|
- `src/transcription/ui/components/table/people.py`
|
|
- `src/transcription/services/people.py`
|
|
- `tests/ui/test_people_page.py`
|
|
- `tests/services/test_v2_crud.py`
|
|
|
|
## Deferred Work
|
|
|
|
- Structured name fields, merge/deduplication, advanced metadata editing, and Person-side relationship editing are not current behavior.
|