generated from john/python-template
291 lines
8.4 KiB
Markdown
291 lines
8.4 KiB
Markdown
# Person User Journey
|
|
|
|
Purpose: Define how a user should interact with the UI to create and manage a Person record, including expected inputs, validation, outcomes, and links to Document relationships.
|
|
|
|
Scope: This document describes intended user interaction for the Person UI. It is the UX contract for the Person entity.
|
|
|
|
Companion schema mapping: schema-mapping.md
|
|
Companion acceptance criteria: acceptance-criteria.md
|
|
|
|
## 1. Overview
|
|
|
|
A Person represents a historical individual who may be associated with one or more Documents.
|
|
|
|
Managing a Person is a profile-first workflow:
|
|
1. The user opens the Person page.
|
|
2. The user selects Create new person.
|
|
3. The user enters known biographical fields.
|
|
4. The system creates the Person record.
|
|
5. The user can later associate the Person with one or more Documents through DocumentPerson links.
|
|
|
|
## 2. User Goal
|
|
|
|
The user wants to:
|
|
1. create and maintain historical person records
|
|
2. reuse the same Person across multiple Documents
|
|
3. record both precise and approximate date values where certainty is limited
|
|
4. link people to documents as author or recipient in future flows
|
|
|
|
## 3. Page Model
|
|
|
|
### 3.1 Person Page
|
|
|
|
The Person page is the general UI surface where users manage people.
|
|
|
|
It should support:
|
|
1. listing or locating existing people
|
|
2. starting the Create new person flow
|
|
3. navigating into a specific Person after it exists
|
|
|
|
### 3.2 Person Detail Page
|
|
|
|
The Person detail page is the page for one specific Person after creation.
|
|
|
|
It should show:
|
|
1. core identity fields
|
|
2. biographical metadata
|
|
3. portrait image when available
|
|
4. related Documents section
|
|
5. empty state when no linked documents exist yet
|
|
|
|
## 4. Entry Point
|
|
|
|
Entry point: Person page
|
|
|
|
Primary action: Create new person
|
|
|
|
Expected UI affordance:
|
|
1. a visible action labeled Create new person
|
|
2. activation opens a dedicated form view, modal, or detail panel
|
|
|
|
Preferred first implementation:
|
|
1. dedicated Person create page or panel
|
|
2. simple labeled form controls
|
|
3. text inputs are acceptable for first release
|
|
|
|
## 5. Create Person Form
|
|
|
|
### 5.1 Required Fields
|
|
|
|
| UI Label | Schema Field | Input Type | Required | Notes |
|
|
|---|---|---|---|---|
|
|
| Full name | full_name | Text input | Yes | Canonical identity field |
|
|
|
|
### 5.2 Optional Name Fields
|
|
|
|
| UI Label | Schema Field | Input Type | Required | Notes |
|
|
|---|---|---|---|---|
|
|
| Display name | display_name | Text input | No | Friendly or abbreviated display |
|
|
| Maiden name | maiden_name | Text input | No | Historical alternate surname |
|
|
|
|
### 5.3 Birth and Death Date Fields
|
|
|
|
| UI Label | Schema Field | Input Type | Required | Notes |
|
|
|---|---|---|---|---|
|
|
| Birth date | birth_date | Date input | No | Exact known date |
|
|
| Birth date (approximate/raw) | birth_date_raw | Text input | No | Approximate or uncertain value |
|
|
| Death date | death_date | Date input | No | Exact known date |
|
|
| Death date (approximate/raw) | death_date_raw | Text input | No | Approximate or uncertain value |
|
|
|
|
Date handling rule:
|
|
1. exact and raw values may both be entered
|
|
2. exact date is canonical when present
|
|
3. raw date is retained as historical context
|
|
|
|
### 5.4 Optional Biographical Fields
|
|
|
|
| UI Label | Schema Field | Input Type | Required | Notes |
|
|
|---|---|---|---|---|
|
|
| Birth place | birth_place | Text input | No | Free text |
|
|
| Death place | death_place | Text input | No | Free text |
|
|
| Biography | biography | Text area | No | Narrative context |
|
|
| Portrait path | portrait_path | Text input | No | File or resource path |
|
|
| Metadata | metadata_ | Hidden or advanced JSON editor | No | Prefer hidden in first release |
|
|
|
|
### 5.5 System Fields
|
|
|
|
| Schema Field | User Editable | Notes |
|
|
|---|---|---|
|
|
| id | No | System-generated |
|
|
| created_at | No | System-generated |
|
|
| updated_at | No | System-managed |
|
|
|
|
## 6. Validation Rules
|
|
|
|
### 6.1 Required Validation
|
|
|
|
1. full_name is required
|
|
2. save is blocked when full_name is empty
|
|
|
|
### 6.2 Date Validation
|
|
|
|
1. birth_date and birth_date_raw may coexist
|
|
2. death_date and death_date_raw may coexist
|
|
3. exact date fields are canonical when present
|
|
4. raw fields remain descriptive context
|
|
|
|
### 6.3 Integrity Validation
|
|
|
|
1. form accepts unknown values for optional fields
|
|
2. missing birth or death data does not block creation
|
|
|
|
## 7. Submission Behavior
|
|
|
|
On submit:
|
|
1. The system validates required fields
|
|
2. The system creates the Person record
|
|
3. The system returns the user to the Person detail page
|
|
4. The system shows a success message
|
|
|
|
Recommended transactional behavior:
|
|
1. Person writes are atomic
|
|
2. no partial save state should be persisted
|
|
|
|
## 8. Expected Result After Success
|
|
|
|
After successful creation:
|
|
1. The user sees the Person detail page for the new record
|
|
2. full_name is visible in the header or summary
|
|
3. empty Related Documents section is shown if no links exist
|
|
4. The user can proceed to link this person from Document workflows
|
|
|
|
## 9. Expected Result After Failure
|
|
|
|
If creation fails:
|
|
1. Show a clear error message
|
|
2. Show field-level feedback for validation failures
|
|
3. preserve entered data where possible
|
|
4. do not show false success messaging
|
|
|
|
## 10. Read Person Journey
|
|
|
|
### 10.1 User Intent
|
|
|
|
The user wants to open a Person and quickly understand:
|
|
1. identity and key biography fields
|
|
2. whether this person is linked to any documents
|
|
3. what next action to take
|
|
|
|
### 10.2 Read Surfaces
|
|
|
|
The Person detail page should show:
|
|
1. full_name and display fields
|
|
2. birth and death fields
|
|
3. biography summary
|
|
4. related documents list or empty state
|
|
|
|
### 10.3 Read Empty State
|
|
|
|
If no linked documents exist:
|
|
1. Show No linked documents yet
|
|
2. provide guidance to link from Document workflow
|
|
|
|
## 11. Update Person Journey
|
|
|
|
### 11.1 User Intent
|
|
|
|
The user wants to correct or enrich person metadata over time.
|
|
|
|
### 11.2 Editable Fields
|
|
|
|
Editable:
|
|
1. full_name
|
|
2. display_name
|
|
3. maiden_name
|
|
4. birth_date
|
|
5. birth_date_raw
|
|
6. birth_place
|
|
7. death_date
|
|
8. death_date_raw
|
|
9. death_place
|
|
10. biography
|
|
11. portrait_path
|
|
|
|
System-managed:
|
|
1. id
|
|
2. created_at
|
|
3. updated_at
|
|
4. metadata_ can remain hidden in first release
|
|
|
|
### 11.3 Update Save Behavior
|
|
|
|
On save:
|
|
1. validate required fields
|
|
2. persist updates
|
|
3. refresh updated_at by system policy
|
|
4. show confirmation
|
|
5. keep user on Person detail page
|
|
|
|
### 11.4 Update Failure Behavior
|
|
|
|
1. Show clear error feedback
|
|
2. preserve form state where possible
|
|
3. Allow retry
|
|
|
|
## 12. Delete Person Journey
|
|
|
|
### 12.1 User Intent
|
|
|
|
The user wants to remove incorrect or duplicate person records safely.
|
|
|
|
### 12.2 Delete Guardrails
|
|
|
|
Delete is allowed when:
|
|
1. Person has no required retained relationships
|
|
|
|
Delete is blocked when:
|
|
1. Person is linked to one or more Documents via DocumentPerson and unlink policy requires cleanup first
|
|
|
|
### 12.3 Blocked Delete UX
|
|
|
|
1. explain that linked Document relationships exist
|
|
2. Show link count or list
|
|
3. provide cleanup path
|
|
|
|
### 12.4 Allowed Delete UX
|
|
|
|
1. Show a confirmation dialog
|
|
2. confirm permanent action
|
|
3. delete Person
|
|
4. return to Person list with success message
|
|
|
|
## 13. Relationship to Other Workflows
|
|
|
|
This Person workflow integrates with:
|
|
1. Document create and update workflows through person lookup and linking
|
|
2. DocumentPerson mapping for role assignments
|
|
3. future recipient and multi-person enhancements
|
|
|
|
## 14. Relationship to Schema Mapping
|
|
|
|
The companion schema-mapping document should specify:
|
|
1. field visibility per CRUD action
|
|
2. current implementation status
|
|
3. intended behavior
|
|
4. gap-to-target items
|
|
|
|
## 15. Deferred Items
|
|
|
|
Deferred to future revisions:
|
|
1. advanced metadata_ editing UI
|
|
2. multi-person role editing in the Person UI itself
|
|
3. richer relationship timeline views
|
|
4. bulk merge or dedup workflows
|
|
5. structured name fields migration (first_name, middle_name, last_name, optional suffix)
|
|
|
|
### 15.1 Structured Name Fields Migration Note
|
|
|
|
For now, `full_name` remains the canonical required name field.
|
|
|
|
Future revision intent:
|
|
1. introduce structured fields such as first_name, middle_name, last_name, and optional suffix
|
|
2. keep full_name during transition for backward compatibility and historical formatting
|
|
3. define normalization and formatting rules for display and sorting
|
|
4. update search and dedup workflows to use both structured and canonical forms during migration
|
|
|
|
Migration considerations:
|
|
1. schema migration and backfill strategy for existing Person records
|
|
2. validation updates for create and update forms
|
|
3. compatibility for existing APIs and UI components that currently rely on full_name
|
|
4. clear precedence and reconciliation rules when structured fields and full_name differ
|