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

Document Acceptance Criteria

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

Companion documents:

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

Scope

This checklist covers:

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

This checklist does not cover:

1. Source upload workflow details
2. Job execution internals
3. Revision editor behavior

Read Acceptance Criteria

RD-1 Document detail retrieval

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

RD-2 Metadata visibility

1. The page shows name, document_type, document_date, document_date_raw, location_created, notes, archive_identifier
2. created_at and updated_at are displayed as system-managed, read-only values

RD-3 Related people section

1. Given zero linked people
2. Then the page shows a no linked people yet empty state
3. Given one linked person
4. Then the page shows that linked person

RD-4 Sources section empty state

1. The page shows a Sources action for the current Document
2. The page shows a primary + Add Source action that opens job-create flow for this Document
3. The action routes to a document-scoped Sources view

RD-5 Jobs section empty state

1. The page shows a Jobs action for the current Document
2. The page shows a primary + Add Job action for the current Document
3. The action routes to a document-scoped Jobs view

RD-6 Filtered navigation readiness

1. The detail page provides links or actions that can route to document-scoped Sources and Jobs views
2. Target views are filtered to the current Document id

RD-7 Failure state

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

Update Acceptance Criteria

UP-1 Edit entry

1. Given a loaded Document detail page
2. When the user chooses Edit document
3. Then editable controls are shown for allowed fields only, including the author relationship selector
4. The author selector includes No author, existing Person options, and a Create new item option
5. Selecting Create new item routes to Person create

UP-2 Editable fields

1. Editable: name, document_type, document_date, document_date_raw, location_created, notes, archive_identifier
2. Not editable: id, created_at, updated_at
3. The edit flow may also change the associated author Person link

UP-3 Required validation

1. name is required
2. document_type is required
3. Save is blocked with inline feedback when either required field is missing

UP-4 Date handling rule

1. document_date only is allowed
2. document_date_raw only is allowed
3. both fields together are allowed
4. if both are present, document_date is treated as canonical exact date and document_date_raw is retained as descriptive context

UP-5 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 Document detail with refreshed values
6. Then updated_at reflects update policy

UP-6 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 Document detail page
2. When the user chooses Delete document
3. Then a confirmation dialog appears with permanent-action wording

DL-2 Dependency guardrails

1. Delete is allowed only when the Document has no related Source records and no related Job records
2. Delete is blocked when at least one related Source or Job exists

DL-3 Blocked delete behavior

1. When blocked
2. Then the UI explains why deletion is blocked
3. Then the UI identifies dependency categories present: Sources, Jobs, or both
4. Then the UI provides navigation to dependency cleanup paths

DL-4 Successful delete

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

DL-5 Delete failure

1. Given backend failure during delete
2. Then a clear error message is shown
3. Then the user remains on Document 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 current deferred-item policy

QG-3 First-release constraints

1. Linked person during create remains optional
2. Recipient and multi-person expansion remain deferred