Documents Page Contract

Purpose

Documents manages the archival record for each historical artifact independently of its source files and transcription jobs. A Document can be created first, linked to people in one or more roles, and used later as the parent for Sources and Jobs.

Routes

Route	Purpose
`/documents`	Searchable archival Document list.
`/documents/new`	Create a Document.
`/documents/{document_id}`	View one Document and its related records.
`/documents/{document_id}/edit`	Edit metadata and the complete Linked People set.
`/documents/{document_id}/delete`	Confirm or block deletion.
`/documents/{document_id}/jobs`	Show Jobs belonging to the Document.
`/documents/{document_id}/sources`	Redirect to the Document-filtered Sources list.
`/documents/{document_id}/print`	Preview and browser-print the persisted Document.

List Behavior

The title is Archival Documents.
Create new document opens the create route.
The table defaults to Document Title order and supports search and column sorting.
Columns are Document Title, Type, Author, Document Date, and Archive Ref.
Document Title is left-aligned; the remaining columns are centered.
Author lists all linked people in the author role.
Date display prefers exact date, then approximate date, then Unknown.
Selecting a row opens Document Detail.
No records displays No documents found in repository.

Create and Edit Behavior

Required:

Document name.
Document type selected from the Document Type registry.

Optional:

Exact date.
Approximate date.
Document location.
Archive identifier.
Notes.
Linked People, with exactly one Person Role per linked Person.

Rules:

Exact date must parse as YYYY-MM-DD; browser presentation may follow locale.
Existing people appear with disambiguating labels.
Create new person opens Person creation.
person_id may preselect that Person in the author role on Document creation.
An invalid requested Person produces a warning rather than a broken form.
return_to=jobs_new returns a successful create to Job creation with the new Document selected.
Edit includes active and inactive Document Types so historical values remain maintainable.
One Linked People table contains Select, Person, and Role columns.
Add and Edit use an inline Person/Role editor; Save, Cancel, and Delete change staged UI state only.
A Person may appear once per Document regardless of role.
Existing inactive-role links remain visible; only active roles may be newly assigned.
Document fields and the complete staged link set commit atomically on the main save.
Save success returns to Document Detail.

Detail Behavior

The heading shows name, type, and internal ID.
The first Source, when present, appears in the dark-room viewer.
Archival Metadata shows authors, Document Type, compact Document date, location, and archive identifier. Notes appear in a separate archival-notes block within the same card.
System Logistics shows created and updated timestamps.
Related People are grouped by role and link to Person Detail.
Sources & Pipeline Jobs shows counts and actions for filtered Sources, Document Jobs, and adding a Job.
Edit Document, Print, and Delete are available from the header.
Invalid IDs and missing Documents produce explicit states without rendering a partial page.

Print Behavior

Print opens a dedicated preview for persisted Document data.
Facsimile places each Source image beside its current transcription and starts every Source on a new printed sheet.
Text only omits images, joins single line breaks inside paragraphs, and preserves blank-line paragraph boundaries.
Non-null revised text takes precedence over raw transcription, including an intentionally empty revision.
Archival metadata resolves Author through the hidden built-in semantic identity, not its mutable label.
Archival metadata includes the Document Type label.
Metadata tables use a narrow non-wrapping label column and wider wrapping data columns rather than stretching across the page.
Job metadata uses one oldest-to-newest column per Job and ends with Status.
Stored text is escaped and Source media uses record-validated application URLs rather than local file paths.
Printing uses the browser print dialog; server-generated PDFs are not provided.

Document Jobs Behavior

The page lists the Document's Jobs newest first with status and Job ID.
Open Job navigates to Job Detail.
Create Job opens Job creation with the Document selected.
No jobs displays an explicit empty state.

Delete Behavior

Deletion is blocked while any Source or Job belongs to the Document.
The blocked state names the dependency categories and provides navigation back and to Jobs.
An unlinked Document requires an explicit permanent-delete action.
Success returns to the Documents list.

Acceptance Checklist

List columns, alignment, search, sorting, date fallback, and row navigation match this contract.
Create/edit enforce name, registered type, and valid exact-date input.
Linked People staging enforces one role and one row per Person.
Document and Linked People writes never partially commit.
Person-first Document creation preselects the requested Person as author.
Detail links people, Sources, and Jobs to the correct records.
Delete never removes a Document with Source or Job dependencies.
Both print formats preserve the frozen content, ordering, text-precedence, and safety contracts.
Service failures use the shared error presenter and never report false success.

Implementation Anchors

src/transcription/ui/pages/documents_page.py
src/transcription/ui/components/table/documents.py
src/transcription/services/documents.py
src/transcription/services/people.py
src/transcription/services/workflows.py
src/transcription/ui/components/linked_people.py
src/transcription/ui/pages/print_preview_page.py
src/transcription/api/print_api.py
tests/ui/test_documents_page.py
tests/services/test_document_service.py

Known Limitations and Deferred Work

Source page ordering remains read-only in V4.4.
Printing other entities, batch printing, and server-side export formats are deferred.

6.2 KiB Raw Blame History