UI update initial phase complete. Still need to create schema-mapping for the two many-to-many tables.

2026-08-02 11:23:04 -05:00
parent 646a360aca
commit 5946867ff3
5 changed files with 775 additions and 0 deletions
@@ -27,11 +27,32 @@ Use this document to describe:
 - intended target behavior
 - implementation gaps between current code and intended UX
 ### acceptance-criteria.md
 An implementation-ready checklist for CRUD behavior and quality gates.
 Use this document to describe:
 - testable acceptance statements by flow (Create, Read, Update, Delete)
 - success and failure behaviors
 - first-release constraints
 - cross-criteria quality gates
 ### traceability-matrix.md
 A criteria-to-code mapping that identifies implementation anchors and status.
 Use this document to describe:
 - acceptance criteria group to implementation file mapping
 - delivery status (implemented, partial, planned)
 - ordered implementation priorities
 ## Organization Rules
 - Store documents under `docs/ui/entities/<entity-name>/`.
 - Create both `user-journey.md` and `schema-mapping.md` for user-facing entities.
 - Create `acceptance-criteria.md` for user-facing entities.
 - Create only `schema-mapping.md` for supporting tables that do not currently have standalone UI.
 - Keep one shared `traceability-matrix.md` under `docs/ui/entities/` to map criteria to implementation anchors.
 - Keep top-level `docs/` reserved for core architecture, requirements, schema, and system-wide reference material.
 ## Current Entity Plan
@@ -0,0 +1,162 @@
 # 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 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
@@ -0,0 +1,238 @@
 # 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.
@@ -0,0 +1,286 @@
 # 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 per-source output and saves revisions.
 ## 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. per-source processing state
 3. original transcription output
 4. revision editor and save actions
 ## 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 is upload-first and auto-creates Job records
 2. intended UX is explicit Create job from the Jobs page
 ## 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. user opens the Jobs page
 2. user selects Create job
 3. 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. 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. 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. per-source status (pending, transcribed, failed)
 4. original transcription output per source
 5. 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 job detail review
 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 is policy-controlled:
 1. deletion may be blocked when related JobSource or source history must be retained
 2. blocked delete must explain constraints and cleanup path
 3. if allowed, delete requires explicit confirmation
 ## 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
