Begin UI update starting with Document table.

2026-08-02 08:02:58 -05:00
parent dfe6f121ff
commit 2b3d33e50e
7 changed files with 580 additions and 0 deletions
@@ -0,0 +1,59 @@
 # UI Documentation
 This folder contains UI-focused design and mapping documents that connect the database schema to user-facing workflows.
 ## Document Types
 ### user-journey.md
 A product and UX contract for a user-facing entity.
 Use this document to describe:
 - what the user is trying to do
 - which screen or action starts the workflow
 - which fields the user sees and edits
 - validation rules
 - expected success and failure outcomes
 - where the user goes next
 ### schema-mapping.md
 A field-level mapping between schema, UI, and implementation.
 Use this document to describe:
 - the authoritative schema fields for an entity
 - which fields are shown, hidden, editable, or system-managed
 - current implementation behavior
 - intended target behavior
 - implementation gaps between current code and intended UX
 ## Organization Rules
 - Store documents under `docs/ui/entities/<entity-name>/`.
 - Create both `user-journey.md` and `schema-mapping.md` for user-facing entities.
 - Create only `schema-mapping.md` for supporting tables that do not currently have standalone UI.
 - Keep top-level `docs/` reserved for core architecture, requirements, schema, and system-wide reference material.
 ## Current Entity Plan
 User-facing entities:
 - `document`
 - `person`
 - `source`
 - `job`
 Supporting entities:
 - `document-person`
 - `job-source`
 ## Relationship to Core Docs
 These UI docs complement, but do not replace:
 - `docs/schema_v2.md`
 - `docs/requirements_v2.md`
 - `docs/architecture_v2.md`
 When there is a conflict:
 - schema definitions come from the database model and schema docs
 - user interaction intent comes from the user-journey docs
 - implementation truth comes from code and is recorded in schema-mapping docs as current-state evidence
