bbchops/transcription
1
0
Fork 0
generated from john/python-template
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

UI updates, changes sync'd to UI docs

Browse Source
This commit is contained in:
Jim Lancaster
2026-08-02 18:20:38 -05:00
parent 9653060c2a
commit 0ab7ad50f2
22 changed files with 447 additions and 431 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ui/entities/document/acceptance-criteria.md
+6 -5
View File
@@ -36,12 +36,12 @@ This checklist does not cover:
4. Then the page shows that linked person
### RD-4 Sources section empty state
1. Given no related Source records
2. Then the page shows no sources added yet and an action to add sources
1. The page shows a Sources action for the current Document
2. The action routes to a document-scoped Sources view
### RD-5 Jobs section empty state
1. Given no related Job records
2. Then the page shows no jobs created yet and an action to start or create jobs
1. The page shows a Jobs action for the current Document
2. 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
@@ -56,11 +56,12 @@ This checklist does not cover:
### 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
3. Then editable controls are shown for allowed fields only, including the author relationship selector
### 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
docs/ui/entities/document/schema-mapping.md
+38 -41
View File
@@ -9,7 +9,7 @@ Acceptance criteria: acceptance-criteria.md
- Table: Document
- Primary key: `id` (UUID)
- Related entities: `Source`, `Job`, `DocumentPerson`
- Related entities: `Source`, `Job`, `DocumentPerson`, `Person`
- Canonical schema references:
- `src/transcription/db/models.py`
- `docs/schema_v2.md`
@@ -26,8 +26,8 @@ This document uses three lenses:
| 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 |
| name | str | No | None | Shown, editable on create and edit | Required |
| document_type | str | Yes | None | Shown, editable on create and 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 |
@@ -64,38 +64,37 @@ Related records during intended 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()`
Current entry point: `/documents` page
Current user action: open create form, fill metadata, optionally select an existing Person
Current backend path: document page submit callback -> `DocumentService.create_document()` -> optional `DocumentService.create_document_person()`
| 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` |
| name | User-provided | User input | Yes | `src/transcription/ui/pages/documents_page.py` |
| document_type | User-provided or None | User input | Yes | `src/transcription/ui/pages/documents_page.py` |
| document_date | Parsed from date input or None | User input | Yes | `src/transcription/ui/pages/documents_page.py` |
| document_date_raw | User-provided or None | User input | Yes | `src/transcription/ui/pages/documents_page.py` |
| location_created | User-provided or None | User input | Yes | `src/transcription/ui/pages/documents_page.py` |
| notes | User-provided or None | User input | Yes | `src/transcription/ui/pages/documents_page.py` |
| archive_identifier | User-provided or None | User input | Yes | `src/transcription/ui/pages/documents_page.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.
- User may optionally select an existing `Person`.
- If selected, `DocumentPerson` is created with role `author`.
- `Job` is not created during Document create.
- `Source` is not created during Document create.
### 4.3 Gap to Target
To satisfy the intended Create flow, implementation must add:
To satisfy the intended Create flow, implementation now includes:
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
3. optional Person lookup through a dropdown of existing people
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
@@ -110,29 +109,27 @@ On the Document detail page, the user should be able to see:
### 5.2 Current Implementation
Current Document visibility in the UI is indirect.
Current Document visibility in the UI is direct.
| 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` |
| name | Rendered as title and detail heading | Yes | Dedicated Document detail page | `src/transcription/ui/pages/documents_page.py` |
| id | Not shown as raw id | No | Internal identifier remains hidden | `src/transcription/ui/pages/documents_page.py` |
| document_type | Rendered | Yes | Shown on detail and editable on create/edit | `src/transcription/ui/pages/documents_page.py` |
| document_date | Rendered | Yes | Exact date shown when present | `src/transcription/ui/pages/documents_page.py` |
| document_date_raw | Rendered | Yes | Approximate date shown when present | `src/transcription/ui/pages/documents_page.py` |
| location_created | Rendered | Yes | Optional metadata shown | `src/transcription/ui/pages/documents_page.py` |
| notes | Rendered | Yes | Optional metadata shown | `src/transcription/ui/pages/documents_page.py` |
| archive_identifier | Rendered | Yes | Optional metadata shown | `src/transcription/ui/pages/documents_page.py` |
| created_at | Rendered read-only | Yes | System timestamp shown on detail | `src/transcription/ui/pages/documents_page.py` |
| updated_at | Rendered read-only | Yes | System timestamp shown on detail | `src/transcription/ui/pages/documents_page.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
To satisfy the intended Read flow, implementation now includes:
1. metadata rendering for Document fields
2. linked people rendering
3. document-scoped Sources and Jobs navigation views
## 6. UPDATE Mapping
@@ -171,10 +168,10 @@ Intended system-managed fields:
### 6.3 Gap to Target
Implementation must add:
Implementation now includes:
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
3. author relationship controls through the edit flow
## 7. DELETE Mapping
@@ -191,11 +188,11 @@ Rules:
| Action | UI Exposed | Backend Capability | Notes |
|---|---|---|---|
| Delete Document | No | Yes | `DocumentService.delete_document()` exists, but no dedicated UI guard flow exists |
| Delete Document | Yes | Yes | `DocumentService.delete_document()` exists and the UI blocks dependent deletes |
### 7.3 Gap to Target
Implementation must add:
Implementation includes:
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
docs/ui/entities/document/user-journey.md
+16 -17
View File
@@ -15,9 +15,9 @@ 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.
4. The user optionally selects one related person from the existing Person list.
5. The system creates the Document.
6. If a person was selected or created, the system links that Person to the Document through DocumentPerson.
6. If a person was selected, the system links that Person to the Document through DocumentPerson with author role.
7. The user sees a success state and lands on the new Document detail page.
## 2. User Goal
@@ -46,9 +46,9 @@ The Document detail page is the page for one specific Document after it has been
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
3. a linked-author summary when available
4. document-scoped navigation links for Sources and Jobs
5. filtered views for sources and jobs linked to the current document
It should later support links to filtered views for:
1. jobs associated with the current document only
@@ -67,7 +67,8 @@ Expected UI affordance:
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.
3. Existing Person records should be selectable through a dropdown.
4. Text inputs are acceptable for the remaining fields in first release.
## 5. Create Document Form
@@ -124,12 +125,13 @@ The Create Document flow may optionally link one related person during first rel
| 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 |
| Related person | Person -> DocumentPerson | Dropdown select | No | Selects an existing Person and links as author when saved |
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.
3. The selected person is linked as author.
4. Additional people and recipient workflows are deferred to a future revision.
### 5.6 Related Records Not Created Directly Here
@@ -144,7 +146,7 @@ First release behavior:
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
2. change the associated Person from the Document edit flow
3. save the Document even if no person is linked
### 6.2 Data Model Interpretation
@@ -162,16 +164,13 @@ This means:
### 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.
1. Dropdown of existing Person records.
2. Clear display of the selected related person before submit.
3. Ability to change or clear the selected person in the Document edit flow.
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.
1. The user should create the Person first from the Person page.
2. The Document create flow only links existing Person records in first release.
## 7. Validation Rules