transcription/docs/ui/entities/job/schema-mapping.md

# Job Schema-to-UI Mapping

Purpose: Map the Job schema to the UI, while clearly separating intended target behavior from current implementation.

Companion document: user-journey.md
Acceptance criteria: acceptance-criteria.md

## 1. Entity Snapshot

- Table: Job
- Primary key: id (UUID)
- Related entities: Document, JobSource, Source
- Canonical schema references:
  - src/transcription/db/models.py
  - docs/schema_v2.md

## 2. Mapping Rules

This document uses three lenses:
1. Intended behavior: what the UX should support.
2. Current behavior: what the code supports today.
3. Gap to target: what must change to align implementation with the intended UX.

## 3. Field Inventory

| Field | DB Type | Nullable | Default/Auto Value | Intended UI Treatment | Notes |
|---|---|---|---|---|---|
| id | UUID | No | uuid4() | Shown read-only in list and detail | Primary key |
| document_id | UUID FK | No | None | Required create input via Document selection | Job belongs to one Document |
| status | enum JobStatus | No | queued | Shown read-only as lifecycle state | System-managed transitions |
| retry_count | int | No | 0 | Shown read-only | Operational counter |
| date_created | datetime | No | datetime.now(UTC) | Shown read-only | System-managed timestamp |
| date_updated | datetime | No | datetime.now(UTC) | Shown read-only | System-managed timestamp |
| provider | str | Yes | None | Visible when known; editable if create-time options are available | Processing metadata |
| model | str | Yes | None | Visible when known; editable if create-time options are available | Processing metadata |
| prompt_name | str | Yes | None | Visible when known; editable if create-time options are available | Prompt metadata |

Related execution fields rendered in Job detail via relationships:
- JobSource.status
- JobSource.error_detail
- JobSource.executed_at
- Source.upload_name, Source.filename, Source.page_number
- Source.raw_transcription, Source.revised_text

## 4. CREATE Mapping

### 4.1 Intended Create Flow

Entry point: Jobs page Create job action  
User action: open create mode, select Document, upload one or more source files or a folder, submit for transcription  
Success destination: Job detail page in detail mode

| Field | Intended User Input | Required | Visible | Notes |
|---|---|---|---|---|
| document_id | Select/search | Yes | Yes | Required create selection |
| status | None | No | Yes (read-only) | Starts at queued and changes by workflow |
| retry_count | None | No | Yes (read-only) | Starts at 0 |
| date_created | None | No | Yes (read-only) | System-generated |
| date_updated | None | No | Yes (read-only) | System-generated |
| provider | Display or select | No | Yes | Visible when known during create and detail |
| model | Display or select | No | Yes | Visible when known during create and detail |
| prompt_name | Display or select | No | Yes | Visible when known during create and detail |

Create-related relationship rules:
1. source file upload is required for create.
2. each uploaded file creates a Source linked to the selected Document.
3. each created Source must be linked to the new Job through JobSource.
4. processing order for multi-file and folder uploads is alphabetical by original filename.

### 4.2 Current Implementation

Current entry point: upload page through create_upload_job()  
Current user action: upload one file through upload flow  
Current backend path: upload submit -> create_upload_job -> _create_upload_records

| Field | Current Value at Create | Source | Visible to User | Evidence |
|---|---|---|---|---|
| id | Generated UUID | System | Yes on jobs list/detail | src/transcription/ui/pages/jobs_page.py |
| document_id | Newly created Document id | Service | Indirectly | src/transcription/services/store.py |
| status | queued | Service/model default | Yes | src/transcription/services/store.py, src/transcription/db/models.py |
| retry_count | 0 | Model default | Yes | src/transcription/db/models.py, src/transcription/ui/pages/jobs_page.py |
| date_created | current UTC timestamp | System | Yes | src/transcription/db/models.py, src/transcription/ui/pages/jobs_page.py |
| date_updated | current UTC timestamp | System | Yes | src/transcription/db/models.py, src/transcription/ui/pages/jobs_page.py |
| provider | None at create, set after transcription update | Workflow/service | Partially | src/transcription/services/workflows.py |
| model | None at create, set after transcription update | Workflow/service | Partially | src/transcription/services/workflows.py |
| prompt_name | None at create, set by workflow updates | Workflow/service | Partially | src/transcription/services/workflows.py |

Current create constraints:
1. no dedicated Create job action in the Jobs page.
2. upload flow currently creates Document, Job, Source, and JobSource together.
3. current upload path accepts a single file per submission.

### 4.3 Gap to Target

To satisfy intended Create flow, implementation must add:
1. Jobs list Create job action that opens Job detail/create mode.
2. explicit Document selection and source upload controls in create mode.
3. multi-file and folder upload support in create mode.
4. deterministic alphabetical page ordering and user guidance.
5. explicit visibility of provider, model, and prompt_name in create/detail when known.

## 5. READ Mapping

### 5.1 Intended Read Behavior

