generated from john/python-template
142 lines
5.2 KiB
Markdown
142 lines
5.2 KiB
Markdown
# 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
|