generated from john/python-template
V6.1 UI refinements, add Maintenance jobs to Settings
Quality Gate / gate (push) Failing after 2m57s
Quality Gate / gate (push) Failing after 2m57s
This commit is contained in:
Jim Lancaster
+17
-18
@@ -27,25 +27,24 @@ Detailed plan: [`v6_0_hosting_migration_plan.md`](v6_0_hosting_migration_plan.md
|
||||
|
||||
## V6.1 - Testing and Refinement
|
||||
|
||||
[*Potential app refinements:*
|
||||
* Create a **single “Maintenance Jobs” UI** backed by your existing async worker pattern, not direct shell execution from the page.
|
||||
1. Add a `maintenance_run` table (`id`, `job_type`, `status`, `started_at`, `finished_at`, `triggered_by`, `summary`, `log_path`, `error_detail`).
|
||||
2. In the UI, add two buttons: **Run Backup** and **Run Storage Reconciliation**; clicking creates a run row and enqueues worker execution.
|
||||
3. Worker executes the existing scripts/commands, captures stdout/stderr to a timestamped log file, updates run status/summary.
|
||||
4. UI shows a run history grid with live status, duration, summary, and “View Log”/“Download Log”.
|
||||
5. Add optional schedule controls (daily/weekly) that create queued runs through the same path so manual and scheduled runs behave identically.
|
||||
Objective: improve navigation and operational workflows after user feedback.
|
||||
|
||||
* Consider a difference Sources for Document page
|
||||
* Presenting the list of Document sources is not very useful.
|
||||
* Consider presenting a thumbnail gallery instead. I think this would make it easier to select the single source file the user is looking for.
|
||||
* This idea may be useful in other areas as well.
|
||||
|
||||
* People detail page -> LINKED DOCUMENTS:
|
||||
* How to handle long list of identically named documents (e.g., "Hig postcard to Zenna")? The table shown is not useful, but there isn't enough real estate in the column to add something like the document date, I don't think.
|
||||
|
||||
* Start reviewing what the UI looks like on a smart phone. How do those cards arrange themselves on a phone?
|
||||
|
||||
]
|
||||
### Scope
|
||||
1. Make Document Detail the primary source-page workspace:
|
||||
- Use Source-style pan/zoom + previous/next page controls.
|
||||
- Move editable revision controls into Document Detail.
|
||||
- Move archival/system metadata to dedicated Document Info route.
|
||||
2. Simplify top navigation:
|
||||
- Remove top-level Tags and Sources entries.
|
||||
- Retire the Tags page and the global Source Asset Records entry flow.
|
||||
3. Improve list/detail clarity:
|
||||
- Add Document transcription status to Archival Documents list.
|
||||
- Add Document Date in People Detail -> Linked Documents table.
|
||||
4. Add worker-backed Settings maintenance runs:
|
||||
- Add `maintenance_run` persistence (`id`, `job_type`, `status`, `started_at`, `finished_at`, `triggered_by`, `summary`, `log_path`, `error_detail`).
|
||||
- Add Run Backup and Run Storage Reconciliation actions that enqueue runs and execute in the worker.
|
||||
- Add run history with status, duration, summary, and log view/download.
|
||||
- Defer daily/weekly scheduling controls to V6.2.
|
||||
|
||||
## V6.2 - Reporting Features
|
||||
|
||||
|
||||
+35
-3
@@ -1,14 +1,15 @@
|
||||
# Data Model and Persistence Schema (Current Baseline: V5.1)
|
||||
# Data Model and Persistence Schema (Current Baseline: V6.1)
|
||||
|
||||
This document is the field-accurate V5.1 schema contract aligned to `src/transcription/db/models.py`.
|
||||
This document is the field-accurate V6.1 schema contract aligned to `src/transcription/db/models.py`.
|
||||
|
||||
## Source of Truth Anchors
|
||||
|
||||
- `src/transcription/db/models.py:60-78` (status and purpose enums)
|
||||
- `src/transcription/db/models.py` (status and purpose enums, including maintenance lifecycle enums)
|
||||
- `src/transcription/db/models.py:80-120` (`DocumentType`, `PersonRole`)
|
||||
- `src/transcription/db/models.py:122-172` (`Tag`, `Document`)
|
||||
- `src/transcription/db/models.py:175-281` (`Person`, `Photo`, `DocumentPerson`, `DocumentTag`)
|
||||
- `src/transcription/db/models.py:285-347` (`Job`)
|
||||
- `src/transcription/db/models.py` (`MaintenanceRun`)
|
||||
- `src/transcription/db/models.py:350-462` (`Source`, `JobSource`)
|
||||
- `src/transcription/db/models.py:465-522` (`ExecutionAttempt`)
|
||||
|
||||
@@ -30,6 +31,9 @@ erDiagram
|
||||
Job ||--o{ JobSource : includes
|
||||
Source ||--o{ JobSource : participates
|
||||
JobSource ||--o{ ExecutionAttempt : attempts
|
||||
MaintenanceRun {
|
||||
uuid id PK
|
||||
}
|
||||
```
|
||||
|
||||
## Authoritative Enumerations
|
||||
@@ -54,6 +58,18 @@ erDiagram
|
||||
- `transcription`
|
||||
- `retranscription`
|
||||
|
||||
### MaintenanceJobType
|
||||
|
||||
- `backup`
|
||||
- `storage_reconciliation`
|
||||
|
||||
### MaintenanceRunStatus
|
||||
|
||||
- `queued`
|
||||
- `processing`
|
||||
- `succeeded`
|
||||
- `failed`
|
||||
|
||||
## Field-Accurate Table Contracts
|
||||
|
||||
### `DocumentType`
|
||||
@@ -201,6 +217,22 @@ Constraint:
|
||||
Index:
|
||||
- `Index("ix_job_status_date_created", "status", "date_created")`
|
||||
|
||||
### `MaintenanceRun`
|
||||
|
||||
| Field | Type | Notes |
|
||||
| :--- | :--- | :--- |
|
||||
| `id` | `UUID` | PK |
|
||||
| `job_type` | `MaintenanceJobType` | non-null enum |
|
||||
| `status` | `MaintenanceRunStatus` | non-null enum, default `queued` |
|
||||
| `started_at` | `datetime \| None` | optional |
|
||||
| `finished_at` | `datetime \| None` | optional |
|
||||
| `triggered_by` | `str \| None` | optional |
|
||||
| `summary` | `str \| None` | optional |
|
||||
| `log_path` | `str \| None` | optional, log-root-relative POSIX path |
|
||||
| `error_detail` | `str \| None` | optional internal failure detail |
|
||||
| `created_at` | `datetime` | default now |
|
||||
| `updated_at` | `datetime` | default now, onupdate |
|
||||
|
||||
### `Source`
|
||||
|
||||
| Field | Type | Notes |
|
||||
|
||||
@@ -11,10 +11,11 @@ Documents manages the archival record for each historical artifact independently
|
||||
| `/documents` | Searchable archival Document list. |
|
||||
| `/documents/new` | Create a Document. |
|
||||
| `/documents/{document_id}` | View one Document and its related records. |
|
||||
| `/documents/{document_id}/info` | View archival metadata and system logistics for one Document. |
|
||||
| `/documents/{document_id}/edit` | Edit metadata and the complete Linked People set. |
|
||||
| `/documents/{document_id}/delete` | Confirm or block deletion. |
|
||||
| `/documents/{document_id}/jobs` | Show Jobs belonging to the Document. |
|
||||
| `/documents/{document_id}/sources` | Redirect to the Document-filtered Sources list. |
|
||||
| `/documents/{document_id}/sources` | Redirect back to Document Detail. |
|
||||
| `/documents/{document_id}/print` | Preview and browser-print the persisted Document. |
|
||||
|
||||
## List Behavior
|
||||
@@ -22,10 +23,11 @@ Documents manages the archival record for each historical artifact independently
|
||||
- The title is **Archival Documents**.
|
||||
- **Create new document** opens the create route.
|
||||
- The table defaults to Document Title order and supports search and column sorting.
|
||||
- Columns are Document Title, Author, Tags, Document Date, Type, and # Sources.
|
||||
- Columns are Document Title, Author, Tags, Document Date, Type, # Sources, and Transcription Status.
|
||||
- Document Title is left-aligned; the remaining columns are centered.
|
||||
- Author lists all linked people in the `author` role.
|
||||
- # Sources reflects the count of linked Source rows for each Document.
|
||||
- Transcription Status reflects the most recent Job status for that Document; documents with no Jobs show a blank marker.
|
||||
- Date display prefers exact date, then approximate date, then `Unknown`.
|
||||
- Selecting a row opens Document Detail.
|
||||
- Row navigation includes list context so Document Detail provides **Back to Documents**.
|
||||
@@ -70,14 +72,19 @@ Rules:
|
||||
|
||||
- The heading shows name, type, and internal ID.
|
||||
- The header includes a contextual back action: **Back to Documents** by default, **Back to Person** when opened from Person Detail, and **Back to Job** when opened from Job Detail.
|
||||
- The first Source, when present, appears in the dark-room viewer.
|
||||
- Archival Metadata shows authors, Document Type, tags, Document date (`MM-DD-YYYY` for exact dates), location (linked to Google Maps when present), and archive identifier. Notes appear in a separate archival-notes block within the same card.
|
||||
- System Logistics shows created and updated timestamps.
|
||||
- The detail workspace shows a Source-style pan/zoom media viewer with **Previous Page** / **Next Page** navigation for document source pages.
|
||||
- The center column is **Editable Revision** for the active source page.
|
||||
- Related People are grouped by role and link to Person Detail.
|
||||
- **Sources & Pipeline Jobs** shows counts and actions for filtered Sources, Document Jobs, and adding a Job.
|
||||
- **Edit Document**, **Print**, and **Delete** are available from the header.
|
||||
- **Source Pages & Transcriptions** shows source/job counts and actions for source detail, document jobs, and adding a Job.
|
||||
- **Edit Document**, **Print**, **Document Details**, and **Delete** are available from the header.
|
||||
- Invalid IDs and missing Documents produce explicit states without rendering a partial page.
|
||||
|
||||
## Document Info Behavior
|
||||
|
||||
- `/documents/{document_id}/info` contains **Archival Metadata** and **System Logistics**.
|
||||
- It includes a **Back to Document** action.
|
||||
- Archival metadata includes authors, document type, tags, document date, location (linked when present), archive identifier, and notes.
|
||||
|
||||
## Print Behavior
|
||||
|
||||
- Print opens a dedicated preview for persisted Document data.
|
||||
|
||||
@@ -64,7 +64,7 @@ Rules:
|
||||
- Birth and death place values are clickable links to Google Maps when present.
|
||||
- FamilySearch ID is shown as a metadata value and is clickable to the FamilySearch person details route when present.
|
||||
- Biography has an explicit empty value.
|
||||
- Linked Documents render as a table with **Document Name**, **Role**, and **Number of Pages**; selecting a row opens Document Detail.
|
||||
- Linked Documents render as a table with **Document Name**, **Document Date**, **Role**, and **Number of Pages**; selecting a row opens Document Detail.
|
||||
- No links shows both an empty state and guidance to link from a Document workflow.
|
||||
- System Logistics shows created and updated timestamps.
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@ Settings manages installation-local registries, safe runtime .env settings, and
|
||||
|
||||
| Route | Purpose |
|
||||
| --- | --- |
|
||||
| `/settings` | Manage Runtime Settings, Document Types, Person Roles, Tags, Prompts, and Home Page Text. |
|
||||
| `/settings` | Manage Runtime Settings, Document Types, Person Roles, Tags, Prompts, Home Page Text, and Maintenance runs. |
|
||||
|
||||
## Behavior
|
||||
|
||||
@@ -19,6 +19,7 @@ Settings manages installation-local registries, safe runtime .env settings, and
|
||||
- **Tags**
|
||||
- **Prompts**
|
||||
- **Home Page Text**
|
||||
- **Maintenance**
|
||||
- **Runtime Settings**
|
||||
- Runtime Settings exposes an allowlisted set of non-secret fields synchronized with `Settings` model fields except excluded secret/unsafe fields.
|
||||
- Runtime Settings is rendered as a compact two-column editor (**Setting**, **Value**) in a centered, narrower responsive container.
|
||||
@@ -31,10 +32,13 @@ Settings manages installation-local registries, safe runtime .env settings, and
|
||||
- Document Types, Person Roles, and Tags support Add/Edit/Delete with existing guardrails.
|
||||
- Prompts exposes only `transcribe_document.md` for editing and restore-from-backup.
|
||||
- Home Page Text edits the same Markdown content rendered on `/homepage`.
|
||||
- Maintenance provides queue-backed **Run Backup** and **Run Storage Reconciliation** actions.
|
||||
- Maintenance run history shows job type, status, started/finished timestamps, duration, summary, and log view/download actions.
|
||||
- Maintenance actions enqueue work and signal the worker; the page itself does not execute shell commands directly.
|
||||
|
||||
## Acceptance Checklist
|
||||
|
||||
- `/ui/settings` renders all six tabs.
|
||||
- `/ui/settings` renders all seven tabs.
|
||||
- Registry and prompt workflows keep existing validation and error handling.
|
||||
- Runtime Settings excludes secret fields and rejects invalid values.
|
||||
- Saving Home Page Text persists content for the homepage view.
|
||||
|
||||
@@ -8,7 +8,7 @@ Sources manages individual archived page/file records. It provides source-media
|
||||
|
||||
| Route | Purpose |
|
||||
| --- | --- |
|
||||
| `/sources` | Global or filtered Source list. |
|
||||
| `/sources` | Document-filtered or Job-filtered Source list; global route redirects to Documents. |
|
||||
| `/sources/{source_id}` | View media, transcription, revision, metadata, and evidence. |
|
||||
| `/sources/{source_id}/delete` | Confirm or block deletion. |
|
||||
|
||||
@@ -16,8 +16,8 @@ The list accepts optional `document_id` and `job_id` query parameters. Document
|
||||
|
||||
## List Behavior
|
||||
|
||||
- The title is **Source Asset Records**, **Sources for Document**, or **Sources for Job** according to context.
|
||||
- Global context provides **Create Job**.
|
||||
- The global `/sources` route redirects to `/documents`.
|
||||
- Filtered list titles are **Sources for Document** and **Sources for Job**.
|
||||
- Filtered context provides **Back to Document** or **Back to Job**.
|
||||
- Rows are ordered by page number and then upload name.
|
||||
- Columns are Upload Title, Page Number, Document Name, Status, and Error Detail.
|
||||
@@ -30,7 +30,7 @@ The list accepts optional `document_id` and `job_id` query parameters. Document
|
||||
## Detail Behavior
|
||||
|
||||
- The heading shows page number, upload name, and Source ID.
|
||||
- **Back to Sources** returns to the global list.
|
||||
- **Back to Document** returns to Document Detail for the active source page.
|
||||
- **Retranscribe Source** opens Create Processing Job with this Source and its Document locked.
|
||||
- **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.
|
||||
|
||||
@@ -1,31 +0,0 @@
|
||||
# Tags Page Contract
|
||||
|
||||
## Purpose
|
||||
|
||||
Tags provides a dedicated browse/filter entry point for document tagging workflows.
|
||||
|
||||
## Route
|
||||
|
||||
| Route | Purpose |
|
||||
| --- | --- |
|
||||
| `/tags` | Browse Documents grouped by Tag and filter to one Tag. |
|
||||
|
||||
## Behavior
|
||||
|
||||
- The page title is **Tags**.
|
||||
- When no tags exist, the page shows `No tags are configured yet.`
|
||||
- A Tag filter select allows narrowing to one tag.
|
||||
- Each rendered group header includes the tag label and document count.
|
||||
- Document names are clickable and open Document Detail.
|
||||
|
||||
## Acceptance Checklist
|
||||
|
||||
- `/ui/tags` renders successfully from the main navigation.
|
||||
- Group counts match the number of linked Documents per Tag.
|
||||
- Filtering hides non-matching tag groups.
|
||||
|
||||
## Implementation Anchors
|
||||
|
||||
- `src/transcription/ui/pages/tags_page.py`
|
||||
- `src/transcription/services/documents.py`
|
||||
- `tests/ui/test_tags_page.py`
|
||||
Reference in New Issue
Block a user