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/source/acceptance-criteria.md
+11 -11
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 job detail in first release
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
3. Then source metadata and preview are displayed for that source only if the detail UI exists in a later revision
### RD-2 Transcription and revision visibility
1. Original transcription context is visible read-only
2. Revision state is visible
3. If revised_text is absent, no revision yet messaging is shown
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
### 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
3. Then revised_text input is available in a later revision of the UI
### UP-2 Revision validation
1. revised_text cannot be saved as empty after trimming
2. Warning feedback is shown for invalid empty input
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
### UP-3 Successful revision save
1. Given valid revision text
2. When the user saves
2. When the user saves in a later revision of the UI
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
1. Given backend failure during save in a later revision of the UI
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 job detail in first release
1. Given a source in source context, typically via a later source detail view
2. When the user selects delete source
3. Then a permanent-action confirmation dialog appears
docs/ui/entities/source/schema-mapping.md
+22 -23
View File
@@ -31,8 +31,8 @@ This document uses three lenses:
| upload_name | str | No | None | Shown read-only after upload | Original user-provided name |
| 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 read-only | Immutable machine output context |
| revised_text | str | Yes | None | Shown editable | Human-authored correction |
| 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 |
| 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 |
@@ -59,9 +59,9 @@ Success destination: source preview or revision flow in job detail context
### 4.2 Current Implementation
Current entry point: upload page through create_upload_job()
Current user action: upload one file through upload flow
Current backend path: upload submit -> create_upload_job -> _create_upload_records
Current entry point: Jobs page create flow
Current user action: upload one or more files or a folder through a single upload widget
Current backend path: job create submit -> create_job_for_document()
| Field | Current Value at Create | Source | Visible to User | Evidence |
|---|---|---|---|---|
@@ -96,34 +96,33 @@ On Source detail/list surfaces, users should be able to see:
### 5.2 Current Implementation
Current Source reading is primarily embedded in job detail.
Current Source reading is primarily embedded in a document-scoped source list and job create/navigation flow.
| Field | Current Rendering | Visible to User | Notes | Evidence |
|---|---|---|---|---|
| upload_name | Shown in source-related UI | Yes | Displayed in job detail source context | src/transcription/ui/components/job_detail.py |
| filename | Indirectly shown in jobs list/detail | Yes | Via Job.filename and source metadata | src/transcription/ui/components/table/jobs.py, src/transcription/ui/pages/jobs_page.py |
| file_path | Used for preview rendering | Indirectly | Source preview in job detail page | src/transcription/ui/pages/jobs_page.py |
| page_number | Not explicitly rendered in current jobs page flow | Limited | Ordering implicit via selected source | jobs page flow |
| raw_transcription | Rendered from JobSource context | Yes | Original transcription card | src/transcription/ui/components/transcript.py |
| revised_text | Rendered/editable in revision editor | Yes | Revision editor in job detail page | src/transcription/ui/pages/jobs_page.py |
| date_uploaded | Limited visibility | Partial | Shown in some source metadata components | src/transcription/ui/components/job_detail.py |
| date_revised | Indirect via revision row timestamp | Partial | Used in revision caption | src/transcription/ui/components/transcript.py |
| 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 |
### 5.3 Gap to Target
To satisfy intended Read flow, implementation must add:
1. dedicated Source list and detail surfaces under Document context
2. explicit page_number presentation and navigation
3. clearer source metadata display independent of Job-centric pages
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
## 6. UPDATE Mapping
### 6.1 Intended Update Behavior
Primary user update for Source is revised_text maintenance.
Primary user update for Source is revised_text maintenance in the service layer; the current UI does not expose this flow.
Intended editable fields (first release):
- revised_text
- revised_text, if the revision UI is restored later
Intended read-only fields (first release):
- document_id
@@ -139,13 +138,13 @@ Intended read-only fields (first release):
| Field | Updatable via UI | Updatable via Service | Notes |
|---|---|---|---|
| revised_text | Yes | Yes | Saved via TranscriptionService.upsert_revision_for_source() |
| revised_text | No | Yes | Saved via TranscriptionService.upsert_revision_for_source(), but not exposed in current UI |
| 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:
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
@@ -154,7 +153,7 @@ Implementation should add:
### 7.1 Intended Delete Behavior
Source deletion should include dependency-aware guardrails.
Source deletion is deferred in the current UI.
Rules:
1. Deletion can proceed when policy allows cleanup of related JobSource records.
@@ -168,7 +167,7 @@ Rules:
### 7.3 Gap to Target
Implementation must add:
Implementation should add in a future revision:
1. source delete controls in source/document context UI
2. dependency checks for JobSource links
3. blocked-delete messaging and cleanup path guidance
docs/ui/entities/source/user-journey.md
+22 -31
View File
@@ -15,7 +15,7 @@ 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 original transcription output and can maintain revised text.
4. The user reviews source lists by document and can navigate to the owning Document or Job.
## 2. User Goal
@@ -34,15 +34,11 @@ The user wants to:
A Source list surface should support:
1. listing source pages for a selected Document
2. sorting by page_number
3. opening a source detail or revision view
3. opening the owning Document or Job context
### 3.2 Source Detail Surface
A Source detail surface should show:
1. file preview (image or PDF)
2. source metadata
3. original transcription context
4. revision editor and revision state
Source detail and revision surfaces are deferred in the current UI.
## 4. Entry Points
@@ -51,7 +47,7 @@ Primary entry points:
2. from Job detail, open source preview and revision editor
Current implementation note:
1. source interaction currently occurs in upload and job-detail flows
1. source interaction currently occurs in job-create and document-scoped source list flows
## 5. Create Source Flow
@@ -106,7 +102,7 @@ After successful source create:
1. Source is linked to the Document
2. Source appears in page order derived from alphabetical upload filename ordering
3. Source is linked to the Job through JobSource at create time
4. The user can open preview and revision workflow
4. The user can open the owning Document or Job context
### 5.8 Source Creation Invariant
@@ -119,40 +115,35 @@ For first release:
### 6.1 User Intent
The user wants to view each page file and understand file identity, processing context, and revision status.
The user wants to view each page file and understand file identity and processing context.
### 6.2 Read Surface Expectations
The UI should show:
1. file preview for the current Source
1. source lists grouped by Document
2. upload_name as the original user-provided filename
3. filename as the stored system filename
4. file_path information, with the option to keep it internal or partially hidden for safety
5. page_number and ordering context
6. whether revised_text exists
7. original transcription output context
4. page_number and ordering context
5. the owning Document and Job navigation context
### 6.3 Read Empty and Missing States
If source is missing:
1. Show clear not found or no source available messaging
If source has no revision:
1. Show empty-state guidance and create-revision action
If source metadata is partially unavailable:
1. Show fallback labels and keep preview and revision actions available where possible
1. Show fallback labels and keep navigation available where possible
## 7. Update Source Journey
### 7.1 User Intent
The user primarily updates page-level revision text while preserving raw machine output.
The user primarily tracks page-level source records while preserving raw machine output in the service layer.
### 7.2 Intended Editable Fields
Editable in first release:
1. revised_text
1. revised_text in a later revision, not in the current simplified UI
Read-only in first release:
1. upload_name
@@ -166,11 +157,11 @@ Read-only in first release:
### 7.3 Revision Save Behavior
On save:
1. validate revision text is non-empty
2. persist revised_text
3. set date_revised
4. show success feedback
5. keep user in current source context
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
### 7.4 Revision Failure Behavior
@@ -196,13 +187,13 @@ Delete is blocked when:
### 8.3 Delete UX
When blocked:
1. explain dependency constraints
2. Show cleanup guidance
1. explain dependency constraints in a future delete flow
2. show cleanup guidance in a future delete flow
When allowed:
1. confirm permanent removal
2. remove source
3. return to source list with success state
1. confirm permanent removal in a future delete flow
2. remove source in a future delete flow
3. return to source list with success state in a future delete flow
## 9. Relationship to Other Workflows