generated from john/python-template
UI update planning continued
This commit is contained in:
Jim Lancaster
@@ -0,0 +1,131 @@
|
||||
# Document Acceptance Criteria
|
||||
|
||||
Purpose: Define implementation-ready acceptance criteria for Document Read, Update, and Delete workflows.
|
||||
|
||||
Companion documents:
|
||||
- docs/ui/entities/document/user-journey.md
|
||||
- docs/ui/entities/document/schema-mapping.md
|
||||
|
||||
## Scope
|
||||
|
||||
This checklist covers:
|
||||
1. Read flow
|
||||
2. Update flow
|
||||
3. Delete flow
|
||||
|
||||
This checklist does not cover:
|
||||
1. Source upload workflow details
|
||||
2. Job execution internals
|
||||
3. Revision editor behavior
|
||||
|
||||
## Read Acceptance Criteria
|
||||
|
||||
### RD-1 Document detail retrieval
|
||||
1. Given a valid Document id
|
||||
2. When the user opens the Document detail page
|
||||
3. Then the system displays Document metadata for that record only
|
||||
|
||||
### RD-2 Metadata visibility
|
||||
1. The page shows name, document_type, document_date, document_date_raw, location_created, notes, archive_identifier
|
||||
2. created_at and updated_at are displayed as system-managed, read-only values
|
||||
|
||||
### RD-3 Related people section
|
||||
1. Given zero linked people
|
||||
2. Then the page shows a no linked people yet empty state
|
||||
3. Given one linked person
|
||||
4. Then the page shows that linked person
|
||||
|
||||
### RD-4 Sources section empty state
|
||||
1. Given no related Source records
|
||||
2. Then the page shows no sources added yet and an action to add sources
|
||||
|
||||
### RD-5 Jobs section empty state
|
||||
1. Given no related Job records
|
||||
2. Then the page shows no jobs created yet and an action to start or create jobs
|
||||
|
||||
### RD-6 Filtered navigation readiness
|
||||
1. The detail page provides links or actions that can route to document-scoped Sources and Jobs views
|
||||
2. Target views are filtered to the current Document id
|
||||
|
||||
### RD-7 Failure state
|
||||
1. Given a nonexistent Document id
|
||||
2. Then the UI shows a clear not found state without crashing
|
||||
|
||||
## Update Acceptance Criteria
|
||||
|
||||
### UP-1 Edit entry
|
||||
1. Given a loaded Document detail page
|
||||
2. When the user chooses Edit document
|
||||
3. Then editable controls are shown for allowed fields only
|
||||
|
||||
### UP-2 Editable fields
|
||||
1. Editable: name, document_type, document_date, document_date_raw, location_created, notes, archive_identifier
|
||||
2. Not editable: id, created_at, updated_at
|
||||
|
||||
### UP-3 Required validation
|
||||
1. name is required
|
||||
2. document_type is required
|
||||
3. Save is blocked with inline feedback when either required field is missing
|
||||
|
||||
### UP-4 Date handling rule
|
||||
1. document_date only is allowed
|
||||
2. document_date_raw only is allowed
|
||||
3. both fields together are allowed
|
||||
4. if both are present, document_date is treated as canonical exact date and document_date_raw is retained as descriptive context
|
||||
|
||||
### UP-5 Successful save
|
||||
1. Given valid input
|
||||
2. When the user saves
|
||||
3. Then changes persist
|
||||
4. Then success feedback is shown
|
||||
5. Then the user remains on Document detail with refreshed values
|
||||
6. Then updated_at reflects update policy
|
||||
|
||||
### UP-6 Save failure
|
||||
1. Given backend failure during save
|
||||
2. Then clear error feedback is shown
|
||||
3. Then the user-entered values remain available for retry where possible
|
||||
4. Then no false success feedback is shown
|
||||
|
||||
## Delete Acceptance Criteria
|
||||
|
||||
### DL-1 Delete entry and confirmation
|
||||
1. Given a Document detail page
|
||||
2. When the user chooses Delete document
|
||||
3. Then a confirmation dialog appears with permanent-action wording
|
||||
|
||||
### DL-2 Dependency guardrails
|
||||
1. Delete is allowed only when the Document has no related Source records and no related Job records
|
||||
2. Delete is blocked when at least one related Source or Job exists
|
||||
|
||||
### DL-3 Blocked delete behavior
|
||||
1. When blocked
|
||||
2. Then the UI explains why deletion is blocked
|
||||
3. Then the UI identifies dependency categories present: Sources, Jobs, or both
|
||||
4. Then the UI provides navigation to dependency cleanup paths
|
||||
|
||||
### DL-4 Successful delete
|
||||
1. Given no blocking dependencies
|
||||
2. When the user confirms delete
|
||||
3. Then the Document is removed
|
||||
4. Then success feedback is shown
|
||||
5. Then the user is returned to the Document list page
|
||||
|
||||
### DL-5 Delete failure
|
||||
1. Given backend failure during delete
|
||||
2. Then a clear error message is shown
|
||||
3. Then the user remains on Document detail with retry path
|
||||
|
||||
## Cross-Criteria Quality Gates
|
||||
|
||||
### QG-1 Separation of intent and implementation
|
||||
1. Journey intent remains in docs/ui/entities/document/user-journey.md
|
||||
2. Current versus target implementation mapping remains in docs/ui/entities/document/schema-mapping.md
|
||||
|
||||
### QG-2 Traceability
|
||||
1. Each accepted behavior maps to at least one future UI action or service call path
|
||||
2. No acceptance criterion contradicts the current deferred-item policy
|
||||
|
||||
### QG-3 First-release constraints
|
||||
1. Linked person during create remains optional
|
||||
2. Recipient and multi-person expansion remain deferred
|
||||
@@ -2,7 +2,8 @@
|
||||
|
||||
Purpose: Map the Document schema to the UI, while clearly separating intended target behavior from current implementation.
|
||||
|
||||
Companion document: `user-journey.md`
|
||||
Companion document: user-journey.md
|
||||
Acceptance criteria: acceptance-criteria.md
|
||||
|
||||
## 1. Entity Snapshot
|
||||
|
||||
@@ -225,7 +226,7 @@ Current implementation:
|
||||
Companion UX spec:
|
||||
- `docs/ui/entities/document/user-journey.md`
|
||||
|
||||
## 10. Acceptance Checklist
|
||||
## 10. Acceptance Checklist Summary
|
||||
|
||||
- Every Document schema field appears in the field inventory.
|
||||
- Intended Create behavior matches the companion user journey.
|
||||
|
||||
@@ -4,6 +4,8 @@ Purpose: Define how a user should interact with the UI to create and manage a Do
|
||||
|
||||
Scope: This document describes intended user interaction for the Document UI. It is the UX contract for the Document entity.
|
||||
|
||||
Companion acceptance criteria: acceptance-criteria.md
|
||||
|
||||
## 1. Overview
|
||||
|
||||
A Document represents a real historical artifact the user wants to describe, organize, and eventually transcribe. The user should be able to create a Document before uploading or linking any source files.
|
||||
@@ -248,27 +250,168 @@ Examples:
|
||||
4. failed DocumentPerson link creation
|
||||
5. database or server error
|
||||
|
||||
## 11. Non-Goals for This Flow
|
||||
## 11. Read Document Journey
|
||||
|
||||
The Create Document flow does not:
|
||||
1. upload document images or PDFs
|
||||
2. create transcription jobs
|
||||
3. start AI processing
|
||||
4. create Source rows directly
|
||||
5. edit page-level transcription content
|
||||
### 11.1 User Intent
|
||||
|
||||
Those actions belong to later workflows.
|
||||
The user wants to open a specific Document and quickly understand:
|
||||
1. what the document is
|
||||
2. which people are linked to it
|
||||
3. whether sources exist
|
||||
4. whether jobs exist
|
||||
5. what the next action should be
|
||||
|
||||
## 12. Relationship to Other Workflows
|
||||
### 11.2 Entry Points
|
||||
|
||||
This Document creation workflow should precede:
|
||||
1. adding Sources to a Document
|
||||
2. creating transcription Jobs
|
||||
3. reviewing raw transcription output
|
||||
4. editing revised transcription text
|
||||
5. linking additional people or recipients later
|
||||
A user can reach a Document detail page by:
|
||||
1. selecting a document from the Document page list
|
||||
2. being redirected after successfully creating a new document
|
||||
3. following a direct link to a known Document record
|
||||
|
||||
## 13. Relationship to Schema Mapping
|
||||
### 11.3 Document Detail Layout
|
||||
|
||||
The Document detail page should include:
|
||||
1. a header area with document name, document type, and key date values
|
||||
2. a metadata section with location_created, notes, and archive_identifier
|
||||
3. system metadata where created_at and updated_at are shown as read-only values
|
||||
4. a related people section
|
||||
5. a Sources section
|
||||
6. a Jobs section
|
||||
|
||||
The Document detail page should support:
|
||||
1. empty-state messaging when no related records exist
|
||||
2. clear next actions from each empty state
|
||||
3. future links to filtered Sources and Jobs views scoped to the current document
|
||||
|
||||
### 11.4 Read Empty States
|
||||
|
||||
If no related records exist:
|
||||
1. People section says no linked people yet
|
||||
2. Sources section says no sources added yet
|
||||
3. Jobs section says no jobs created yet
|
||||
4. each section presents one clear next action
|
||||
|
||||
### 11.5 Read Success Criteria
|
||||
|
||||
A successful Read experience means:
|
||||
1. user can identify the Document immediately
|
||||
2. user can see whether work has started
|
||||
3. user can navigate directly to document-scoped Jobs and Sources workflows
|
||||
|
||||
## 12. Update Document Journey
|
||||
|
||||
### 12.1 User Intent
|
||||
|
||||
The user wants to correct or enrich metadata after creation without touching jobs or source transcriptions directly.
|
||||
|
||||
### 12.2 Update Entry Point
|
||||
|
||||
From the Document detail page:
|
||||
1. user selects Edit document
|
||||
2. UI opens edit mode or a dedicated edit view
|
||||
|
||||
### 12.3 Editable Fields
|
||||
|
||||
First release editable fields:
|
||||
1. name
|
||||
2. document_type
|
||||
3. document_date
|
||||
4. document_date_raw
|
||||
5. location_created
|
||||
6. notes
|
||||
7. archive_identifier
|
||||
|
||||
Read-only or system-managed fields:
|
||||
1. id
|
||||
2. created_at
|
||||
3. updated_at
|
||||
|
||||
### 12.4 Update Validation Rules
|
||||
|
||||
1. name remains required
|
||||
2. document_type remains required
|
||||
3. document_date and document_date_raw may both be present
|
||||
4. if both date fields are present, document_date remains canonical
|
||||
5. validation errors should be shown inline and block save
|
||||
|
||||
### 12.5 Update Save Behavior
|
||||
|
||||
On save:
|
||||
1. system validates form data
|
||||
2. system persists Document updates
|
||||
3. updated_at is refreshed by system policy
|
||||
4. UI shows a confirmation message
|
||||
5. user remains on Document detail page with refreshed values
|
||||
|
||||
### 12.6 Update Failure Behavior
|
||||
|
||||
If save fails:
|
||||
1. show a clear error message
|
||||
2. keep user edits in form where possible
|
||||
3. do not show stale success messaging
|
||||
4. allow retry without losing context
|
||||
|
||||
## 13. Delete Document Journey
|
||||
|
||||
### 13.1 User Intent
|
||||
|
||||
The user wants to remove a Document only when it is safe and unambiguous.
|
||||
|
||||
### 13.2 Delete Entry Point
|
||||
|
||||
From the Document detail page:
|
||||
1. user selects Delete document
|
||||
2. UI opens a confirmation dialog explaining permanence
|
||||
|
||||
### 13.3 Delete Guardrails
|
||||
|
||||
Delete is allowed only when:
|
||||
1. the Document has no related Source records
|
||||
2. the Document has no related Job records
|
||||
|
||||
Delete is blocked when:
|
||||
1. any Source exists for the Document
|
||||
2. any Job exists for the Document
|
||||
|
||||
### 13.4 Blocked Delete UX
|
||||
|
||||
When blocked:
|
||||
1. show an explicit reason that related Jobs or Sources exist
|
||||
2. show which dependency types are present
|
||||
3. provide links to filtered Sources and Jobs for cleanup
|
||||
4. keep the Document unchanged
|
||||
|
||||
### 13.5 Allowed Delete UX
|
||||
|
||||
When allowed:
|
||||
1. show final confirmation with document name
|
||||
2. perform delete
|
||||
3. show success confirmation
|
||||
4. return user to Document page list
|
||||
|
||||
### 13.6 Delete Failure Behavior
|
||||
|
||||
If delete fails due to system error:
|
||||
1. show a clear error message
|
||||
2. keep user on Document detail page
|
||||
3. preserve ability to retry
|
||||
|
||||
## 14. Non-Goals for This Flow
|
||||
|
||||
The Document journey does not define:
|
||||
1. Source upload field-level UX
|
||||
2. Job execution internals
|
||||
3. revision editor behavior for transcriptions
|
||||
4. multi-person recipient workflows in first release
|
||||
|
||||
## 15. Relationship to Other Workflows
|
||||
|
||||
This Document workflow integrates with:
|
||||
1. Sources workflow for adding pages or files to the document
|
||||
2. Jobs workflow for transcription execution
|
||||
3. Person workflow for future expansion beyond one optional linked person
|
||||
|
||||
## 16. Relationship to Schema Mapping
|
||||
|
||||
This document is the intended UX contract.
|
||||
|
||||
@@ -278,10 +421,10 @@ The companion schema-mapping document should answer:
|
||||
3. whether the field is hidden, editable, or system-managed
|
||||
4. what the implementation gap is between intended UX and current code
|
||||
|
||||
## 14. Deferred Items
|
||||
## 17. Deferred Items
|
||||
|
||||
These topics are intentionally deferred to future revisions:
|
||||
1. multiple linked people during create
|
||||
2. recipient support during create
|
||||
1. multiple linked people during create and update
|
||||
2. recipient support during create and update
|
||||
3. a broader role model for non-author document relationships
|
||||
4. filtered Jobs and Sources list navigation details
|
||||
|
||||
Reference in New Issue
Block a user