@@ -0,0 +1,68 @@
 # UI Entity Traceability Matrix
 Purpose: Map acceptance criteria to concrete implementation anchors and current delivery status.
 Updated: 2026-08-02
 Status legend:
 - Implemented: behavior exists in current UI and service flow
 - Partial: parts exist, but user-facing behavior or guardrails are incomplete
 - Planned: documented intent with no dedicated UI implementation yet
 ## Document
 | Criteria Group | Acceptance IDs | Status | Primary Implementation Anchors | Notes |
 |---|---|---|---|---|
 | Read detail and metadata | RD-1, RD-2, RD-7 | Planned | src/transcription/ui/pages/jobs_page.py; src/transcription/ui/components/table/jobs.py; src/transcription/ui/components/transcript.py | No dedicated Document detail page yet; Document metadata is not rendered as first-class UI. |
 | Related sections and empty states | RD-3, RD-4, RD-5, RD-6 | Planned | src/transcription/ui/pages/jobs_page.py | Document-scoped related sections are defined in docs, not yet implemented in a dedicated Document view. |
 | Update entry and validation | UP-1, UP-2, UP-3, UP-4, UP-5, UP-6 | Planned | src/transcription/services/documents.py | Service update path exists; no dedicated Document edit UI flow yet. |
 | Delete controls and guardrails | DL-1, DL-2, DL-3, DL-4, DL-5 | Planned | src/transcription/services/documents.py | Service delete path exists; no UI delete control or dependency guard UX yet. |
 ## Person
 | Criteria Group | Acceptance IDs | Status | Primary Implementation Anchors | Notes |
 |---|---|---|---|---|
 | Create flow and validation | CR-1, CR-2, CR-3, CR-4, CR-5 | Planned | src/transcription/services/documents.py | Person create service exists; no dedicated Person page/form yet. |
 | Read detail and linked documents | RD-1, RD-2, RD-3, RD-4 | Planned | src/transcription/services/documents.py; src/transcription/ui | No dedicated Person detail UI in current pages. |
 | Update behavior | UP-1, UP-2, UP-3, UP-4, UP-5 | Planned | src/transcription/services/documents.py | Service update exists; no first-class Person edit surface yet. |
 | Delete behavior and guardrails | DL-1, DL-2, DL-3, DL-4, DL-5 | Planned | src/transcription/services/documents.py | Service delete exists; relationship-aware UI guard flow is not implemented. |
 ## Source
 | Criteria Group | Acceptance IDs | Status | Primary Implementation Anchors | Notes |
 |---|---|---|---|---|
 | Create entry and required links | CR-1, CR-2, CR-4, CR-5 | Partial | src/transcription/services/store.py; src/transcription/ui/pages/upload_page.py | Upload flow creates Document, Job, Source, and JobSource together; first-release job-context-only Source create intent is documented but not exposed as dedicated Source create UI. |
 | Ordering and filename policy | CR-3 | Partial | src/transcription/services/store.py | Current implementation persists generated filenames and assigns page_number in upload flow; target policy requires strict alphabetical ordering guidance and UUID.extension convention. |
 | Read and revision visibility | RD-1, RD-2, RD-3 | Implemented | src/transcription/ui/pages/jobs_page.py; src/transcription/ui/components/job_detail.py; src/transcription/ui/components/transcript.py | Source preview and revision context are available primarily in job detail flow. |
 | Revision update behavior | UP-1, UP-2, UP-3, UP-4 | Implemented | src/transcription/services/transcription.py; src/transcription/ui/pages/jobs_page.py; src/transcription/ui/components/transcript.py | Revised text editing and save feedback path exists in job detail revision flow. |
 | Delete and dependency guardrails | DL-1, DL-2, DL-3, DL-4, DL-5 | Planned | src/transcription/services/transcription.py | Source delete service path exists; dedicated UI delete control and guardrail messaging are not implemented. |
 ## Job
 | Criteria Group | Acceptance IDs | Status | Primary Implementation Anchors | Notes |
 |---|---|---|---|---|
 | Create entry and required links | CR-1, CR-2, CR-5, CR-6 | Partial | src/transcription/services/store.py; src/transcription/ui/pages/upload_page.py; src/transcription/ui/pages/jobs_page.py | Current create path is upload-first and implicit; target requires explicit Create job flow from Jobs page. |
 | Source ordering and upload behavior | CR-3 | Partial | src/transcription/services/store.py | Current upload path is single-file create and uses service-assigned page defaults; target requires multi-file or folder handling with alphabetical ordering guidance. |
 | Provider/model/prompt visibility | CR-4, RD-4 | Partial | src/transcription/services/workflows.py; src/transcription/ui/pages/jobs_page.py | Values are populated in workflow updates but not rendered as first-class fields in current job detail. |
 | Jobs list and detail read states | RD-1, RD-2, RD-3, RD-5 | Implemented | src/transcription/ui/pages/jobs_page.py; src/transcription/ui/components/table/jobs.py; tests/ui/test_jobs_page.py | Jobs list, detail route, and invalid/missing id states are present. |
 | Revision update behavior | UP-1, UP-2, UP-3, UP-4 | Implemented | src/transcription/ui/pages/jobs_page.py; src/transcription/ui/components/transcript.py; src/transcription/services/transcription.py | Revision editing and save feedback exist in job detail source context. |
 | Lifecycle visibility and retry indicators | UP-5 | Partial | src/transcription/services/jobs.py; src/transcription/services/workflows.py; src/transcription/ui/pages/jobs_page.py | Status and retry_count are visible, but lifecycle controls remain system-managed and create-mode visibility targets are still pending. |
 | Delete and dependency guardrails | DL-1, DL-2, DL-3, DL-4, DL-5 | Planned | src/transcription/services/jobs.py | Backend delete exists; dedicated UI delete flow and policy messaging are not implemented. |
 ## Quality Gate Coverage
 | Quality Gate | Acceptance IDs | Status | Notes |
 |---|---|---|---|
 | Separation of intent vs implementation | QG-1 across entities | Implemented | user-journey.md, schema-mapping.md, and acceptance-criteria.md are maintained per entity. |
 | Traceability from criteria to implementation | QG-2 across entities | Implemented | This matrix provides criterion-to-code anchors and current status tags. |
 | First-release constraints | QG-3 across entities | Partial | Constraints are documented for Document, Person, Source, and Job; implementation remains mixed across entities. |
 ## Suggested Implementation Order
 1. Document: add dedicated detail/read surface and metadata rendering.
 2. Document: add edit and delete UI with dependency guardrails.
 3. Person: add create/read/update/delete pages and relationship-aware delete constraints.
 4. Job: add explicit Create job flow from Jobs page with Document selection and source upload controls.
 5. Job: render provider/model/prompt_name visibility in create and detail when known.
 6. Source: align create flow behavior with documented job-context-only invariant and ordering/filename policy.
 7. Source: add delete UI with dependency checks and blocked-delete guidance.