manoel freitas
9dd6fcf409
Archive completed public-site and production-provider changes into main specs, remove duplicate active changes, and add complete-foundation-parity so Phase 0 staging and remaining foundation gaps block Phase 2 cleanly. Co-authored-by: Cursor <cursoragent@cursor.com>
107 lines
4.7 KiB
Markdown
107 lines
4.7 KiB
Markdown
# content-media Specification
|
|
|
|
## Purpose
|
|
Define validation, storage, responsive variants, disk selection, and accessibility requirements for public content images.
|
|
|
|
## Requirements
|
|
### Requirement: Public content images are validated and stored securely
|
|
|
|
The system SHALL validate public content uploads (service covers, portfolio covers/gallery, testimonial photos, site OG image) per SPEC §6.4 and §12.4. Validation MUST enforce MIME allowlist (jpeg, png, webp), matching extensions, maximum size of 10 MB, and mandatory alt text when an image is uploaded.
|
|
|
|
#### Scenario: Invalid MIME is rejected
|
|
|
|
- **WHEN** an admin uploads a file with disallowed MIME type
|
|
- **THEN** validation MUST fail with a pt-BR error message
|
|
|
|
#### Scenario: Oversized file is rejected
|
|
|
|
- **WHEN** an admin uploads an image exceeding 10 MB
|
|
- **THEN** validation MUST fail
|
|
|
|
#### Scenario: Storage path is not derived from original filename
|
|
|
|
- **WHEN** an image is stored
|
|
- **THEN** the physical path MUST be generated (UUID/hash based)
|
|
- **AND** MUST NOT use the original upload filename as the storage key
|
|
|
|
#### Scenario: Alt text required with image
|
|
|
|
- **WHEN** an admin uploads a cover or gallery image without alt text
|
|
- **THEN** validation MUST fail
|
|
|
|
#### Scenario: Images are not stored in PostgreSQL
|
|
|
|
- **WHEN** content with images is persisted
|
|
- **THEN** only the filesystem path MUST be stored in the database
|
|
- **AND** binary image data MUST NOT be written to PostgreSQL columns
|
|
|
|
### Requirement: Public images are served in responsive variants
|
|
|
|
The system SHALL generate or serve responsive variants for public content images (service covers, portfolio covers and gallery, testimonial photos) and reference them with `srcset` and `sizes` so browsers download an appropriately sized file (SPEC §6.4). Variant generation MUST happen on upload, not on each request.
|
|
|
|
#### Scenario: Variants are produced on upload
|
|
|
|
- **WHEN** an admin uploads a public content image
|
|
- **THEN** responsive variants MUST be generated and stored alongside the original
|
|
- **AND** the database MUST keep only paths, never binary data
|
|
|
|
#### Scenario: Public markup offers multiple sources
|
|
|
|
- **WHEN** a public page renders a content image
|
|
- **THEN** the `img` element MUST expose `srcset` with the available variants
|
|
- **AND** MUST expose a `sizes` attribute matching the layout
|
|
|
|
#### Scenario: Missing variant falls back to the original
|
|
|
|
- **GIVEN** an image stored before variant generation existed
|
|
- **WHEN** it is rendered on a public page
|
|
- **THEN** the original file MUST be used without breaking the page
|
|
|
|
### Requirement: Public images avoid layout shift and defer offscreen loading
|
|
|
|
Public content images SHALL reserve their space through explicit `width` and `height` (or equivalent aspect-ratio styling) and MUST use `loading="lazy"` when rendered below the fold. Above-the-fold hero imagery MUST NOT be lazy loaded (SPEC §6.4, §6.6).
|
|
|
|
#### Scenario: Offscreen image is lazy loaded
|
|
|
|
- **WHEN** a page renders an image below the first viewport
|
|
- **THEN** the `img` element MUST carry `loading="lazy"`
|
|
|
|
#### Scenario: Hero image loads eagerly
|
|
|
|
- **WHEN** the home hero image is rendered
|
|
- **THEN** it MUST NOT carry `loading="lazy"`
|
|
|
|
#### Scenario: Dimensions are reserved
|
|
|
|
- **WHEN** any public content image is rendered
|
|
- **THEN** width and height (or aspect ratio) MUST be declared so layout does not shift after load
|
|
|
|
### Requirement: Production images are not served from ephemeral container disk
|
|
|
|
Public image variants SHALL be stored on the configured filesystem disk (S3-compatible in production) and referenced by URL, so a container restart or redeploy does not lose media (SPEC §6.4).
|
|
|
|
#### Scenario: Media survives container replacement
|
|
|
|
- **GIVEN** production uses the S3-compatible disk
|
|
- **WHEN** the application container is replaced
|
|
- **THEN** previously uploaded images and variants MUST remain reachable
|
|
|
|
### Requirement: CMS public image uploads select production object storage disk
|
|
|
|
Public content image uploads (Filament FileUpload via `PublicImageUploadRules`) MUST store files on the disk matching the configured default filesystem (SPEC §6.4). When `FILESYSTEM_DISK` is `r2`, uploads MUST use the `r2` disk. When `FILESYSTEM_DISK` is `s3`, uploads MUST use the `s3` disk. Otherwise uploads MUST use the local `public` disk.
|
|
|
|
#### Scenario: Production R2 disk is used for CMS uploads
|
|
|
|
- **WHEN** `FILESYSTEM_DISK=r2`
|
|
- **THEN** `PublicImageUploadRules::disk()` MUST return `r2`
|
|
|
|
#### Scenario: Legacy S3 default still supported
|
|
|
|
- **WHEN** `FILESYSTEM_DISK=s3`
|
|
- **THEN** `PublicImageUploadRules::disk()` MUST return `s3`
|
|
|
|
#### Scenario: Local development uses public disk
|
|
|
|
- **WHEN** `FILESYSTEM_DISK` is `local`, unset, or any value other than `r2`/`s3`
|
|
- **THEN** `PublicImageUploadRules::disk()` MUST return `public`
|