generated from john/python-template
230 lines
7.5 KiB
Markdown
230 lines
7.5 KiB
Markdown
# 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 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
|
|
|
|
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 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 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 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 occurs in job-create flow and dedicated Sources list/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. The user starts from a job-creation or job-configuration flow
|
|
2. The user can upload one or more files, or upload a whole folder
|
|
3. The system creates Source rows linked to the selected Document
|
|
4. The 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. The user can open the owning Document or Job context
|
|
|
|
### 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 and processing context.
|
|
|
|
### 6.2 Read Surface Expectations
|
|
|
|
The UI should show:
|
|
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
|
|
|
|
If source is missing:
|
|
1. Show clear not found or no source available messaging
|
|
|
|
If source metadata is partially unavailable:
|
|
1. Show fallback labels and keep navigation available where possible
|
|
|
|
## 7. Update Source Journey
|
|
|
|
### 7.1 User Intent
|
|
|
|
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 in Source detail
|
|
|
|
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 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
|
|
|
|
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 in a future delete flow
|
|
2. show cleanup guidance in a future delete flow
|
|
|
|
When allowed:
|
|
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
|
|
|
|
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
|
|
5. source delete UI with dependency-aware confirmation
|