generated from john/python-template
131 lines
3.3 KiB
Markdown
131 lines
3.3 KiB
Markdown
# Data Model and Persistence Schema (Version 4)
|
|
|
|
This schema reflects the current V4 persistence contract.
|
|
|
|
## Entity Relationship Overview
|
|
|
|
```mermaid
|
|
erDiagram
|
|
Document ||--o{ Source : has
|
|
Document ||--o{ Job : has
|
|
Document ||--o{ DocumentPerson : links
|
|
Person ||--o{ DocumentPerson : links
|
|
Job ||--o{ JobSource : includes
|
|
Source ||--o{ JobSource : participates
|
|
Source ||--o{ ExecutionAttempt : records
|
|
|
|
Document {
|
|
uuid id PK
|
|
string title
|
|
uuid type_id FK
|
|
string language
|
|
datetime doc_date
|
|
string date_note
|
|
string comments
|
|
string location
|
|
datetime created_at
|
|
datetime updated_at
|
|
}
|
|
|
|
Source {
|
|
uuid id PK
|
|
uuid document_id FK
|
|
string original_name
|
|
string media_type
|
|
string storage_path
|
|
int file_size
|
|
string file_hash
|
|
string raw_transcription
|
|
datetime created_at
|
|
datetime updated_at
|
|
}
|
|
|
|
Job {
|
|
uuid id PK
|
|
uuid document_id FK
|
|
enum status
|
|
string prompt
|
|
json model_settings_json
|
|
datetime created_at
|
|
datetime updated_at
|
|
}
|
|
|
|
JobSource {
|
|
uuid job_id FK
|
|
uuid source_id FK
|
|
enum status
|
|
uuid selected_attempt_id FK
|
|
string error_message
|
|
datetime created_at
|
|
datetime updated_at
|
|
}
|
|
|
|
ExecutionAttempt {
|
|
uuid id PK
|
|
uuid source_id FK
|
|
uuid job_id FK
|
|
enum outcome
|
|
string provider_name
|
|
string provider_model
|
|
string request_manifest_hash
|
|
json request_manifest_json
|
|
json transport_evidence_json
|
|
string transcript_text
|
|
string error_category
|
|
string error_message
|
|
float duration_seconds
|
|
datetime started_at
|
|
datetime completed_at
|
|
datetime created_at
|
|
}
|
|
```
|
|
|
|
## Authoritative Enumerations
|
|
|
|
### JobStatus
|
|
|
|
- `queued`
|
|
- `processing`
|
|
- `transcribed`
|
|
- `completed` (legacy-compatible)
|
|
- `partial_success`
|
|
- `failed`
|
|
|
|
### JobSourceStatus
|
|
|
|
- `pending`
|
|
- `transcribed`
|
|
- `failed`
|
|
- `cancelled`
|
|
|
|
## Aggregate Ownership
|
|
|
|
- `Document` aggregate: `Document`, linked `Source`, linked `DocumentPerson`.
|
|
- `Job` aggregate: `Job`, `JobSource` rows, selected-attempt pointers.
|
|
- Evidence aggregate: append-only `ExecutionAttempt` rows keyed by `source_id` + `job_id`.
|
|
|
|
## Persistence Invariants
|
|
|
|
1. `ExecutionAttempt` rows are immutable after creation, except explicit support fields reserved for compatibility migrations.
|
|
2. `JobSource.status` is queue/projection state; it does not duplicate full attempt payload.
|
|
3. `Source.raw_transcription` is a projection, not the complete evidence record.
|
|
4. `Job` terminal status is derived from `JobSource` outcomes.
|
|
5. Registry semantic keys, when present, are immutable once created.
|
|
|
|
## Media Storage Semantics
|
|
|
|
1. `Source.storage_path` references canonical stored bytes used by processing.
|
|
2. Canonical stored bytes may reflect ingest-time normalization.
|
|
3. File hash and size fields describe canonical stored bytes.
|
|
|
|
## Query and Loading Requirements
|
|
|
|
- Relationship access from service/UI layers must use explicit eager loading patterns compatible with `lazy="raise"`.
|
|
- Candidate-attempt views should select latest/selected attempts explicitly; do not rely on implicit lazy traversal.
|
|
|
|
## Cross-Reference
|
|
|
|
- [System Architecture](architecture_v4.md)
|
|
- [System Requirements](requirements_v4.md)
|
|
- [Error Handling Policy](error_handling_v4.md)
|