transcription/docs/ui/entities/person/acceptance-criteria.md

Person Acceptance Criteria

Purpose: Define implementation-ready acceptance criteria for Person Create, Read, Update, and Delete workflows.

Companion documents:

• docs/ui/entities/person/user-journey.md
• docs/ui/entities/person/schema-mapping.md

Scope

This checklist covers:

1. Create flow
2. Read flow
3. Update flow
4. Delete flow

This checklist does not cover:

1. advanced metadata_ editing UX
2. structured-name schema migration implementation
3. bulk merge or dedup workflow design

Create Acceptance Criteria

CR-1 Person creation entry

1. Given a Person page
2. When the user selects Create new person
3. Then the user can open a Person create form

CR-2 Required field validation

1. full_name is required
2. Save is blocked when full_name is empty
3. Inline feedback is shown for required-field errors

CR-3 Optional field handling

1. Optional fields may be blank without blocking create
2. Date raw and exact fields can coexist
3. Exact date remains canonical when both exact and raw are provided
4. Portrait uploads persist under uploads/portraits/person and store a relative portrait_path

CR-4 Successful create outcome

1. Given valid input
2. When the user saves
3. Then the Person record is created
4. Then success feedback is shown
5. Then the user is routed to Person detail page

CR-5 Create failure outcome

1. Given backend failure during create
2. Then clear error feedback is shown
3. Then entered values are retained where possible
4. Then no false success feedback is shown

Read Acceptance Criteria

RD-1 Person detail retrieval

1. Given a valid Person id
2. When the user opens the Person detail page
3. Then the system displays Person metadata for that record only

RD-2 Metadata visibility

1. The page shows full_name and available optional person fields
2. created_at and updated_at are shown as system-managed, read-only values
3. portrait_path is rendered when available, including an image preview when possible
4. relative portrait_path values resolve through /uploads for image rendering

RD-3 Linked documents section

1. Given no linked DocumentPerson rows
2. Then the page shows a no linked documents yet empty state
3. Given linked documents exist
4. Then the page shows linked document entries

RD-4 Read failure state

1. Given a nonexistent Person id
2. Then the UI shows a clear not found state without crashing

Update Acceptance Criteria

UP-1 Edit entry

1. Given a loaded Person detail page
2. When the user selects Edit person
3. Then editable controls are shown for allowed fields only

UP-2 Editable fields

1. Editable: full_name, display_name, maiden_name, birth/death fields, places, biography, portrait_path
2. Not editable: id, created_at, updated_at
3. metadata_ remains hidden in first release

UP-3 Required validation

1. full_name remains required
2. Save is blocked with inline feedback when full_name is empty

UP-4 Successful save

1. Given valid input
2. When the user saves
3. Then changes persist
4. Then success feedback is shown
5. Then the user remains on Person detail with refreshed values

UP-5 Save failure

1. Given backend failure during save
2. Then clear error feedback is shown
3. Then the user-entered values remain available for retry where possible
4. Then no false success feedback is shown

Delete Acceptance Criteria

DL-1 Delete entry and confirmation

1. Given a Person detail page
2. When the user selects Delete person
3. Then a confirmation dialog appears with permanent-action wording

DL-2 Relationship guardrails

1. Delete is allowed only when relationship policy allows it
2. If linked DocumentPerson rows must be removed first, delete is blocked

DL-3 Blocked delete behavior

1. When blocked
2. Then the UI explains why deletion is blocked
3. Then the UI identifies linked-document dependency presence
4. Then the UI provides navigation to cleanup paths

DL-4 Successful delete

1. Given no blocking dependencies
2. When the user confirms delete
3. Then the Person record is removed
4. Then success feedback is shown
5. Then the user returns to the Person list page

DL-5 Delete failure

1. Given backend failure during delete
2. Then clear error feedback is shown
3. Then the user remains on Person detail with retry path

Cross-Criteria Quality Gates

QG-1 Separation of intent and implementation

1. UX intent remains in user-journey.md
2. Current versus target implementation mapping remains in schema-mapping.md

QG-2 Traceability

1. Each accepted behavior maps to at least one future UI action or service call path
2. No acceptance criterion contradicts the deferred-item policy

QG-3 First-release constraints

1. metadata_ remains hidden in first release
2. structured name field split remains deferred
3. recipient and multi-person role management stays in later revisions