agatha
61d923d5be
Short IDs become the canonical identifier in URLs (/i/:short_id), MinIO/R2 storage keys, and all API responses. Hash-based deduplication is preserved. Includes two-phase Alembic migration (003 adds nullable column, 004 enforces NOT NULL) with a backfill script to copy storage objects and populate short_id for existing images. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
105 lines
8.9 KiB
Markdown
105 lines
8.9 KiB
Markdown
# Feature Specification: Short Image IDs
|
||
|
||
**Feature Branch**: `017-short-id-migration`
|
||
**Created**: 2026-05-09
|
||
**Status**: Draft
|
||
**Input**: User description: "Replace UUID-based image identifiers with 8-character base62 short IDs. Short IDs become the canonical identifier in URLs (/i/:short_id replacing /images/:uuid), MinIO storage keys, and all API responses. Existing hash-based deduplication is preserved. Migration includes backfilling short IDs for existing images, renaming storage objects, and regenerating file URLs. Frontend routes update to use short IDs throughout."
|
||
|
||
## User Scenarios & Testing *(mandatory)*
|
||
|
||
### User Story 1 — Clean, Shareable Image Links (Priority: P1)
|
||
|
||
A user wants to share an image with someone. They copy the page URL or use the "Copy URL" button and get a short, clean link they can paste anywhere. The link is brief enough to share in a message without looking like machine-generated noise.
|
||
|
||
**Why this priority**: This is the primary user-facing value of the change. Every image in the library benefits immediately. Short links are more trustworthy, easier to share, and less likely to break in messaging apps that truncate long URLs.
|
||
|
||
**Independent Test**: Open any image detail page. Confirm the URL in the browser address bar is short (e.g. `/i/AbCdEfGh`). Copy the URL and paste it into a new tab — confirm the correct image loads. Share the link with someone who is not logged in and confirm they can view the image.
|
||
|
||
**Acceptance Scenarios**:
|
||
|
||
1. **Given** a user is on the image detail page, **When** they look at the browser address bar, **Then** the URL contains a short 8-character identifier rather than a long UUID.
|
||
2. **Given** a short image URL, **When** an unauthenticated user opens it, **Then** the image loads correctly without requiring login.
|
||
3. **Given** a short image URL, **When** it is pasted into a messaging app or email, **Then** it is compact enough to read at a glance and does not get truncated.
|
||
|
||
---
|
||
|
||
### User Story 2 — New Uploads Assigned Short IDs (Priority: P2)
|
||
|
||
When a new image is uploaded, the system assigns it a short ID immediately. The image is accessible via its short URL straight away. If the same file has already been uploaded before, the existing record is returned rather than creating a duplicate — the deduplication behaviour is unchanged.
|
||
|
||
**Why this priority**: This ensures the new convention is in place going forward. Without this, the migration work in US3 would need to be re-run for any new uploads.
|
||
|
||
**Independent Test**: Upload a new image. Confirm the detail page URL contains an 8-character short ID. Upload the exact same file again — confirm no new record is created and the existing short URL is returned.
|
||
|
||
**Acceptance Scenarios**:
|
||
|
||
1. **Given** a user uploads an image, **When** the upload completes, **Then** the image is accessible at a short URL (`/i/{short_id}`).
|
||
2. **Given** a user uploads a file that is identical to a previously uploaded image, **When** the upload completes, **Then** the system returns the existing image's short URL rather than creating a duplicate entry.
|
||
3. **Given** a newly uploaded image, **When** the "Copy URL" button is used, **Then** the copied link is the short image page URL.
|
||
|
||
---
|
||
|
||
### User Story 3 — All Existing Images Migrated to Short IDs (Priority: P3)
|
||
|
||
All images that existed before this change are assigned short IDs and remain fully accessible. Their stored files are renamed to match the new convention. After migration, all image links throughout the application use short IDs — no UUID-based links remain active.
|
||
|
||
**Why this priority**: Without migration, legacy images would either be inaccessible or require maintaining two parallel URL schemes. Clean cutover is preferable. This is lower priority than P1/P2 because it is an administrative operation rather than a user-facing feature, but it must complete before the feature can be considered fully shipped.
|
||
|
||
**Independent Test**: After running the migration, browse the library and open several images — confirm all detail pages use short URLs. Confirm no broken images or missing thumbnails.
|
||
|
||
**Acceptance Scenarios**:
|
||
|
||
1. **Given** images that existed before the migration, **When** the migration completes, **Then** all are accessible via short URLs.
|
||
2. **Given** the migration has run, **When** a user browses the library and opens any image, **Then** the detail page URL is a short ID URL.
|
||
3. **Given** the migration has run, **When** any image or thumbnail is displayed, **Then** it loads correctly with no broken images.
|
||
4. **Given** the migration is running, **When** it encounters an error on one image, **Then** it reports the failure clearly and continues processing remaining images rather than aborting entirely.
|
||
|
||
---
|
||
|
||
### Edge Cases
|
||
|
||
- What happens if a short ID collision occurs during generation? The system must retry with a new ID rather than failing or overwriting an existing image.
|
||
- What happens if a record lacks a short ID but the file content is unchanged? The migration assigns a new short ID without re-uploading the file.
|
||
- What happens if the migration is interrupted partway through? Already-migrated images remain accessible; un-migrated images are identifiable so the migration can be re-run safely.
|
||
- What happens if a thumbnail does not exist for an image (e.g., GIFs where generation failed)? The migration skips the thumbnail rename for that record and continues.
|
||
- What happens if a user has bookmarked a UUID-based URL before the migration? Those URLs become invalid; this is acceptable for a personal tool with no external consumers.
|
||
|
||
## Requirements *(mandatory)*
|
||
|
||
### Functional Requirements
|
||
|
||
- **FR-001**: The system MUST assign every image a unique 8-character short ID composed of alphanumeric characters (a–z, A–Z, 0–9).
|
||
- **FR-002**: Every image detail page MUST be accessible at the path `/i/{short_id}`.
|
||
- **FR-003**: The UUID-based image detail route (`/images/{uuid}`) MUST be retired; short ID routes are the sole canonical paths.
|
||
- **FR-004**: Image storage objects (original and thumbnail) MUST use the short ID as their storage key, following flat naming: `{short_id}` for the original and `{short_id}-thumb` for the thumbnail.
|
||
- **FR-005**: The publicly accessible image file URL and thumbnail URL MUST reflect the new storage key names.
|
||
- **FR-006**: On upload, the system MUST check whether an identical file (by hash) already exists and return the existing record rather than creating a duplicate, regardless of short IDs.
|
||
- **FR-007**: The system MUST generate a new short ID on upload, retrying automatically if a collision with an existing ID is detected.
|
||
- **FR-008**: A migration process MUST assign short IDs to all existing images that do not have one, rename their storage objects to match the new keys, and update all stored URLs.
|
||
- **FR-009**: The migration MUST be re-runnable safely — images already migrated MUST be skipped rather than processed again.
|
||
- **FR-010**: All application links that reference images (library grid, detail page, API responses) MUST use short IDs after the migration.
|
||
|
||
### Key Entities
|
||
|
||
- **Image**: Each image has a unique short ID (8 alphanumeric characters) that serves as its canonical identifier in URLs, storage, and API responses. The image retains its content hash for deduplication. The short ID is independent of the hash.
|
||
- **Storage Object**: Each image has two storage objects — an original and a thumbnail — named using the short ID (`{short_id}` and `{short_id}-thumb`). Flat naming, no folder structure.
|
||
|
||
## Success Criteria *(mandatory)*
|
||
|
||
### Measurable Outcomes
|
||
|
||
- **SC-001**: All image detail page URLs use an 8-character alphanumeric identifier at `/i/{short_id}`.
|
||
- **SC-002**: 100% of existing images are accessible via short URL after migration completes, with no broken images or missing thumbnails.
|
||
- **SC-003**: Uploading the same file twice produces one record — deduplication rate remains 100% for identical files.
|
||
- **SC-004**: The migration completes without data loss — no image file or thumbnail is deleted before its renamed copy is confirmed present in storage.
|
||
- **SC-005**: The migration is idempotent — running it a second time produces no changes and no errors.
|
||
|
||
## Assumptions
|
||
|
||
- UUID-based image URLs do not need to remain accessible after migration; this is a personal tool with no external consumers relying on the old URL structure.
|
||
- The migration will be run manually by the operator as a one-time administrative step; it does not need to be triggered from the UI.
|
||
- Storage object renaming is implemented as copy-then-delete to avoid data loss if the process is interrupted mid-run.
|
||
- The short ID character set is base62 (a–z, A–Z, 0–9); no special characters, ensuring URL-safe identifiers without percent-encoding.
|
||
- The `hash` column is retained and continues to be used for deduplication; it is not removed as part of this change.
|
||
- Thumbnails may not exist for all images (e.g., some GIFs); the migration handles missing thumbnails gracefully by skipping the thumbnail rename for those records.
|