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:

• Job detail renders metadata and document links; source-level review/editing is reached through job-scoped Sources routes.

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: Jobs page create flow
Current user action: select Document and upload one or more files or a folder through a single upload widget
Current backend path: job create submit -> create_job_for_document()

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	Selected existing Document id	User selection + service write	Indirectly	src/transcription/ui/pages/jobs_page.py, 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	Yes	src/transcription/services/workflows.py
model	None at create, set after transcription update	Workflow/service	Yes	src/transcription/services/workflows.py
prompt_name	None at create, set by workflow updates	Workflow/service	Yes	src/transcription/services/workflows.py

Current create constraints:

1. dedicated Create job action exists in the Jobs page.
2. job create flow requires a Document selection.
3. current upload path accepts one widget for files or folder selection.

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	Rendered as labeled fields in Job detail	Yes	Shows pending fallback when unset	src/transcription/ui/pages/jobs_page.py

Source-related read behavior:

1. Job detail exposes Sources navigation for current job context.
2. Source preview, transcription context, and revision editor are rendered in Source detail.
3. invalid or missing job ids show explicit UI states.

5.3 Gap to Target

To satisfy intended Read flow, implementation must add:

1. optional in-page source summaries in Job detail if future UX requires fewer navigation steps.
2. richer filtering/search UX if needed.

6. UPDATE Mapping

6.1 Intended Update Behavior

Primary user updates in first release are source revision edits in Source detail reached from Job detail.

Intended editable scope (first release):

• Source.revised_text through Source 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 Source detail	Yes	Yes	Saved via transcription service revision path from Sources page detail route
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 now includes:

1. create-mode handling for provider/model/prompt visibility and optional selection.
2. detail display for provider/model/prompt and document-scoped navigation links.
3. source revision workflow through job-scoped Sources and Source detail pages.
4. manual controls for retry and state transitions remain deferred.

7. DELETE Mapping

7.1 Intended Delete Behavior

Job deletion is implemented as a dedicated delete route with processing-state 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	Yes	Yes	Job delete page confirms permanent action and blocks when processing

7.3 Gap to Target

Implementation may add in a future revision:

1. inline delete entry in Job detail header.
2. richer dependency messaging beyond processing-state guardrail.

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/pages/sources_page.py
• src/transcription/services/jobs.py
• src/transcription/services/workflows.py
• src/transcription/services/store.py
• src/transcription/services/transcription.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 explicit jobs creation plus source review/editing through dedicated Sources routes.
• 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.