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

UI slog grinds on

Browse Source
This commit is contained in:
Jim Lancaster
2026-08-02 23:44:53 -05:00
parent c098013a68
commit 47aef0e26e
13 changed files with 192 additions and 162 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ui/entities/source/acceptance-criteria.md
+14 -14
View File
@@ -59,14 +59,14 @@ This checklist does not cover:
## Read Acceptance Criteria
### RD-1 Source detail retrieval
1. Given a valid Source id in source context, typically via a document-scoped source list in first release
2. When the user opens source detail or equivalent panel
3. Then source metadata and preview are displayed for that source only if the detail UI exists in a later revision
1. Given a valid Source id in source context
2. When the user opens source detail
3. Then source metadata and preview are displayed for that source only
### RD-2 Transcription and revision visibility
1. Original transcription context is visible read-only when the revision UI exists
2. Revision state is visible when the revision UI exists
3. If revised_text is absent, no revision yet messaging is shown when the revision UI exists
1. Original transcription context is visible read-only in Source detail
2. Revision state is visible in Source detail
3. If revised_text is absent, revision input opens as empty and can be edited
### RD-3 Missing source state
1. Given a missing source
@@ -77,29 +77,29 @@ This checklist does not cover:
### UP-1 Revision editing entry
1. Given a source context
2. When the user enters revision edit flow
3. Then revised_text input is available in a later revision of the UI
3. Then revised_text input is available in Source detail
### UP-2 Revision validation
1. revised_text cannot be saved as empty after trimming when the revision UI exists
2. Warning feedback is shown for invalid empty input when the revision UI exists
1. revised_text cannot be saved as empty after trimming
2. Warning feedback is shown for invalid empty input
### UP-3 Successful revision save
1. Given valid revision text
2. When the user saves in a later revision of the UI
2. When the user saves
3. Then revised_text persists
4. Then date_revised is updated
5. Then success feedback is shown
6. Then refreshed revision content is visible
### UP-4 Revision save failure
1. Given backend failure during save in a later revision of the UI
1. Given backend failure during save
2. Then clear error feedback is shown
3. Then the user-entered text remains available for retry where possible
## Delete Acceptance Criteria
### DL-1 Delete entry and confirmation
1. Given a source in source context, typically via a later source detail view
1. Given a source in source context
2. When the user selects delete source
3. Then a permanent-action confirmation dialog appears
@@ -135,7 +135,7 @@ This checklist does not cover:
2. No acceptance criterion contradicts first-release deferred items
### QG-3 First-release constraints
1. Source interaction may remain job-detail-centric initially
1. Source creation remains job-create-centric
2. revised_text is the primary editable source field in first release
3. source creation requires both Document linkage and Job linkage at create time
4. richer source management surfaces are phased in later
4. source delete management surfaces are phased in later
docs/ui/entities/source/schema-mapping.md
+25 -25
View File
@@ -32,7 +32,7 @@ This document uses three lenses:
| filename | str | No | None | Shown read-only | Stored filename |
| file_path | str | No | None | Usually hidden; preview uses path internally | Filesystem path |
| raw_transcription | str | Yes | None | Shown indirectly or hidden | Immutable machine output context |
| revised_text | str | Yes | None | Hidden in current simplified UI | Human-authored correction |
| revised_text | str | Yes | None | Editable in Source detail | Human-authored correction |
| date_uploaded | datetime | No | datetime.now(UTC) | Shown read-only | System-managed timestamp |
| date_revised | datetime | Yes | None | Shown read-only | Set when revision is saved |
@@ -66,8 +66,8 @@ Current backend path: job create submit -> create_job_for_document()
| Field | Current Value at Create | Source | Visible to User | Evidence |
|---|---|---|---|---|
| id | Generated UUID | System | No | Source model default in src/transcription/db/models.py |
| document_id | Created Document id | Service | Indirectly | src/transcription/services/store.py |
| page_number | 1 | Service default in upload flow | No | src/transcription/services/store.py |
| document_id | Selected existing Document id | Job create selection + service write | Indirectly | src/transcription/ui/pages/jobs_page.py, src/transcription/services/store.py |
| page_number | Sequential assignment based on existing max and alphabetical upload order | Service | No | src/transcription/services/store.py |
| upload_name | original filename basename | User file name transformed by service | Indirectly | src/transcription/services/store.py |
| filename | stored generated filename | Service | Indirectly | src/transcription/services/store.py |
| file_path | stored path | Service | Indirectly | src/transcription/services/store.py |
@@ -78,11 +78,11 @@ Current backend path: job create submit -> create_job_for_document()
### 4.3 Gap to Target
To satisfy intended Create flow, implementation must add:
To satisfy intended Create flow, implementation now includes:
1. multi-source and folder upload support in job create/configure flows
2. deterministic page_number assignment from alphabetical original filename ordering
3. enforced create-time Source-to-Document and Source-to-Job linkage invariants
4. complete filename storage policy migration to UUID.extension only
4. filename storage policy using UUID.extension
## 5. READ Mapping
@@ -96,33 +96,33 @@ On Source detail/list surfaces, users should be able to see:
### 5.2 Current Implementation
Current Source reading is primarily embedded in a document-scoped source list and job create/navigation flow.
Current Source reading is centered on dedicated Sources list/detail routes with optional document/job filtering.
| Field | Current Rendering | Visible to User | Notes | Evidence |
|---|---|---|---|---|
| upload_name | Shown in document-scoped source list | Yes | Displayed in source list context | src/transcription/ui/pages/documents_page.py |
| filename | Shown in document-scoped source list | Yes | Source metadata shown in list | src/transcription/ui/pages/documents_page.py |
| file_path | Hidden from current simplified UI | No | Operational path remains internal | current UI pages |
| page_number | Shown in document-scoped source list | Yes | Ordering visible in document source list | src/transcription/ui/pages/documents_page.py |
| raw_transcription | Not shown in current simplified UI | No | Source preview/revision UI deferred | current UI pages |
| revised_text | Not shown in current simplified UI | No | Source revision UI deferred | current UI pages |
| date_uploaded | Not shown in current simplified UI | No | Operational metadata only | current UI pages |
| date_revised | Not shown in current simplified UI | No | Operational metadata only | current UI pages |
| upload_name | Shown in Sources list and Source detail | Yes | Displayed in source context | src/transcription/ui/pages/sources_page.py |
| filename | Shown in Sources list and Source detail | Yes | Source metadata shown in list/detail | src/transcription/ui/pages/sources_page.py |
| file_path | Hidden from direct text rendering | No | Used internally for preview rendering | src/transcription/ui/components/document_panzoom.py |
| page_number | Shown in Sources list and Source detail | Yes | Ordering visible in filtered/global list | src/transcription/ui/pages/sources_page.py |
| raw_transcription | Shown read-only in Source detail | Yes | Read from latest linked JobSource context | src/transcription/ui/pages/sources_page.py |
| revised_text | Shown and editable in Source detail | Yes | Saved through revision action | src/transcription/ui/pages/sources_page.py |
| date_uploaded | Shown in Source detail | Yes | Read-only metadata | src/transcription/ui/pages/sources_page.py |
| date_revised | Shown in Source detail | Yes | Read-only metadata after revision save | src/transcription/ui/pages/sources_page.py |
### 5.3 Gap to Target
To satisfy intended Read flow, implementation must add:
1. richer source detail and revision surfaces if the review workflow returns later
2. optional page-specific navigation if needed beyond the document-scoped list
1. optional list filtering controls in-page (current filtering is URL/context based)
2. optional page-specific navigation enhancements beyond current list/detail pattern
## 6. UPDATE Mapping
### 6.1 Intended Update Behavior
Primary user update for Source is revised_text maintenance in the service layer; the current UI does not expose this flow.
Primary user update for Source is revised_text maintenance in Source detail.
Intended editable fields (first release):
- revised_text, if the revision UI is restored later
- revised_text
Intended read-only fields (first release):
- document_id
@@ -138,16 +138,15 @@ Intended read-only fields (first release):
| Field | Updatable via UI | Updatable via Service | Notes |
|---|---|---|---|
| revised_text | No | Yes | Saved via TranscriptionService.upsert_revision_for_source(), but not exposed in current UI |
| revised_text | Yes | Yes | Saved via TranscriptionService.upsert_revision_for_source() from Source detail |
| date_revised | No | Yes | Set automatically on revision save |
| other fields | No | Technically yes in service layer | No first-class UI editing flow |
### 6.3 Gap to Target
Implementation should add in a later revision:
1. explicit Source edit boundaries in dedicated Source UI
2. validation and save UX for revisions in document-scoped source views
3. optional future controls for page ordering and metadata corrections
1. optional future controls for page ordering and metadata corrections
2. revision history and conflict-resolution UX beyond single revised_text updates
## 7. DELETE Mapping
@@ -192,9 +191,10 @@ Schema and models:
Current implementation:
- src/transcription/services/store.py
- src/transcription/services/transcription.py
- src/transcription/ui/pages/sources_page.py
- src/transcription/ui/pages/jobs_page.py
- src/transcription/ui/components/transcript.py
- src/transcription/ui/components/job_detail.py
- src/transcription/ui/pages/documents_page.py
- src/transcription/ui/components/document_panzoom.py
Companion UX spec:
- docs/ui/entities/source/user-journey.md
@@ -207,6 +207,6 @@ Acceptance checklist:
- Every Source schema field appears in the field inventory.
- Intended Create behavior matches the companion user journey.
- Source create invariant requires both Document linkage and Job linkage at create time.
- Current behavior reflects upload-centric and job-detail-centric implementation.
- Current behavior reflects upload-centric create flow and dedicated Sources list/detail review flow.
- Gaps between intended and current behavior are explicit.
- Read, Update, and Delete sections distinguish target behavior from current code.
docs/ui/entities/source/user-journey.md
+22 -12
View File
@@ -15,7 +15,8 @@ Managing Source records is page-first:
1. The user starts from a transcription job flow.
2. The user adds one or more source files.
3. The system creates Source records linked to the Document and linked to the Job through JobSource.
4. The user reviews source lists by document and can navigate to the owning Document or Job.
4. The user reviews source lists from a dedicated Sources page.
5. The user opens Source detail to review preview, metadata, transcription text, and revision text.
## 2. User Goal
@@ -32,22 +33,29 @@ The user wants to:
### 3.1 Source List Surface
A Source list surface should support:
1. listing source pages for a selected Document
1. listing source pages globally or filtered by selected Document or Job
2. sorting by page_number
3. opening the owning Document or Job context
4. opening Source detail for a selected source
### 3.2 Source Detail Surface
Source detail and revision surfaces are deferred in the current UI.
Source detail supports:
1. pan/zoom image or PDF preview
2. read-only source metadata (page number, names, timestamps)
3. read-only original transcription text
4. editable revision text with save action
## 4. Entry Points
Primary entry points:
1. from Job workflow, Add sources while creating or configuring a job
2. from Job detail, open source preview and revision editor
2. from Job detail, open filtered Sources for the current Job
3. from Document detail, open filtered Sources for the current Document
4. from global navigation, open all Sources
Current implementation note:
1. source interaction currently occurs in job-create and document-scoped source list flows
1. source interaction occurs in job-create flow and dedicated Sources list/detail flows
## 5. Create Source Flow
@@ -120,11 +128,12 @@ The user wants to view each page file and understand file identity and processin
### 6.2 Read Surface Expectations
The UI should show:
1. source lists grouped by Document
1. source lists for current context (all, document-filtered, or job-filtered)
2. upload_name as the original user-provided filename
3. filename as the stored system filename
4. page_number and ordering context
5. the owning Document and Job navigation context
6. direct action to open Source detail
### 6.3 Read Empty and Missing States
@@ -143,7 +152,7 @@ The user primarily tracks page-level source records while preserving raw machine
### 7.2 Intended Editable Fields
Editable in first release:
1. revised_text in a later revision, not in the current simplified UI
1. revised_text in Source detail
Read-only in first release:
1. upload_name
@@ -157,11 +166,11 @@ Read-only in first release:
### 7.3 Revision Save Behavior
On save:
1. validate revision text is non-empty when the revision UI exists in a later release
2. persist revised_text when the revision UI exists
3. set date_revised when the revision UI exists
4. show success feedback when the revision UI exists
5. keep user in current source context when the revision UI exists
1. validate revision text is non-empty after trimming
2. persist revised_text
3. set date_revised
4. show success feedback
5. keep user in current source context
### 7.4 Revision Failure Behavior
@@ -217,3 +226,4 @@ Deferred to future revisions:
2. multi-file upload progress and resumable upload UX
3. revision history versions beyond a single revised_text field
4. richer per-page status dashboards
5. source delete UI with dependency-aware confirmation