fragginwagon
f1e5c98013
Add worker-owned image derivative job execution with explicit PROCESSING, COMPLETED, and FAILED outcomes, plus tests and documentation. Verification: npm test passed 70 tests, worker tests passed 2 tests, and integration passed 14 tests. No build script is configured.
111 lines
2.6 KiB
Markdown
111 lines
2.6 KiB
Markdown
# Image Management
|
|
|
|
## Requirements
|
|
|
|
Multiple images are core functionality.
|
|
|
|
Use cases include:
|
|
- card front/back
|
|
- corners
|
|
- edges/whitening
|
|
- holographic details
|
|
- merchandise angles
|
|
- defects/details
|
|
|
|
## Workflow
|
|
|
|
`Upload → Validate → Store Original → Queue Processing → Generate Derivatives → Complete`
|
|
|
|
Support:
|
|
- multiple-file upload
|
|
- drag/drop
|
|
- preview
|
|
- reorder
|
|
- primary image
|
|
- delete
|
|
- add images later
|
|
|
|
Image count is configurable.
|
|
|
|
## Storage
|
|
|
|
Images are not stored in PostgreSQL.
|
|
|
|
Use an `ImageStorage` abstraction.
|
|
|
|
Initial:
|
|
- Docker-mounted local storage
|
|
|
|
Future:
|
|
- S3-compatible object storage
|
|
|
|
The API uses an `ImageStorage` contract with `put`, `get`, and `delete`
|
|
operations. The current local adapter rejects absolute and traversal paths and
|
|
does not overwrite an existing key. It stores bytes outside PostgreSQL; image
|
|
metadata remains in `inventory_images`.
|
|
|
|
## Processing
|
|
|
|
Validate:
|
|
- MIME type
|
|
- file signature where practical
|
|
- size
|
|
- image dimensions
|
|
- configured image count
|
|
|
|
The metadata service currently enforces JPEG, PNG, and WebP MIME types, a
|
|
10 MiB default file-size limit, and a 10,000-pixel maximum width and height.
|
|
Multipart upload validation now checks the declared MIME type against JPEG,
|
|
PNG, and WebP signatures before storage. Image dimensions are supplied by the
|
|
upload transport until a decoder-backed dimension extractor is added.
|
|
|
|
Generate:
|
|
- thumbnail
|
|
- medium
|
|
- large/responsive derivatives
|
|
|
|
Modern formats such as WebP/AVIF may be used where appropriate.
|
|
|
|
Retain originals where practical.
|
|
|
|
Derivative orchestration currently defines thumbnail, medium, and large WebP
|
|
variants and writes them through `ImageStorage` using an injected renderer.
|
|
The concrete decoder/encoder and worker queue remain separate infrastructure
|
|
work so local development does not depend on a machine-specific binary.
|
|
|
|
The worker now owns the derivative job lifecycle and reports explicit
|
|
`PENDING`, `PROCESSING`, `COMPLETED`, or `FAILED` outcomes. Queue transport and
|
|
persistent job records remain deployment-specific work.
|
|
|
|
## Metadata
|
|
|
|
Store:
|
|
- storage key
|
|
- original filename
|
|
- MIME type
|
|
- file size
|
|
- dimensions
|
|
- alt text
|
|
- order
|
|
- primary flag
|
|
- processing status
|
|
- timestamps
|
|
|
|
## Alt text
|
|
|
|
Generate an initial suggestion automatically, but require the seller to be able to review/edit it.
|
|
|
|
Do not invent details not visible or supplied by the seller.
|
|
|
|
## Accessibility
|
|
|
|
Public galleries must support:
|
|
- keyboard operation
|
|
- accessible controls
|
|
- visible focus
|
|
- meaningful names
|
|
- focus management
|
|
- screen-reader-friendly state
|
|
|
|
Primary images power cards, search results, homepage previews, and social/share metadata.
|