transcription/docs/ui/entities/job/user-journey.md

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