generated from john/python-template
100 lines
4.1 KiB
Markdown
100 lines
4.1 KiB
Markdown
# Implementation Plan (Version 4)
|
|
|
|
## Goal
|
|
|
|
Implement the Version 4 project definition from the current repository state while preserving existing data by default.
|
|
|
|
## Migration Policy
|
|
|
|
- Database changes are non-destructive by default.
|
|
- Exception: the legacy `document_type` text field may be replaced by a `document_type_id` reference without migrating existing text values.
|
|
- Exception: `document_person` links may be recreated manually.
|
|
|
|
## Current Project Impact
|
|
|
|
- `src/transcription/db/models.py` requires full schema alignment with the V4 core documents.
|
|
- `src/transcription/services/documents.py` requires set-based document-person sync and document-type resolution.
|
|
- API modules require additive role-aware relationship behavior and document-type selection behavior.
|
|
- UI pages require grouped role displays, multi-role editing, and registry-backed document-type selection.
|
|
- Existing tests require updates for role enforcement, document-type selection, and regression safety.
|
|
|
|
## Implementation Phases
|
|
|
|
### 1. Finalize the Transition Documents
|
|
|
|
- Confirm the reset scope.
|
|
- Confirm the database exception policy.
|
|
- Keep core V4 documents as the only authoritative product definition.
|
|
|
|
### 2. Align the Persistence Layer
|
|
|
|
- Update SQLModel definitions to match the final V4 schema.
|
|
- Add `person_role` and `document_type` support.
|
|
- Replace legacy document-type storage with `document_type_id`.
|
|
- Apply the accepted manual exception strategy for `document_type` and `document_person` data.
|
|
- Preserve all other data structures non-destructively.
|
|
|
|
### 3. Update Services and Write Semantics
|
|
|
|
- Implement set-based synchronization for document-person updates.
|
|
- Implement deterministic uniqueness and relationship-write conflict checks.
|
|
- Remove suggestion-related service behavior.
|
|
- Add document-type resolution and validation by stable code or id.
|
|
|
|
### 4. Update API Contracts
|
|
|
|
- Keep API evolution additive.
|
|
- Add role-aware relationship retrieval and write behavior.
|
|
- Add document-type catalog retrieval and code-based selection for document writes.
|
|
- Remove suggestion-related API surfaces from the V4 target state.
|
|
|
|
### 5. Update UI Workflows
|
|
|
|
- Replace single-person link editing with grouped multi-role editing.
|
|
- Render grouped role links on document and person detail views.
|
|
- Replace free-text document type entry with registry-backed selection.
|
|
- Preserve clear validation and conflict messaging.
|
|
|
|
### 6. Verification and Hardening
|
|
|
|
- Add or update service tests for many-per-role behavior, uniqueness conflict handling, and set-based sync correctness.
|
|
- Add API tests for relationship behavior and document-type selection.
|
|
- Add UI tests or walkthrough coverage for grouped roles and type selection.
|
|
- Add regression coverage for delete and cleanup semantics.
|
|
- Enforce backup-first test execution for AI-run unit tests: backup `./data` before tests, then always prompt for restore after successful tests.
|
|
- Keep restore confirmation-gated by default so code and test outcomes can be reviewed before data is reverted.
|
|
|
|
## Done When
|
|
|
|
- Core V4 documents and code paths agree on the final project definition.
|
|
- Relationship-role writes are deterministic and non-destructive.
|
|
- Relationship-write conflict rules are enforced consistently.
|
|
- Document type selection is registry-backed.
|
|
- The accepted manual exceptions for `document_type` and `document_person` are completed.
|
|
- The focused test coverage passes.
|
|
|
|
## Out of Scope
|
|
|
|
- Suggested/asserted relationship state.
|
|
- Suggestion review or extraction workflows.
|
|
- Global person entity-resolution engine.
|
|
- Automated semantic document-type classification.
|
|
|
|
## Delivery Order Recommendation
|
|
|
|
1. Freeze scope boundary and implementation plan.
|
|
2. Freeze core V4 documents.
|
|
3. Align persistence models.
|
|
4. Align services and API behavior.
|
|
5. Align UI behavior.
|
|
6. Run focused verification and regression checks.
|
|
|
|
## Related Local References
|
|
|
|
- [V4 Scope Boundary](scope_boundary_v4.md)
|
|
- [System Overview](index_v4.md)
|
|
- [System Requirements](requirements_v4.md)
|
|
- [Data Model](schema_v4.md)
|
|
- [System Architecture](architecture_v4.md)
|
|
- [Error Handling Policy](error_handling_v4.md)
|