@hed-hog/catalog 0.0.295 → 0.0.297

package/README.md

@@ -1,409 +1,409 @@
-# @hed-hog/catalog
-
-## Overview
-
-`@hed-hog/catalog` is the central catalog module for HedHog. It manages:
-
-- catalog categories
-- brands, merchants, sites, offers, and products
-- structured technical attributes by category
-- product attribute values with typed storage
-- product images and comparison-oriented payloads
-
-The module keeps the existing generic CRUD backbone, pagination, locale, roles, Prisma integration, and admin experience. The main architectural change is that structured attribute tables are now the primary source of truth for technical metadata, while legacy JSON snapshots remain secondary and derived.
-
-## Core architecture
-
-### Primary domain entities
-
-- `catalog_category`
-  Product taxonomy used by the catalog itself.
-- `catalog_attribute`
-  Master definition of a technical/comparable attribute.
-- `catalog_attribute_option`
-  Enumerated values for `option` attributes.
-- `catalog_category_attribute`
-  Rules that define which attributes belong to a category and how they behave in UI/comparison.
-- `catalog_product_attribute_value`
-  Typed value storage for product attributes.
-- `catalog_product`
-  Main product record with brand, category, content, status, and secondary snapshots.
-
-### Supporting entities
-
-- `catalog_brand`
-  Supports `logo_file_id` via the shared `file` module.
-- `catalog_site`
-  Supports `logo_file_id` and site-specific JSON settings.
-- `catalog_merchant`
-  Supports `logo_file_id` when merchant branding is needed.
-- `catalog_product_image`
-  Product gallery/media records via `file_id`.
-- `catalog_offer`, `catalog_affiliate_program`, `catalog_product_site`, `catalog_comparison`, and related tables
-  Commercial/publication/comparison layers that build on top of products and attributes.
-
-## Structured attributes vs JSON snapshots
-
-### Primary data
-
-The canonical source for technical product data is:
-
-1. `catalog_category`
-2. `catalog_attribute`
-3. `catalog_category_attribute`
-4. `catalog_product_attribute_value`
-
-This is what enables:
-
-- consistent admin forms
-- typed validation
-- category-aware required fields
-- filters and sorting by normalized values
-- comparison payload generation
-
-### Secondary data
-
-`catalog_product.spec_snapshot_json` and `catalog_product.comparison_snapshot_json` are still present for compatibility and fast reads.
-
-Important rules:
-
-- they are **not** the primary source of truth anymore
-- they should be treated as **derived/cache fields**
-- they are materialized from structured attributes
-- old data should not be deleted without a migration plan
-
-The service now exposes snapshot materialization helpers and keeps snapshots warm after attribute updates.
-
-## Main tables
-
-### `catalog_category`
-
-Suggested use:
-
-- create taxonomy nodes like `gpu`, `cpu`, `motherboard`, `ram`, `ssd`, `monitor`
-- optionally organize them with `parent_category_id`
-- control whether the category participates in comparison with `comparison_enabled`
-
-Key fields:
-
-- `slug`
-- `name`
-- `description`
-- `parent_category_id`
-- `comparison_enabled`
-- `status`
-- `sort_order`
-
-### `catalog_attribute`
-
-Defines the technical vocabulary shared across categories.
-
-Key fields:
-
-- `code`
-- `slug`
-- `name`
-- `description`
-- `data_type`
-- `unit`
-- `group_name`
-- `comparison_mode`
-- `is_filterable`
-- `is_sortable`
-- `is_comparable`
-- `is_required_default`
-- `status`
-- `display_order`
-
-Supported `data_type` values:
-
-- `text`
-- `long_text`
-- `number`
-- `boolean`
-- `option`
-
-### `catalog_attribute_option`
-
-Used when `catalog_attribute.data_type = option`.
-
-Key fields:
-
-- `attribute_id`
-- `slug`
-- `label`
-- `option_value`
-- `normalized_value`
-- `sort_order`
-- `status`
-- `is_default`
-
-### `catalog_category_attribute`
-
-Binds attributes to categories and controls behavior.
-
-Key fields:
-
-- `catalog_category_id`
-- `attribute_id`
-- `is_required`
-- `is_highlight`
-- `is_filter_visible`
-- `is_comparison_visible`
-- `sort_order`
-- `weight`
-- `facet_mode`
-
-### `catalog_product_attribute_value`
-
-Stores one typed value per `product_id + attribute_id`.
-
-Key fields:
-
-- `product_id`
-- `attribute_id`
-- `attribute_option_id`
-- `value_text`
-- `value_number`
-- `value_boolean`
-- `raw_value`
-- `value_unit`
-- `normalized_value`
-- `normalized_text`
-- `normalized_number`
-- `source_type`
-- `confidence_score`
-- `is_verified`
-
-## Attribute value rules
-
-Only one value channel should be used per attribute value row:
-
-- `text` and `long_text` use `value_text`
-- `number` uses `value_number`
-- `boolean` uses `value_boolean`
-- `option` uses `attribute_option_id`
-
-The backend validates this and rejects inconsistent payloads.
-
-## Initial catalog seeds
-
-The module now ships declarative YAML seeds in `libraries/catalog/hedhog/data`.
-
-Seeded categories:
-
-- `gpu`
-- `cpu`
-- `motherboard`
-- `ram`
-- `ssd`
-- `monitor`
-
-Seeded example attributes:
-
-### GPU
-
-- `chipset`
-- `vram_gb`
-- `memory_type`
-- `memory_bus_bits`
-- `boost_clock_mhz`
-- `tdp_w`
-- `length_mm`
-- `ray_tracing`
-
-### CPU
-
-- `cores`
-- `threads`
-- `base_clock_ghz`
-- `boost_clock_ghz`
-- `socket`
-- `tdp_w`
-- `integrated_graphics`
-
-Seeded example options:
-
-- GPU memory types like `GDDR6`, `GDDR6X`, `GDDR7`, `HBM3`, `HBM3E`
-- CPU sockets like `AM4`, `AM5`, `LGA1700`, `LGA1851`, `sTR5`
-
-## Admin resources
-
-The catalog admin supports generic CRUD plus specialized product attribute editing.
-
-Main resources:
-
-- `categories`
-- `brands`
-- `sites`
-- `products`
-- `attribute-groups`
-- `attributes`
-- `attribute-options`
-- `category-attributes`
-- `product-attributes`
-- `comparisons`
-- `offers`
-- `merchants`
-- `affiliate-programs`
-- `seo-rules`
-- `import-sources`
-
-### Product admin experience
-
-When editing a product:
-
-1. select `catalog_category_id`
-2. the admin loads category attributes dynamically
-3. fields are grouped by attribute group or `group_name`
-4. typed inputs are rendered for `text`, `long_text`, `number`, `boolean`, and `option`
-5. required fields are validated before save
-6. values are persisted into `catalog_product_attribute_value`
-
-The product screen also shows:
-
-- brand
-- category
-- status and active flag
-- grouped technical attributes
-- product images as a secondary block
-- snapshots as secondary/derived data
-
-## Logos and files
-
-The module uses the shared `file` flow already present in the monorepo.
-
-### Brand logo
-
-Use `catalog_brand.logo_file_id`.
-
-### Site logo
-
-Use `catalog_site.logo_file_id`.
-
-### Merchant logo
-
-Use `catalog_merchant.logo_file_id`.
-
-### Product gallery
-
-Use `catalog_product_image.file_id`.
-
-No custom upload mechanism was introduced. The admin uses the same file upload pattern already used across the project.
-
-## Runtime helpers
-
-`CatalogService` now includes helpers for:
-
-- listing category attributes
-- listing product attributes
-- building a structured product payload
-- building a comparison payload from structured attributes
-- materializing `spec_snapshot_json` and `comparison_snapshot_json`
-
-Relevant endpoints:
-
-- `GET /catalog/categories/tree`
-- `GET /catalog/categories/:id/attributes`
-- `GET /catalog/products/:id/attributes`
-- `PUT /catalog/products/:id/attributes`
-- `GET /catalog/products/:id/structured`
-- `GET /catalog/products/:id/comparison-payload`
-- `POST /catalog/products/:id/materialize-snapshots`
-- generic CRUD under `/catalog/:resource`
-
-## Safe transition strategy
-
-The module preserves snapshot fields to avoid destructive migration behavior.
-
-Current strategy:
-
-- structured attribute tables are canonical
-- snapshots remain readable
-- snapshots are regenerated from structured values
-- attribute updates trigger snapshot materialization
-- compatibility aliases are still accepted in a few payloads where the old UI/model used different names
-
-This keeps the module safe for gradual adoption while avoiding JSON-first modeling going forward.
-
-## How to apply schema and seeds
-
-This repository follows a database-first HedHog workflow.
-
-### Schema/data apply
-
-```powershell
-hedhog dev apply
-pnpm db:update
-```
-
-`hedhog dev apply` applies table YAML and the declarative data under `hedhog/data`, so the catalog seed data lives in the same standard workflow as the rest of the project.
-
-### Build checks
-
-```powershell
-pnpm --filter api build
-pnpm --filter @hed-hog/catalog build
-pnpm --filter admin build
-```
-
-## Example flows
-
-### 1. Create a brand with logo
-
-1. Open `Catalog > Brands`
-2. Create a brand with `name`, `slug`, and optional `website_url`
-3. Upload the logo through the shared upload field
-4. Save, which stores the uploaded file in `logo_file_id`
-
-### 2. Create a category
-
-1. Open `Catalog > Categories`
-2. Create `gpu`-like or business-specific categories
-3. Configure `comparison_enabled`, hierarchy, and status
-
-### 3. Create an attribute
-
-1. Open `Catalog > Attributes`
-2. Define `code`, `slug`, `name`, `data_type`, and `group_name`
-3. Mark whether the attribute is filterable/sortable/comparable
-
-### 4. Link an attribute to a category
-
-1. Open `Catalog > Category Attributes`
-2. Pick the category and the attribute
-3. Configure required/highlight/filter/comparison behavior
-4. Save ordering and facet mode
-
-### 5. Create a product
-
-1. Open `Catalog > Products`
-2. Fill the base product fields
-3. Choose brand and category
-4. Save the product
-
-### 6. Save product technical attributes
-
-1. In the same product sheet, after category selection, the technical fields load automatically
-2. Fill typed values
-3. Save the product
-4. The admin persists values to `catalog_product_attribute_value`
-5. Snapshots are materialized as derived JSON
-
-## Starting with GPU and CPU
-
-The seeded data is enough to bootstrap a real first catalog slice:
-
-1. create brands like `NVIDIA`, `AMD`, `Intel`
-2. create products under `gpu` and `cpu`
-3. fill structured attributes
-4. optionally attach product images
-5. use comparison payload endpoints to power future storefront or editorial flows
-
-## Future improvements
-
-- automatic snapshot materialization on more product lifecycle events
-- richer import pipelines that map external payloads directly to structured attributes
-- category-specific admin presets and product templates
-- storefront queries optimized for faceting and comparison at scale
-- deeper read models for SEO, rankings, and recommendation features
+# @hed-hog/catalog
+
+## Overview
+
+`@hed-hog/catalog` is the central catalog module for HedHog. It manages:
+
+- catalog categories
+- brands, merchants, sites, offers, and products
+- structured technical attributes by category
+- product attribute values with typed storage
+- product images and comparison-oriented payloads
+
+The module keeps the existing generic CRUD backbone, pagination, locale, roles, Prisma integration, and admin experience. The main architectural change is that structured attribute tables are now the primary source of truth for technical metadata, while legacy JSON snapshots remain secondary and derived.
+
+## Core architecture
+
+### Primary domain entities
+
+- `catalog_category`
+  Product taxonomy used by the catalog itself.
+- `catalog_attribute`
+  Master definition of a technical/comparable attribute.
+- `catalog_attribute_option`
+  Enumerated values for `option` attributes.
+- `catalog_category_attribute`
+  Rules that define which attributes belong to a category and how they behave in UI/comparison.
+- `catalog_product_attribute_value`
+  Typed value storage for product attributes.
+- `catalog_product`
+  Main product record with brand, category, content, status, and secondary snapshots.
+
+### Supporting entities
+
+- `catalog_brand`
+  Supports `logo_file_id` via the shared `file` module.
+- `catalog_site`
+  Supports `logo_file_id` and site-specific JSON settings.
+- `catalog_merchant`
+  Supports `logo_file_id` when merchant branding is needed.
+- `catalog_product_image`
+  Product gallery/media records via `file_id`.
+- `catalog_offer`, `catalog_affiliate_program`, `catalog_product_site`, `catalog_comparison`, and related tables
+  Commercial/publication/comparison layers that build on top of products and attributes.
+
+## Structured attributes vs JSON snapshots
+
+### Primary data
+
+The canonical source for technical product data is:
+
+1. `catalog_category`
+2. `catalog_attribute`
+3. `catalog_category_attribute`
+4. `catalog_product_attribute_value`
+
+This is what enables:
+
+- consistent admin forms
+- typed validation
+- category-aware required fields
+- filters and sorting by normalized values
+- comparison payload generation
+
+### Secondary data
+
+`catalog_product.spec_snapshot_json` and `catalog_product.comparison_snapshot_json` are still present for compatibility and fast reads.
+
+Important rules:
+
+- they are **not** the primary source of truth anymore
+- they should be treated as **derived/cache fields**
+- they are materialized from structured attributes
+- old data should not be deleted without a migration plan
+
+The service now exposes snapshot materialization helpers and keeps snapshots warm after attribute updates.
+
+## Main tables
+
+### `catalog_category`
+
+Suggested use:
+
+- create taxonomy nodes like `gpu`, `cpu`, `motherboard`, `ram`, `ssd`, `monitor`
+- optionally organize them with `parent_category_id`
+- control whether the category participates in comparison with `comparison_enabled`
+
+Key fields:
+
+- `slug`
+- `name`
+- `description`
+- `parent_category_id`
+- `comparison_enabled`
+- `status`
+- `sort_order`
+
+### `catalog_attribute`
+
+Defines the technical vocabulary shared across categories.
+
+Key fields:
+
+- `code`
+- `slug`
+- `name`
+- `description`
+- `data_type`
+- `unit`
+- `group_name`
+- `comparison_mode`
+- `is_filterable`
+- `is_sortable`
+- `is_comparable`
+- `is_required_default`
+- `status`
+- `display_order`
+
+Supported `data_type` values:
+
+- `text`
+- `long_text`
+- `number`
+- `boolean`
+- `option`
+
+### `catalog_attribute_option`
+
+Used when `catalog_attribute.data_type = option`.
+
+Key fields:
+
+- `attribute_id`
+- `slug`
+- `label`
+- `option_value`
+- `normalized_value`
+- `sort_order`
+- `status`
+- `is_default`
+
+### `catalog_category_attribute`
+
+Binds attributes to categories and controls behavior.
+
+Key fields:
+
+- `catalog_category_id`
+- `attribute_id`
+- `is_required`
+- `is_highlight`
+- `is_filter_visible`
+- `is_comparison_visible`
+- `sort_order`
+- `weight`
+- `facet_mode`
+
+### `catalog_product_attribute_value`
+
+Stores one typed value per `product_id + attribute_id`.
+
+Key fields:
+
+- `product_id`
+- `attribute_id`
+- `attribute_option_id`
+- `value_text`
+- `value_number`
+- `value_boolean`
+- `raw_value`
+- `value_unit`
+- `normalized_value`
+- `normalized_text`
+- `normalized_number`
+- `source_type`
+- `confidence_score`
+- `is_verified`
+
+## Attribute value rules
+
+Only one value channel should be used per attribute value row:
+
+- `text` and `long_text` use `value_text`
+- `number` uses `value_number`
+- `boolean` uses `value_boolean`
+- `option` uses `attribute_option_id`
+
+The backend validates this and rejects inconsistent payloads.
+
+## Initial catalog seeds
+
+The module now ships declarative YAML seeds in `libraries/catalog/hedhog/data`.
+
+Seeded categories:
+
+- `gpu`
+- `cpu`
+- `motherboard`
+- `ram`
+- `ssd`
+- `monitor`
+
+Seeded example attributes:
+
+### GPU
+
+- `chipset`
+- `vram_gb`
+- `memory_type`
+- `memory_bus_bits`
+- `boost_clock_mhz`
+- `tdp_w`
+- `length_mm`
+- `ray_tracing`
+
+### CPU
+
+- `cores`
+- `threads`
+- `base_clock_ghz`
+- `boost_clock_ghz`
+- `socket`
+- `tdp_w`
+- `integrated_graphics`
+
+Seeded example options:
+
+- GPU memory types like `GDDR6`, `GDDR6X`, `GDDR7`, `HBM3`, `HBM3E`
+- CPU sockets like `AM4`, `AM5`, `LGA1700`, `LGA1851`, `sTR5`
+
+## Admin resources
+
+The catalog admin supports generic CRUD plus specialized product attribute editing.
+
+Main resources:
+
+- `categories`
+- `brands`
+- `sites`
+- `products`
+- `attribute-groups`
+- `attributes`
+- `attribute-options`
+- `category-attributes`
+- `product-attributes`
+- `comparisons`
+- `offers`
+- `merchants`
+- `affiliate-programs`
+- `seo-rules`
+- `import-sources`
+
+### Product admin experience
+
+When editing a product:
+
+1. select `catalog_category_id`
+2. the admin loads category attributes dynamically
+3. fields are grouped by attribute group or `group_name`
+4. typed inputs are rendered for `text`, `long_text`, `number`, `boolean`, and `option`
+5. required fields are validated before save
+6. values are persisted into `catalog_product_attribute_value`
+
+The product screen also shows:
+
+- brand
+- category
+- status and active flag
+- grouped technical attributes
+- product images as a secondary block
+- snapshots as secondary/derived data
+
+## Logos and files
+
+The module uses the shared `file` flow already present in the monorepo.
+
+### Brand logo
+
+Use `catalog_brand.logo_file_id`.
+
+### Site logo
+
+Use `catalog_site.logo_file_id`.
+
+### Merchant logo
+
+Use `catalog_merchant.logo_file_id`.
+
+### Product gallery
+
+Use `catalog_product_image.file_id`.
+
+No custom upload mechanism was introduced. The admin uses the same file upload pattern already used across the project.
+
+## Runtime helpers
+
+`CatalogService` now includes helpers for:
+
+- listing category attributes
+- listing product attributes
+- building a structured product payload
+- building a comparison payload from structured attributes
+- materializing `spec_snapshot_json` and `comparison_snapshot_json`
+
+Relevant endpoints:
+
+- `GET /catalog/categories/tree`
+- `GET /catalog/categories/:id/attributes`
+- `GET /catalog/products/:id/attributes`
+- `PUT /catalog/products/:id/attributes`
+- `GET /catalog/products/:id/structured`
+- `GET /catalog/products/:id/comparison-payload`
+- `POST /catalog/products/:id/materialize-snapshots`
+- generic CRUD under `/catalog/:resource`
+
+## Safe transition strategy
+
+The module preserves snapshot fields to avoid destructive migration behavior.
+
+Current strategy:
+
+- structured attribute tables are canonical
+- snapshots remain readable
+- snapshots are regenerated from structured values
+- attribute updates trigger snapshot materialization
+- compatibility aliases are still accepted in a few payloads where the old UI/model used different names
+
+This keeps the module safe for gradual adoption while avoiding JSON-first modeling going forward.
+
+## How to apply schema and seeds
+
+This repository follows a database-first HedHog workflow.
+
+### Schema/data apply
+
+```powershell
+hedhog dev apply
+pnpm db:update
+```
+
+`hedhog dev apply` applies table YAML and the declarative data under `hedhog/data`, so the catalog seed data lives in the same standard workflow as the rest of the project.
+
+### Build checks
+
+```powershell
+pnpm --filter api build
+pnpm --filter @hed-hog/catalog build
+pnpm --filter admin build
+```
+
+## Example flows
+
+### 1. Create a brand with logo
+
+1. Open `Catalog > Brands`
+2. Create a brand with `name`, `slug`, and optional `website_url`
+3. Upload the logo through the shared upload field
+4. Save, which stores the uploaded file in `logo_file_id`
+
+### 2. Create a category
+
+1. Open `Catalog > Categories`
+2. Create `gpu`-like or business-specific categories
+3. Configure `comparison_enabled`, hierarchy, and status
+
+### 3. Create an attribute
+
+1. Open `Catalog > Attributes`
+2. Define `code`, `slug`, `name`, `data_type`, and `group_name`
+3. Mark whether the attribute is filterable/sortable/comparable
+
+### 4. Link an attribute to a category
+
+1. Open `Catalog > Category Attributes`
+2. Pick the category and the attribute
+3. Configure required/highlight/filter/comparison behavior
+4. Save ordering and facet mode
+
+### 5. Create a product
+
+1. Open `Catalog > Products`
+2. Fill the base product fields
+3. Choose brand and category
+4. Save the product
+
+### 6. Save product technical attributes
+
+1. In the same product sheet, after category selection, the technical fields load automatically
+2. Fill typed values
+3. Save the product
+4. The admin persists values to `catalog_product_attribute_value`
+5. Snapshots are materialized as derived JSON
+
+## Starting with GPU and CPU
+
+The seeded data is enough to bootstrap a real first catalog slice:
+
+1. create brands like `NVIDIA`, `AMD`, `Intel`
+2. create products under `gpu` and `cpu`
+3. fill structured attributes
+4. optionally attach product images
+5. use comparison payload endpoints to power future storefront or editorial flows
+
+## Future improvements
+
+- automatic snapshot materialization on more product lifecycle events
+- richer import pipelines that map external payloads directly to structured attributes
+- category-specific admin presets and product templates
+- storefront queries optimized for faceting and comparison at scale
+- deeper read models for SEO, rankings, and recommendation features