generated from john/python-template
189 lines
6.4 KiB
Markdown
189 lines
6.4 KiB
Markdown
# Version 1 Implementation Plan
|
|
|
|
This plan defines the path from current implementation to **Version 1 complete**, aligned to the updated domain model:
|
|
|
|
- `Document` groups one or more content `Source` records
|
|
- `Job` owns original immutable provider output (`text`) and processing metadata
|
|
- `Revision` stores optional user-authored edits linked to a `Source`
|
|
|
|
The objective is to complete V1 scope with production readiness while keeping non-V1 enhancements out of active delivery.
|
|
|
|
---
|
|
|
|
## V1 Completion Definition
|
|
|
|
V1 is complete when all of the following are true:
|
|
|
|
1. **Functional complete**
|
|
- Upload, queue, processing, status display, and transcription result inspection work end-to-end.
|
|
- Optional revision workflow is implemented (create/list/view).
|
|
2. **Data-model complete**
|
|
- Runtime behavior, persistence, and tests all align to `Document` / `Source` / `Job` / `Revision`.
|
|
3. **Operational complete**
|
|
- Error handling, logs, and runbooks support reliable operation.
|
|
4. **Documentation complete**
|
|
- Architecture, requirements, schema, error handling, and index are consistent and current.
|
|
|
|
---
|
|
|
|
## Phase 1 — Data Contract Stabilization (Schema-First)
|
|
|
|
**Goal:** Lock a single canonical contract before further feature work.
|
|
|
|
### Tasks
|
|
1. Confirm and document invariants:
|
|
- `Job.text` is original immutable transcription output.
|
|
- `Revision` is optional and user-authored.
|
|
- Revisions may derive from original `Job.text` or a previous revision.
|
|
2. Verify relationship cardinality assumptions:
|
|
- `Document` -> many `Source`
|
|
- `Document` -> many `Job`
|
|
- `Source` -> one `Job`
|
|
- `Source` -> many `Revision`
|
|
3. Ensure field naming consistency (`date_created`, `date_updated`, `date_uploaded`) across code and docs.
|
|
4. Freeze V1 status lifecycle to current implementation (`queued`, `processing`, `transcribed`, `failed`).
|
|
|
|
### Deliverables
|
|
- Updated `docs/schema.md` and `docs/requirements.md` traceability alignment.
|
|
- Explicit V1 data invariants section in architecture docs.
|
|
|
|
### Exit Criteria
|
|
- No conflicting definitions of ownership/cardinality/status remain in docs.
|
|
|
|
---
|
|
|
|
## Phase 2 — Service Layer Refactor To New Model
|
|
|
|
**Goal:** Remove all obsolete `Transcript` assumptions from service/workflow code.
|
|
|
|
### Tasks
|
|
1. Refactor `services/transcription.py`:
|
|
- Replace transcript CRUD assumptions with job-output + revision operations.
|
|
2. Refactor `services/jobs.py`:
|
|
- Replace old timestamp/relationship accessors with current model fields.
|
|
3. Refactor `services/documents.py` and `services/store.py`:
|
|
- Ensure upload creates and links `Document`, `Source`, and `Job` correctly.
|
|
4. Refactor `services/workflows.py`:
|
|
- Persist original provider output to `Job`.
|
|
- Persist failure detail to `Job.error_detail`.
|
|
- Use `Revision` only for user-authored edits.
|
|
|
|
### Deliverables
|
|
- Service layer fully aligned with new schema.
|
|
|
|
### Exit Criteria
|
|
- No service module imports or persists `Transcript` model artifacts.
|
|
|
|
---
|
|
|
|
## Phase 3 — UI Contract Alignment
|
|
|
|
**Goal:** Align pages/components to source/job/revision semantics.
|
|
|
|
### Tasks
|
|
1. Update job detail and related UI components:
|
|
- Display original immutable transcription from `Job.text`.
|
|
- Display optional revisions sourced from `Source.revisions`.
|
|
2. Replace legacy terminology in UI copy:
|
|
- “transcript history” -> “revision history” where appropriate.
|
|
3. Align date fields with new schema naming.
|
|
4. Preserve clear user messaging when no revisions exist.
|
|
|
|
### Deliverables
|
|
- Updated jobs page and detail components.
|
|
|
|
### Exit Criteria
|
|
- UI behavior and labels match documentation and domain model.
|
|
|
|
---
|
|
|
|
## Phase 4 — Database Bootstrap, Migration, and Safety
|
|
|
|
**Goal:** Make schema transition safe in dev/test and repeatable for deployment.
|
|
|
|
### Tasks
|
|
1. Update bootstrap compatibility logic in `db/operations.py`:
|
|
- Remove obsolete transcript-table assumptions.
|
|
- Add forward-compatible patches for current tables only.
|
|
2. Define migration/backfill approach for existing local data.
|
|
3. Document rollback and recovery steps.
|
|
4. Rehearse migration path against representative data.
|
|
|
|
### Deliverables
|
|
- Migration/upgrade runbook.
|
|
- Validated bootstrap behavior for dev/test.
|
|
|
|
### Exit Criteria
|
|
- Migration path is documented and tested with no unresolved data-loss risk.
|
|
|
|
---
|
|
|
|
## Phase 5 — Test Suite Realignment
|
|
|
|
**Goal:** Restore full confidence after the schema redesign.
|
|
|
|
### Tasks
|
|
1. Rewrite model tests for:
|
|
- `Document`, `Source`, `Job`, `Revision` relationships and invariants.
|
|
2. Rewrite service/integration tests:
|
|
- Worker success/failure paths using `Job.text` / `Job.error_detail`.
|
|
- Optional revision creation and lineage behavior.
|
|
3. Update UI tests for new job-detail/revision rendering behavior.
|
|
4. Re-enable strict CI quality gates (lint, type, tests).
|
|
|
|
### Deliverables
|
|
- Updated test matrix and passing CI.
|
|
|
|
### Exit Criteria
|
|
- Critical user flows and failure paths are covered and green.
|
|
|
|
---
|
|
|
|
## Phase 6 — Reliability, Operations, and Release Readiness
|
|
|
|
**Goal:** Ensure V1 is operable and launch-safe.
|
|
|
|
### Tasks
|
|
1. Verify error taxonomy behavior across UI/API/service/worker.
|
|
2. Confirm structured logging includes relevant identifiers (`job_id`, `document_id`, `source_id` when applicable).
|
|
3. Validate retry behavior and terminal failure handling.
|
|
4. Finalize release checklist, deployment steps, and rollback procedure.
|
|
5. Execute final acceptance run against requirements traceability.
|
|
|
|
### Deliverables
|
|
- V1 release checklist and acceptance evidence.
|
|
|
|
### Exit Criteria
|
|
- Stakeholder sign-off and launch readiness achieved.
|
|
|
|
---
|
|
|
|
## Requirement Traceability Focus
|
|
|
|
The plan must keep clear evidence against these requirement groups:
|
|
|
|
- **Core flow:** REQ-0 to REQ-6
|
|
- **Runtime and operations constraints:** REQ-7 to REQ-12
|
|
- **Revision workflow:** REQ-13
|
|
|
|
A lightweight traceability table should be maintained with:
|
|
|
|
- requirement ID
|
|
- implementation status (`not started` / `in progress` / `done`)
|
|
- validation evidence (test name, screenshot, or runbook step)
|
|
|
|
---
|
|
|
|
## Suggested Execution Rhythm
|
|
|
|
- **Weekly:** requirement status and risk review
|
|
- **Per PR:** contract checks (model names, field names, lifecycle values)
|
|
- **Milestone checks:** end of Phases 2, 4, and 6
|
|
|
|
---
|
|
|
|
## Scope Discipline Rule (V1 Focus)
|
|
|
|
- Only work required to satisfy V1 requirements enters this plan.
|
|
- Nice-to-have enhancements are captured in a separate backlog document.
|
|
- Schema or contract changes after Phase 1 require explicit approval and traceability impact review. |