generated from john/python-template
UI update planning continued
This commit is contained in:
Jim Lancaster
@@ -0,0 +1,228 @@
|
||||
# Source User Journey
|
||||
|
||||
Purpose: Define how a user should interact with the UI to create and manage Source records, including page-level transcription context and revision behavior.
|
||||
|
||||
Scope: This document describes intended user interaction for the Source UI. It is the UX contract for the Source entity.
|
||||
|
||||
Companion schema mapping: schema-mapping.md
|
||||
Companion acceptance criteria: acceptance-criteria.md
|
||||
|
||||
## 1. Overview
|
||||
|
||||
A Source represents one page or file unit associated with a Document.
|
||||
|
||||
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.
|
||||
|
||||
## 2. User Goal
|
||||
|
||||
The user wants to:
|
||||
1. add page files to a Document
|
||||
2. ensure every source is attached to the transcription job context
|
||||
3. keep page order reliable
|
||||
4. review original machine output
|
||||
5. save human revisions per page
|
||||
6. navigate source pages efficiently
|
||||
|
||||
## 3. Page Model
|
||||
|
||||
### 3.1 Source List Surface
|
||||
|
||||
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.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
|
||||
|
||||
## 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
|
||||
|
||||
Current implementation note:
|
||||
1. source interaction currently occurs in upload and job-detail flows
|
||||
|
||||
## 5. Create Source Flow
|
||||
|
||||
### 5.1 User Intent
|
||||
|
||||
The user wants to attach one or more files to a Document so each page can be processed and reviewed.
|
||||
|
||||
### 5.2 Create from Job Context
|
||||
|
||||
1. user starts from a job-creation or job-configuration flow
|
||||
2. user can upload one or more files, or upload a whole folder
|
||||
3. system creates Source rows linked to the selected Document
|
||||
4. system creates JobSource links for the active Job as part of this flow
|
||||
5. source creation fails if required Document or Job linkage cannot be established
|
||||
|
||||
### 5.3 Source Create Inputs
|
||||
|
||||
| UI Label | Schema Field | Input Type | Required | Notes |
|
||||
|---|---|---|---|---|
|
||||
| Source files | upload_name/filename/file_path | Multi-file upload or folder upload | Yes | User may select one file, many files, or a folder |
|
||||
| Processing order | page_number assignment rule | System rule | Yes | If multiple files are uploaded, processing order is alphabetical by original filename |
|
||||
| Document reference | document_id | Hidden/context | Yes | Comes from selected Document |
|
||||
| Job reference | JobSource.job_id | Hidden/context | Yes | Required for first-release source creation |
|
||||
|
||||
### 5.4 Filename Strategy
|
||||
|
||||
1. store original user filename in upload_name
|
||||
2. store persisted filename using UUID plus original extension only, in the form UUID.extension
|
||||
3. this replaces the previous UUID-upload_name.extension pattern
|
||||
|
||||
### 5.5 Ordering Guidance
|
||||
|
||||
1. multi-file or folder uploads are processed alphabetically by original filename
|
||||
2. UI should show a warning or helper note so users understand that filename conventions control order
|
||||
|
||||
Suggested helper text:
|
||||
1. Files are processed alphabetically by original filename. Use leading numbers such as 001, 002, 003 to control page order.
|
||||
|
||||
### 5.6 System-Managed Values at Create
|
||||
|
||||
| Schema Field | User Editable | Notes |
|
||||
|---|---|---|
|
||||
| id | No | System-generated |
|
||||
| date_uploaded | No | System-generated |
|
||||
| raw_transcription | No | Filled later by processing |
|
||||
| revised_text | No | Initially empty |
|
||||
| date_revised | No | Initially null |
|
||||
|
||||
### 5.7 Expected Create Result
|
||||
|
||||
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. user can open preview and revision workflow
|
||||
|
||||
### 5.8 Source Creation Invariant
|
||||
|
||||
For first release:
|
||||
1. every new Source must have a Document link (Source.document_id)
|
||||
2. every new Source must have a Job link through JobSource (JobSource.job_id -> JobSource.source_id)
|
||||
3. source creation is treated as part of transcription workflow, not a standalone document-only upload path
|
||||
|
||||
## 6. Read Source Journey
|
||||
|
||||
### 6.1 User Intent
|
||||
|
||||
The user wants to view each page file and understand file identity, processing context, and revision status.
|
||||
|
||||
### 6.2 Read Surface Expectations
|
||||
|
||||
The UI should show:
|
||||
1. file preview for the current Source
|
||||
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
|
||||
|
||||
### 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
|
||||
|
||||
## 7. Update Source Journey
|
||||
|
||||
### 7.1 User Intent
|
||||
|
||||
The user primarily updates page-level revision text while preserving raw machine output.
|
||||
|
||||
### 7.2 Intended Editable Fields
|
||||
|
||||
Editable in first release:
|
||||
1. revised_text
|
||||
|
||||
Read-only in first release:
|
||||
1. upload_name
|
||||
2. filename
|
||||
3. file_path
|
||||
4. raw_transcription
|
||||
5. page_number
|
||||
6. date_uploaded
|
||||
7. date_revised set by system on revision save
|
||||
|
||||
### 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
|
||||
|
||||
### 7.4 Revision Failure Behavior
|
||||
|
||||
If save fails:
|
||||
1. show clear error feedback
|
||||
2. keep user input where possible
|
||||
3. allow retry
|
||||
|
||||
## 8. Delete Source Journey
|
||||
|
||||
### 8.1 User Intent
|
||||
|
||||
The user may need to remove incorrect or duplicate source files from a Document.
|
||||
|
||||
### 8.2 Guardrails
|
||||
|
||||
Delete is allowed when:
|
||||
1. policy allows removal of related processing history
|
||||
|
||||
Delete is blocked when:
|
||||
1. policy requires preserving dependent job-source execution records until explicit cleanup
|
||||
|
||||
### 8.3 Delete UX
|
||||
|
||||
When blocked:
|
||||
1. explain dependency constraints
|
||||
2. show cleanup guidance
|
||||
|
||||
When allowed:
|
||||
1. confirm permanent removal
|
||||
2. remove source
|
||||
3. return to source list with success state
|
||||
|
||||
## 9. Relationship to Other Workflows
|
||||
|
||||
Source workflow integrates with:
|
||||
1. Document workflow for ownership and page organization
|
||||
2. Job workflow for processing status and outputs
|
||||
3. revision workflow for human correction lifecycle
|
||||
|
||||
## 10. Relationship to Schema Mapping
|
||||
|
||||
The companion schema-mapping document should specify:
|
||||
1. field visibility per CRUD action
|
||||
2. current implementation status
|
||||
3. intended behavior
|
||||
4. gap-to-target items
|
||||
|
||||
## 11. Deferred Items
|
||||
|
||||
Deferred to future revisions:
|
||||
1. bulk page reordering UX
|
||||
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
|
||||
Reference in New Issue
Block a user