ref for projection snapshots

catalog/projection.go

@@ -9,6 +9,7 @@
 // Mapping source JSON → Projection is per-tenant and lives in Schema.
 // The consensus mapping for DefaultSchema() is:
 //
+//	item_id          ← int coercion of source[ItemIdField]   (omitempty; 0 = unset)
 //	id               ← IDPrefix + SKU (e.g. "sku:<SKU>")
 //	sku              ← source[SKUField]
 //	title            ← source[TitleField]            (omitempty, optional)
@@ -48,8 +49,17 @@ import (
 //
 // Field rationale:
 //
-//	ID               — opaque published identity; SKU alone is not a stable
-//	                  cross-module id (different scopes reuse it).
+//	ItemID           — opaque numeric catalog item id from the producer's
+//	                  source (e.g. product service `/api/get/{sku}` integer
+//	                  `id` field, or the bygglagret raw row `item_id`).
+//	                  Carried here as uint32 to mirror go-cart-actor's
+//	                  proto messages.AddItem.ItemId which dedupes cart lines
+//	                  on equality. Zero means "producer didn't publish" — a
+//	                  legitimate value when the source has no integer id
+//	                  (the cart fall-back path uses HTTP PRODUCT_BASE_URL
+//	                  to recover the id in that case).
+//	ID               — opaque published string identity; SKU alone is not a
+//	                  stable cross-module id (different scopes reuse it).
 //	SKU              — domain identifier; the join key cart already uses.
 //	PriceIncVat      — display + checkout projection; NOT transactional truth.
 //	                  System of record for the total is settled via the
@@ -66,10 +76,16 @@ import (
 //	                  tracking for non-stock items.
 //	Category / Brand / Image — display projection only.
 //	UpdatedAt        — version stamp for snapshot + revalidate.
+//
+// WIRE-COMPAT: adding a field is forward+backward-safe. Old snapshot
+// readers ignore unknown JSON keys; new readers populate the field from
+// the JSON token. The on-disk snapshot binary header/record layout is
+// unchanged \u2014 only the per-blob JSON payload gains a key.
 type Projection struct {
-	ID          string      `json:"id"`
-	SKU         string      `json:"sku"`
-	Title       string      `json:"title,omitempty"`
+	ItemID uint32 `json:"item_id,omitempty"`
+	ID     string `json:"id"`
+	SKU    string `json:"sku"`
+	Title  string `json:"title,omitempty"`
 	PriceIncVat money.Cents `json:"price_inc_vat"`
 	Currency    string      `json:"currency,omitempty"`
 	// TaxClass uses a string identifier (see platform/tax class constants).