Implementation Plan (Version 4)

Goal

Implement V4 document-person relationship expansion and document type governance with extensible registries, assisted suggestion lifecycle, and policy-enforced exclusivity while preserving V3 transcription behavior.

Current Project Impact

src/transcription/db/models.py will require relationship schema evolution for role extensibility and suggestion lifecycle support.
src/transcription/db/models.py will require document type registry entities and document type reference updates.
src/transcription/services/documents.py will require set-based relationship sync and policy checks.
src/transcription/services/documents.py will require registry-based document type lookup, validation, and normalization helpers.
API modules under src/transcription/api/** will require role/state-aware contracts and suggestion lifecycle endpoints.
API modules under src/transcription/api/** will require additive document type catalog and code-based selection contracts.
UI pages under src/transcription/ui/pages/** will require multi-role, multi-person editing, suggestion review controls, and registry-backed type selectors.
Existing tests under tests/services, tests/api, and tests/ui need expanded coverage for V4 behavior and regression safety.

Implementation Phases

1. Finalize V4 Schema Decisions

Role extensibility mechanism: use role registry tables.
Document type extensibility mechanism: use document_type registry tables.
Suggestion storage model: use a separate document_person_suggestion table.
Exclusivity baseline: author vs recipient exclusive, mentioned non-exclusive.
Enforce exclusivity on asserted links; evaluate conflicts on suggestion acceptance.

2. Evolve Persistence Layer

Implement selected schema model in SQLModel.
Add constraints and indexes for dedupe, filtering, and policy support.
Add migration/backfill logic for V3 links to V4 asserted semantics.
Add conflict scan tooling for historical records violating exclusivity rules.
Perform a one-time manual mapping of existing document type values to registry-backed type references (document_type_id) for the current small corpus.

3. Implement Service-Layer Policy and Sync Semantics

Add relationship delta sync operations (set-based add/remove).
Implement centralized policy evaluator for exclusivity checks.
Add suggestion lifecycle operations (propose/list/accept/reject).
Ensure accepted suggestions create/confirm asserted links atomically.
Add document type resolution operations by stable code and active/inactive state handling.

4. Implement API Contract Changes

Add role-aware and state-aware query parameters/filters.
Add suggestion lifecycle endpoints and response models.
Add deterministic conflict/error payloads aligned to V4 error policy.
Use additive endpoint evolution for V4; during development mode, deprecate then remove without maintaining long-lived legacy runtime compatibility layers.
Add document type catalog endpoints with active-only filtering and code-based selection for document writes.

5. Update UI Workflows

Replace single-author controls with grouped multi-role selectors.
Replace unconstrained document type free-text entry with registry-backed type selection.
Add pending suggestion review panel and accept/reject actions.
Update document/person detail cards to group links by role and state.
Preserve edit-state ergonomics on validation/conflict failures.

6. Verification and Hardening

Add service tests for:
- many-per-role behavior,
- exclusivity enforcement,
- set-based sync correctness,
- suggestion transition validity,
- document type code resolution and inactive-type handling.
Add API tests for role/state filtering and conflict response shapes.
Add API tests for document type catalog retrieval and code-based write validation.
Add UI tests/manual walkthroughs for create/edit/review workflows.
Add UI tests/manual walkthroughs for registry-backed document type selection and validation messaging.
Add regression tests for document/person delete cleanup semantics.

Done When

V4 relationship schema and contracts are implemented and validated.
V4 document type registry schema and contracts are implemented and validated.
Suggestions remain non-canonical until explicit acceptance.
Exclusivity policy is enforced deterministically across service/API boundaries.
Existing V3 links are migrated to V4 asserted semantics without data loss.
Existing document type strings are manually normalized to registry references for the current corpus.
Test suite includes V4-specific coverage and passes on supported backends.

Out of Scope

Automatic acceptance of suggestions.
Global person entity-resolution/merge engine.
Core transcription execution redesign unrelated to relationship expansion.
Automated semantic document type classification.

Delivery Order Recommendation

Requirements freeze (requirements_v4.md).
Schema decision freeze (schema_v4.md).
Error policy freeze (error_handling_v4.md).
Implementation of persistence and service layer.
API and UI changes.
Final integration and regression validation.

5.4 KiB Raw Blame History