generated from john/python-template
183 lines
7.0 KiB
Markdown
183 lines
7.0 KiB
Markdown
# 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: Document create/edit flows
|
|
Current user action: select an existing Person from the Document author dropdown
|
|
Current backend path: Document page submit callback -> `DocumentService.create_document_person()` or `delete_document_person()` as the author selection changes
|
|
|
|
| Field | Current Value at Create | Source | Visible to User | Evidence |
|
|
|---|---|---|---|---|
|
|
| id | Generated UUID | System | No | src/transcription/db/models.py |
|
|
| document_id | Caller-provided | Document UI | Indirectly | src/transcription/ui/pages/documents_page.py |
|
|
| person_id | Caller-provided | Document UI | Indirectly | src/transcription/ui/pages/documents_page.py |
|
|
| role | Default author in current UI | 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 UI-backed CRUD through Document create/edit flows and Person detail rendering, with no standalone DocumentPerson UI.
|
|
- Gaps between intended and current behavior are explicit.
|