transcription/docs/ui/entities/document-person/schema-mapping.md

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.