# 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.