@@ -0,0 +1,234 @@
 # Document Schema-to-UI Mapping
 Purpose: Map the Document schema to the UI, while clearly separating intended target behavior from current implementation.
 Companion document: `user-journey.md`
 ## 1. Entity Snapshot
 - Table: Document
 - Primary key: `id` (UUID)
 - Related entities: `Source`, `Job`, `DocumentPerson`
 - Canonical schema references:
  - `src/transcription/db/models.py`
  - `docs/schema_v2.md`
 ## 2. Mapping Rules
 This document uses three lenses:
 1. Intended behavior: what the UX should support.
 2. Current behavior: what the code supports today.
 3. Gap to target: what must change to align implementation with the intended UX.
 ## 3. Field Inventory
 | Field | DB Type | Nullable | Default/Auto Value | Intended UI Treatment | Notes |
 |---|---|---|---|---|---|
 | id | UUID | No | `uuid4()` | Hidden, system-managed | Primary key |
 | name | str | No | None | Shown, editable on create and future edit | Required |
 | document_type | str | Yes | None | Shown, editable on create and future edit | Required by intended UX |
 | document_date | date | Yes | None | Shown, editable | Canonical exact date when present |
 | document_date_raw | str | Yes | None | Shown, editable | Approximate or unknown date text |
 | location_created | str | Yes | None | Shown, editable | Optional metadata |
 | notes | str | Yes | None | Shown, editable | Optional metadata |
 | archive_identifier | str | Yes | None | Shown, editable | Free text in first release |
 | created_at | datetime | No | `datetime.now(UTC)` | Hidden or read-only | System-managed |
 | updated_at | datetime | No | `datetime.now(UTC)` | Hidden or read-only | System-managed |
 ## 4. CREATE Mapping
 ### 4.1 Intended Create Flow
 Entry point: Document page  
 User action: Create new document  
 Success destination: new Document detail page
 | Field | Intended User Input | Required | Visible | Notes |
 |---|---|---|---|---|
 | name | Text input | Yes | Yes | Primary identifier used by the user |
 | document_type | Text input | Yes | Yes | Free text in first release |
 | document_date | Date input | No | Yes | Structured exact date |
 | document_date_raw | Text input | No | Yes | Approximate or uncertain date |
 | location_created | Text input | No | Yes | Optional |
 | notes | Text area | No | Yes | Optional |
 | archive_identifier | Text input | No | Yes | Free text |
 | created_at | None | No | No | System-generated |
 | updated_at | None | No | No | Not used during initial create |
 Related records during intended create:
 - A related person may optionally be selected or created.
 - If present, the system creates a `DocumentPerson` link.
 - Jobs are not created during Document create.
 - Sources are not created during Document create.
 ### 4.2 Current Implementation
 Current entry point: upload page  
 Current user action: upload file via upload widget  
 Current backend path: upload page submit callback -> `create_upload_job()` -> `_create_upload_records()`
 | Field | Current Value at Create | Source | Visible to User | Evidence |
 |---|---|---|---|---|
 | id | Generated UUID | System | No | `Document` default factory in `src/transcription/db/models.py` |
 | name | Basename of uploaded filename | User file name transformed by service | Indirectly | Set in `src/transcription/services/store.py` |
 | document_type | `None` | Service default | No | Not set in `src/transcription/services/store.py` |
 | document_date | `None` | Service default | No | Not set in `src/transcription/services/store.py` |
 | document_date_raw | `None` | Service default | No | Not set in `src/transcription/services/store.py` |
 | location_created | `None` | Service default | No | Not set in `src/transcription/services/store.py` |
 | notes | `None` | Service default | No | Not set in `src/transcription/services/store.py` |
 | archive_identifier | `None` | Service default | No | Not set in `src/transcription/services/store.py` |
 | created_at | Current UTC timestamp | System | No | Default factory in `src/transcription/db/models.py` |
 | updated_at | Current UTC timestamp | System | No | Default factory in `src/transcription/db/models.py` |
 Current related-record behavior:
 - `Job` is created automatically.
 - `Source` is created automatically.
 - `JobSource` is created automatically.
 - No `Person` or `DocumentPerson` records are created.
 ### 4.3 Gap to Target
 To satisfy the intended Create flow, implementation must add:
 1. a Document page and dedicated create form
 2. user-entered metadata fields for `document_type`, `document_date`, `document_date_raw`, `location_created`, `notes`, and `archive_identifier`
 3. optional Person lookup and inline Person creation
 4. optional `DocumentPerson` link creation when a person is chosen
 5. post-submit routing to a Document detail page
 6. removal of the assumption that Document creation always starts with file upload
 ## 5. READ Mapping
 ### 5.1 Intended Read Behavior
 On the Document detail page, the user should be able to see:
 1. Document metadata
 2. linked people
 3. a Sources section with empty-state behavior when no sources exist
 4. a Jobs section with empty-state behavior when no jobs exist
 5. future links to filtered Jobs and Sources views for the current document
 ### 5.2 Current Implementation
 Current Document visibility in the UI is indirect.
 | Field | Current Rendering | Visible to User | Notes | Evidence |
 |---|---|---|---|---|
 | name | Indirect filename context in jobs list and job detail | Yes, indirect | The UI shows source/job filename, not a dedicated Document page | `src/transcription/ui/pages/jobs_page.py`, `src/transcription/ui/components/table/jobs.py` |
 | id | Not shown as Document id | No | Job id is shown instead | `src/transcription/ui/pages/jobs_page.py` |
 | document_type | Not rendered | No | Hidden metadata | no current UI field |
 | document_date | Not rendered | No | Hidden metadata | no current UI field |
 | document_date_raw | Not rendered | No | Hidden metadata | no current UI field |
 | location_created | Not rendered | No | Hidden metadata | no current UI field |
 | notes | Not rendered | No | Hidden metadata | no current UI field |
 | archive_identifier | Not rendered | No | Hidden metadata | no current UI field |
 | created_at | Not rendered as Document timestamp | No | Job timestamps are shown instead | `src/transcription/ui/components/table/jobs.py` |
 | updated_at | Not rendered as Document timestamp | No | Job metadata is shown instead | `src/transcription/ui/components/transcript.py` |
 ### 5.3 Gap to Target
 To satisfy the intended Read flow, implementation must add:
 1. a Document detail page
 2. metadata rendering for Document fields
 3. linked people rendering
 4. Sources and Jobs sections with empty states
 5. filtered navigation from the detail page into document-specific Jobs and Sources views
 ## 6. UPDATE Mapping
 ### 6.1 Intended Update Behavior
 The user should eventually be able to edit Document metadata from the Document detail page or a dedicated edit flow.
 Intended editable fields:
 - `name`
 - `document_type`
 - `document_date`
 - `document_date_raw`
 - `location_created`
 - `notes`
 - `archive_identifier`
 Intended system-managed fields:
 - `id`
 - `created_at`
 - `updated_at`
 ### 6.2 Current Implementation
 | Field | Updatable via UI | Updatable via Service | Notes |
 |---|---|---|---|
 | id | No | Practically no | Primary key should be treated as immutable |
 | name | No | Yes | `DocumentService.update_document()` |
 | document_type | No | Yes | `DocumentService.update_document()` |
 | document_date | No | Yes | `DocumentService.update_document()` |
 | document_date_raw | No | Yes | `DocumentService.update_document()` |
 | location_created | No | Yes | `DocumentService.update_document()` |
 | notes | No | Yes | `DocumentService.update_document()` |
 | archive_identifier | No | Yes | `DocumentService.update_document()` |
 | created_at | No | Technically yes | Should remain system-managed |
 | updated_at | No | Technically yes | Should remain system-managed |
 ### 6.3 Gap to Target
 Implementation must add:
 1. Document edit controls in the UI
 2. validation and save behavior for Document metadata
 3. a consistent `updated_at` update policy if metadata edits are introduced
 ## 7. DELETE Mapping
 ### 7.1 Intended Delete Behavior
 The UI should eventually provide a delete action for Document with guardrails.
 Rules:
 1. A Document can be deleted when it has no attached Jobs and no attached Sources.
 2. If dependent Jobs or Sources exist, the UI should block deletion and explain that those related records must be removed first.
 3. Delete confirmation should make it clear that the action is permanent.
 ### 7.2 Current Implementation
 | Action | UI Exposed | Backend Capability | Notes |
 |---|---|---|---|
 | Delete Document | No | Yes | `DocumentService.delete_document()` exists, but no dedicated UI guard flow exists |
 ### 7.3 Gap to Target
 Implementation must add:
 1. a Document delete control in the UI
 2. pre-delete dependency checks for Jobs and Sources
 3. user-facing messaging when deletion is blocked
 4. confirmation UX for successful delete attempts
 ## 8. Hidden and System-Managed Fields
 | Field | Category | Why Hidden or Protected |
 |---|---|---|
 | id | System-managed | Internal identifier |
 | created_at | System-managed | Audit timestamp |
 | updated_at | System-managed | Audit timestamp |
 ## 9. Traceability Anchors
 Schema and models:
 - `docs/schema_v2.md`
 - `src/transcription/db/models.py`
 Current implementation:
 - `src/transcription/services/documents.py`
 - `src/transcription/services/store.py`
 - `src/transcription/ui/pages/upload_page.py`
 - `src/transcription/ui/pages/jobs_page.py`
 - `src/transcription/ui/components/table/jobs.py`
 - `src/transcription/ui/components/transcript.py`
 Companion UX spec:
 - `docs/ui/entities/document/user-journey.md`
 ## 10. Acceptance Checklist
 - Every Document schema field appears in the field inventory.
 - Intended Create behavior matches the companion user journey.
 - Current Create behavior reflects the existing upload-driven implementation.
 - Gaps between intended and current behavior are explicit.
 - Read, Update, and Delete sections distinguish target behavior from current code.
