generated from john/python-template
100 lines
5.0 KiB
Markdown
100 lines
5.0 KiB
Markdown
# Jobs Page Contract
|
|
|
|
## Purpose
|
|
|
|
Jobs manages transcription processing runs. A Job belongs to one Document, links one or more Source pages, records processing provenance, and exposes lifecycle actions without making lifecycle fields directly editable.
|
|
|
|
## Routes
|
|
|
|
| Route | Purpose |
|
|
| --- | --- |
|
|
| `/jobs` | Searchable processing Job list. |
|
|
| `/jobs/new` | Create and queue a Job. |
|
|
| `/jobs/{job_id}` | View status, execution logistics, and related records. |
|
|
| `/jobs/{job_id}/cancel` | Confirm cancellation. |
|
|
| `/jobs/{job_id}/resubmit` | Confirm resubmission of failed Sources. |
|
|
| `/jobs/{job_id}/delete` | Confirm or block deletion. |
|
|
|
|
## List Behavior
|
|
|
|
- The title is **Transcription Pipeline Jobs**.
|
|
- **Create job** opens Job creation and **Refresh** reloads the table.
|
|
- Columns are Job ID, Status, Document Name, # Sources, Retries, and Updated.
|
|
- Updated is the primary date/sort field.
|
|
- Search covers Job ID, document name, and status.
|
|
- Status is displayed as a semantic status chip.
|
|
- Selecting a row opens Job Detail.
|
|
- Global Job-list row navigation includes list context so Job Detail provides **Back to Jobs**.
|
|
- No records displays `No job records found in repository.`
|
|
|
|
## Create Behavior
|
|
|
|
- A Target Document and at least one source file are required.
|
|
- `document_id` may preselect a Target Document.
|
|
- If no Documents exist, the page explains the prerequisite and links to Document creation with a return path.
|
|
- Provider and Model are selectable when creating a new Job.
|
|
- Upload accepts JPEG, PNG, TIFF, and PDF files and supports multiple/folder selection.
|
|
- The visible upload queue is sorted alphabetically by original filename.
|
|
- Files can be removed individually or cleared before submission.
|
|
- Helper text explains numeric filename prefixes for page ordering.
|
|
- Submission creates the Job, Source records, and JobSource links, notifies the worker, and opens Job Detail.
|
|
- When opened with `source_id`, creation becomes a retranscription flow: Source and Document are locked, Provider is
|
|
read-only, Model is restricted to `PROVIDER_MODELS`, no upload is accepted, and one existing Source is linked.
|
|
|
|
## Detail and Lifecycle Behavior
|
|
|
|
- The heading shows Job ID and a status badge.
|
|
- Job Detail includes a contextual back action: **Back to Jobs** by default and **Back to Document** when opened from a Document-filtered Job list.
|
|
- Execution Logistics shows provider, model, prompt, retry count, and last update.
|
|
- Document Links show a clickable Document Name (with Job context), Sources count, and a single **View Sources** action using job filtering.
|
|
- Queued and processing Jobs show an auto-refresh notice and reload every four seconds.
|
|
- Polling stops when the Job becomes terminal or a refresh fails.
|
|
- Queued and processing Jobs expose **Cancel**.
|
|
- Jobs other than `transcribed` expose **Resubmit** under the current UI rule. The service blocks resubmission while processing is active or when no failed Sources exist.
|
|
- All Jobs expose **Delete Job**, subject to explicit evidence-deletion guardrails.
|
|
- Invalid and missing IDs produce explicit states.
|
|
|
|
## Cancel Behavior
|
|
|
|
- The confirmation explains that processing stops and remaining pending Sources become cancelled.
|
|
- The service decides whether the current state permits cancellation.
|
|
- Success updates the Job, notifies the worker, and returns to Job Detail.
|
|
|
|
## Resubmit Behavior
|
|
|
|
- The page shows current status and failed Source count.
|
|
- The page explains that resubmission queues failed linked Sources while preserving immutable prior attempt evidence.
|
|
- The service blocks submission while processing is active or when no failed Sources exist.
|
|
- `JobSource` remains the latest compatibility projection, while every provider call appends an `ExecutionAttempt`.
|
|
- The selected `Source.raw_transcription` projection remains available while a retry is pending or fails.
|
|
- Success reports the number of resubmitted Sources and returns to Job Detail.
|
|
|
|
## Delete Behavior
|
|
|
|
- Deletion is blocked while status is `processing`.
|
|
- Allowed deletion explicitly warns that related `JobSource` projections,
|
|
immutable execution attempts, captured transport responses, and attempt-owned
|
|
artifacts are permanently removed.
|
|
- Source records and source files remain available for separate deletion.
|
|
- Success returns to the Jobs list.
|
|
|
|
## Acceptance Checklist
|
|
|
|
- Job creation cannot proceed without a valid Document and at least one Source.
|
|
- Upload ordering and removal controls match the displayed queue.
|
|
- Detail shows current status and provenance summary with correct related links.
|
|
- Active Jobs refresh without overlapping permanent polling after terminal state.
|
|
- Cancel, resubmit, and delete honor service guardrails and show actionable failures.
|
|
- Lifecycle fields cannot be edited directly.
|
|
|
|
## Implementation Anchors
|
|
|
|
- `src/transcription/ui/pages/jobs_page.py`
|
|
- `src/transcription/ui/components/table/jobs.py`
|
|
- `src/transcription/services/jobs.py`
|
|
- `src/transcription/services/store.py`
|
|
- `src/transcription/services/workflows.py`
|
|
- `tests/ui/test_jobs_page.py`
|
|
- `tests/services/test_job_service.py`
|
|
- `tests/services/test_store.py`
|