@fayz-ai/db 0.12.0 → 0.13.0

package/migrations/085_catalog_products.sql

@@ -0,0 +1,333 @@
+-- ============================================================================
+-- 085_catalog_products.sql — the catalog contract, part 1 (PRD 04 / #139):
+-- ONE catalog item archetype. `public.products` carries `kind good|service`
+-- (DATA-MODEL §1: a sixth "services" table was rejected); the drifted
+-- `public.services` table is folded into products and kept as a compatibility
+-- MIRROR; products and categories get the authz scaffold plus the catalog
+-- release rule (available_in).
+--
+-- What this file does, in order (every step idempotent + replay-safe):
+--   1. products: kind (good|service), subkind (vertical/plugin discriminator),
+--      duration_minutes (core, services), service_kind (ADR 0009 promoted
+--      column: standard|evaluation|return — a schedulable state, not JSONB).
+--   2. authz scaffold on products, categories and services (mirror), plus the
+--      RESTRICTIVE release policy: a tenant-wide item (unit_id null) is visible
+--      in a unit only if it has no `available_in` tuple or one for that unit
+--      ("no tuples ⇒ everywhere", §9.1); a unit-scoped item is governed by
+--      has_unit as every business row.
+--   3. a BEFORE trigger normalises writes: legacy `kind` values the fleet
+--      wrote before this contract ('menu_item', 'sale', 'ingredient', 'asset',
+--      'intermediate', 'course') map to kind + subkind so old TS keeps working;
+--      service_kind is filled for services and cleared for goods. Unknown
+--      kinds are left for the CHECK to reject.
+--   4. FOLD: every public.services row becomes a products row with the SAME id
+--      (ADR 0007 spirit — order_items.service_id keeps meaning); the FKs of
+--      order_items.service_id and appointment_items.service_id are repointed
+--      to products(id).
+--   5. COMPAT: public.services stays a physical table (a VIEW would break the
+--      replay of 004/006/025/034, which ALTER/INDEX/POLICY it — applied files
+--      are never edited). It is a projection of products WHERE kind='service'
+--      maintained by triggers in BOTH directions, so `.from('services')` reads
+--      AND writes keep working; a transaction-local flag stops the echo.
+--      Deprecation: Phase 1 makes it read-only, Phase 2 drops it
+--      (docs/data/phase-0/04-catalog-contract.md).
+--   6. stock/min_stock stay (inventory owns balances, #143) — commented as
+--      deprecated; global search sources split goods and services.
+-- ============================================================================
+
+-- ── 1. products columns ─────────────────────────────────────────────────
+ALTER TABLE public.products ADD COLUMN IF NOT EXISTS kind text NOT NULL DEFAULT 'good';
+ALTER TABLE public.products ADD COLUMN IF NOT EXISTS subkind text;
+ALTER TABLE public.products ADD COLUMN IF NOT EXISTS duration_minutes integer;
+ALTER TABLE public.products ADD COLUMN IF NOT EXISTS service_kind text;
+
+COMMENT ON COLUMN public.products.kind IS
+  'Catalog archetype: good | service. The only discriminator the core knows (DATA-MODEL §1). Vertical/plugin refinements go in subkind.';
+COMMENT ON COLUMN public.products.subkind IS
+  'Vertical or plugin discriminator inside a kind (menu_item, ingredient, asset, intermediate, course, …). Free text: a new subkind is a row, not a migration.';
+COMMENT ON COLUMN public.products.duration_minutes IS
+  'Core duration of a service (kind=service); the agenda reads it. NULL for goods.';
+COMMENT ON COLUMN public.products.service_kind IS
+  'ADR 0009 promoted column: standard | evaluation | return — a schedulable state (RN-CAT-03), never JSONB. NULL for goods, standard by default for services.';
+COMMENT ON COLUMN public.products.stock IS
+  'deprecated: inventory owns balances (#143). Kept only until the inventory slice moves the last reader; never write it from the catalog.';
+COMMENT ON COLUMN public.products.min_stock IS
+  'deprecated: inventory owns balances (#143). Kept only until the inventory slice moves the last reader; never write it from the catalog.';
+
+CREATE INDEX IF NOT EXISTS products_tenant_kind_idx ON public.products (tenant_id, kind);
+CREATE INDEX IF NOT EXISTS products_tenant_subkind_idx ON public.products (tenant_id, subkind) WHERE subkind IS NOT NULL;
+
+-- ── 2. authz scaffold (§4/§7 template) ─────────────────────────────────
+-- Catalog is a tenant-wide resource: unit_id is null by default; owner scoping
+-- off. products / categories / services (mirror) share the 'catalog' keys.
+-- enforce mode replaces the 004/006 tenant-only policies (a replay of 004/006
+-- recreates them; this call converges the table again).
+SELECT app.scaffold_table('public.products',   'catalog.product',  'catalog', false, 'enforce');
+SELECT app.scaffold_table('public.categories', 'catalog.category', 'catalog', false, 'enforce');
+SELECT app.scaffold_table('public.services',   'catalog.product',  'catalog', false, 'enforce');
+
+-- The release mechanism (§9.1). Permissive policies OR together, so a
+-- restriction has to be AS RESTRICTIVE: it ANDs with the scaffold's select.
+--   unit-scoped item (unit_id set)  → has_unit decides (scaffold), this is true
+--   tenant-wide item (unit_id null) → visible where available_in says; no tuple
+--                                     ⇒ everywhere
+-- Created AFTER the scaffold (enforce drops every foreign policy) so a replay
+-- converges: scaffold drops it, this recreates it.
+DROP POLICY IF EXISTS products_available_in ON public.products;
+CREATE POLICY products_available_in ON public.products AS RESTRICTIVE FOR SELECT TO authenticated
+  USING (unit_id IS NOT NULL OR (select app.available_in_my_units('catalog.product', id)));
+DROP POLICY IF EXISTS services_available_in ON public.services;
+CREATE POLICY services_available_in ON public.services AS RESTRICTIVE FOR SELECT TO authenticated
+  USING (unit_id IS NOT NULL OR (select app.available_in_my_units('catalog.product', id)));
+
+-- categories: shared taxonomy with hierarchy — the parent must be a category of
+-- the same tenant. ON DELETE SET NULL (parent_id): only the pointer is cleared,
+-- never tenant_id (a bare SET NULL on a composite FK would null both).
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conrelid = 'public.categories'::regclass AND conname = 'categories_parent_tenant_fk') THEN
+    ALTER TABLE public.categories
+      ADD CONSTRAINT categories_parent_tenant_fk FOREIGN KEY (tenant_id, parent_id)
+      REFERENCES public.categories (tenant_id, id) ON DELETE SET NULL (parent_id);
+  END IF;
+END $$;
+CREATE INDEX IF NOT EXISTS categories_tenant_parent_idx ON public.categories (tenant_id, parent_id);
+COMMENT ON COLUMN public.categories.kind IS
+  'Taxonomy namespace. Catalog categories use the product kind they classify (good | service); other plugins keep their own (menu_category, …).';
+
+-- ── 3. write normalisation (legacy kind compat + service_kind pairing) ──
+-- Runs BEFORE the CHECKs. Legacy vocabulary written by the fleet before this
+-- contract: plugin-menu 'menu_item', plugin-inventory 'sale' | 'ingredient' |
+-- 'asset' (+ V1 'intermediate'), courses 'course'. Anything else is left as
+-- written so the CHECK rejects it (an unknown kind must not silently become a
+-- good). Deprecated: once every writer speaks kind+subkind the map goes away.
+CREATE OR REPLACE FUNCTION app.trg_catalog_products_normalise()
+RETURNS trigger LANGUAGE plpgsql SET search_path = '' AS $$
+BEGIN
+  IF NEW.kind IS NULL THEN
+    NEW.kind := 'good';
+  END IF;
+  IF NEW.kind NOT IN ('good', 'service') THEN
+    CASE NEW.kind
+      WHEN 'menu_item'    THEN NEW.subkind := coalesce(NEW.subkind, 'menu_item');    NEW.kind := 'good';
+      WHEN 'ingredient'   THEN NEW.subkind := coalesce(NEW.subkind, 'ingredient');   NEW.kind := 'good';
+      WHEN 'asset'        THEN NEW.subkind := coalesce(NEW.subkind, 'asset');        NEW.kind := 'good';
+      WHEN 'intermediate' THEN NEW.subkind := coalesce(NEW.subkind, 'intermediate'); NEW.kind := 'good';
+      WHEN 'sale'         THEN NEW.kind := 'good';
+      WHEN 'course'       THEN NEW.subkind := coalesce(NEW.subkind, 'course');       NEW.kind := 'service';
+      ELSE NULL; -- unknown: the CHECK constraint rejects it
+    END CASE;
+  END IF;
+  IF NEW.kind = 'service' THEN
+    NEW.service_kind := coalesce(NEW.service_kind, 'standard');
+  ELSE
+    NEW.service_kind := NULL;
+  END IF;
+  RETURN NEW;
+END $$;
+DROP TRIGGER IF EXISTS products_catalog_normalise ON public.products;
+CREATE TRIGGER products_catalog_normalise
+  BEFORE INSERT OR UPDATE ON public.products
+  FOR EACH ROW EXECUTE FUNCTION app.trg_catalog_products_normalise();
+
+-- ── 4. FOLD services → products (same id) ──────────────────────────────
+INSERT INTO public.products (
+  id, tenant_id, category_id, name, description, price, cost, currency, image_url,
+  status, is_active, tags, metadata, custom_fields, created_by, created_at, updated_at,
+  unit_id, owner_id, kind, duration_minutes
+)
+SELECT
+  s.id, s.tenant_id, s.category_id, s.name, s.description, s.price, s.cost, s.currency, s.image_url,
+  s.status, s.is_active, s.tags, s.metadata, s.custom_fields, s.created_by, s.created_at, s.updated_at,
+  s.unit_id, s.owner_id, 'service', s.duration_minutes
+FROM public.services s
+ON CONFLICT (id) DO NOTHING;
+
+-- ── 4b. the rows that were already there ────────────────────────────────
+-- ADD COLUMN IF NOT EXISTS matches a NAME, not a CONTRACT. A pool that already
+-- had a free-text `kind` keeps every value it ever wrote — salon carries 8 NULL,
+-- 4 'sale' and 1 'asset' — and the normaliser above only ever sees a WRITE, so
+-- those rows reach the CHECK untouched and it refuses the whole file.
+--
+-- The map is not restated here. A no-op UPDATE puts each stale row through the
+-- BEFORE trigger, so the legacy vocabulary is translated in exactly ONE place;
+-- a second copy would be the thing that drifts. Only rows that need it are
+-- touched, so a pool already speaking kind+subkind moves nothing.
+UPDATE public.products SET kind = kind
+ WHERE kind IS NULL OR kind NOT IN ('good', 'service');
+
+-- CHECKs after the fold (existing goods have service_kind NULL; folded services
+-- went through the normaliser and carry 'standard').
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conrelid = 'public.products'::regclass AND conname = 'products_kind_check') THEN
+    ALTER TABLE public.products ADD CONSTRAINT products_kind_check CHECK (kind IN ('good', 'service'));
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conrelid = 'public.products'::regclass AND conname = 'products_service_kind_check') THEN
+    ALTER TABLE public.products ADD CONSTRAINT products_service_kind_check
+      CHECK (service_kind IS NULL OR service_kind IN ('standard', 'evaluation', 'return'));
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conrelid = 'public.products'::regclass AND conname = 'products_service_kind_pairing_check') THEN
+    ALTER TABLE public.products ADD CONSTRAINT products_service_kind_pairing_check
+      CHECK ((kind = 'service') = (service_kind IS NOT NULL));
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conrelid = 'public.products'::regclass AND conname = 'products_duration_check') THEN
+    ALTER TABLE public.products ADD CONSTRAINT products_duration_check
+      CHECK (duration_minutes IS NULL OR duration_minutes >= 0);
+  END IF;
+END $$;
+
+-- FKs that pointed at services now point at products (rows carry the same id).
+DO $$
+DECLARE r record;
+BEGIN
+  FOR r IN
+    SELECT c.conname, c.conrelid::regclass AS tbl
+      FROM pg_constraint c
+     WHERE c.contype = 'f'
+       AND c.confrelid = 'public.services'::regclass
+       AND c.conrelid IN ('public.order_items'::regclass, 'public.appointment_items'::regclass)
+  LOOP
+    EXECUTE format('ALTER TABLE %s DROP CONSTRAINT %I', r.tbl, r.conname);
+  END LOOP;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conrelid = 'public.order_items'::regclass AND conname = 'order_items_service_id_fkey') THEN
+    ALTER TABLE public.order_items
+      ADD CONSTRAINT order_items_service_id_fkey FOREIGN KEY (service_id) REFERENCES public.products(id) ON DELETE SET NULL;
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conrelid = 'public.appointment_items'::regclass AND conname = 'appointment_items_service_id_fkey') THEN
+    ALTER TABLE public.appointment_items
+      ADD CONSTRAINT appointment_items_service_id_fkey FOREIGN KEY (service_id) REFERENCES public.products(id) ON DELETE SET NULL;
+  END IF;
+END $$;
+
+-- ── 5. COMPAT mirror: public.services ⇄ public.products (kind='service') ─
+-- The flag `fayz.catalog_sync` (transaction-local GUC) marks a write that the
+-- other side already reflects, so the two triggers never echo each other.
+-- Both are SECURITY DEFINER: the authz decision was taken by RLS on the table
+-- the caller wrote (both carry the same catalog policies); the projection is a
+-- mechanical consequence and must not be filtered by the caller's scope.
+
+-- products → services
+CREATE OR REPLACE FUNCTION app.trg_catalog_products_mirror()
+RETURNS trigger LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+BEGIN
+  IF coalesce(current_setting('fayz.catalog_sync', true), '') = 'on' THEN
+    RETURN NULL;
+  END IF;
+  PERFORM set_config('fayz.catalog_sync', 'on', true);
+  IF TG_OP = 'DELETE' OR (TG_OP = 'UPDATE' AND NEW.kind <> 'service') THEN
+    DELETE FROM public.services s WHERE s.id = OLD.id;
+  END IF;
+  IF TG_OP IN ('INSERT', 'UPDATE') AND NEW.kind = 'service' THEN
+    INSERT INTO public.services (
+      id, tenant_id, category_id, name, description, price, cost, currency, duration_minutes, image_url,
+      status, is_active, tags, metadata, custom_fields, created_by, created_at, updated_at, unit_id, owner_id
+    ) VALUES (
+      NEW.id, NEW.tenant_id, NEW.category_id, NEW.name, NEW.description, NEW.price, NEW.cost, NEW.currency, NEW.duration_minutes, NEW.image_url,
+      NEW.status, NEW.is_active, NEW.tags, NEW.metadata, NEW.custom_fields, NEW.created_by, NEW.created_at, NEW.updated_at, NEW.unit_id, NEW.owner_id
+    )
+    ON CONFLICT (id) DO UPDATE SET
+      tenant_id = EXCLUDED.tenant_id, category_id = EXCLUDED.category_id, name = EXCLUDED.name,
+      description = EXCLUDED.description, price = EXCLUDED.price, cost = EXCLUDED.cost, currency = EXCLUDED.currency,
+      duration_minutes = EXCLUDED.duration_minutes, image_url = EXCLUDED.image_url, status = EXCLUDED.status,
+      is_active = EXCLUDED.is_active, tags = EXCLUDED.tags, metadata = EXCLUDED.metadata, custom_fields = EXCLUDED.custom_fields,
+      created_by = EXCLUDED.created_by, created_at = EXCLUDED.created_at, updated_at = EXCLUDED.updated_at,
+      unit_id = EXCLUDED.unit_id, owner_id = EXCLUDED.owner_id;
+  END IF;
+  PERFORM set_config('fayz.catalog_sync', '', true);
+  RETURN NULL;
+END $$;
+DROP TRIGGER IF EXISTS products_catalog_mirror ON public.products;
+CREATE TRIGGER products_catalog_mirror
+  AFTER INSERT OR UPDATE OR DELETE ON public.products
+  FOR EACH ROW EXECUTE FUNCTION app.trg_catalog_products_mirror();
+
+-- services → products (old TS writing `.from('services')`). BEFORE row trigger:
+-- the write is forwarded to products, the flag tells the products trigger not
+-- to project it back, and the statement then lands on services itself so
+-- INSERT … RETURNING keeps working. Named zz_* so it fires after the created_by
+-- / updated_at triggers of the table (BEFORE triggers run in name order).
+CREATE OR REPLACE FUNCTION app.trg_catalog_services_forward()
+RETURNS trigger LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+BEGIN
+  IF coalesce(current_setting('fayz.catalog_sync', true), '') = 'on' THEN
+    RETURN CASE WHEN TG_OP = 'DELETE' THEN OLD ELSE NEW END;
+  END IF;
+  IF TG_OP = 'UPDATE' AND NEW.id IS DISTINCT FROM OLD.id THEN
+    RAISE EXCEPTION 'services: changing the id of a service is not supported (compat mirror)' USING ERRCODE = '0A000';
+  END IF;
+  PERFORM set_config('fayz.catalog_sync', 'on', true);
+  IF TG_OP = 'DELETE' THEN
+    DELETE FROM public.products p WHERE p.id = OLD.id;
+  ELSE
+    INSERT INTO public.products (
+      id, tenant_id, category_id, name, description, price, cost, currency, image_url,
+      status, is_active, tags, metadata, custom_fields, created_by, created_at, updated_at,
+      unit_id, owner_id, kind, duration_minutes
+    ) VALUES (
+      NEW.id, NEW.tenant_id, NEW.category_id, NEW.name, NEW.description, NEW.price, NEW.cost, NEW.currency, NEW.image_url,
+      NEW.status, NEW.is_active, NEW.tags, NEW.metadata, NEW.custom_fields, NEW.created_by, NEW.created_at, NEW.updated_at,
+      NEW.unit_id, NEW.owner_id, 'service', NEW.duration_minutes
+    )
+    ON CONFLICT (id) DO UPDATE SET
+      tenant_id = EXCLUDED.tenant_id, category_id = EXCLUDED.category_id, name = EXCLUDED.name,
+      description = EXCLUDED.description, price = EXCLUDED.price, cost = EXCLUDED.cost, currency = EXCLUDED.currency,
+      image_url = EXCLUDED.image_url, status = EXCLUDED.status, is_active = EXCLUDED.is_active, tags = EXCLUDED.tags,
+      metadata = EXCLUDED.metadata, custom_fields = EXCLUDED.custom_fields, created_by = EXCLUDED.created_by,
+      updated_at = EXCLUDED.updated_at, unit_id = EXCLUDED.unit_id, owner_id = EXCLUDED.owner_id,
+      kind = 'service', duration_minutes = EXCLUDED.duration_minutes;
+  END IF;
+  PERFORM set_config('fayz.catalog_sync', '', true);
+  RETURN CASE WHEN TG_OP = 'DELETE' THEN OLD ELSE NEW END;
+END $$;
+DROP TRIGGER IF EXISTS zz_services_catalog_forward ON public.services;
+CREATE TRIGGER zz_services_catalog_forward
+  BEFORE INSERT OR UPDATE OR DELETE ON public.services
+  FOR EACH ROW EXECUTE FUNCTION app.trg_catalog_services_forward();
+
+-- Reconcile the mirror from the source of truth: add missing projections,
+-- drop orphans (a service row whose product is gone or is no longer a
+-- service). Returns the diff; a non-zero diff outside a migration is a bug.
+CREATE OR REPLACE FUNCTION app.catalog_reconcile_services_mirror(OUT added integer, OUT removed integer)
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+BEGIN
+  PERFORM set_config('fayz.catalog_sync', 'on', true);
+  WITH del AS (
+    DELETE FROM public.services s
+     WHERE NOT EXISTS (SELECT 1 FROM public.products p WHERE p.id = s.id AND p.kind = 'service')
+    RETURNING 1
+  ) SELECT count(*) INTO removed FROM del;
+  WITH ins AS (
+    INSERT INTO public.services (
+      id, tenant_id, category_id, name, description, price, cost, currency, duration_minutes, image_url,
+      status, is_active, tags, metadata, custom_fields, created_by, created_at, updated_at, unit_id, owner_id
+    )
+    SELECT p.id, p.tenant_id, p.category_id, p.name, p.description, p.price, p.cost, p.currency, p.duration_minutes, p.image_url,
+           p.status, p.is_active, p.tags, p.metadata, p.custom_fields, p.created_by, p.created_at, p.updated_at, p.unit_id, p.owner_id
+      FROM public.products p
+     WHERE p.kind = 'service'
+       AND NOT EXISTS (SELECT 1 FROM public.services s WHERE s.id = p.id)
+    RETURNING 1
+  ) SELECT count(*) INTO added FROM ins;
+  PERFORM set_config('fayz.catalog_sync', '', true);
+END $$;
+REVOKE ALL ON FUNCTION app.catalog_reconcile_services_mirror() FROM public, anon, authenticated;
+GRANT EXECUTE ON FUNCTION app.catalog_reconcile_services_mirror() TO service_role;
+SELECT app.catalog_reconcile_services_mirror();
+
+COMMENT ON TABLE public.services IS
+  'DEPRECATED compat mirror of public.products WHERE kind = ''service'' (PRD 04 / #139). Reads and writes are forwarded by triggers; the source of truth is products. Phase 1: read-only; Phase 2: dropped. New code reads products.';
+
+-- ── 6. global search: goods and services are two sources over one table ─
+UPDATE public.fayz_search_sources
+   SET filter_expr = 'kind = ''good'''
+ WHERE entity_key = 'product' AND relation = 'public.products';
+UPDATE public.fayz_search_sources
+   SET relation = 'public.products', filter_expr = 'kind = ''service'''
+ WHERE entity_key = 'service';
+SELECT public.fayz_search_reindex();
+
+-- ── grants: unchanged for the three pre-existing tables (004 granted ALL to
+-- authenticated/service_role; RLS narrows). The compat mirror follows products.
+GRANT SELECT, INSERT, UPDATE, DELETE ON public.products, public.categories, public.services TO authenticated;
+GRANT ALL ON public.products, public.categories, public.services TO service_role;

