generated from john/python-template
119 lines
8.6 KiB
Markdown
119 lines
8.6 KiB
Markdown
# System Requirements (Current Baseline: V6.1)
|
|
|
|
These requirements define the active V6.1 contract and align to current implementation.
|
|
|
|
Requirement IDs encode the baseline that introduced them (`REQ-4-*` from V4, `REQ-6-*` from V6) and
|
|
are stable. Never renumber an existing ID; retire it explicitly instead.
|
|
|
|
## Functional Requirements
|
|
|
|
### Domain and Record Management
|
|
|
|
- **REQ-4-001 Document Registry:** The system must create and update `Document` records with title, type, date metadata, optional location, optional archive identifier, and optional notes.
|
|
- **REQ-4-002 Source Registry:** The system must create and update `Source` records linked to exactly one `Document`.
|
|
- **REQ-4-003 People Registry:** The system must create and update `Person` records, support many-to-many links to `Document` with role, and support many-to-many Person tagging via the shared Tag registry.
|
|
- **REQ-4-004 Registry Semantics:** Document types and person roles must support optional immutable semantic keys and hard-delete only when unreferenced.
|
|
|
|
### Job and Workflow Behavior
|
|
|
|
- **REQ-4-010 Job Creation:** The system must create `Job` records from uploaded sources and from retranscription of existing sources.
|
|
- **REQ-4-011 Prompt Snapshotting:** Job creation must persist effective prompt and runtime settings as immutable per-job snapshots.
|
|
- **REQ-4-012 Queue Membership:** Each `(job, source)` pair must be represented by one `JobSource` row.
|
|
- **REQ-4-013 Job Status Lifecycle:** `Job.status` must use one of `queued`, `processing`, `transcribed`, `partial_success`, `failed`.
|
|
- **REQ-4-014 JobSource Status Lifecycle:** `JobSource.status` must use one of `pending`, `transcribed`, `failed`, `cancelled`.
|
|
- **REQ-4-015 Terminal Job Resolution:** Job terminal status must derive from page outcomes as `transcribed`, `partial_success`, or `failed`.
|
|
- **REQ-4-016 Cancellation Semantics:** Job cancellation must set remaining `pending` page entries to `cancelled`.
|
|
|
|
### Transcription and Evidence
|
|
|
|
- **REQ-4-020 Attempt Evidence:** Each provider call must emit one append-only `ExecutionAttempt` record.
|
|
- **REQ-4-021 Attempt Payload:** `ExecutionAttempt` must retain request manifest/hash, outcome, timing, model/provider fields, and error details when present.
|
|
- **REQ-4-022 Transport Evidence:** Provider response evidence must be attached to the attempt when a response is available.
|
|
- **REQ-4-023 Source Projection Rule:** `Source.raw_transcription` is a projection chosen from attempt outcomes and can be repointed by explicit promotion.
|
|
- **REQ-4-024 Candidate Visibility:** UI must expose candidate attempts with metadata needed for comparative review and selection.
|
|
|
|
### Media and Access
|
|
|
|
- **REQ-4-030 Ingest Canonicalization:** Stored source bytes may be normalized at ingest (for example orientation correction); stored bytes are the canonical processing source.
|
|
- **REQ-4-031 Path Safety:** Client-facing media URLs must be generated from controlled application paths only.
|
|
- **REQ-4-032 Print Media Validation:** Print/export source media must be served through record-validated API routes.
|
|
|
|
### Error and UX Contracts
|
|
|
|
- **REQ-4-040 Error Envelope:** Service/API errors must map to structured, user-safe error categories and messages.
|
|
- **REQ-4-041 Partial Failure Visibility:** Mixed page outcomes must be visible at job and page level.
|
|
- **REQ-4-042 Retry Support:** Failed and cancelled pages must support targeted retranscription without requiring full document recreation.
|
|
|
|
### Person Imagery
|
|
|
|
- **REQ-6-001 Photo Records:** The system must store reusable `Photo` records that are either owned by a `Person` or unowned for homepage gallery use.
|
|
- **REQ-6-002 Primary Photo:** At most one photo per owning `Person` may be marked `is_primary`; setting a new primary must clear the previous one.
|
|
- **REQ-6-003 Primary Reassignment:** Deleting an owner's primary photo must promote a remaining photo of that owner rather than leaving the owner without a primary.
|
|
|
|
### Operational Maintenance
|
|
|
|
- **REQ-6-010 Queued Maintenance Runs:** Settings-initiated maintenance must persist a `MaintenanceRun` and execute in the worker, not inline in the request that started it.
|
|
- **REQ-6-011 Maintenance Run Types:** `MaintenanceRun.job_type` must use one of `backup`, `storage_reconciliation`, `gedcom_import`.
|
|
- **REQ-6-012 Maintenance Status Lifecycle:** `MaintenanceRun.status` must use one of `queued`, `processing`, `succeeded`, `failed`.
|
|
- **REQ-6-013 Single Claim:** A queued run must be claimed by at most one worker, using a conditional status update rather than read-then-write.
|
|
- **REQ-6-014 Run History:** Completed runs must retain status, timing, summary, log reference, and error detail, and expose the log for viewing and download.
|
|
- **REQ-6-015 GEDCOM Upload Import:** Settings must support manual `.ged` upload and queue-backed import into genealogy tables.
|
|
- **REQ-6-016 GEDCOM Idempotent Upsert:** GEDCOM import must upsert `GenealogyPerson` and `GenealogyFamily` by FamilySearch IDs and avoid duplicate imported citations on re-run.
|
|
|
|
### Deployment and Runtime Configuration
|
|
|
|
- **REQ-6-020 Production Persistence:** Production must run against PostgreSQL; SQLite remains supported for local development and tests.
|
|
- **REQ-6-021 Split Worker Deployment:** Production must support running the worker as its own process with the app started at `RUN_EMBEDDED_WORKER=false`.
|
|
- **REQ-6-022 Runtime Settings Persistence:** Runtime settings edits must persist to the mounted production environment file and survive container restart.
|
|
- **REQ-6-023 Configuration Contract Sync:** `.env.production.example` must stay synchronized with `Settings` keys and production-safe defaults.
|
|
- **REQ-6-024 Health Reporting:** The deployed stack must report app and worker health through `/healthz`.
|
|
- **REQ-6-025 Backup and Restore:** Database and media/config backups must be produced on a host-visible path with a tested restore procedure.
|
|
|
|
## Non-Functional Requirements
|
|
|
|
- **REQ-4-100 Boundary Integrity:** UI pages/components must not access persistence directly and must call service APIs.
|
|
- **REQ-4-101 Service Ownership:** Aggregate writes must occur in owning service/workflow modules, not in UI handlers.
|
|
- **REQ-4-102 Deterministic Loading:** ORM relationship reads in service/UI code must use explicit eager loading compatible with `lazy="raise"`.
|
|
- **REQ-4-103 Async Safety:** Long-running provider calls must not block UI event handlers directly.
|
|
- **REQ-4-104 Evidence Durability:** Attempt evidence must survive process restart once the transaction commits.
|
|
- **REQ-4-105 Test Guardrails:** Architecture boundary tests must remain in place for services and UI boundaries.
|
|
|
|
## Requirement Interpretation Notes
|
|
|
|
### Status and lifecycle semantics
|
|
|
|
- `REQ-4-013` and `REQ-4-015` intentionally bind success to `transcribed`, not a generic `completed`, so docs, tests, and runtime transitions stay consistent.
|
|
- `REQ-4-016` and `REQ-4-042` distinguish cancellation from failure at page level (`cancelled` vs `failed`) while still allowing targeted retranscription.
|
|
|
|
### Evidence semantics
|
|
|
|
- `REQ-4-020` through `REQ-4-024` separate authoritative history (`ExecutionAttempt`) from operational projection (`Source.raw_transcription`).
|
|
- This supports immutable provenance while allowing explicit candidate promotion for operator workflows.
|
|
|
|
### Boundary and loading semantics
|
|
|
|
- `REQ-4-100` and `REQ-4-101` codify aggregate/service ownership and keep UI out of persistence concerns.
|
|
- `REQ-4-102` exists to enforce deterministic query shape under `lazy="raise"` and avoid hidden data access in rendering callbacks.
|
|
|
|
## Verification Anchors
|
|
|
|
- Service boundary enforcement: `tests/test_service_boundaries.py`
|
|
- UI boundary enforcement: `tests/test_ui_boundaries.py`
|
|
- Job lifecycle reliability and terminal status behavior: `tests/services/test_workflows_reliability.py`
|
|
- Evidence append-only and projection behavior: `tests/services/test_store.py`, `tests/services/test_transcription_service.py`
|
|
- Person photo ownership and primary selection: `tests/services/test_photo_service.py`
|
|
- Maintenance run lifecycle and worker execution: `tests/services/test_maintenance_service.py`
|
|
- Runtime settings persistence: `tests/ui/test_runtime_settings_store.py`, `tests/services/test_settings_services.py`
|
|
- Configuration contract synchronization: `tests/test_meta_contract_guards.py`
|
|
- Deployment health reporting: `tests/api/test_health.py`
|
|
|
|
## Traceability Notes
|
|
|
|
- Source of truth for status enums:
|
|
- `src/transcription/db/models.py`
|
|
- Source of truth for workflow transitions:
|
|
- `src/transcription/services/workflows.py`
|
|
- `src/transcription/services/jobs.py`
|
|
- Source of truth for attempt evidence writes:
|
|
- `src/transcription/services/sources.py`
|