# Architect — F-011 Product images

## Decision
Keep product images inside the catalog module. Product and variant images are catalog-owned presentation metadata, not a separate bounded context yet.

## Data model
Add `catalog_product_images`:
- `id uuid primary key default gen_random_uuid()`
- `product_id uuid not null references catalog_products(id) on delete cascade`
- `variant_id uuid null references catalog_product_variants(id) on delete cascade`
- `url text not null`
- `alt_text text not null`
- `position integer not null`
- `role text not null check (role in ('main', 'gallery'))`
- timestamps

Rules:
- `position >= 0`
- `variant_id` is optional; when present it must belong to the same `product_id`.
- Exactly one `main` image per product-level set and per variant-level set. Implement with partial unique indexes:
  - `(product_id) WHERE variant_id IS NULL AND role = 'main'`
  - `(variant_id) WHERE variant_id IS NOT NULL AND role = 'main'`
- Stable ordering by `position`, then `created_at`, then `id`.

## Domain/application
Add image domain types in catalog:
- `ProductImageRole = 'main' | 'gallery'`
- `ProductImage` with productId, optional variantId, url, altText, position, role.
- `NewProductImage` and `ProductImagePatch`.

Add `ProductImageRepository` port. It is the boundary that makes storage swappable:
- API/application depend only on the port.
- Local-first storage is represented as URLs accepted by the adapter/repository path for this slice.
- Future CDN/image processing must touch infrastructure only.

Use cases:
- `ListProductImages(productId, variantId?)`
- `AttachProductImage(productId, input)`; verify product exists, and if `variantId` is passed verify it belongs to that product.
- `DetachProductImage(productId, imageId)`
- `ReorderProductImages(productId, items)`; validates all listed images belong to the same product/scope.

## API
Admin mutations, public read through product serialization:
- `GET /productos/:slug` includes ordered `images` list for product-level images.
- `GET /products/search` may continue returning product core only unless cheap to include images; acceptance only requires product exposes ordered image list.
- `GET /products/:id/images` returns ordered product-level images.
- `POST /products/:id/images` attaches product or variant image. Body: `url`, `altText`, `role`, optional `variantId`, optional `position`.
- `DELETE /products/:id/images/:imageId` detaches.
- `PATCH /products/:id/images/reorder` accepts ordered `{ imageId, position }[]`.

Validation:
- URL must be a bounded string and should be parseable URL or local absolute path beginning with `/`.
- `altText` is required, trimmed, max 300.
- `role` uses the domain enum.

## Tests/evidence
- Unit test use cases with fake repositories:
  - ordered list preserves repository ordering.
  - attach rejects missing product.
  - attach rejects variant from another product.
- Repository/migration shape can be covered by existing migration integration test when `TEST_DATABASE_URL` exists.
- `npm test`, `npm run typecheck`, and root `./scripts/verify.sh` must be green.

## Out of scope guardrails
No binary upload, CDN, resizing, optimization pipeline, or external object-store SDK in F-011. No new runtime dependency expected.