transcription/docs/ui/entities/person/user-journey.md

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
5. If portrait upload is used, the file is stored under uploads/portraits/person and portrait_path is set to that relative file path

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
5. portrait preview resolved from /uploads when portrait_path is a relative path

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