generated from john/python-template
65 lines
2.9 KiB
Markdown
65 lines
2.9 KiB
Markdown
# Home Page Contract
|
|
|
|
## Purpose
|
|
|
|
Home provides a user-maintained landing page for the local archive. It combines a database-backed image gallery with Markdown text and lets the operator edit both without changing application source or prompt assets.
|
|
|
|
## Routes
|
|
|
|
| Route | Browser path | Purpose |
|
|
| --- | --- | --- |
|
|
| `/homepage` | `/ui/homepage` | View homepage gallery and Markdown. |
|
|
| `/homepage/edit` | `/ui/homepage/edit` | Upload images, manage image metadata, and edit Markdown. |
|
|
|
|
The application root and `/ui` redirect to `/ui/homepage`.
|
|
|
|
## View Behavior
|
|
|
|
- The visible page heading is **Home**; the browser tab title is **VibeScribe Home**.
|
|
- The featured homepage image (`photo.is_primary`) is shown first; remaining images are shown in random order.
|
|
- The current image appears in the shared dark-room viewer with its description.
|
|
- Saved Markdown is rendered in the **Home Text** card.
|
|
- Missing text displays `No homepage text saved yet.`
|
|
- Missing image displays the viewer's empty state.
|
|
- **Edit Home Page** opens the edit route.
|
|
- The same Home Text content is also editable from **Settings → Home Page Text**.
|
|
|
|
## Edit Behavior
|
|
|
|
- The image upload accepts JPEG, PNG, GIF, WebP, BMP, and TIFF files and supports multi-file uploads.
|
|
- A successful upload immediately stores files in the shared `photo` table/media layout and displays a positive notification.
|
|
- The editor supports per-image description edits, setting a featured image, and deleting the current image.
|
|
- The Markdown textarea is initialized from the currently stored homepage text.
|
|
- **Save** writes the textarea content, displays `Homepage saved`, and returns to Home.
|
|
- **Cancel** returns to Home without saving textarea changes. An image already uploaded during the edit session remains stored.
|
|
|
|
## Storage Contract
|
|
|
|
- Homepage markdown text is mutable application data at `UPLOAD_DIR/homepage.md`.
|
|
- Homepage images are stored as `photo` rows (`person_id = NULL`) with files under `UPLOAD_DIR/photos/`.
|
|
- Uploaded images are renamed to `{photo_id}{suffix}`.
|
|
- Homepage images are database records; markdown remains file-backed.
|
|
|
|
## Acceptance Checklist
|
|
|
|
- `/`, `/ui`, and the application brand reach Home.
|
|
- Home renders with or without stored Markdown and image content.
|
|
- Edit loads existing Markdown.
|
|
- Supported image upload stores one or more images and makes the first image featured when no featured image exists yet.
|
|
- Save persists Markdown and returns to Home.
|
|
- Cancel does not save changed Markdown.
|
|
|
|
## Implementation Anchors
|
|
|
|
- `src/transcription/ui/pages/home_page.py`
|
|
- `src/transcription/ui/homepage_store.py`
|
|
- `src/transcription/ui/components/app_shell.py`
|
|
- `tests/ui/test_upload_page.py`
|
|
- `tests/ui/test_navigation_and_mounts.py`
|
|
- `tests/ui/test_pages_registration.py`
|
|
|
|
## Known Limitations
|
|
|
|
- Homepage markdown storage location is `UPLOAD_DIR/homepage.md` and must remain writable in the active runtime environment.
|
|
- Uploading an image is immediate and is not rolled back by Cancel.
|