@fayz-ai/db 0.11.0 → 0.13.0

package/migrations/087_catalog_packages.sql

@@ -0,0 +1,134 @@
+-- ============================================================================
+-- 087_catalog_packages.sql — the catalog contract, part 3 (PRD 04 R4 / #139):
+-- the `packages` facet — service_packages + service_package_items. Contract
+-- only: tables, scaffold, invariants. No RPC, no purchase/consumption model
+-- (client_package_purchases is Phase 3's — RN-CAT-01 needs the package to be
+-- SOLD as a package, never exploded into items; that is the orders slice).
+-- ============================================================================
+
+-- ── 0. the V1 tables that got here first ────────────────────────────────
+-- beauty shipped packages before the catalog contract named the columns, so a
+-- salon pool already has both tables under the older vocabulary: an item points
+-- at `service_id` from when services were their own table, and counts sessions
+-- in `included_quantity`. CREATE TABLE IF NOT EXISTS sees the NAME and returns
+-- happy, and every statement below then asks for a column that never arrived.
+--
+-- 085 folded services into products keeping the SAME id, so `service_id`
+-- already holds a valid products id — this is a rename, not a conversion, and
+-- no row moves.
+--
+-- What is genuinely NEW (currency, sessions_total, metadata) is added, and what
+-- V1 had and the contract does not name (max_uses, unit_price) is LEFT WHERE IT
+-- IS. Dropping a column to make a table match a diagram is how a pool loses the
+-- one field a screen still reads.
+DO $$
+BEGIN
+  IF to_regclass('public.service_package_items') IS NOT NULL THEN
+    IF EXISTS (SELECT 1 FROM information_schema.columns
+                WHERE table_schema='public' AND table_name='service_package_items' AND column_name='service_id')
+       AND NOT EXISTS (SELECT 1 FROM information_schema.columns
+                WHERE table_schema='public' AND table_name='service_package_items' AND column_name='product_id') THEN
+      ALTER TABLE public.service_package_items RENAME COLUMN service_id TO product_id;
+    END IF;
+    IF EXISTS (SELECT 1 FROM information_schema.columns
+                WHERE table_schema='public' AND table_name='service_package_items' AND column_name='included_quantity')
+       AND NOT EXISTS (SELECT 1 FROM information_schema.columns
+                WHERE table_schema='public' AND table_name='service_package_items' AND column_name='quantity') THEN
+      ALTER TABLE public.service_package_items RENAME COLUMN included_quantity TO quantity;
+      -- a session count was integer; the contract measures quantity, which can
+      -- be fractional for a service sold by the half-hour.
+      ALTER TABLE public.service_package_items ALTER COLUMN quantity TYPE numeric;
+    END IF;
+    ALTER TABLE public.service_package_items ADD COLUMN IF NOT EXISTS metadata jsonb NOT NULL DEFAULT '{}'::jsonb;
+  END IF;
+
+  IF to_regclass('public.service_packages') IS NOT NULL THEN
+    ALTER TABLE public.service_packages ADD COLUMN IF NOT EXISTS currency text NOT NULL DEFAULT 'BRL';
+    ALTER TABLE public.service_packages ADD COLUMN IF NOT EXISTS sessions_total integer;
+    ALTER TABLE public.service_packages ADD COLUMN IF NOT EXISTS created_by uuid REFERENCES auth.users(id) ON DELETE SET NULL;
+    -- max_uses is the same count under the older name. It is COPIED, not
+    -- renamed: something may still read it, and a copy costs a column while a
+    -- rename costs a screen.
+    IF EXISTS (SELECT 1 FROM information_schema.columns
+                WHERE table_schema='public' AND table_name='service_packages' AND column_name='max_uses') THEN
+      UPDATE public.service_packages SET sessions_total = max_uses
+       WHERE sessions_total IS NULL AND max_uses IS NOT NULL;
+      COMMENT ON COLUMN public.service_packages.max_uses IS
+        'DEPRECATED (087): the contract counts sessions_total. Kept as a mirror until the readers move.';
+    END IF;
+  END IF;
+END $$;
+
+CREATE TABLE IF NOT EXISTS public.service_packages (
+  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,
+  price          numeric NOT NULL DEFAULT 0 CHECK (price >= 0),
+  currency       text NOT NULL DEFAULT 'BRL',
+  sessions_total integer CHECK (sessions_total IS NULL OR sessions_total > 0),
+  validity_days  integer CHECK (validity_days IS NULL OR validity_days > 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()
+);
+SELECT app.scaffold_table('public.service_packages', 'catalog.service_package', 'catalog', false, 'enforce');
+DROP TRIGGER IF EXISTS service_packages_created_by ON public.service_packages;
+CREATE TRIGGER service_packages_created_by BEFORE INSERT ON public.service_packages
+  FOR EACH ROW EXECUTE FUNCTION public.handle_created_by();
+COMMENT ON TABLE public.service_packages IS
+  'Catalog facet "packages" (PRD 04 R4, RN-CAT-01): a combo of services sold as one item — price, total sessions, validity. V1 service_packages (+ package_settings/package_unit_shares as metadata / available_in grants). Contract only in Phase 0.';
+
+-- A tenant-wide package is released per unit like any catalog item.
+DROP POLICY IF EXISTS service_packages_available_in ON public.service_packages;
+CREATE POLICY service_packages_available_in ON public.service_packages AS RESTRICTIVE FOR SELECT TO authenticated
+  USING (unit_id IS NOT NULL OR (select app.available_in_my_units('catalog.service_package', id)));
+
+CREATE TABLE IF NOT EXISTS public.service_package_items (
+  id         uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id  uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
+  package_id uuid NOT NULL,
+  product_id uuid NOT NULL,                       -- a products row with kind = 'service'
+  quantity   numeric NOT NULL DEFAULT 1 CHECK (quantity > 0),
+  sort_order integer NOT NULL DEFAULT 0,
+  metadata   jsonb NOT NULL DEFAULT '{}'::jsonb,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT service_package_items_package_fk FOREIGN KEY (tenant_id, package_id) REFERENCES public.service_packages (tenant_id, id) ON DELETE CASCADE,
+  CONSTRAINT service_package_items_product_fk FOREIGN KEY (tenant_id, product_id) REFERENCES public.products (tenant_id, id) ON DELETE CASCADE,
+  CONSTRAINT service_package_items_unique UNIQUE (package_id, product_id)
+);
+SELECT app.scaffold_table('public.service_package_items', 'catalog.service_package_item', 'catalog', false, 'enforce');
+CREATE INDEX IF NOT EXISTS service_package_items_product_idx ON public.service_package_items (tenant_id, product_id);
+-- an item of a package is not more visible than the package
+DROP POLICY IF EXISTS service_package_items_available_in ON public.service_package_items;
+CREATE POLICY service_package_items_available_in ON public.service_package_items AS RESTRICTIVE FOR SELECT TO authenticated
+  USING ((select app.available_in_my_units('catalog.service_package', package_id)));
+COMMENT ON TABLE public.service_package_items IS
+  'Services (products kind=service) inside a package with their quantity of sessions. V1 service_package_items. Inherits (tenant_id, unit_id) from the package.';
+
+-- Invariants: the item is a service; the item lives in the package's scope.
+CREATE OR REPLACE FUNCTION app.trg_catalog_service_package_items_guard()
+RETURNS trigger LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE v_kind text; v_tenant uuid; v_unit uuid;
+BEGIN
+  SELECT p.kind INTO v_kind FROM public.products p WHERE p.id = NEW.product_id;
+  IF v_kind IS DISTINCT FROM 'service' THEN
+    RAISE EXCEPTION 'service_package_items: product % is not a service', NEW.product_id USING ERRCODE = '23514';
+  END IF;
+  SELECT s.tenant_id, s.unit_id INTO v_tenant, v_unit FROM public.service_packages s WHERE s.id = NEW.package_id;
+  IF v_tenant IS NULL THEN
+    RAISE EXCEPTION 'service_package_items: package % does not exist', NEW.package_id USING ERRCODE = '23503';
+  END IF;
+  NEW.tenant_id := v_tenant;
+  NEW.unit_id := v_unit;
+  RETURN NEW;
+END $$;
+DROP TRIGGER IF EXISTS service_package_items_guard ON public.service_package_items;
+CREATE TRIGGER service_package_items_guard BEFORE INSERT OR UPDATE ON public.service_package_items
+  FOR EACH ROW EXECUTE FUNCTION app.trg_catalog_service_package_items_guard();
+
+GRANT SELECT, INSERT, UPDATE, DELETE ON public.service_packages, public.service_package_items TO authenticated;
+GRANT ALL ON public.service_packages, public.service_package_items TO service_role;

package/migrations/090_orders_venda.sql

@@ -0,0 +1,166 @@
+-- ============================================================================
+-- 090_orders_venda.sql — orders is the Venda, and only the Venda (#140).
+--
+-- ADR 0004 (amended): the sale (atendimento, comanda, quote, shop order) lives
+-- in the core `orders`; money lives in the financial plugin as an invoice
+-- (plg_financial_invoices). `orders.kind` may therefore no longer be
+-- 'invoice_receivable' / 'invoice_payable' — those rows are data-migrated into
+-- invoices by plugin-financial 016 and the kinds are rejected here from now on.
+--
+-- Sale kinds are open: a plugin registers its kind as a ROW in
+-- public.order_kinds (never DDL), optionally with the statuses it uses and the
+-- transitions it allows. A registered kind with `transitions` gets its state
+-- machine enforced by a BEFORE trigger; a kind registered without transitions
+-- (agenda's appointment, the CRM's quote/deal, the shop's order) keeps its
+-- lifecycle in the plugin until that plugin's own slice tightens it — nothing
+-- that writes orders today changes behaviour. The default machine, applied when
+-- a kind is registered with no explicit statuses/transitions, is
+-- draft → confirmed → completed | cancelled.
+--
+-- Extension naming (documented in docs/data/phase-0/05-orders-invoices-ledger.md):
+-- an app or plugin that extends a core table names the extension
+-- plg_<plugin>_order_ext / plg_<plugin>_order_item_ext — never the core name.
+-- The readiness gate (scripts/migration-readiness.mjs, check `collision`)
+-- enforces it.
+--
+-- Idempotent and replay-safe.
+-- ============================================================================
+
+-- ── the kind registry ────────────────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS public.order_kinds (
+  kind        text PRIMARY KEY,
+  plugin      text NOT NULL,
+  description text,
+  statuses    text[],          -- NULL = any status accepted
+  transitions jsonb,           -- NULL = free; else {"from": ["to", …]} — "*" wildcards allowed
+  created_at  timestamptz NOT NULL DEFAULT now(),
+  updated_at  timestamptz NOT NULL DEFAULT now(),
+  CHECK (kind ~ '^[a-z][a-z0-9_]*$'),
+  CHECK (kind NOT IN ('invoice_receivable', 'invoice_payable'))
+);
+DROP TRIGGER IF EXISTS order_kinds_updated_at ON public.order_kinds;
+CREATE TRIGGER order_kinds_updated_at BEFORE UPDATE ON public.order_kinds
+  FOR EACH ROW EXECUTE FUNCTION public.handle_updated_at();
+
+ALTER TABLE public.order_kinds ENABLE ROW LEVEL SECURITY;
+-- The registry is global configuration, harmless to read: every session may
+-- list it (the UI renders the machine); only the platform writes it.
+GRANT SELECT ON public.order_kinds TO anon, authenticated, service_role;
+GRANT ALL ON public.order_kinds TO service_role;
+REVOKE INSERT, UPDATE, DELETE ON public.order_kinds FROM anon, authenticated;
+DROP POLICY IF EXISTS order_kinds_select ON public.order_kinds;
+CREATE POLICY order_kinds_select ON public.order_kinds FOR SELECT TO anon, authenticated, service_role USING (true);
+
+-- ── register_order_kind: a plugin declares (or refines) its sale kind ─────
+-- Idempotent upsert. With p_statuses/p_transitions NULL on first registration
+-- the kind gets the default machine; passing explicit values (re)defines it;
+-- passing '{}'::jsonb… is a machine with no allowed transition (rarely useful),
+-- while NULL transitions on an EXISTING row is left untouched (a re-register
+-- with defaults never loosens what a plugin tightened).
+CREATE OR REPLACE FUNCTION public.register_order_kind(
+  p_kind text,
+  p_plugin text,
+  p_statuses text[] DEFAULT NULL,
+  p_transitions jsonb DEFAULT NULL,
+  p_description text DEFAULT NULL
+) RETURNS void
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  v_statuses text[] := p_statuses;
+  v_transitions jsonb := p_transitions;
+BEGIN
+  IF p_kind IN ('invoice_receivable', 'invoice_payable') THEN
+    RAISE EXCEPTION 'register_order_kind: % is not a sale kind — a receivable/payable is a plg_financial_invoices row', p_kind
+      USING ERRCODE = '23514';
+  END IF;
+  IF p_statuses IS NULL AND p_transitions IS NULL THEN
+    v_statuses := ARRAY['draft', 'confirmed', 'completed', 'cancelled'];
+    v_transitions := '{"draft": ["confirmed", "cancelled"], "confirmed": ["completed", "cancelled"]}'::jsonb;
+  END IF;
+  INSERT INTO public.order_kinds (kind, plugin, description, statuses, transitions)
+  VALUES (p_kind, p_plugin, p_description, v_statuses, v_transitions)
+  ON CONFLICT (kind) DO UPDATE
+    SET plugin = EXCLUDED.plugin,
+        description = coalesce(EXCLUDED.description, public.order_kinds.description),
+        statuses = CASE WHEN p_statuses IS NULL AND p_transitions IS NULL THEN public.order_kinds.statuses ELSE EXCLUDED.statuses END,
+        transitions = CASE WHEN p_statuses IS NULL AND p_transitions IS NULL THEN public.order_kinds.transitions ELSE EXCLUDED.transitions END;
+END $$;
+REVOKE ALL ON FUNCTION public.register_order_kind(text, text, text[], jsonb, text) FROM public, anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.register_order_kind(text, text, text[], jsonb, text) TO service_role;
+
+-- ── the platform's own kinds ─────────────────────────────────────────────
+-- 'sale' and 'dine_in' are the core Venda kinds and carry the default machine.
+-- The kinds plugins already write today are registered with the statuses they
+-- use and NO transition enforcement (their slices own their lifecycles) so this
+-- migration changes nothing they do; the CRM's quote/deal flows are already
+-- constrained by its own kind→status CHECK.
+SELECT public.register_order_kind('sale', 'orders', NULL, NULL, 'A sale (atendimento, comanda fechada, venda avulsa): the core Venda');
+SELECT public.register_order_kind('dine_in', 'orders', NULL, NULL, 'A table order (comanda de mesa) — restaurant vertical');
+SELECT public.register_order_kind('appointment', 'agenda',
+  ARRAY['scheduled', 'confirmed', 'in_progress', 'completed', 'cancelled', 'no_show', 'invoiced', 'paid'], NULL,
+  'An appointment''s commercial document (agenda); lifecycle owned by plugin-agenda');
+SELECT public.register_order_kind('service_order', 'agenda',
+  ARRAY['draft', 'scheduled', 'confirmed', 'in_progress', 'completed', 'cancelled', 'invoiced', 'paid'], NULL,
+  'A service order (agenda); lifecycle owned by plugin-agenda');
+SELECT public.register_order_kind('quote', 'crm',
+  ARRAY['draft', 'sent', 'approved', 'rejected', 'expired', 'converted', 'archived'], NULL,
+  'A quote (CRM); lifecycle owned by plugin-crm');
+SELECT public.register_order_kind('deal', 'crm',
+  ARRAY['open', 'won', 'lost', 'archived'], NULL,
+  'A deal (CRM); lifecycle owned by plugin-crm');
+SELECT public.register_order_kind('shop', 'shop', NULL, '{"*": ["*"]}'::jsonb,
+  'A storefront order mirrored into the core (@fayz-ai/shop); status is the shop order status');
+-- Legacy payable "invoices" (orders kind=invoice_payable, migrated into payable
+-- invoices by plugin-financial 016) keep their document — items, cost centre and
+-- chart-of-accounts classification — as kind 'purchase'. New payables have no
+-- order at all: an invoice can exist without a Venda.
+SELECT public.register_order_kind('purchase', 'financial', NULL, '{"*": ["*"]}'::jsonb,
+  'A purchase/expense document behind a legacy payable invoice; new payables carry no order');
+
+-- ── the guard: no invoice kinds; per-kind lifecycle ──────────────────────
+CREATE OR REPLACE FUNCTION public.trg_orders_kind_guard()
+RETURNS trigger LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  v_kind public.order_kinds%ROWTYPE;
+  v_allowed jsonb;
+BEGIN
+  IF NEW.kind IN ('invoice_receivable', 'invoice_payable') THEN
+    RAISE EXCEPTION 'orders.kind % is retired: a receivable/payable is an invoice (public.financial_create_invoice / plg_financial_invoices), not an order', NEW.kind
+      USING ERRCODE = '23514', HINT = 'ADR 0004: orders is the Venda; money lives in the financial plugin.';
+  END IF;
+
+  SELECT * INTO v_kind FROM public.order_kinds k WHERE k.kind = NEW.kind;
+  IF NOT FOUND THEN
+    RETURN NEW; -- unregistered kind: no machine (register it to opt in)
+  END IF;
+
+  IF v_kind.statuses IS NOT NULL AND NEW.status IS NOT NULL AND NOT (NEW.status = ANY (v_kind.statuses)) THEN
+    RAISE EXCEPTION 'orders: status % is not valid for kind % (allowed: %)', NEW.status, NEW.kind, array_to_string(v_kind.statuses, ', ')
+      USING ERRCODE = '23514';
+  END IF;
+
+  -- Transitions are checked between two states of the SAME machine: a row that
+  -- changes kind, or whose previous status predates the machine (a migrated
+  -- legacy row), is entering it, not moving inside it.
+  IF TG_OP = 'UPDATE' AND v_kind.transitions IS NOT NULL
+     AND OLD.kind = NEW.kind
+     AND OLD.status IS DISTINCT FROM NEW.status AND OLD.status IS NOT NULL
+     AND (v_kind.statuses IS NULL OR OLD.status = ANY (v_kind.statuses)) THEN
+    v_allowed := coalesce(v_kind.transitions -> OLD.status, v_kind.transitions -> '*', '[]'::jsonb);
+    IF NOT (v_allowed ? coalesce(NEW.status, '') OR v_allowed ? '*') THEN
+      RAISE EXCEPTION 'orders: kind % cannot go from % to %', NEW.kind, OLD.status, coalesce(NEW.status, '<null>')
+        USING ERRCODE = '23514', HINT = 'The allowed transitions of a kind are the row of public.order_kinds.';
+    END IF;
+  END IF;
+
+  IF NEW.status = 'completed' AND (TG_OP = 'INSERT' OR OLD.status IS DISTINCT FROM 'completed') THEN
+    NEW.completed_at := coalesce(NEW.completed_at, now());
+  END IF;
+  RETURN NEW;
+END $$;
+REVOKE ALL ON FUNCTION public.trg_orders_kind_guard() FROM public, anon, authenticated;
+
+DROP TRIGGER IF EXISTS orders_kind_guard ON public.orders;
+CREATE TRIGGER orders_kind_guard BEFORE INSERT OR UPDATE OF kind, status ON public.orders
+  FOR EACH ROW EXECUTE FUNCTION public.trg_orders_kind_guard();

package/migrations/091_orders_scaffold.sql

@@ -0,0 +1,92 @@
+-- ============================================================================
+-- 091_orders_scaffold.sql — the Venda and its lines on the authz template (#140).
+--
+-- public.orders and public.order_items get the ONE RLS template of the authz
+-- core (app.scaffold_table, enforce mode): tenant_id / unit_id / owner_id,
+-- unique(tenant_id, id), composite FKs to app.units / app.memberships,
+-- tenant-first indexes, forced RLS and the four `<table>_authz_*` policies
+-- keyed on orders.read/create/edit/delete. owner_id stays NULL: the sale is a
+-- unit-scoped document, not a personal one (owner scoping off in both vertical
+-- templates).
+--
+-- order_items, until now a child table without tenant_id (RLS through the
+-- parent's FK), becomes a first-class business table: tenant_id backfilled from
+-- the order and kept in step by a BEFORE trigger (legacy writers insert lines
+-- with order_id only), unit_id inherited the same way, composite FK
+-- (tenant_id, order_id) → orders(tenant_id, id), and the promoted column
+-- execution_status (ADR 0009: what participates in a state machine or a money
+-- invariant is a column, not JSONB — the clinic's is_executed/execution_* lands
+-- here, everything else stays in metadata).
+--
+-- Idempotent and replay-safe: scaffold_table converges (a replay of 002/004/006
+-- re-creates the generic policies; this file's enforce pass drops them again).
+-- ============================================================================
+
+-- ── orders ───────────────────────────────────────────────────────────────
+SELECT app.scaffold_table('public.orders', 'orders.order', 'orders', false, 'enforce');
+
+-- ── order_items: structural columns first, then the scaffold ─────────────
+ALTER TABLE public.order_items ADD COLUMN IF NOT EXISTS tenant_id uuid;
+ALTER TABLE public.order_items ADD COLUMN IF NOT EXISTS unit_id uuid;
+ALTER TABLE public.order_items ADD COLUMN IF NOT EXISTS execution_status text;
+ALTER TABLE public.order_items ADD COLUMN IF NOT EXISTS updated_at timestamptz NOT NULL DEFAULT now();
+
+UPDATE public.order_items oi
+   SET tenant_id = o.tenant_id
+  FROM public.orders o
+ WHERE o.id = oi.order_id AND oi.tenant_id IS NULL;
+UPDATE public.order_items oi
+   SET unit_id = o.unit_id
+  FROM public.orders o
+ WHERE o.id = oi.order_id AND oi.unit_id IS NULL AND o.unit_id IS NOT NULL;
+
+DO $$
+BEGIN
+  -- Only after the backfill: an orphan line (order gone) would block NOT NULL.
+  IF NOT EXISTS (SELECT 1 FROM public.order_items WHERE tenant_id IS NULL) THEN
+    ALTER TABLE public.order_items ALTER COLUMN tenant_id SET NOT NULL;
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conrelid = 'public.order_items'::regclass AND conname = 'order_items_tenant_id_fkey') THEN
+    ALTER TABLE public.order_items ADD CONSTRAINT order_items_tenant_id_fkey
+      FOREIGN KEY (tenant_id) REFERENCES public.tenants(id) ON DELETE CASCADE;
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conrelid = 'public.order_items'::regclass AND conname = 'order_items_tenant_order_fk') THEN
+    ALTER TABLE public.order_items ADD CONSTRAINT order_items_tenant_order_fk
+      FOREIGN KEY (tenant_id, order_id) REFERENCES public.orders(tenant_id, id) ON DELETE CASCADE;
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conrelid = 'public.order_items'::regclass AND conname = 'order_items_execution_status_check') THEN
+    ALTER TABLE public.order_items ADD CONSTRAINT order_items_execution_status_check
+      CHECK (execution_status IS NULL OR execution_status IN ('pending', 'in_progress', 'executed', 'cancelled'));
+  END IF;
+END $$;
+CREATE INDEX IF NOT EXISTS order_items_tenant_order_idx ON public.order_items (tenant_id, order_id);
+
+-- A line inherits tenant and unit from its order (legacy writers send order_id
+-- only); a line can never claim another tenant than its order.
+CREATE OR REPLACE FUNCTION public.trg_order_items_inherit()
+RETURNS trigger LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE v_tenant uuid; v_unit uuid;
+BEGIN
+  SELECT o.tenant_id, o.unit_id INTO v_tenant, v_unit FROM public.orders o WHERE o.id = NEW.order_id;
+  IF v_tenant IS NULL THEN
+    RAISE EXCEPTION 'order_items: order % not found', NEW.order_id USING ERRCODE = '23503';
+  END IF;
+  IF NEW.tenant_id IS NOT NULL AND NEW.tenant_id <> v_tenant THEN
+    RAISE EXCEPTION 'order_items: tenant_id must be the order''s tenant' USING ERRCODE = '23514';
+  END IF;
+  NEW.tenant_id := v_tenant;
+  IF NEW.unit_id IS NULL THEN NEW.unit_id := v_unit; END IF;
+  RETURN NEW;
+END $$;
+REVOKE ALL ON FUNCTION public.trg_order_items_inherit() FROM public, anon, authenticated;
+DROP TRIGGER IF EXISTS order_items_inherit ON public.order_items;
+CREATE TRIGGER order_items_inherit BEFORE INSERT OR UPDATE OF order_id, tenant_id ON public.order_items
+  FOR EACH ROW EXECUTE FUNCTION public.trg_order_items_inherit();
+
+SELECT app.scaffold_table('public.order_items', 'orders.order_item', 'orders', false, 'enforce');
+
+-- Grants: 004 already granted ALL on every public table to authenticated and
+-- service_role; restated for the two tables so a pool that pruned grants
+-- converges (RLS narrows).
+GRANT SELECT, INSERT, UPDATE, DELETE ON public.orders, public.order_items TO authenticated;
+GRANT ALL ON public.orders, public.order_items TO service_role;

package/migrations/095_config_field_rules.sql

@@ -0,0 +1,261 @@
+-- ============================================================================
+-- 095_config_field_rules.sql — FieldRules with three states (PRD 07 R1 / #144).
+--
+-- RN-CLI-02: for each context (pre-registration, scheduling, check-in, internal
+-- form, …) every field of an entity is hidden · visible · required. The rule
+-- lives per tenant AND per unit: a row with unit_id NULL is the tenant default
+-- (the network's decision — the franchisor "replicates the configuration to
+-- every unit" by writing it once here); a row with a unit_id is that unit's
+-- override. A rule may also be per role (role_key): a field hidden for the
+-- reception never reaches her payload, whatever the client sends.
+--
+-- The validation is a server-side contract any plugin's RPC reuses:
+--   field_rules_resolve(context, reference, unit)   → (field_key, state) as the caller sees it
+--   field_rules_validate(context, reference, payload, unit) → {ok, missing, hidden, payload}
+--   field_rules_check(context, reference, payload, unit)    → the stripped payload, or RAISE
+-- RN-AGD-07: the check-in RPC calls field_rules_check('check_in', 'person', …)
+-- and a missing required field stops it with a message in pt-BR (the one place
+-- the PRD literally requires the product copy to come from the database).
+--
+-- Vocabulary is the field registry's (035 plg_entity_fields.reference/key), so
+-- a rule names a declared field and the check reads its label from there.
+-- Contexts are rows in field_rule_contexts — a plugin adds one with an INSERT.
+--
+-- Idempotent and replay-safe.
+-- ============================================================================
+
+-- ── permission keys of the plugin 'config' + role templates ─────────────
+-- read/create/edit/delete/manage: the five actions app.scaffold_table's policy
+-- template expects; manage implies every action.
+SELECT app.seed_permissions('[
+  {"key":"config.read","plugin":"config","description":"Read tenant/unit configuration (field rules, holidays, access grants)"},
+  {"key":"config.create","plugin":"config","description":"Create configuration rows"},
+  {"key":"config.edit","plugin":"config","description":"Edit configuration rows"},
+  {"key":"config.delete","plugin":"config","description":"Delete configuration rows"},
+  {"key":"config.manage","plugin":"config","description":"Manage tenant/unit configuration (field rules, holidays, access grants)"}
+]'::jsonb);
+
+-- Managers configure; everyone else reads (the calendar and the form rules are
+-- what every role renders from). Rows land in the templates; existing tenants
+-- whose template is known (tenants.settings->>'template') pick them up below,
+-- the synthetic tenants are re-seeded by seed/080_config.sql, and the owner
+-- role gets every new key by the 043 trigger.
+SELECT app.seed_role_template_rows('generic', 'admin', 'Administrator', 1, ARRAY['config.manage']);
+SELECT app.seed_role_template_rows('generic', 'manager', 'Manager', 2, ARRAY['config.manage']);
+SELECT app.seed_role_template_rows('generic', 'staff', 'Staff', 3, ARRAY['config.read']);
+SELECT app.seed_role_template_rows('generic', 'viewer', 'Viewer', 4, ARRAY['config.read']);
+SELECT app.seed_role_template_rows('salon', 'manager', 'Gerente', 1, ARRAY['config.manage']);
+SELECT app.seed_role_template_rows('salon', 'reception', 'Recepção', 2, ARRAY['config.read']);
+SELECT app.seed_role_template_rows('salon', 'professional', 'Profissional', 3, ARRAY['config.read']);
+SELECT app.seed_role_template_rows('salon', 'financial', 'Financeiro', 4, ARRAY['config.read']);
+SELECT app.seed_role_template_rows('clinic', 'manager', 'Coordenação', 1, ARRAY['config.manage']);
+SELECT app.seed_role_template_rows('clinic', 'reception', 'Recepção', 2, ARRAY['config.read']);
+SELECT app.seed_role_template_rows('clinic', 'professional', 'Profissional', 3, ARRAY['config.read']);
+SELECT app.seed_role_template_rows('clinic', 'financial', 'Financeiro', 4, ARRAY['config.read']);
+SELECT app.seed_role_template_rows('restaurant', 'manager', 'Gerente', 1, ARRAY['config.manage']);
+SELECT app.seed_role_template_rows('restaurant', 'cashier', 'Caixa', 2, ARRAY['config.read']);
+SELECT app.seed_role_template_rows('restaurant', 'waiter', 'Garçom', 3, ARRAY['config.read']);
+SELECT app.seed_role_template_rows('restaurant', 'kitchen', 'Cozinha', 4, ARRAY['config.read']);
+
+-- Tenants already instantiated from a template: add the new keys to their system
+-- roles (never removes anything — same contract as app.seed_role_template).
+DO $$
+DECLARE r record;
+BEGIN
+  FOR r IN SELECT t.id, t.settings->>'template' AS template FROM public.tenants t
+            WHERE t.settings ? 'template'
+              AND EXISTS (SELECT 1 FROM app.role_templates rt WHERE rt.template = t.settings->>'template') LOOP
+    PERFORM app.seed_role_template(r.id, r.template);
+  END LOOP;
+END $$;
+
+-- ── contexts: an open list ──────────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS public.field_rule_contexts (
+  key         text PRIMARY KEY CHECK (key ~ '^[a-z][a-z0-9_]*$'),
+  plugin      text NOT NULL,
+  description text,
+  created_at  timestamptz NOT NULL DEFAULT now()
+);
+INSERT INTO public.field_rule_contexts (key, plugin, description) VALUES
+  ('pre_registration', 'people', 'Public pre-registration form (QR at the unit)'),
+  ('scheduling',       'agenda', 'Booking / scheduling form'),
+  ('check_in',         'agenda', 'Check-in: the client arrives (status Aguardando)'),
+  ('internal_form',    'people', 'Internal record form filled by staff'),
+  ('person',           'people', 'The person record itself'),
+  ('order',            'orders', 'Order / sale form')
+ON CONFLICT (key) DO NOTHING;
+
+REVOKE ALL ON public.field_rule_contexts FROM anon, authenticated;
+ALTER TABLE public.field_rule_contexts ENABLE ROW LEVEL SECURITY;
+GRANT SELECT ON public.field_rule_contexts TO authenticated;
+GRANT ALL ON public.field_rule_contexts TO service_role;
+DROP POLICY IF EXISTS field_rule_contexts_select ON public.field_rule_contexts;
+CREATE POLICY field_rule_contexts_select ON public.field_rule_contexts FOR SELECT TO authenticated USING (true);
+
+-- ── the rules ───────────────────────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS public.field_rules (
+  id          uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id   uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
+  unit_id     uuid,                                   -- NULL = tenant default (network), else the unit's override
+  context     text NOT NULL REFERENCES public.field_rule_contexts(key) ON DELETE RESTRICT,
+  reference   text NOT NULL CHECK (reference ~ '^[a-z][a-z0-9_]*$'),   -- 035 plg_entity_fields.reference
+  field_key   text NOT NULL CHECK (field_key ~ '^[a-z][a-zA-Z0-9_]*$'), -- 035 plg_entity_fields.key
+  state       text NOT NULL CHECK (state IN ('hidden', 'visible', 'required')),
+  role_key    text,                                   -- NULL = every role; else app.roles.key of this tenant
+  sort_order  integer NOT NULL DEFAULT 0,
+  updated_by  uuid,
+  created_at  timestamptz NOT NULL DEFAULT now(),
+  updated_at  timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT field_rules_unit_fk FOREIGN KEY (tenant_id, unit_id) REFERENCES app.units(tenant_id, id) ON DELETE CASCADE,
+  CONSTRAINT field_rules_role_fk FOREIGN KEY (tenant_id, role_key) REFERENCES app.roles(tenant_id, key) ON DELETE CASCADE
+);
+-- One rule per (tenant, unit-or-default, context, reference, field, role-or-any).
+CREATE UNIQUE INDEX IF NOT EXISTS field_rules_one_per_scope
+  ON public.field_rules (tenant_id, coalesce(unit_id, '00000000-0000-0000-0000-000000000000'::uuid), context, reference, field_key, coalesce(role_key, ''));
+CREATE INDEX IF NOT EXISTS field_rules_lookup
+  ON public.field_rules (tenant_id, context, reference);
+
+-- The one RLS template (043): tenant + unit scope, config.* actions, no owner scoping.
+SELECT app.scaffold_table('public.field_rules', 'config.field_rule', 'config', false, 'enforce');
+REVOKE ALL ON public.field_rules FROM anon;
+GRANT SELECT, INSERT, UPDATE, DELETE ON public.field_rules TO authenticated;
+GRANT ALL ON public.field_rules TO service_role;
+
+-- updated_by is the actor, derived — never trusted from the row.
+CREATE OR REPLACE FUNCTION public.field_rules_stamp_actor()
+RETURNS trigger LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+BEGIN
+  NEW.updated_by := coalesce(auth.uid(), NEW.updated_by);
+  RETURN NEW;
+END $$;
+REVOKE ALL ON FUNCTION public.field_rules_stamp_actor() FROM public, anon, authenticated;
+DROP TRIGGER IF EXISTS field_rules_actor ON public.field_rules;
+CREATE TRIGGER field_rules_actor BEFORE INSERT OR UPDATE ON public.field_rules
+  FOR EACH ROW EXECUTE FUNCTION public.field_rules_stamp_actor();
+
+-- ── resolve: what the caller sees for (context, reference) in a unit ────
+-- Precedence: unit+role > unit > tenant+role > tenant. Role = the caller's
+-- effective role in that unit (§8). A tenant default is "the network default":
+-- with no available_in grant it applies everywhere; once released to specific
+-- units (resource_grants 'available_in' on config.field_rule) it applies only
+-- there. Fields with no rule are not returned — the caller treats them as visible.
+CREATE OR REPLACE FUNCTION public.field_rules_resolve(p_context text, p_reference text, p_unit uuid DEFAULT NULL)
+RETURNS TABLE (field_key text, state text, source text, sort_order integer)
+LANGUAGE sql STABLE SECURITY DEFINER SET search_path = ''
+AS $$
+  WITH me AS (
+    SELECT app.current_tenant_id() AS tenant_id,
+           (SELECT r.key FROM app.roles r
+             WHERE r.id = app.effective_role_id(app.current_tenant_id(), auth.uid(), p_unit)) AS role_key
+  ),
+  cand AS (
+    SELECT fr.field_key, fr.state, fr.sort_order,
+           CASE WHEN fr.unit_id IS NULL THEN 'tenant' ELSE 'unit' END
+             || CASE WHEN fr.role_key IS NULL THEN '' ELSE ':role' END AS source,
+           (CASE WHEN fr.unit_id IS NULL THEN 0 ELSE 2 END) + (CASE WHEN fr.role_key IS NULL THEN 0 ELSE 1 END) AS prio
+      FROM public.field_rules fr, me
+     WHERE fr.tenant_id = me.tenant_id
+       AND fr.context = p_context
+       AND fr.reference = p_reference
+       AND (fr.unit_id IS NULL OR fr.unit_id = p_unit)
+       AND (fr.role_key IS NULL OR fr.role_key = me.role_key)
+       AND (
+            fr.unit_id IS NOT NULL
+         OR p_unit IS NULL
+         OR NOT EXISTS (SELECT 1 FROM app.resource_grants g
+                         WHERE g.tenant_id = fr.tenant_id AND g.resource_type = 'config.field_rule'
+                           AND g.resource_id = fr.id AND g.relation = 'available_in')
+         OR EXISTS (SELECT 1 FROM app.resource_grants g
+                     WHERE g.tenant_id = fr.tenant_id AND g.resource_type = 'config.field_rule'
+                       AND g.resource_id = fr.id AND g.relation = 'available_in'
+                       AND g.subject_type = 'unit' AND g.subject_id = p_unit)
+       )
+  )
+  SELECT DISTINCT ON (c.field_key) c.field_key, c.state, c.source, c.sort_order
+    FROM cand c
+   ORDER BY c.field_key, c.prio DESC;
+$$;
+
+-- ── validate: the payload against the resolved rules ────────────────────
+-- {ok, missing:[keys], hidden:[keys], payload} — payload is the input with
+-- every hidden key stripped (a hidden field never leaves the server), missing
+-- lists required keys that are absent, null or blank.
+CREATE OR REPLACE FUNCTION public.field_rules_validate(p_context text, p_reference text, p_payload jsonb, p_unit uuid DEFAULT NULL)
+RETURNS jsonb
+LANGUAGE plpgsql STABLE SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  v_payload jsonb := coalesce(p_payload, '{}'::jsonb);
+  v_missing text[] := '{}';
+  v_hidden  text[] := '{}';
+  r record;
+BEGIN
+  IF jsonb_typeof(v_payload) <> 'object' THEN
+    RAISE EXCEPTION 'field_rules_validate: payload must be a JSON object' USING ERRCODE = '22023';
+  END IF;
+  FOR r IN SELECT * FROM public.field_rules_resolve(p_context, p_reference, p_unit) ORDER BY sort_order, field_key LOOP
+    IF r.state = 'hidden' THEN
+      IF v_payload ? r.field_key THEN
+        v_hidden := v_hidden || r.field_key;
+        v_payload := v_payload - r.field_key;
+      END IF;
+    ELSIF r.state = 'required' THEN
+      IF NOT (v_payload ? r.field_key)
+         OR jsonb_typeof(v_payload -> r.field_key) = 'null'
+         OR (jsonb_typeof(v_payload -> r.field_key) = 'string' AND btrim(v_payload ->> r.field_key) = '') THEN
+        v_missing := v_missing || r.field_key;
+      END IF;
+    END IF;
+  END LOOP;
+  RETURN jsonb_build_object(
+    'ok', cardinality(v_missing) = 0,
+    'missing', to_jsonb(v_missing),
+    'hidden', to_jsonb(v_hidden),
+    'payload', v_payload
+  );
+END $$;
+
+-- ── check: the RPC contract ─────────────────────────────────────────────
+-- Returns the stripped payload; a missing required field RAISES 23514 whose
+-- MESSAGE is the pt-BR product copy the PRD requires ("Campo obrigatório: …",
+-- labels from the field registry when declared) and whose DETAIL carries the
+-- machine-readable keys. Any plugin RPC: v_payload := field_rules_check(...).
+CREATE OR REPLACE FUNCTION public.field_rules_check(p_context text, p_reference text, p_payload jsonb, p_unit uuid DEFAULT NULL)
+RETURNS jsonb
+LANGUAGE plpgsql STABLE SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  v_res    jsonb := public.field_rules_validate(p_context, p_reference, p_payload, p_unit);
+  v_tenant uuid := app.current_tenant_id();
+  v_labels text;
+BEGIN
+  IF (v_res ->> 'ok')::boolean THEN
+    RETURN v_res -> 'payload';
+  END IF;
+  SELECT string_agg(coalesce(
+           (SELECT f.label FROM public.plg_entity_fields f
+             WHERE f.reference = p_reference AND f.key = k.key
+               AND (f.tenant_id IS NULL OR f.tenant_id = v_tenant)
+               AND f.archived_at IS NULL AND nullif(btrim(f.label), '') IS NOT NULL
+             ORDER BY f.tenant_id NULLS LAST LIMIT 1),
+           k.key), ', ' ORDER BY k.ord)
+    INTO v_labels
+    FROM jsonb_array_elements_text(v_res -> 'missing') WITH ORDINALITY AS k(key, ord);
+  RAISE EXCEPTION 'Campo obrigatório: %', v_labels
+    USING ERRCODE = '23514',
+          DETAIL = format('field_rules_check: required fields missing for %s/%s: %s', p_context, p_reference, (v_res -> 'missing')::text),
+          HINT = 'Preencha os campos obrigatórios antes de continuar.';
+END $$;
+
+REVOKE ALL ON FUNCTION public.field_rules_resolve(text, text, uuid) FROM public, anon;
+REVOKE ALL ON FUNCTION public.field_rules_validate(text, text, jsonb, uuid) FROM public, anon;
+REVOKE ALL ON FUNCTION public.field_rules_check(text, text, jsonb, uuid) FROM public, anon;
+GRANT EXECUTE ON FUNCTION public.field_rules_resolve(text, text, uuid) TO authenticated, service_role;
+GRANT EXECUTE ON FUNCTION public.field_rules_validate(text, text, jsonb, uuid) TO authenticated, service_role;
+GRANT EXECUTE ON FUNCTION public.field_rules_check(text, text, jsonb, uuid) TO authenticated, service_role;
+
+COMMENT ON TABLE public.field_rules IS
+  'FieldRules (PRD 07 R1): per tenant (unit_id NULL = network default) and per unit, per context and optional role, '
+  'each declared field is hidden | visible | required. Resolved by field_rules_resolve(); enforced by field_rules_check().';
+COMMENT ON TABLE public.field_rule_contexts IS
+  'Open list of FieldRule contexts (pre_registration, scheduling, check_in, internal_form, person, order, …). A plugin adds one with an INSERT.';