transcription/docs/ui/entities/job/acceptance-criteria.md

Job Acceptance Criteria

Purpose: Define implementation-ready acceptance criteria for Job Create, Read, Update, and Delete workflows.

Companion documents:

• docs/ui/entities/job/user-journey.md
• docs/ui/entities/job/schema-mapping.md

Scope

This checklist covers:

1. Create flow
2. Read flow
3. Update flow
4. Delete flow

This checklist does not cover:

1. provider-specific transcription internals
2. advanced workflow scheduling and queue orchestration controls
3. multi-job bulk operations

Create Acceptance Criteria

CR-1 Job creation entry

1. Given the user is on the Jobs page
2. When the user selects Create job
3. Then the user is taken to Job detail/create mode

CR-2 Required create values

1. document_id must be selected before submit
2. at least one source file must be uploaded before submit
3. each uploaded file creates a Source linked to the selected Document
4. each created Source is linked to the new Job through JobSource

CR-3 Source ordering behavior

1. Given multi-file or folder upload
2. When source records are created
3. Then page ordering follows alphabetical order of original filenames
4. Then helper text explains how filename conventions control ordering

CR-4 Provider/model/prompt visibility

1. provider, model, and prompt_name are visible in create flow when known
2. provider, model, and prompt_name are visible in detail flow when known
3. if values are unknown at create time, UI shows clear unknown or pending state without blocking submit

CR-5 Successful create outcome

1. Given valid inputs
2. When the user submits create
3. Then the Job record is created and linked to selected Document
4. Then source and JobSource records are created for uploads
5. Then job status is queued or processing based on execution timing
6. Then the user is routed to Job detail mode

CR-6 Create failure outcome

1. Given create validation or persistence failure
2. Then clear error feedback is shown
3. Then no false success feedback is shown
4. Then entered selections are preserved where possible
5. Then retry path remains available

Read Acceptance Criteria

RD-1 Jobs list retrieval

1. Given one or more jobs exist
2. When the user opens the Jobs page
3. Then all jobs are listed in a table or equivalent list surface

RD-2 Jobs list fields

1. Jobs list shows job id
2. Jobs list shows status
3. Jobs list shows created or updated timestamps
4. Jobs list shows retry_count when available
5. Jobs list provides navigation to Job detail for each row

RD-3 Job detail retrieval

1. Given a valid job id
2. When the user opens Job detail
3. Then job metadata for that record only is shown
4. Then source preview or source warning state is shown

RD-4 Detail execution context visibility

1. provider, model, and prompt_name are displayed when known
2. status lifecycle value is visible
3. source-level transcription and revision context is visible

RD-5 Missing and invalid id states

1. Given an invalid job id format
2. Then UI shows invalid job id state without crashing
3. Given a valid but nonexistent job id
4. Then UI shows job not found state without crashing

Update Acceptance Criteria

UP-1 Revision edit entry

1. Given a job detail page with source context
2. When the user enters revision edit flow
3. Then revised_text input is available

UP-2 Revision validation

1. revised_text cannot be saved as empty after trimming
2. Warning feedback is shown for invalid empty input

UP-3 Successful revision save

1. Given valid revision text
2. When the user saves
3. Then revised_text persists
4. Then success feedback is shown
5. Then refreshed revision content is visible

UP-4 Revision save failure

1. Given backend failure during revision save
2. Then clear error feedback is shown
3. Then the user-entered text remains available for retry where possible

UP-5 Job lifecycle state update visibility

1. status changes from queued to processing to terminal states are reflected in UI
2. retry_count updates are reflected when retry logic runs
3. users cannot directly edit lifecycle state fields in first release

Delete Acceptance Criteria

DL-1 Delete entry and confirmation

1. Given a job detail context with delete affordance
2. When the user selects delete job
3. Then a permanent-action confirmation dialog appears

DL-2 Dependency guardrails

1. If deletion policy requires retention handling for related JobSource history, delete is blocked
2. If deletion policy allows dependent cleanup path, delete can proceed

DL-3 Blocked delete behavior

1. When blocked
2. Then UI explains dependency constraints
3. Then UI provides cleanup guidance

DL-4 Successful delete

1. Given no blocking dependencies
2. When the user confirms deletion
3. Then job is removed
4. Then success feedback is shown
5. Then the user returns to Jobs list

DL-5 Delete failure

1. Given backend failure during delete
2. Then clear error feedback is shown
3. Then the user remains in Job context with retry path

Cross-Criteria Quality Gates

QG-1 Separation of intent and implementation

1. UX intent remains in user-journey.md
2. Current versus target implementation mapping remains in schema-mapping.md

QG-2 Traceability

1. Each accepted behavior maps to at least one UI action or service path
2. No acceptance criterion contradicts first-release deferred items

QG-3 First-release constraints

1. Jobs page remains list-all with explicit Create job action
2. Job create requires Document selection and source upload
3. provider/model/prompt_name are visible to users when known
4. manual retry controls may remain deferred while status visibility is required