generated from john/python-template
86 lines
5.6 KiB
Markdown
86 lines
5.6 KiB
Markdown
# System Requirements (Current Baseline: V5.1)
|
|
|
|
These requirements define the active V5.1 contract and align to current implementation.
|
|
|
|
## 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.
|
|
|
|
## 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`
|
|
|
|
## 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`
|