generated from john/python-template
UI update planning complete
This commit is contained in:
Jim Lancaster
@@ -0,0 +1,182 @@
|
||||
# DocumentPerson Schema-to-UI Mapping
|
||||
|
||||
Purpose: Map the DocumentPerson schema to UI-facing workflows, while separating intended target behavior from current implementation.
|
||||
|
||||
Supporting entity note: DocumentPerson does not currently have a standalone UI surface.
|
||||
|
||||
## 1. Entity Snapshot
|
||||
|
||||
- Table: document_person
|
||||
- Primary key: id (UUID)
|
||||
- Related entities: Document, Person
|
||||
- Canonical schema references:
|
||||
- src/transcription/db/models.py
|
||||
- docs/schema_v2.md
|
||||
|
||||
## 2. Mapping Rules
|
||||
|
||||
This document uses three lenses:
|
||||
1. Intended behavior: what user-facing workflows should support indirectly.
|
||||
2. Current behavior: what code supports today.
|
||||
3. Gap to target: what must change to align implementation with intended UX.
|
||||
|
||||
## 3. Field Inventory
|
||||
|
||||
| Field | DB Type | Nullable | Default/Auto Value | Intended UI Treatment | Notes |
|
||||
|---|---|---|---|---|---|
|
||||
| id | UUID | No | uuid4() | Hidden, system-managed | Primary key |
|
||||
| document_id | UUID FK | No | None | Context-managed | Selected Document context |
|
||||
| person_id | UUID FK | No | None | Context-managed | Selected Person context |
|
||||
| role | enum DocumentPersonRole | No | author | Visible in relationship context | First-release behavior may default to author |
|
||||
| created_at | datetime | No | datetime.now(UTC) | Hidden or read-only | System-managed timestamp |
|
||||
|
||||
Constraint behavior:
|
||||
1. document_id, person_id, and role are unique as a tuple.
|
||||
2. duplicate links for the same document, person, and role must be rejected.
|
||||
|
||||
## 4. CREATE Mapping
|
||||
|
||||
### 4.1 Intended Create Flow
|
||||
|
||||
Entry points are indirect through user-facing entities:
|
||||
1. Document create or update workflows may create one or more DocumentPerson links.
|
||||
2. Person relationship workflows may create DocumentPerson links.
|
||||
|
||||
| Field | Intended User Input | Required | Visible | Notes |
|
||||
|---|---|---|---|---|
|
||||
| document_id | None | Yes | No | Derived from selected Document |
|
||||
| person_id | None | Yes | No | Derived from selected Person |
|
||||
| role | Select or default | Yes | Indirectly | Defaults to author in first-release behavior |
|
||||
| created_at | None | No | No | System-generated |
|
||||
|
||||
### 4.2 Current Implementation
|
||||
|
||||
Current entry point: service-level creation via DocumentService.create_document_person()
|
||||
Current user action: no dedicated DocumentPerson UI
|
||||
Current backend path: Document and Person workflows call DocumentPerson CRUD in DocumentService
|
||||
|
||||
| Field | Current Value at Create | Source | Visible to User | Evidence |
|
||||
|---|---|---|---|---|
|
||||
| id | Generated UUID | System | No | src/transcription/db/models.py |
|
||||
| document_id | Caller-provided | Service/API caller | No | src/transcription/services/documents.py |
|
||||
| person_id | Caller-provided | Service/API caller | No | src/transcription/services/documents.py |
|
||||
| role | Caller-provided or default author | Service/model default | No | src/transcription/db/models.py, src/transcription/services/documents.py |
|
||||
| created_at | Current UTC timestamp | System | No | src/transcription/db/models.py |
|
||||
|
||||
### 4.3 Gap to Target
|
||||
|
||||
To satisfy intended supporting behavior, implementation must add:
|
||||
1. explicit UI relationship controls in Document and/or Person detail flows.
|
||||
2. duplicate-link handling with clear user feedback.
|
||||
3. role-selection UX when role expansion is enabled beyond default author.
|
||||
|
||||
## 5. READ Mapping
|
||||
|
||||
### 5.1 Intended Read Behavior
|
||||
|
||||
Users should see DocumentPerson relationships indirectly in user-facing surfaces:
|
||||
1. Document detail shows linked people.
|
||||
2. Person detail shows linked documents.
|
||||
3. Relationship role is shown where relevant.
|
||||
|
||||
### 5.2 Current Implementation
|
||||
|
||||
Current read behavior is mainly service-level.
|
||||
|
||||
| Field | Current Rendering | Visible to User | Notes | Evidence |
|
||||
|---|---|---|---|---|
|
||||
| document_id/person_id link | Indirect relationship usage in workflows | Partial | Document/Person dedicated relationship surfaces are planned | docs/ui/entities/document/*, docs/ui/entities/person/* |
|
||||
| role | Not shown in current job-centric pages | No | Role expansion is deferred in user-facing workflows | docs/ui/entities/person/user-journey.md |
|
||||
| created_at | Not rendered | No | Operational metadata only | current UI pages |
|
||||
|
||||
Service read/query coverage:
|
||||
1. read_document_person() returns one link by id.
|
||||
2. list_document_people() supports filtering by document_id and person_id.
|
||||
|
||||
### 5.3 Gap to Target
|
||||
|
||||
To satisfy intended read behavior, implementation must add:
|
||||
1. linked-people and linked-documents UI sections backed by list_document_people().
|
||||
2. relationship role display where role context is required.
|
||||
|
||||
## 6. UPDATE Mapping
|
||||
|
||||
### 6.1 Intended Update Behavior
|
||||
|
||||
DocumentPerson updates are limited to relationship role or relationship-management actions.
|
||||
|
||||
Intended editable fields:
|
||||
- role (when role management is enabled)
|
||||
|
||||
Intended read-only fields:
|
||||
- id
|
||||
- document_id
|
||||
- person_id
|
||||
- created_at
|
||||
|
||||
### 6.2 Current Implementation
|
||||
|
||||
| Field | Updatable via UI | Updatable via Service | Notes |
|
||||
|---|---|---|---|
|
||||
| role | No | Yes | DocumentService.update_document_person() supports updates |
|
||||
| document_id/person_id | No | Technically yes via full-row update | Should generally be treated as immutable link identity |
|
||||
| created_at | No | Technically yes | Should remain system-managed |
|
||||
|
||||
### 6.3 Gap to Target
|
||||
|
||||
Implementation should add:
|
||||
1. explicit relationship-role edit controls when product scope enables them.
|
||||
2. safeguards against mutating link identity instead of recreating links.
|
||||
|
||||
## 7. DELETE Mapping
|
||||
|
||||
### 7.1 Intended Delete Behavior
|
||||
|
||||
Deletion of DocumentPerson should be exposed as unlink behavior in Document and Person flows.
|
||||
|
||||
Rules:
|
||||
1. unlink should remove only the selected relationship.
|
||||
2. unlink must not delete the underlying Document or Person records.
|
||||
|
||||
### 7.2 Current Implementation
|
||||
|
||||
| Action | UI Exposed | Backend Capability | Notes |
|
||||
|---|---|---|---|
|
||||
| Delete DocumentPerson link | No | Yes | DocumentService.delete_document_person() exists |
|
||||
|
||||
### 7.3 Gap to Target
|
||||
|
||||
Implementation must add:
|
||||
1. unlink controls in relationship sections.
|
||||
2. confirmation and success feedback for relationship removal.
|
||||
3. blocked-delete guidance if policy constraints are added later.
|
||||
|
||||
## 8. Hidden and System-Managed Fields
|
||||
|
||||
| Field | Category | Why Hidden or Protected |
|
||||
|---|---|---|
|
||||
| id | System-managed | Internal identifier |
|
||||
| document_id | Context-managed | Derived from selected Document |
|
||||
| person_id | Context-managed | Derived from selected Person |
|
||||
| created_at | System-managed | Audit timestamp |
|
||||
|
||||
## 9. Traceability Anchors
|
||||
|
||||
Schema and models:
|
||||
- docs/schema_v2.md
|
||||
- src/transcription/db/models.py
|
||||
|
||||
Current implementation:
|
||||
- src/transcription/services/documents.py
|
||||
- tests/services/test_v2_crud.py
|
||||
|
||||
Related user-facing workflows:
|
||||
- docs/ui/entities/document/user-journey.md
|
||||
- docs/ui/entities/person/user-journey.md
|
||||
|
||||
## 10. Coverage Summary
|
||||
|
||||
- Every DocumentPerson schema field appears in the field inventory.
|
||||
- Intended behavior is defined as supporting workflow behavior rather than standalone UI.
|
||||
- Current behavior reflects service-level CRUD with no dedicated UI.
|
||||
- Gaps between intended and current behavior are explicit.
|
||||
Reference in New Issue
Block a user