generated from john/python-template
135 lines
6.5 KiB
Markdown
135 lines
6.5 KiB
Markdown
# 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, Author, Tags, Document Date, Type, and # Sources.
|
|
- Document Title is left-aligned; the remaining columns are centered.
|
|
- Author lists all linked people in the `author` role.
|
|
- # Sources reflects the count of linked Source rows for each Document.
|
|
- 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.
|
|
- Tags.
|
|
- Linked People, with exactly one Person Role per linked Person.
|
|
|
|
Rules:
|
|
|
|
- Exact date must parse as `YYYY-MM-DD`; browser presentation may follow locale.
|
|
- The exact-date input is labeled **Document date**.
|
|
- Existing people appear with disambiguating labels.
|
|
- Tag assignment supports selecting existing tags and adding new labels inline.
|
|
- **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, tags, Document date (`MM-DD-YYYY` for exact dates), 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.
|