generated from john/python-template
95 lines
3.8 KiB
Markdown
95 lines
3.8 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 a portrait and 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}/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.
|
|
- Portrait path or uploaded portrait.
|
|
- 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`.
|
|
- Portrait uploads are stored under the configured upload root in a Person-specific directory and update Portrait path.
|
|
- 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.
|
|
- The portrait viewer resolves supported relative upload paths and absolute HTTP/data URLs.
|
|
- 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.
|
|
- 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.
|
|
|
|
## 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.
|
|
- Portrait 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.
|