generated from john/python-template
287 lines
8.6 KiB
Markdown
287 lines
8.6 KiB
Markdown
# 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. The user opens the Jobs page
|
|
2. The user selects Create job
|
|
3. The 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. The 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. The 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
|