# 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 job metadata and follows document-scoped links for Sources and Jobs.

## 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. document-scoped navigation links for the current Document
3. provider/model/prompt visibility when known
4. no delete action in first release

## 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 uses explicit /jobs/new creation
2. intended UX is explicit Create job from the Jobs page
3. current detail view is link-oriented and routes source review/editing through dedicated Source detail

## 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. document-scoped and job-scoped navigation links
4. source review entry through job-scoped Sources list

Source detail should show:
1. source metadata and preview
2. original transcription output per source
3. 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 Source detail reached from job-scoped Sources navigation

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 uses explicit guardrails:
1. deletion is blocked while status is processing
2. blocked delete explains constraints and offers back navigation
3. allowed delete requires explicit confirmation and then returns to Jobs list with success feedback

## 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