generated from john/python-template
UI update initial phase complete. Still need to create schema-mapping for the two many-to-many tables.
This commit is contained in:
Jim Lancaster
@@ -0,0 +1,286 @@
|
||||
# Job User Journey
|
||||
|
||||
Purpose: Define how a user should interact with the UI to create and manage a Job record, including document linking, source uploads, processing status, and page-level review.
|
||||
|
||||
Scope: This document describes intended user interaction for the Job UI. It is the UX contract for the Job entity.
|
||||
|
||||
Companion schema mapping: schema-mapping.md
|
||||
Companion acceptance criteria: acceptance-criteria.md
|
||||
|
||||
## 1. Overview
|
||||
|
||||
A Job represents one transcription run for a selected Document and one or more uploaded source files.
|
||||
|
||||
Managing a Job is run-first:
|
||||
1. The user opens the Jobs page.
|
||||
2. The user selects Create job.
|
||||
3. The user lands on a Job detail/create surface.
|
||||
4. The user links a Document and uploads one or more source files.
|
||||
5. The user submits for transcription.
|
||||
6. The system creates and processes the Job.
|
||||
7. The user reviews per-source output and saves revisions.
|
||||
|
||||
## 2. User Goal
|
||||
|
||||
The user wants to:
|
||||
1. see all jobs in one place
|
||||
2. create a new transcription run intentionally
|
||||
3. attach the run to the correct Document
|
||||
4. upload source file(s) for that run
|
||||
5. submit and monitor processing state
|
||||
6. review and revise page-level outputs
|
||||
|
||||
## 3. Page Model
|
||||
|
||||
### 3.1 Jobs List Page
|
||||
|
||||
The Jobs page is the primary UI surface where users manage jobs.
|
||||
|
||||
It should support:
|
||||
1. listing all jobs
|
||||
2. searching or filtering jobs
|
||||
3. opening job detail for any row
|
||||
4. starting Create job
|
||||
5. clear empty state when no jobs exist
|
||||
|
||||
### 3.2 Job Detail/Create Page
|
||||
|
||||
The Job detail/create page is used for both creating a new Job and viewing an existing Job.
|
||||
|
||||
Create mode should include:
|
||||
1. document selection
|
||||
2. source upload controls
|
||||
3. submit for transcription action
|
||||
|
||||
Detail mode should include:
|
||||
1. job metadata and status
|
||||
2. per-source processing state
|
||||
3. original transcription output
|
||||
4. revision editor and save actions
|
||||
|
||||
## 4. Entry Points
|
||||
|
||||
Primary entry points:
|
||||
1. from Jobs page, Create job
|
||||
2. from Jobs page row selection, open existing Job detail
|
||||
|
||||
Current implementation note:
|
||||
1. current code path is upload-first and auto-creates Job records
|
||||
2. intended UX is explicit Create job from the Jobs page
|
||||
|
||||
## 5. Create Job Flow
|
||||
|
||||
### 5.1 User Intent
|
||||
|
||||
The user wants to start a transcription run by selecting the right Document and providing source files in one guided flow.
|
||||
|
||||
### 5.2 Create Entry
|
||||
|
||||
1. user opens the Jobs page
|
||||
2. user selects Create job
|
||||
3. system opens Job detail/create page in create mode
|
||||
|
||||
### 5.3 Create Inputs
|
||||
|
||||
| UI Label | Schema Area | Input Type | Required | Notes |
|
||||
|---|---|---|---|---|
|
||||
| Document | Job.document_id | Select/search | Yes | Links the run to one Document |
|
||||
| Source files | Source upload fields | Multi-file upload or folder upload | Yes | User may select one file, many files, or a folder |
|
||||
| Processing order | Source.page_number assignment rule | System rule | Yes | If multiple files are uploaded, order is alphabetical by original filename |
|
||||
| Provider | Job.provider | Display or select | No | Visible to user when known; selectable when options are available |
|
||||
| Model | Job.model | Display or select | No | Visible to user when known; selectable when options are available |
|
||||
| Prompt | Job.prompt_name | Display or select | No | Visible to user when known; selectable when options are available |
|
||||
|
||||
### 5.4 Source Handling Rules
|
||||
|
||||
1. each uploaded file becomes a Source linked to the selected Document
|
||||
2. each created Source is linked to the Job through JobSource
|
||||
3. multi-file or folder uploads are processed alphabetically by original filename
|
||||
4. upload_name stores the original filename
|
||||
5. stored filename uses UUID plus original extension in the form UUID.extension
|
||||
|
||||
Suggested helper text:
|
||||
1. Files are processed alphabetically by original filename. Use leading numbers such as 001, 002, 003 to control page order.
|
||||
|
||||
### 5.5 Validation Rules
|
||||
|
||||
Create submission must be blocked when:
|
||||
1. no Document is selected
|
||||
2. no source file is uploaded
|
||||
|
||||
Create submission should provide clear feedback when:
|
||||
1. uploaded files are invalid or unreadable
|
||||
2. persistence fails for Job, Source, or JobSource linkage
|
||||
|
||||
### 5.6 Submission Behavior
|
||||
|
||||
On submit:
|
||||
1. validate create inputs
|
||||
2. create Job record linked to selected Document
|
||||
3. create Source records for uploaded files
|
||||
4. create JobSource links for each Source in the Job
|
||||
5. queue processing for transcription
|
||||
6. route user to Job detail mode
|
||||
|
||||
Recommended transactional behavior:
|
||||
1. intended create writes should succeed or fail together
|
||||
2. user should not receive false success when required records fail
|
||||
|
||||
### 5.7 Create Success Result
|
||||
|
||||
After successful create:
|
||||
1. job appears in Jobs list
|
||||
2. job detail shows selected Document and created source set
|
||||
3. status appears as queued or processing based on execution timing
|
||||
4. user can monitor progress and open page-level review
|
||||
|
||||
### 5.8 Create Failure Result
|
||||
|
||||
If create fails:
|
||||
1. show clear error message
|
||||
2. preserve entered selections where possible
|
||||
3. keep retry path available
|
||||
4. do not show false success feedback
|
||||
|
||||
## 6. Read Job Journey
|
||||
|
||||
### 6.1 User Intent
|
||||
|
||||
The user wants to quickly understand what the job is, its current status, and which source pages need review.
|
||||
|
||||
### 6.2 Jobs List Expectations
|
||||
|
||||
The Jobs list should show, at minimum:
|
||||
1. job identifier
|
||||
2. document context
|
||||
3. current status
|
||||
4. creation or update timestamp
|
||||
5. quick action to open detail
|
||||
|
||||
Optional first-release columns if available:
|
||||
1. retry count
|
||||
2. provider/model summary
|
||||
|
||||
### 6.3 Job Detail Expectations
|
||||
|
||||
The Job detail should show:
|
||||
1. job status and summary metadata
|
||||
2. selected Document context
|
||||
3. per-source status (pending, transcribed, failed)
|
||||
4. original transcription output per source
|
||||
5. revision editor and latest revised content
|
||||
|
||||
### 6.4 Read Empty and Missing States
|
||||
|
||||
If no jobs exist:
|
||||
1. list shows no jobs yet empty state
|
||||
2. list shows Create job action
|
||||
|
||||
If a job id is invalid or missing:
|
||||
1. show clear not found state
|
||||
2. do not crash the page
|
||||
|
||||
If a job has no source items due to failure:
|
||||
1. show clear warning state
|
||||
2. keep recovery guidance visible
|
||||
|
||||
## 7. Job Status Lifecycle UX
|
||||
|
||||
### 7.1 Status Values
|
||||
|
||||
The UI should map to model-backed job states:
|
||||
1. queued
|
||||
2. processing
|
||||
3. transcribed
|
||||
4. completed
|
||||
5. partial_success
|
||||
6. failed
|
||||
|
||||
### 7.2 In-Progress States
|
||||
|
||||
When status is queued or processing:
|
||||
1. show active progress state
|
||||
2. keep detail page refresh-safe
|
||||
3. indicate that source-level results may still be arriving
|
||||
|
||||
### 7.3 Terminal States
|
||||
|
||||
When status is completed:
|
||||
1. show completion success state
|
||||
2. direct user to revision workflow
|
||||
|
||||
When status is partial_success:
|
||||
1. show mixed outcome state
|
||||
2. identify failed pages
|
||||
3. guide user to review available successful pages and retry strategy
|
||||
|
||||
When status is failed:
|
||||
1. show failure state with actionable message
|
||||
2. keep navigation and retry guidance available
|
||||
|
||||
## 8. Update Job Journey
|
||||
|
||||
### 8.1 User Intent
|
||||
|
||||
The user primarily updates job-related review outcomes by editing revised transcription text per source page.
|
||||
|
||||
### 8.2 First-Release Editable Scope
|
||||
|
||||
Editable in first release:
|
||||
1. source-level revised_text through job detail review
|
||||
|
||||
Read-only in first release:
|
||||
1. Job.document_id after create
|
||||
2. job status values managed by processing workflow
|
||||
3. provider/model/prompt values may be system-managed, but should remain visible in UI when known
|
||||
|
||||
### 8.3 Update Save Behavior
|
||||
|
||||
On revision save:
|
||||
1. validate revised text
|
||||
2. persist revised text for selected source
|
||||
3. update revised timestamp fields by system policy
|
||||
4. show success feedback
|
||||
|
||||
On save failure:
|
||||
1. show clear error feedback
|
||||
2. preserve entered text where possible
|
||||
3. allow retry
|
||||
|
||||
## 9. Delete and Retention Policy
|
||||
|
||||
### 9.1 User Intent
|
||||
|
||||
The user may need to remove invalid or duplicate jobs safely.
|
||||
|
||||
### 9.2 First-Release Policy
|
||||
|
||||
Delete behavior is policy-controlled:
|
||||
1. deletion may be blocked when related JobSource or source history must be retained
|
||||
2. blocked delete must explain constraints and cleanup path
|
||||
3. if allowed, delete requires explicit confirmation
|
||||
|
||||
## 10. Relationship to Other Workflows
|
||||
|
||||
Job workflow integrates with:
|
||||
1. Document workflow for ownership context
|
||||
2. Source workflow for uploaded page records and ordering
|
||||
3. Revision workflow for human correction lifecycle
|
||||
4. Worker processing workflow for queued execution and status transitions
|
||||
|
||||
## 11. 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
|
||||
|
||||
## 12. Deferred Items
|
||||
|
||||
Deferred to future revisions:
|
||||
1. manual retry controls from job detail
|
||||
2. advanced provider/model/prompt policy controls beyond basic create-time visibility
|
||||
3. advanced bulk actions across multiple jobs
|
||||
4. live streaming progress updates beyond refresh-based updates
|
||||
5. job templates or preset configurations
|
||||
Reference in New Issue
Block a user