generated from john/python-template
288 lines
10 KiB
Markdown
288 lines
10 KiB
Markdown
# Document User Journey
|
|
|
|
Purpose: Define how a user should interact with the UI to create and manage a Document record, including expected inputs, validation, results, and related record creation.
|
|
|
|
Scope: This document describes intended user interaction for the Document UI. It is the UX contract for the Document entity.
|
|
|
|
## 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.
|
|
|
|
Creating a Document is a metadata-first workflow:
|
|
1. The user opens the Document page.
|
|
2. The user selects Create new document.
|
|
3. The user enters descriptive metadata about the document.
|
|
4. The user optionally links one related person.
|
|
5. The system creates the Document.
|
|
6. If a person was selected or created, the system links that Person to the Document through DocumentPerson.
|
|
7. The user sees a success state and lands on the new Document detail page.
|
|
|
|
## 2. User Goal
|
|
|
|
The user wants to create a new Document record that:
|
|
1. Has enough metadata to identify the historical artifact.
|
|
2. Can optionally be linked to a person.
|
|
3. Exists independently of transcription jobs and source uploads.
|
|
4. Is ready for later steps such as adding sources, starting jobs, and reviewing transcriptions.
|
|
|
|
## 3. Page Model
|
|
|
|
### 3.1 Document Page
|
|
|
|
The Document page is the general UI surface where users manage documents.
|
|
|
|
It should support:
|
|
1. listing or locating existing documents
|
|
2. starting the Create new document flow
|
|
3. navigating into a specific Document after it exists
|
|
|
|
### 3.2 Document Detail Page
|
|
|
|
The Document detail page is the page for one specific Document after it has been created.
|
|
|
|
It should show:
|
|
1. the Document metadata
|
|
2. related people linked to the Document
|
|
3. a Sources section
|
|
4. a Jobs section
|
|
5. empty states when no sources or jobs exist yet
|
|
|
|
It should later support links to filtered views for:
|
|
1. jobs associated with the current document only
|
|
2. sources associated with the current document only
|
|
|
|
## 4. Entry Point
|
|
|
|
Entry point: Document page
|
|
|
|
Primary action: Create new document
|
|
|
|
Expected UI affordance:
|
|
1. A visible button, link, or primary action labeled Create new document.
|
|
2. Activation opens a dedicated form view, modal, or detail panel for creating a Document.
|
|
|
|
Preferred first implementation:
|
|
1. A dedicated Document create page or panel.
|
|
2. A simple form with explicit labels.
|
|
3. Text inputs are acceptable for first release, even where future versions may use dropdowns or richer selectors.
|
|
|
|
## 5. Create Document Form
|
|
|
|
The Create Document form should contain the following fields.
|
|
|
|
### 5.1 Required Fields
|
|
|
|
| UI Label | Schema Field | Input Type | Required | Notes |
|
|
|---|---|---|---|---|
|
|
| Document name | name | Text input | Yes | Examples: Pioneer Days, Letter from Zenna to Omie |
|
|
| Document type | document_type | Text input | Yes | Examples: book, letter, enlistment papers, military record, other |
|
|
|
|
### 5.2 Date Fields
|
|
|
|
| UI Label | Schema Field | Input Type | Required | Notes |
|
|
|---|---|---|---|---|
|
|
| Exact date | document_date | Date input | No | Use when the exact date is known |
|
|
| Approximate date | document_date_raw | Text input | No | Use when exact date is uncertain, approximate, or unknown |
|
|
|
|
Date handling rule:
|
|
1. The form may allow both fields to be entered.
|
|
2. If both fields are entered, `document_date` is the canonical structured date.
|
|
3. `document_date_raw` may still be retained as the user-entered descriptive form.
|
|
4. The UI should explain the distinction clearly.
|
|
|
|
Examples:
|
|
1. Exact date: `07/13/1885`
|
|
2. Approximate date: `c. 1885`
|
|
3. Approximate date: `Fall 1925`
|
|
4. Approximate date: `unknown`
|
|
|
|
### 5.3 Optional Metadata Fields
|
|
|
|
| UI Label | Schema Field | Input Type | Required | Notes |
|
|
|---|---|---|---|---|
|
|
| Document location | location_created | Text input | No | Where the document was created |
|
|
| Notes | notes | Multiline text area | No | Freeform notes about the document |
|
|
| Archive identifier | archive_identifier | Text input | No | Free text for now; may represent inventory code, storage reference, or repository note |
|
|
|
|
Archive identifier guidance:
|
|
1. First implementation should treat this as free text.
|
|
2. Helper text may explain that this can store a repository code, box or folder reference, or storage note.
|
|
|
|
### 5.4 System Fields
|
|
|
|
| Schema Field | User Editable | Notes |
|
|
|---|---|---|
|
|
| created_at | No | System-generated at creation time |
|
|
| updated_at | No | Not user-entered during creation |
|
|
|
|
### 5.5 Optional Related Person
|
|
|
|
The Create Document flow may optionally link one related person during first release.
|
|
|
|
| UI Label | Schema Area | Input Type | Required | Notes |
|
|
|---|---|---|---|---|
|
|
| Related person | Person -> DocumentPerson | Search/select or create inline | No | Intended to support common author-like associations without making the field mandatory |
|
|
|
|
First release behavior:
|
|
1. The user may save a Document without linking any person.
|
|
2. If a person is linked during create, only one person is supported in first release.
|
|
3. Additional people and recipient workflows are deferred to a future revision.
|
|
|
|
### 5.6 Related Records Not Created Directly Here
|
|
|
|
| Related Area | Included in Document Create | Notes |
|
|
|---|---|---|
|
|
| Jobs | No | Jobs are created later when transcription work begins |
|
|
| Sources | No | Sources are added later as uploaded pages or files |
|
|
|
|
## 6. Related Person Workflow
|
|
|
|
### 6.1 User Intent
|
|
|
|
The user should be able to:
|
|
1. select an existing Person to associate with the Document
|
|
2. create a new Person if the person does not already exist
|
|
3. save the Document even if no person is linked
|
|
|
|
### 6.2 Data Model Interpretation
|
|
|
|
Person selection source:
|
|
1. The UI should select from Person records.
|
|
2. If a person is linked, the system should create a DocumentPerson record.
|
|
3. Role handling for non-author document relationships is deferred.
|
|
4. If the first release needs a persisted role immediately, the role can default to `author` until the relationship model is broadened.
|
|
|
|
This means:
|
|
1. The user does not choose from DocumentPerson records.
|
|
2. DocumentPerson is the relationship created after the Person is chosen or created.
|
|
|
|
### 6.3 Related Person UI Behavior
|
|
|
|
Minimum acceptable first implementation:
|
|
1. Searchable or scrollable list of existing Person records.
|
|
2. Option to create a new Person inline or in a small secondary flow.
|
|
3. Clear display of the selected related person before submit.
|
|
|
|
If the person does not exist:
|
|
1. User selects Create new person.
|
|
2. User enters the minimum required Person information.
|
|
3. System creates Person.
|
|
4. System returns to Document create flow.
|
|
5. System links the new Person if the user completes Document creation.
|
|
|
|
## 7. Validation Rules
|
|
|
|
### 7.1 Required Field Validation
|
|
|
|
The form must reject submission if:
|
|
1. `name` is empty
|
|
2. `document_type` is empty
|
|
|
|
### 7.2 Date Validation
|
|
|
|
The form should allow:
|
|
1. `document_date` only
|
|
2. `document_date_raw` only
|
|
3. both `document_date` and `document_date_raw`
|
|
4. neither date field
|
|
|
|
If both are present:
|
|
1. `document_date` is treated as the canonical exact date
|
|
2. `document_date_raw` is retained as descriptive context
|
|
|
|
### 7.3 Related Person Validation
|
|
|
|
The form must not require a linked person in first release.
|
|
|
|
If a related person is selected or created:
|
|
1. the selected value must resolve to a valid Person record before final save
|
|
2. the DocumentPerson link must not be partially persisted on failure
|
|
|
|
## 8. Submission Behavior
|
|
|
|
When the user submits the form, the system should perform these logical steps:
|
|
1. validate form inputs
|
|
2. create the Document record
|
|
3. create a Person record only if the user chose to add a new related person
|
|
4. create one DocumentPerson record only if a related person was selected or created
|
|
5. persist all intended records successfully before reporting success to the user
|
|
|
|
Expected write sequence:
|
|
1. insert Document
|
|
2. insert Person only if needed
|
|
3. insert DocumentPerson link only if a person is linked
|
|
|
|
Recommended transactional behavior:
|
|
1. all related writes should succeed or fail together
|
|
2. the user should not end up with a partial create state where the Document exists but an intended person link does not
|
|
|
|
## 9. Expected Result After Success
|
|
|
|
After successful creation, the user should expect to see:
|
|
1. confirmation that the Document was created successfully
|
|
2. the Document name displayed in the resulting UI state
|
|
3. the Document metadata displayed on the new Document detail page
|
|
4. any linked person displayed in the resulting UI state
|
|
5. a Sources section showing an empty state when no sources exist yet
|
|
6. a Jobs section showing an empty state when no jobs exist yet
|
|
7. a clear next step, such as adding source files
|
|
|
|
Recommended success route:
|
|
1. navigate to the new Document detail page
|
|
2. show Document summary metadata
|
|
3. show linked people section
|
|
4. show empty-state placeholders for Sources and Jobs
|
|
|
|
## 10. Expected Result After Failure
|
|
|
|
If submission fails, the user should expect:
|
|
1. clear error messaging
|
|
2. field-level validation feedback where applicable
|
|
3. no false success message
|
|
4. preservation of entered form values when possible
|
|
|
|
Examples:
|
|
1. missing required name
|
|
2. missing required document type
|
|
3. failed person creation
|
|
4. failed DocumentPerson link creation
|
|
5. database or server error
|
|
|
|
## 11. Non-Goals for This Flow
|
|
|
|
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
|
|
|
|
Those actions belong to later workflows.
|
|
|
|
## 12. Relationship to Other Workflows
|
|
|
|
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
|
|
|
|
## 13. Relationship to Schema Mapping
|
|
|
|
This document is the intended UX contract.
|
|
|
|
The companion schema-mapping document should answer:
|
|
1. which schema field appears on which screen
|
|
2. whether the field is currently implemented
|
|
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
|
|
|
|
These topics are intentionally deferred to future revisions:
|
|
1. multiple linked people during create
|
|
2. recipient support during create
|
|
3. a broader role model for non-author document relationships
|
|
4. filtered Jobs and Sources list navigation details
|