generated from john/python-template
52 lines
4.2 KiB
Markdown
52 lines
4.2 KiB
Markdown
# Document Transcription System Requirements (Version 4)
|
|
|
|
This document defines the baseline requirements for the document transcription system.
|
|
|
|
## Requirements Model
|
|
|
|
| ID | Category | Requirement | Verify Method |
|
|
| --- | --- | --- | --- |
|
|
| REQ-0 | System | Provide end-to-end multi-page document transcription with persistent, inspectable async job states. | demonstration |
|
|
| REQ-1 | Functional | Allow users to upload one or more images as ordered `Source` pages under a `Document`. | test |
|
|
| REQ-2 | Functional | Process page transcription asynchronously using an `asyncio` worker pool bounded by rate limits. | test |
|
|
| REQ-3 | Functional | Persist submission-time prompt configuration and full page-level provider response evidence for every job execution. | test |
|
|
| REQ-4 | Functional | Support job states `queued`, `processing`, `completed`, `partial_success`, and `failed`, plus page states `pending`, `transcribed`, and `failed`. | inspection |
|
|
| REQ-5 | Functional | Allow users to manage historical `Person` records and link multiple people per role to a `Document`. | test |
|
|
| REQ-6 | Functional | Support an extensible role taxonomy for document-person relationships. | inspection |
|
|
| REQ-7 | Policy Constraint | Enforce deterministic relationship-role writes with uniqueness on `(document_id, person_id, role_id)` and explicit conflict responses for invalid duplicate link attempts. | test |
|
|
| REQ-8 | Functional | Use set-based synchronization for document-person mutations so updates add and remove only the intended links. | test |
|
|
| REQ-9 | Functional | Maintain immutable machine output on `Source.raw_transcription` while permitting inline human edits on `Source.revised_text`. | test |
|
|
| REQ-10 | Functional | Support a registry-driven `DocumentType` taxonomy with stable codes, mutable labels, and active/inactive lifecycle control. | test |
|
|
| REQ-11 | Data Constraint | Store `Document` type as a controlled reference to `DocumentType`. | test |
|
|
| REQ-12 | Interface | Render multi-page transcriptions sequentially by `page_number` with document, people, and document-type metadata. | demonstration |
|
|
| REQ-13 | Interface | Document create/edit UI must support selecting multiple people per role and selecting an active document type from the registry. | demonstration |
|
|
| REQ-14 | API Constraint | Expose additive, role-aware retrieval and write behavior for document-person links and code-based selection for document types. | test |
|
|
| REQ-15 | Data Constraint | Calculate and store cryptographic file hashes (SHA-256) and file sizes for uploaded source images. | test |
|
|
| REQ-16 | Data Constraint | Preserve a portable relational model across supported backends using SQLModel, SQLAlchemy, SQLite, and PostgreSQL. | inspection |
|
|
| REQ-17 | Reliability | Ensure delete and update flows for documents, people, and relationship links remain deterministic and safe. | test |
|
|
| REQ-18 | Operations Constraint | Keep canonical development, testing, restore, and recovery workflows OS-independent. | inspection |
|
|
| REQ-19 | Quality | Provide automated coverage for async transcription workflows, relationship-role enforcement, document-type selection, and regression behavior. | test |
|
|
|
|
## Clarifying Constraints
|
|
|
|
1. `DocumentType.code` and `PersonRole.code` are stable machine identifiers.
|
|
2. `DocumentType.label` and `PersonRole.label` may evolve without changing canonical identity.
|
|
3. Relationship-write policy and conflict handling must be consistent across UI, API, services, and persistence.
|
|
4. Many-per-role behavior is required for document-person links.
|
|
5. Relationship conflicts must fail deterministically without partial mutation.
|
|
|
|
## Element Satisfaction Mapping
|
|
|
|
- UI (NiceGUI): Satisfies REQ-0, REQ-1, REQ-5, REQ-9, REQ-12, REQ-13.
|
|
- API (FastAPI): Satisfies REQ-1, REQ-4, REQ-5, REQ-7, REQ-8, REQ-14.
|
|
- Worker (`asyncio`): Satisfies REQ-2, REQ-3, REQ-4.
|
|
- Persistence (SQLModel / SQLAlchemy): Satisfies REQ-3, REQ-9, REQ-10, REQ-11, REQ-15, REQ-16, REQ-17.
|
|
- Test Suite: Verifies all test-marked requirements and satisfies REQ-19.
|
|
|
|
## Related Local References
|
|
|
|
- [System Overview](index_v4.md)
|
|
- [System Architecture](architecture_v4.md)
|
|
- [Data Model](schema_v4.md)
|
|
- [Error Handling Policy](error_handling_v4.md)
|