UI update planning continued

2026-08-02 10:00:03 -05:00
parent 2b3d33e50e
commit 646a360aca
9 changed files with 1576 additions and 21 deletions
@@ -0,0 +1,141 @@
+# 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 job detail 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
+
+### RD-2 Transcription and revision visibility
+1. Original transcription context is visible read-only
+2. Revision state is visible
+3. If revised_text is absent, no revision yet messaging is shown
+
+### 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
+
+### 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 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
+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 job detail in first release
+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 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