package/migrations/086_catalog_pricing.sql

@@ -0,0 +1,194 @@
+-- ============================================================================
+-- 086_catalog_pricing.sql — the catalog contract, part 2 (PRD 04 R3 / #139):
+-- price tables with validity and scope (unit / channel), price table items,
+-- product variants (the "variations" facet), and catalog_price() — the one
+-- resolver every seller (POS, online, agenda) calls.
+--
+-- The base price stays on the item (products.price). A price table overrides
+-- it for a scope and a validity window; the resolver picks the most specific
+-- applicable table: unit-specific > channel-specific > default > base price.
+--
+-- All three tables are business tables of plugin 'catalog' (scaffold, enforce).
+-- price_table_items inherit (tenant_id, unit_id) from their table so RLS on the
+-- rows agrees with RLS on the table they belong to.
+-- ============================================================================
+
+-- ── price_tables ────────────────────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS public.price_tables (
+  id          uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id   uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
+  name        text NOT NULL,
+  description text,
+  -- scope: a unit (null = tenant-wide) and/or a sales channel (null = every
+  -- channel). Channel vocabulary: 'pos' | 'online' | 'app' — free text so a new
+  -- channel is a row, not a migration.
+  channel     text,
+  currency    text NOT NULL DEFAULT 'BRL',
+  valid_from  date,
+  valid_to    date,
+  is_default  boolean NOT NULL DEFAULT false,
+  priority    integer NOT NULL DEFAULT 0,
+  is_active   boolean NOT NULL DEFAULT true,
+  metadata    jsonb NOT NULL DEFAULT '{}'::jsonb,
+  created_by  uuid REFERENCES auth.users(id) ON DELETE SET NULL,
+  created_at  timestamptz NOT NULL DEFAULT now(),
+  updated_at  timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT price_tables_validity_check CHECK (valid_from IS NULL OR valid_to IS NULL OR valid_to >= valid_from)
+);
+-- A pool that already carries a V1-shaped `price_tables` skips the CREATE above
+-- (IF NOT EXISTS matches the NAME, not the shape), and the scope index below
+-- then asks for columns that were never added. Additive, so the existing rows
+-- and their prices are untouched — a cluster's own table converges instead of
+-- failing the apply.
+ALTER TABLE public.price_tables ADD COLUMN IF NOT EXISTS name        text;
+ALTER TABLE public.price_tables ADD COLUMN IF NOT EXISTS channel     text;
+ALTER TABLE public.price_tables ADD COLUMN IF NOT EXISTS currency    text NOT NULL DEFAULT 'BRL';
+ALTER TABLE public.price_tables ADD COLUMN IF NOT EXISTS valid_to    date;
+ALTER TABLE public.price_tables ADD COLUMN IF NOT EXISTS is_default  boolean NOT NULL DEFAULT false;
+ALTER TABLE public.price_tables ADD COLUMN IF NOT EXISTS priority    integer NOT NULL DEFAULT 0;
+ALTER TABLE public.price_tables ADD COLUMN IF NOT EXISTS metadata    jsonb NOT NULL DEFAULT '{}'::jsonb;
+ALTER TABLE public.price_tables ADD COLUMN IF NOT EXISTS created_by  uuid REFERENCES auth.users(id) ON DELETE SET NULL;
+-- `name` is NOT NULL on a fresh pool; on a converging one the V1 rows have no
+-- name yet, so it is backfilled from what that table did carry rather than
+-- rejecting rows the merchant already owns.
+UPDATE public.price_tables SET name = COALESCE(name, description, 'Tabela ' || left(id::text, 8))
+ WHERE name IS NULL;
+ALTER TABLE public.price_tables ALTER COLUMN name SET NOT NULL;
+
+SELECT app.scaffold_table('public.price_tables', 'catalog.price_table', 'catalog', false, 'enforce');
+CREATE INDEX IF NOT EXISTS price_tables_tenant_scope_idx
+  ON public.price_tables (tenant_id, unit_id, channel) WHERE is_active;
+DROP TRIGGER IF EXISTS price_tables_created_by ON public.price_tables;
+CREATE TRIGGER price_tables_created_by BEFORE INSERT ON public.price_tables
+  FOR EACH ROW EXECUTE FUNCTION public.handle_created_by();
+COMMENT ON TABLE public.price_tables IS
+  'Catalog price tables (PRD 04 R3): a set of item prices valid for a window and a scope (unit_id, channel). V1 price_tables. Resolved by public.catalog_price().';
+
+-- ── price_table_items ───────────────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS public.price_table_items (
+  id             uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id      uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
+  price_table_id uuid NOT NULL,
+  product_id     uuid NOT NULL,
+  price          numeric NOT NULL CHECK (price >= 0),
+  min_qty        numeric NOT NULL DEFAULT 1 CHECK (min_qty > 0),
+  metadata       jsonb NOT NULL DEFAULT '{}'::jsonb,
+  created_at     timestamptz NOT NULL DEFAULT now(),
+  updated_at     timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT price_table_items_table_fk   FOREIGN KEY (tenant_id, price_table_id) REFERENCES public.price_tables (tenant_id, id) ON DELETE CASCADE,
+  CONSTRAINT price_table_items_product_fk FOREIGN KEY (tenant_id, product_id)     REFERENCES public.products (tenant_id, id) ON DELETE CASCADE,
+  CONSTRAINT price_table_items_unique UNIQUE (price_table_id, product_id, min_qty)
+);
+SELECT app.scaffold_table('public.price_table_items', 'catalog.price_table_item', 'catalog', false, 'enforce');
+CREATE INDEX IF NOT EXISTS price_table_items_product_idx ON public.price_table_items (tenant_id, product_id);
+-- an item's price is not more visible than the item itself (release rule of 075)
+DROP POLICY IF EXISTS price_table_items_available_in ON public.price_table_items;
+CREATE POLICY price_table_items_available_in ON public.price_table_items AS RESTRICTIVE FOR SELECT TO authenticated
+  USING ((select app.available_in_my_units('catalog.product', product_id)));
+COMMENT ON TABLE public.price_table_items IS
+  'One price of one product in one price table (optional quantity tier via min_qty). V1 price_table_items. Inherits (tenant_id, unit_id) from the table.';
+
+-- Items live in the scope of their table: copy (tenant_id, unit_id) from the
+-- parent on every write so has_unit() answers the same for both.
+CREATE OR REPLACE FUNCTION app.trg_catalog_price_table_items_scope()
+RETURNS trigger LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE v_tenant uuid; v_unit uuid;
+BEGIN
+  SELECT t.tenant_id, t.unit_id INTO v_tenant, v_unit FROM public.price_tables t WHERE t.id = NEW.price_table_id;
+  IF v_tenant IS NULL THEN
+    RAISE EXCEPTION 'price_table_items: price table % does not exist', NEW.price_table_id USING ERRCODE = '23503';
+  END IF;
+  NEW.tenant_id := v_tenant;
+  NEW.unit_id := v_unit;
+  RETURN NEW;
+END $$;
+DROP TRIGGER IF EXISTS price_table_items_scope ON public.price_table_items;
+CREATE TRIGGER price_table_items_scope BEFORE INSERT OR UPDATE ON public.price_table_items
+  FOR EACH ROW EXECUTE FUNCTION app.trg_catalog_price_table_items_scope();
+-- …and when a table changes scope, its items follow.
+CREATE OR REPLACE FUNCTION app.trg_catalog_price_tables_rescope_items()
+RETURNS trigger LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+BEGIN
+  IF NEW.unit_id IS DISTINCT FROM OLD.unit_id THEN
+    UPDATE public.price_table_items i SET unit_id = NEW.unit_id WHERE i.price_table_id = NEW.id;
+  END IF;
+  RETURN NULL;
+END $$;
+DROP TRIGGER IF EXISTS price_tables_rescope_items ON public.price_tables;
+CREATE TRIGGER price_tables_rescope_items AFTER UPDATE OF unit_id ON public.price_tables
+  FOR EACH ROW EXECUTE FUNCTION app.trg_catalog_price_tables_rescope_items();
+
+-- ── product_variants (the "variations" facet) ───────────────────────────
+CREATE TABLE IF NOT EXISTS public.product_variants (
+  id          uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id   uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
+  product_id  uuid NOT NULL,
+  name        text NOT NULL,
+  sku         text,
+  -- either an absolute price or a delta on the resolved item price
+  price       numeric CHECK (price IS NULL OR price >= 0),
+  price_delta numeric NOT NULL DEFAULT 0,
+  attributes  jsonb NOT NULL DEFAULT '{}'::jsonb,   -- {"size":"M","color":"blue"}
+  sort_order  integer NOT NULL DEFAULT 0,
+  is_active   boolean NOT NULL DEFAULT true,
+  metadata    jsonb NOT NULL DEFAULT '{}'::jsonb,
+  created_at  timestamptz NOT NULL DEFAULT now(),
+  updated_at  timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT product_variants_product_fk FOREIGN KEY (tenant_id, product_id) REFERENCES public.products (tenant_id, id) ON DELETE CASCADE
+);
+SELECT app.scaffold_table('public.product_variants', 'catalog.product_variant', 'catalog', false, 'enforce');
+CREATE INDEX IF NOT EXISTS product_variants_product_idx ON public.product_variants (tenant_id, product_id);
+-- a variant is not more visible than its item (release rule of 075)
+DROP POLICY IF EXISTS product_variants_available_in ON public.product_variants;
+CREATE POLICY product_variants_available_in ON public.product_variants AS RESTRICTIVE FOR SELECT TO authenticated
+  USING ((select app.available_in_my_units('catalog.product', product_id)));
+CREATE UNIQUE INDEX IF NOT EXISTS product_variants_sku_uq ON public.product_variants (tenant_id, sku) WHERE sku IS NOT NULL;
+COMMENT ON TABLE public.product_variants IS
+  'Variations of a catalog item (size, colour, volume…): own sku, absolute price or delta on the resolved price. Catalog facet "variations" (PRD 04 R3).';
+
+-- ── catalog_price(product, unit, channel, at, qty) ──────────────────────
+-- The resolver. SECURITY INVOKER on purpose: the caller sees the price tables
+-- her RLS lets her see (a unit-scoped table is invisible outside its unit), so
+-- the answer is always one she is entitled to. Ranking: unit-specific >
+-- channel-specific > higher priority > the default table > highest quantity
+-- tier that applies > most recent validity; then the item's base price.
+CREATE OR REPLACE FUNCTION public.catalog_price(
+  p_product uuid,
+  p_unit    uuid    DEFAULT NULL,
+  p_channel text    DEFAULT NULL,
+  p_at      date    DEFAULT current_date,
+  p_qty     numeric DEFAULT 1
+)
+RETURNS numeric
+LANGUAGE sql STABLE SET search_path = ''
+AS $$
+  SELECT coalesce(
+    (SELECT i.price
+       FROM public.price_table_items i
+       JOIN public.price_tables t ON t.tenant_id = i.tenant_id AND t.id = i.price_table_id
+      WHERE i.product_id = p_product
+        AND t.is_active
+        AND (t.valid_from IS NULL OR t.valid_from <= p_at)
+        AND (t.valid_to   IS NULL OR t.valid_to   >= p_at)
+        AND (t.unit_id IS NULL OR t.unit_id = p_unit)
+        AND (t.channel IS NULL OR t.channel = p_channel)
+        AND i.min_qty <= coalesce(p_qty, 1)
+      ORDER BY (t.unit_id IS NOT NULL) DESC,
+               (t.channel IS NOT NULL) DESC,
+               t.priority DESC,
+               t.is_default DESC,
+               i.min_qty DESC,
+               t.valid_from DESC NULLS LAST,
+               t.created_at DESC
+      LIMIT 1),
+    (SELECT p.price FROM public.products p WHERE p.id = p_product)
+  );
+$$;
+REVOKE ALL ON FUNCTION public.catalog_price(uuid, uuid, text, date, numeric) FROM public, anon;
+GRANT EXECUTE ON FUNCTION public.catalog_price(uuid, uuid, text, date, numeric) TO authenticated, service_role;
+COMMENT ON FUNCTION public.catalog_price(uuid, uuid, text, date, numeric) IS
+  'Resolves the selling price of a catalog item for a unit, a channel, a date and a quantity: the most specific applicable price table (unit > channel > default), else products.price.';
+
+-- ── grants ──────────────────────────────────────────────────────────────
+GRANT SELECT, INSERT, UPDATE, DELETE ON public.price_tables, public.price_table_items, public.product_variants TO authenticated;
+GRANT ALL ON public.price_tables, public.price_table_items, public.product_variants TO service_role;