generated from john/python-template
90 lines
4.6 KiB
Markdown
90 lines
4.6 KiB
Markdown
# Sources Page Contract
|
|
|
|
## Purpose
|
|
|
|
Sources manages individual archived page/file records. It provides source-media viewing, current processing context, provider evidence inspection, previous/next page navigation, and human revision without allowing machine output to be edited.
|
|
|
|
## Routes
|
|
|
|
| Route | Purpose |
|
|
| --- | --- |
|
|
| `/sources` | Global or filtered Source list. |
|
|
| `/sources/{source_id}` | View media, transcription, revision, metadata, and evidence. |
|
|
| `/sources/{source_id}/delete` | Confirm or block deletion. |
|
|
|
|
The list accepts optional `document_id` and `job_id` query parameters. Document context takes precedence if both parse successfully.
|
|
|
|
## List Behavior
|
|
|
|
- The title is **Source Asset Records**, **Sources for Document**, or **Sources for Job** according to context.
|
|
- Global context provides **Create Job**.
|
|
- Filtered context provides **Back to Document** or **Back to Job**.
|
|
- Rows are ordered by page number and then upload name.
|
|
- Columns are Document Name, Page Number, Upload Title, Status, and Error Detail.
|
|
- Document Name, Upload Title, and Error Detail are left-aligned; Status is centered.
|
|
- Stored Filename is intentionally absent from the list.
|
|
- Selecting a row opens Source Detail.
|
|
- No records displays `No source asset records found in repository.`
|
|
|
|
## Detail Behavior
|
|
|
|
- The heading shows page number, upload name, and Source ID.
|
|
- **Back to Sources** returns to the global list.
|
|
- **Delete Source** opens the guarded delete route.
|
|
- Previous and Next navigate only among Sources belonging to the same Document in page order; unavailable boundary actions are disabled.
|
|
- The media viewer resolves the stored Source path through the configured upload root.
|
|
- Transcription Text is read-only and prefers the latest JobSource transcription, then the Source projection.
|
|
- Editable Revision is seeded from an existing revision or the machine transcription.
|
|
- Source Metadata shows upload name, stored filename, page number, Document Name, Document ID, and stored path. Source ID appears in the page-header subtitle.
|
|
- SourceJob Metadata shows latest status, Job ID, execution time, provider, model, prompt, and failure detail.
|
|
- Revision Logistics shows revised state, last-revised time, and upload time.
|
|
|
|
## Provider Evidence
|
|
|
|
- Provider Evidence is associated with the latest JobSource execution.
|
|
- New attempts display separate expandable Request Manifest, Transport Response, OpenRouter SDK Response Snapshot,
|
|
Normalized Metadata, Software Context, and Derived Artifacts sections.
|
|
- Historical `raw_api_response` values are labeled as OpenRouter SDK response snapshots.
|
|
- Missing evidence has an explicit empty state.
|
|
- Historical executions explicitly state that exact transport evidence was not captured.
|
|
- **Export Evidence** downloads a versioned package containing source identity, attempts, artifacts, relationships,
|
|
schema versions, and integrity digests without source binaries, credentials, or machine-local source paths.
|
|
|
|
## Revision Behavior
|
|
|
|
- Machine transcription is never edited directly.
|
|
- A revision must contain non-whitespace text.
|
|
- Save persists revised text and updates the saved timestamp without leaving the page.
|
|
- Reset restores the in-memory revision from page load or the most recent successful save. When no revision exists, it restores the machine transcription; it does not re-read the database.
|
|
- A failed latest execution displays guidance that a human revision can preserve corrected text.
|
|
|
|
## Delete Behavior
|
|
|
|
- Deletion is allowed only when the Source has no JobSource links.
|
|
- A linked Source shows cleanup guidance and navigation to Jobs.
|
|
- An unlinked Source requires explicit permanent deletion.
|
|
- Success returns to the Sources list.
|
|
|
|
## Acceptance Checklist
|
|
|
|
- Global, Document-filtered, and Job-filtered lists show the correct context and return action.
|
|
- List columns and alignments match this contract and omit Stored Filename.
|
|
- Previous/next navigation never crosses Document boundaries.
|
|
- Detail keeps machine output read-only and human revision separately editable.
|
|
- Empty, failed, and missing-evidence states remain explicit.
|
|
- JSON evidence is readable without being mislabeled as native transport evidence.
|
|
- Delete cannot remove a Source with processing-history links.
|
|
|
|
## Implementation Anchors
|
|
|
|
- `src/transcription/ui/pages/sources_page.py`
|
|
- `src/transcription/ui/components/table/sources.py`
|
|
- `src/transcription/services/sources.py`
|
|
- `tests/ui/test_sources_page.py`
|
|
- `tests/services/test_transcription_service.py`
|
|
- `tests/services/test_v2_crud.py`
|
|
|
|
## Planned Changes
|
|
|
|
- Source page reordering is deferred to the [draft V4.3 scope](../../ver4.3/scope_boundary_v4_3.md).
|