# Catalog Foundation

## Product family and variant

The catalog separates the commercial product family from its concrete variant.

A product family always has at least one variant. For simple products, the system creates
a hidden/default-style variant automatically rather than maintaining a separate product shape.

Examples:
- Product family: T-Shirt
  - Variant: Black / M
  - Variant: Black / L
- Product family: Water Bottle
  - Default variant: Water Bottle

The database enforces one default variant per family.

## Product types

Initial product types:
- standard
- service
- bundle
- recipe

Bundle and recipe are intentionally distinct concepts.
Recipe behavior and production consumption are not implemented in this increment.

## Tracking readiness

`tracking_mode` supports:
- none
- batch
- serial

This increment only stores catalog readiness. Batch/serial operational ledgers belong to
Inventory and will be implemented there.

## Units

Units are tenant-owned master data.

Variant units define conversion to the base unit using `NUMERIC(18,6)`.

Rules:
- conversion factor must be positive
- a variant can have only one base unit
- one unit may be marked sellable and/or purchasable

## Barcodes

Barcodes:
- are unique within a tenant
- point to a variant
- may optionally point to a specific variant unit

Supported initial barcode types:
- EAN-13
- EAN-8
- UPC-A
- Code 128
- QR
- Internal
- Weight-scale

## Public/API identity

Internal relations use BIGINT keys.
External APIs expose ULID public IDs.

## APIs

- `GET /api/v1/catalog/product-families`
- `POST /api/v1/catalog/product-families`
- `GET /api/v1/catalog/units`
- `POST /api/v1/catalog/units`
- `POST /api/v1/catalog/variants/{variantPublicId}/units`
- `POST /api/v1/catalog/variants/{variantPublicId}/barcodes`

## Permissions

- `catalog.view`
- `catalog.manage`

## Audit events

- `catalog.product_family.created`
- `catalog.unit.created`
- `catalog.variant_unit.created`
- `catalog.barcode.created`

## Deliberately deferred

- category hierarchy
- brands
- product images/media
- alternate/supplier SKUs
- generated internal barcode service
- weight-scale parsing rules
- bundle components
- batch/serial operational records
- recipe/production domain
- pricing
- tax/fiscal classification