bbchops/transcription
1
0
Fork 0
generated from john/python-template
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

UI slog grinds on

Browse Source
This commit is contained in:
Jim Lancaster
2026-08-02 23:44:53 -05:00
parent c098013a68
commit 47aef0e26e
13 changed files with 192 additions and 162 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ui/entities/person/acceptance-criteria.md
+2
View File
@@ -35,6 +35,7 @@ This checklist does not cover:
1. Optional fields may be blank without blocking create
2. Date raw and exact fields can coexist
3. Exact date remains canonical when both exact and raw are provided
4. Portrait uploads persist under uploads/portraits/person and store a relative portrait_path
### CR-4 Successful create outcome
1. Given valid input
@@ -60,6 +61,7 @@ This checklist does not cover:
1. The page shows full_name and available optional person fields
2. created_at and updated_at are shown as system-managed, read-only values
3. portrait_path is rendered when available, including an image preview when possible
4. relative portrait_path values resolve through /uploads for image rendering
### RD-3 Linked documents section
1. Given no linked DocumentPerson rows
docs/ui/entities/person/schema-mapping.md
+43 -42
View File
@@ -72,31 +72,31 @@ Related records during intended create:
### 4.2 Current Implementation
Current entry point: no dedicated Person UI page yet
Current user action: none in UI
Current backend path: service calls via DocumentService.create_person()
Current entry point: dedicated People page and Person create/edit flows
Current user action: open Person create page, fill form fields, optionally upload portrait
Current backend path: People page submit callbacks -> DocumentService.create_person() / update_person()
| Field | Current Value at Create | Source | Visible to User | Evidence |
|---|---|---|---|---|
| id | Generated UUID | System | No | Person model default factory in src/transcription/db/models.py |
| full_name | Caller-provided | Service/API caller | No | create_person() in src/transcription/services/documents.py |
| display_name | Caller-provided or None | Service/API caller | No | create_person() in src/transcription/services/documents.py |
| maiden_name | Caller-provided or None | Service/API caller | No | create_person() in src/transcription/services/documents.py |
| birth_date | Caller-provided or None | Service/API caller | No | create_person() in src/transcription/services/documents.py |
| birth_date_raw | Caller-provided or None | Service/API caller | No | create_person() in src/transcription/services/documents.py |
| birth_place | Caller-provided or None | Service/API caller | No | create_person() in src/transcription/services/documents.py |
| death_date | Caller-provided or None | Service/API caller | No | create_person() in src/transcription/services/documents.py |
| death_date_raw | Caller-provided or None | Service/API caller | No | create_person() in src/transcription/services/documents.py |
| death_place | Caller-provided or None | Service/API caller | No | create_person() in src/transcription/services/documents.py |
| biography | Caller-provided or None | Service/API caller | No | create_person() in src/transcription/services/documents.py |
| portrait_path | Caller-provided or None | Service/API caller | No | create_person() in src/transcription/services/documents.py |
| full_name | Form input | User input | Yes | src/transcription/ui/pages/people_page.py |
| display_name | Form input or None | User input | Yes | src/transcription/ui/pages/people_page.py |
| maiden_name | Form input or None | User input | Yes | src/transcription/ui/pages/people_page.py |
| birth_date | Form input or None | User input | Yes | src/transcription/ui/pages/people_page.py |
| birth_date_raw | Form input or None | User input | Yes | src/transcription/ui/pages/people_page.py |
| birth_place | Form input or None | User input | Yes | src/transcription/ui/pages/people_page.py |
| death_date | Form input or None | User input | Yes | src/transcription/ui/pages/people_page.py |
| death_date_raw | Form input or None | User input | Yes | src/transcription/ui/pages/people_page.py |
| death_place | Form input or None | User input | Yes | src/transcription/ui/pages/people_page.py |
| biography | Form input or None | User input | Yes | src/transcription/ui/pages/people_page.py |
| portrait_path | Relative upload path or manual path | Upload helper + user input | Yes | src/transcription/ui/pages/people_page.py, src/transcription/services/store.py |
| metadata_ | Caller-provided or None | Service/API caller | No | Person model in src/transcription/db/models.py |
| created_at | Current UTC timestamp | System | No | Person model default in src/transcription/db/models.py |
| updated_at | Current UTC timestamp | System | No | Person model default in src/transcription/db/models.py |
### 4.3 Gap to Target
To satisfy the intended Create flow, implementation must add:
To satisfy the intended Create flow, implementation now includes:
1. a Person page and dedicated create form
2. user-entered controls for Person fields
3. create validation and success/failure UX states
@@ -113,24 +113,24 @@ On the Person detail page, the user should be able to see:
### 5.2 Current Implementation
Current Person visibility in the UI is not implemented as a dedicated page.
Current Person visibility is implemented in dedicated list/detail/edit/delete pages.
| Field | Current Rendering | Visible to User | Notes | Evidence |
|---|---|---|---|---|
| full_name | Rendered in header and summary | Yes | Dedicated Person page exists | `src/transcription/ui/pages/people_page.py` |
| display_name | Not rendered | No | No current Person page | no Person page in src/transcription/ui |
| maiden_name | Not rendered | No | No current Person page | no Person page in src/transcription/ui |
| birth_date | Not rendered | No | No current Person page | no Person page in src/transcription/ui |
| birth_date_raw | Not rendered | No | No current Person page | no Person page in src/transcription/ui |
| birth_place | Not rendered | No | No current Person page | no Person page in src/transcription/ui |
| death_date | Not rendered | No | No current Person page | no Person page in src/transcription/ui |
| death_date_raw | Not rendered | No | No current Person page | no Person page in src/transcription/ui |
| death_place | Not rendered | No | No current Person page | no Person page in src/transcription/ui |
| biography | Not rendered | No | No current Person page | no Person page in src/transcription/ui |
| display_name | Rendered | Yes | Visible in detail and list contexts | src/transcription/ui/pages/people_page.py |
| maiden_name | Rendered | Yes | Visible in detail context | src/transcription/ui/pages/people_page.py |
| birth_date | Rendered | Yes | Visible in detail context | src/transcription/ui/pages/people_page.py |
| birth_date_raw | Rendered | Yes | Visible in detail context | src/transcription/ui/pages/people_page.py |
| birth_place | Rendered | Yes | Visible in detail context | src/transcription/ui/pages/people_page.py |
| death_date | Rendered | Yes | Visible in detail context | src/transcription/ui/pages/people_page.py |
| death_date_raw | Rendered | Yes | Visible in detail context | src/transcription/ui/pages/people_page.py |
| death_place | Rendered | Yes | Visible in detail context | src/transcription/ui/pages/people_page.py |
| biography | Rendered | Yes | Visible in detail context | src/transcription/ui/pages/people_page.py |
| portrait_path | Rendered as text and image when available | Yes | Dedicated Person page exists | `src/transcription/ui/pages/people_page.py` |
| metadata_ | Not rendered | No | Hidden advanced field | no current UI field |
| created_at | Not rendered | No | No current Person page | no Person page in src/transcription/ui |
| updated_at | Not rendered | No | No current Person page | no Person page in src/transcription/ui |
| created_at | Rendered read-only | Yes | Visible in detail context | src/transcription/ui/pages/people_page.py |
| updated_at | Rendered read-only | Yes | Visible in detail context | src/transcription/ui/pages/people_page.py |
### 5.3 Gap to Target
@@ -171,17 +171,17 @@ Hidden in first release:
| Field | Updatable via UI | Updatable via Service | Notes |
|---|---|---|---|
| id | No | Practically no | Primary key should be treated as immutable |
| full_name | No | Yes | DocumentService.update_person() |
| display_name | No | Yes | DocumentService.update_person() |
| maiden_name | No | Yes | DocumentService.update_person() |
| birth_date | No | Yes | DocumentService.update_person() |
| birth_date_raw | No | Yes | DocumentService.update_person() |
| birth_place | No | Yes | DocumentService.update_person() |
| death_date | No | Yes | DocumentService.update_person() |
| death_date_raw | No | Yes | DocumentService.update_person() |
| death_place | No | Yes | DocumentService.update_person() |
| biography | No | Yes | DocumentService.update_person() |
| portrait_path | No | Yes | DocumentService.update_person() |
| full_name | Yes | Yes | Editable from Person edit page via DocumentService.update_person() |
| display_name | Yes | Yes | Editable from Person edit page via DocumentService.update_person() |
| maiden_name | Yes | Yes | Editable from Person edit page via DocumentService.update_person() |
| birth_date | Yes | Yes | Editable from Person edit page via DocumentService.update_person() |
| birth_date_raw | Yes | Yes | Editable from Person edit page via DocumentService.update_person() |
| birth_place | Yes | Yes | Editable from Person edit page via DocumentService.update_person() |
| death_date | Yes | Yes | Editable from Person edit page via DocumentService.update_person() |
| death_date_raw | Yes | Yes | Editable from Person edit page via DocumentService.update_person() |
| death_place | Yes | Yes | Editable from Person edit page via DocumentService.update_person() |
| biography | Yes | Yes | Editable from Person edit page via DocumentService.update_person() |
| portrait_path | Yes | Yes | Editable manually and via portrait upload helper |
| metadata_ | No | Yes | Technically updatable, hidden in first release |
| created_at | No | Technically yes | Should remain system-managed |
| updated_at | No | Technically yes | Should remain system-managed |
@@ -208,11 +208,11 @@ Rules:
| Action | UI Exposed | Backend Capability | Notes |
|---|---|---|---|
| Delete Person | No | Yes | DocumentService.delete_person() exists, but no dedicated UI guard flow exists |
| Delete Person | Yes | Yes | Dedicated delete page enforces linked-document guardrails before service delete |
### 7.3 Gap to Target
Implementation must add:
Implementation includes:
1. a Person delete control in the UI
2. relationship-aware pre-delete checks
3. user-facing blocked-delete messaging
@@ -247,7 +247,8 @@ Schema and models:
Current implementation:
- src/transcription/services/documents.py
- src/transcription/ui (no dedicated Person pages yet)
- src/transcription/ui/pages/people_page.py
- src/transcription/services/store.py
Companion UX spec:
- docs/ui/entities/person/user-journey.md
@@ -259,6 +260,6 @@ Acceptance checklist:
- Every Person schema field appears in the field inventory.
- Intended Create behavior matches the companion user journey.
- Current Create behavior reflects service-level implementation.
- Current Create behavior reflects dedicated UI form implementation with optional portrait upload handling.
- Gaps between intended and current behavior are explicit.
- Read, Update, and Delete sections distinguish target behavior from current code.
docs/ui/entities/person/user-journey.md
+2
View File
@@ -136,6 +136,7 @@ On submit:
2. The system creates the Person record
3. The system returns the user to the Person detail page
4. The system shows a success message
5. If portrait upload is used, the file is stored under uploads/portraits/person and portrait_path is set to that relative file path
Recommended transactional behavior:
1. Person writes are atomic
@@ -173,6 +174,7 @@ The Person detail page should show:
2. birth and death fields
3. biography summary
4. related documents list or empty state
5. portrait preview resolved from /uploads when portrait_path is a relative path
### 10.3 Read Empty State