generated from john/python-template
UI update planning continued
This commit is contained in:
Jim Lancaster
@@ -0,0 +1,289 @@
|
||||
# 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. related Documents section
|
||||
4. 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. system validates required fields
|
||||
2. system creates Person record
|
||||
3. system returns user to Person detail page
|
||||
4. system shows 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. user sees 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. user can proceed to link this person from Document workflows
|
||||
|
||||
## 9. Expected Result After Failure
|
||||
|
||||
If creation fails:
|
||||
1. show 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 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
|
||||
Reference in New Issue
Block a user