generated from john/python-template
UI update planning continued
This commit is contained in:
Jim Lancaster
@@ -0,0 +1,213 @@
|
||||
# Source Schema-to-UI Mapping
|
||||
|
||||
Purpose: Map the Source schema to the UI, while clearly separating intended target behavior from current implementation.
|
||||
|
||||
Companion document: user-journey.md
|
||||
Acceptance criteria: acceptance-criteria.md
|
||||
|
||||
## 1. Entity Snapshot
|
||||
|
||||
- Table: Source
|
||||
- Primary key: id (UUID)
|
||||
- Related entities: Document, JobSource, Job
|
||||
- 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 |
|
||||
| document_id | UUID FK | No | None | Hidden/context-managed | Selected Document context |
|
||||
| page_number | int | No | 1 | Shown read-only or ordered list | Sequential ordering |
|
||||
| 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 |
|
||||
| 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 |
|
||||
|
||||
## 4. CREATE Mapping
|
||||
|
||||
### 4.1 Intended Create Flow
|
||||
|
||||
Entry point: Job creation or job configuration Add sources action
|
||||
User action: upload one or more source files, or a whole folder
|
||||
Success destination: source preview or revision flow in job detail context
|
||||
|
||||
| Field | Intended User Input | Required | Visible | Notes |
|
||||
|---|---|---|---|---|
|
||||
| document_id | Hidden/context | Yes | No | Comes from selected Document |
|
||||
| JobSource.job_id | Hidden/context | Yes | No | Comes from active Job; required for first release |
|
||||
| page_number | Auto or user-assisted ordering | Yes | Indirectly | Should preserve sequence |
|
||||
| upload_name | File picker name | Yes | Yes | Original display name |
|
||||
| filename | None | Yes | No or read-only | System-stored as UUID.extension |
|
||||
| file_path | None | Yes | No | Storage path |
|
||||
| raw_transcription | None | No | No | Filled by processing |
|
||||
| revised_text | None | No | No | Initially empty |
|
||||
| date_uploaded | None | No | No | System-generated |
|
||||
| date_revised | None | No | No | Null until revision |
|
||||
|
||||
### 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
|
||||
|
||||
| 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 |
|
||||
| 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 |
|
||||
| raw_transcription | None initially | System | No at create | Source model defaults |
|
||||
| revised_text | None initially | System | No at create | Source model defaults |
|
||||
| date_uploaded | current UTC timestamp | System | No | Source model default |
|
||||
| date_revised | None | System | No | Source model default |
|
||||
|
||||
### 4.3 Gap to Target
|
||||
|
||||
To satisfy intended Create flow, implementation must add:
|
||||
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
|
||||
|
||||
## 5. READ Mapping
|
||||
|
||||
### 5.1 Intended Read Behavior
|
||||
|
||||
On Source detail/list surfaces, users should be able to see:
|
||||
1. source page preview
|
||||
2. source metadata and ordering
|
||||
3. revision state
|
||||
4. original transcription context
|
||||
|
||||
### 5.2 Current Implementation
|
||||
|
||||
Current Source reading is primarily embedded in job detail.
|
||||
|
||||
| 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 |
|
||||
|
||||
### 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
|
||||
|
||||
## 6. UPDATE Mapping
|
||||
|
||||
### 6.1 Intended Update Behavior
|
||||
|
||||
Primary user update for Source is revised_text maintenance.
|
||||
|
||||
Intended editable fields (first release):
|
||||
- revised_text
|
||||
|
||||
Intended read-only fields (first release):
|
||||
- document_id
|
||||
- page_number
|
||||
- upload_name
|
||||
- filename
|
||||
- file_path
|
||||
- raw_transcription
|
||||
- date_uploaded
|
||||
- date_revised
|
||||
|
||||
### 6.2 Current Implementation
|
||||
|
||||
| Field | Updatable via UI | Updatable via Service | Notes |
|
||||
|---|---|---|---|
|
||||
| revised_text | Yes | Yes | Saved via TranscriptionService.upsert_revision_for_source() |
|
||||
| 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:
|
||||
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
|
||||
|
||||
## 7. DELETE Mapping
|
||||
|
||||
### 7.1 Intended Delete Behavior
|
||||
|
||||
Source deletion should include dependency-aware guardrails.
|
||||
|
||||
Rules:
|
||||
1. Deletion can proceed when policy allows cleanup of related JobSource records.
|
||||
2. If related execution history must be preserved first, deletion is blocked with guidance.
|
||||
|
||||
### 7.2 Current Implementation
|
||||
|
||||
| Action | UI Exposed | Backend Capability | Notes |
|
||||
|---|---|---|---|
|
||||
| Delete Source | No | Yes | TranscriptionService.delete_source() exists, no dedicated UI delete flow |
|
||||
|
||||
### 7.3 Gap to Target
|
||||
|
||||
Implementation must add:
|
||||
1. source delete controls in source/document context UI
|
||||
2. dependency checks for JobSource links
|
||||
3. blocked-delete messaging and cleanup path guidance
|
||||
4. confirmation UX for successful delete attempts
|
||||
|
||||
## 8. Hidden and System-Managed Fields
|
||||
|
||||
| Field | Category | Why Hidden or Protected |
|
||||
|---|---|---|
|
||||
| id | System-managed | Internal identifier |
|
||||
| document_id | Context-managed | Derived from selected document context |
|
||||
| file_path | Operational/internal | Used for file storage and preview plumbing |
|
||||
| date_uploaded | System-managed | Audit timestamp |
|
||||
| date_revised | System-managed | Revision timestamp set by system |
|
||||
|
||||
## 9. Traceability Anchors
|
||||
|
||||
Schema and models:
|
||||
- docs/schema_v2.md
|
||||
- src/transcription/db/models.py
|
||||
|
||||
Current implementation:
|
||||
- src/transcription/services/store.py
|
||||
- src/transcription/services/transcription.py
|
||||
- src/transcription/ui/pages/jobs_page.py
|
||||
- src/transcription/ui/components/transcript.py
|
||||
- src/transcription/ui/components/job_detail.py
|
||||
|
||||
Companion UX spec:
|
||||
- docs/ui/entities/source/user-journey.md
|
||||
|
||||
Acceptance checklist:
|
||||
- docs/ui/entities/source/acceptance-criteria.md
|
||||
|
||||
## 10. Acceptance Checklist Summary
|
||||
|
||||
- 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.
|
||||
- Gaps between intended and current behavior are explicit.
|
||||
- Read, Update, and Delete sections distinguish target behavior from current code.
|
||||
Reference in New Issue
Block a user