# 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