@@ -0,0 +1,287 @@
 # Document User Journey
 Purpose: Define how a user should interact with the UI to create and manage a Document record, including expected inputs, validation, results, and related record creation.
 Scope: This document describes intended user interaction for the Document UI. It is the UX contract for the Document entity.
 ## 1. Overview
 A Document represents a real historical artifact the user wants to describe, organize, and eventually transcribe. The user should be able to create a Document before uploading or linking any source files.
 Creating a Document is a metadata-first workflow:
 1. The user opens the Document page.
 2. The user selects Create new document.
 3. The user enters descriptive metadata about the document.
 4. The user optionally links one related person.
 5. The system creates the Document.
 6. If a person was selected or created, the system links that Person to the Document through DocumentPerson.
 7. The user sees a success state and lands on the new Document detail page.
 ## 2. User Goal
 The user wants to create a new Document record that:
 1. Has enough metadata to identify the historical artifact.
 2. Can optionally be linked to a person.
 3. Exists independently of transcription jobs and source uploads.
 4. Is ready for later steps such as adding sources, starting jobs, and reviewing transcriptions.
 ## 3. Page Model
 ### 3.1 Document Page
 The Document page is the general UI surface where users manage documents.
 It should support:
 1. listing or locating existing documents
 2. starting the Create new document flow
 3. navigating into a specific Document after it exists
 ### 3.2 Document Detail Page
 The Document detail page is the page for one specific Document after it has been created.
 It should show:
 1. the Document metadata
 2. related people linked to the Document
 3. a Sources section
 4. a Jobs section
 5. empty states when no sources or jobs exist yet
 It should later support links to filtered views for:
 1. jobs associated with the current document only
 2. sources associated with the current document only
 ## 4. Entry Point
 Entry point: Document page
 Primary action: Create new document
 Expected UI affordance:
 1. A visible button, link, or primary action labeled Create new document.
 2. Activation opens a dedicated form view, modal, or detail panel for creating a Document.
 Preferred first implementation:
 1. A dedicated Document create page or panel.
 2. A simple form with explicit labels.
 3. Text inputs are acceptable for first release, even where future versions may use dropdowns or richer selectors.
 ## 5. Create Document Form
 The Create Document form should contain the following fields.
 ### 5.1 Required Fields
 | UI Label | Schema Field | Input Type | Required | Notes |
 |---|---|---|---|---|
 | Document name | name | Text input | Yes | Examples: Pioneer Days, Letter from Zenna to Omie |
 | Document type | document_type | Text input | Yes | Examples: book, letter, enlistment papers, military record, other |
 ### 5.2 Date Fields
 | UI Label | Schema Field | Input Type | Required | Notes |
 |---|---|---|---|---|
 | Exact date | document_date | Date input | No | Use when the exact date is known |
 | Approximate date | document_date_raw | Text input | No | Use when exact date is uncertain, approximate, or unknown |
 Date handling rule:
 1. The form may allow both fields to be entered.
 2. If both fields are entered, `document_date` is the canonical structured date.
 3. `document_date_raw` may still be retained as the user-entered descriptive form.
 4. The UI should explain the distinction clearly.
 Examples:
 1. Exact date: `07/13/1885`
 2. Approximate date: `c. 1885`
 3. Approximate date: `Fall 1925`
 4. Approximate date: `unknown`
 ### 5.3 Optional Metadata Fields
 | UI Label | Schema Field | Input Type | Required | Notes |
 |---|---|---|---|---|
 | Document location | location_created | Text input | No | Where the document was created |
 | Notes | notes | Multiline text area | No | Freeform notes about the document |
 | Archive identifier | archive_identifier | Text input | No | Free text for now; may represent inventory code, storage reference, or repository note |
 Archive identifier guidance:
 1. First implementation should treat this as free text.
 2. Helper text may explain that this can store a repository code, box or folder reference, or storage note.
 ### 5.4 System Fields
 | Schema Field | User Editable | Notes |
 |---|---|---|
 | created_at | No | System-generated at creation time |
 | updated_at | No | Not user-entered during creation |
 ### 5.5 Optional Related Person
 The Create Document flow may optionally link one related person during first release.
 | UI Label | Schema Area | Input Type | Required | Notes |
 |---|---|---|---|---|
 | Related person | Person -> DocumentPerson | Search/select or create inline | No | Intended to support common author-like associations without making the field mandatory |
 First release behavior:
 1. The user may save a Document without linking any person.
 2. If a person is linked during create, only one person is supported in first release.
 3. Additional people and recipient workflows are deferred to a future revision.
 ### 5.6 Related Records Not Created Directly Here
 | Related Area | Included in Document Create | Notes |
 |---|---|---|
 | Jobs | No | Jobs are created later when transcription work begins |
 | Sources | No | Sources are added later as uploaded pages or files |
 ## 6. Related Person Workflow
 ### 6.1 User Intent
 The user should be able to:
 1. select an existing Person to associate with the Document
 2. create a new Person if the person does not already exist
 3. save the Document even if no person is linked
 ### 6.2 Data Model Interpretation
 Person selection source:
 1. The UI should select from Person records.
 2. If a person is linked, the system should create a DocumentPerson record.
 3. Role handling for non-author document relationships is deferred.
 4. If the first release needs a persisted role immediately, the role can default to `author` until the relationship model is broadened.
 This means:
 1. The user does not choose from DocumentPerson records.
 2. DocumentPerson is the relationship created after the Person is chosen or created.
 ### 6.3 Related Person UI Behavior
 Minimum acceptable first implementation:
 1. Searchable or scrollable list of existing Person records.
 2. Option to create a new Person inline or in a small secondary flow.
 3. Clear display of the selected related person before submit.
 If the person does not exist:
 1. User selects Create new person.
 2. User enters the minimum required Person information.
 3. System creates Person.
 4. System returns to Document create flow.
 5. System links the new Person if the user completes Document creation.
 ## 7. Validation Rules
 ### 7.1 Required Field Validation
 The form must reject submission if:
 1. `name` is empty
 2. `document_type` is empty
 ### 7.2 Date Validation
 The form should allow:
 1. `document_date` only
 2. `document_date_raw` only
 3. both `document_date` and `document_date_raw`
 4. neither date field
 If both are present:
 1. `document_date` is treated as the canonical exact date
 2. `document_date_raw` is retained as descriptive context
 ### 7.3 Related Person Validation
 The form must not require a linked person in first release.
 If a related person is selected or created:
 1. the selected value must resolve to a valid Person record before final save
 2. the DocumentPerson link must not be partially persisted on failure
 ## 8. Submission Behavior
 When the user submits the form, the system should perform these logical steps:
 1. validate form inputs
 2. create the Document record
 3. create a Person record only if the user chose to add a new related person
 4. create one DocumentPerson record only if a related person was selected or created
 5. persist all intended records successfully before reporting success to the user
 Expected write sequence:
 1. insert Document
 2. insert Person only if needed
 3. insert DocumentPerson link only if a person is linked
 Recommended transactional behavior:
 1. all related writes should succeed or fail together
 2. the user should not end up with a partial create state where the Document exists but an intended person link does not
 ## 9. Expected Result After Success
 After successful creation, the user should expect to see:
 1. confirmation that the Document was created successfully
 2. the Document name displayed in the resulting UI state
 3. the Document metadata displayed on the new Document detail page
 4. any linked person displayed in the resulting UI state
 5. a Sources section showing an empty state when no sources exist yet
 6. a Jobs section showing an empty state when no jobs exist yet
 7. a clear next step, such as adding source files
 Recommended success route:
 1. navigate to the new Document detail page
 2. show Document summary metadata
 3. show linked people section
 4. show empty-state placeholders for Sources and Jobs
 ## 10. Expected Result After Failure
 If submission fails, the user should expect:
 1. clear error messaging
 2. field-level validation feedback where applicable
 3. no false success message
 4. preservation of entered form values when possible
 Examples:
 1. missing required name
 2. missing required document type
 3. failed person creation
 4. failed DocumentPerson link creation
 5. database or server error
 ## 11. Non-Goals for This Flow
 The Create Document flow does not:
 1. upload document images or PDFs
 2. create transcription jobs
 3. start AI processing
 4. create Source rows directly
 5. edit page-level transcription content
 Those actions belong to later workflows.
 ## 12. Relationship to Other Workflows
 This Document creation workflow should precede:
 1. adding Sources to a Document
 2. creating transcription Jobs
 3. reviewing raw transcription output
 4. editing revised transcription text
 5. linking additional people or recipients later
 ## 13. Relationship to Schema Mapping
 This document is the intended UX contract.
 The companion schema-mapping document should answer:
 1. which schema field appears on which screen
 2. whether the field is currently implemented
 3. whether the field is hidden, editable, or system-managed
 4. what the implementation gap is between intended UX and current code
 ## 14. Deferred Items
 These topics are intentionally deferred to future revisions:
 1. multiple linked people during create
 2. recipient support during create
 3. a broader role model for non-author document relationships
 4. filtered Jobs and Sources list navigation details