On Job list/detail surfaces, users should be able to see:
1. all jobs in one list.
2. status and timeline context.
3. selected Document context.
4. source-level processing and transcription results.
5. provider/model/prompt_name when known.

### 5.2 Current Implementation

Current read behavior exists in jobs list and jobs detail routes.

| Field | Current Rendering | Visible to User | Notes | Evidence |
|---|---|---|---|---|
| id | Jobs list row and detail header | Yes | Primary visible identifier | src/transcription/ui/pages/jobs_page.py |
| status | Jobs list and detail | Yes | Chip styling for transcribed; text for others | src/transcription/ui/pages/jobs_page.py |
| retry_count | Jobs list table | Yes | Included in row model | src/transcription/ui/components/table/jobs.py |
| date_created | Jobs list table | Yes | Included in row model | src/transcription/ui/components/table/jobs.py |
| date_updated | Jobs list table | Yes | Included in row model | src/transcription/ui/components/table/jobs.py |
| document_id | Not rendered directly as labeled field | Partial | Document context exists by relationship but limited direct display | src/transcription/ui/pages/jobs_page.py |
| provider/model/prompt_name | Not rendered as first-class labels | Partial | Stored in job records after processing updates | src/transcription/services/workflows.py |

Source-related read behavior:
1. one primary source preview is shown in detail.
2. original transcription and revision editor are rendered for source context.
3. invalid or missing job ids show explicit UI states.

### 5.3 Gap to Target

To satisfy intended Read flow, implementation must add:
1. list-level create affordance and enhanced filtering/search UX.
2. explicit Document context rendering in list and detail.
3. explicit provider/model/prompt_name rendering in detail when known.
4. richer multi-source detail navigation when more than one source is linked.

## 6. UPDATE Mapping

### 6.1 Intended Update Behavior

Primary user updates in first release are revision edits in job detail source context.

Intended editable scope (first release):
- Source.revised_text through Job detail review

Intended read-only Job fields in first release:
- id
- document_id after create
- status
- retry_count
- date_created
- date_updated

Job metadata visibility policy:
- provider, model, and prompt_name should be visible when known.
- create-time editing of provider/model/prompt_name is optional and depends on available options.

### 6.2 Current Implementation

| Field/Area | Updatable via UI | Updatable via Service | Notes |
|---|---|---|---|
| Source.revised_text from job detail | Yes | Yes | Saved via transcription service revision path |
| status | No | Yes | Updated by workflow lifecycle services |
| retry_count | No | Yes | Incremented by workflow retry logic |
| provider/model/prompt_name | No | Yes | Set during transcription result finalization |
| document_id | No | Technically via model/service update | Treated as fixed post-create in intended UX |

### 6.3 Gap to Target

Implementation should add:
1. explicit create-mode handling for provider/model/prompt visibility and optional selection.
2. richer detail display for provider/model/prompt and source-level execution outcomes.
3. optional future manual controls for retry and state transitions.

## 7. DELETE Mapping

### 7.1 Intended Delete Behavior

Job deletion should include dependency-aware guardrails.

Rules:
1. deletion is allowed only when policy allows cleanup or retention handling for related JobSource records.
2. blocked deletion must explain constraints and required cleanup path.
3. successful deletion requires confirmation and returns user to Jobs list.

### 7.2 Current Implementation

| Action | UI Exposed | Backend Capability | Notes |
|---|---|---|---|
| Delete Job | No | Yes | JobService.delete_job() exists; no dedicated UI delete flow |

### 7.3 Gap to Target

Implementation must add:
1. delete control in Job detail.
2. dependency checks and blocked-delete messaging.
3. success navigation and confirmation UX.

## 8. Hidden and System-Managed Fields

| Field | Category | Why Hidden or Protected |
|---|---|---|
| status | System-managed lifecycle | Managed by worker lifecycle transitions |
| retry_count | System-managed operational state | Reflects retry behavior, not direct user input |
| date_created | System-managed | Audit timestamp |
| date_updated | System-managed | Audit timestamp |

## 9. Traceability Anchors

Schema and models:
- docs/schema_v2.md
- src/transcription/db/models.py

Current implementation:
- src/transcription/ui/pages/jobs_page.py
- src/transcription/ui/components/table/jobs.py
- src/transcription/ui/components/transcript.py
- src/transcription/services/jobs.py
- src/transcription/services/workflows.py
- src/transcription/services/store.py

Companion UX spec:
- docs/ui/entities/job/user-journey.md

Acceptance checklist:
- docs/ui/entities/job/acceptance-criteria.md

## 10. Acceptance Checklist Summary

- Every Job schema field appears in the field inventory.
- Intended Create behavior matches the companion user journey.
- Current behavior reflects existing upload-first creation and jobs read surfaces.
- Provider/model/prompt visibility intent is explicit for create and detail views.
- Gaps between intended and current behavior are explicit.
- Read, Update, and Delete sections distinguish target behavior from current code.