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

Source Acceptance Criteria

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

Companion documents:

• docs/ui/entities/source/user-journey.md
• docs/ui/entities/source/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. advanced multi-version revision history design
2. job orchestration state-machine behavior
3. provider-level transcription internals

Create Acceptance Criteria

CR-1 Source creation entry

1. Given the user is in job creation or job configuration flow
2. When the user selects Add sources
3. Then the user can upload one or more source files or a folder
4. Then source creation is not offered as a standalone first-release document-only flow

CR-2 Required create values

1. document_id is derived from selected Document context
2. JobSource.job_id is derived from the active Job context
3. Each created Source is linked to the active Job through JobSource at create time
4. page_number is assigned to preserve ordering
5. upload_name, filename, and file_path are persisted for each created source

CR-3 Ordering and filename strategy

1. Given a multi-file or folder upload
2. When source records are created
3. Then page ordering follows alphabetical order of original filenames
4. Then upload_name stores the original filename
5. Then filename is stored using UUID plus original extension in the form UUID.extension

CR-4 Successful create outcome

1. Given valid uploads
2. When source creation completes
3. Then Source records are created and linked to the Document
4. Then Source records are linked to the active Job through JobSource
5. Then source list reflects new pages in sequence
6. Then the user can open preview or revision workflow

CR-5 Create failure outcome

1. Given upload or persistence failure
2. Then clear error feedback is shown
3. Then no false success feedback is shown
4. Then retry path remains available
5. Then creation fails when required Document or Job linkage cannot be established

Read Acceptance Criteria

RD-1 Source detail retrieval

1. Given a valid Source id in source context, typically via a document-scoped source list in first release
2. When the user opens source detail or equivalent panel
3. Then source metadata and preview are displayed for that source only if the detail UI exists in a later revision

RD-2 Transcription and revision visibility

1. Original transcription context is visible read-only when the revision UI exists
2. Revision state is visible when the revision UI exists
3. If revised_text is absent, no revision yet messaging is shown when the revision UI exists

RD-3 Missing source state

1. Given a missing source
2. Then UI shows clear no source available or not found messaging without crashing

Update Acceptance Criteria

UP-1 Revision editing entry

1. Given a source context
2. When the user enters revision edit flow
3. Then revised_text input is available in a later revision of the UI

UP-2 Revision validation

1. revised_text cannot be saved as empty after trimming when the revision UI exists
2. Warning feedback is shown for invalid empty input when the revision UI exists

UP-3 Successful revision save

1. Given valid revision text
2. When the user saves in a later revision of the UI
3. Then revised_text persists
4. Then date_revised is updated
5. Then success feedback is shown
6. Then refreshed revision content is visible

UP-4 Revision save failure

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

Delete Acceptance Criteria

DL-1 Delete entry and confirmation

1. Given a source in source context, typically via a later source detail view
2. When the user selects delete source
3. Then a permanent-action confirmation dialog appears

DL-2 Dependency guardrails

1. If policy requires cleanup of related JobSource records first, delete is blocked
2. If 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 guidance for dependency cleanup

DL-4 Successful delete

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

DL-5 Delete failure

1. Given backend failure during delete
2. Then clear error feedback is shown
3. Then the user remains in source 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 future UI action or service path
2. No acceptance criterion contradicts first-release deferred items

QG-3 First-release constraints

1. Source interaction may remain job-detail-centric initially
2. revised_text is the primary editable source field in first release
3. source creation requires both Document linkage and Job linkage at create time
4. richer source management surfaces are phased in later