@fayz-ai/db 0.9.0 → 0.11.0

package/migrations/024_analytics_engine.sql

@@ -0,0 +1,317 @@
+-- ============================================================================
+-- The analytics engine — one aggregate function for every domain
+-- ----------------------------------------------------------------------------
+-- Until now every number in the product was computed twice and differently: a
+-- dashboard KPI pulled `listOrders({limit: 200})` and summed in JavaScript,
+-- while the report engine ran a flat SELECT over a `rep_*` view. Two engines,
+-- two answers, and the KPI silently wrong the moment a tenant passes 200 rows.
+--
+-- This is the half that belongs to NO domain: an allowlist of queryable read
+-- models, an identifier guard, and analytics_run() — which groups, buckets and
+-- aggregates any registered read model from parameters. "Orders over time" and
+-- "sales by product" are the same call with different dimensions, so adding a
+-- report stops being a database migration.
+--
+-- Each domain ships its own read models and registers them (see
+-- packages/shop/migrations/0039_analytics_read_models.sql). A salon, a school
+-- and a store all reuse this function over completely different views.
+--
+-- Because a KPI and the report behind it are literally the same query with and
+-- without the GROUP BY, they cannot disagree.
+--
+-- SECURITY. This function builds dynamic SQL from caller-supplied strings, so:
+--   * the source must be registered in plg_analytics_read_models — an allowlist,
+--     not a prefix convention a future view could accidentally satisfy;
+--   * every column name is verified to exist on that source via
+--     information_schema before it reaches the statement;
+--   * aggregates and time grains are matched against fixed enums;
+--   * identifiers go through %I and literals through %L, never concatenation;
+--   * the function is SECURITY INVOKER and read models are security_invoker=true,
+--     so the underlying RLS still decides which rows exist. The explicit tenant
+--     filter is defence in depth, not the only lock.
+--
+-- Idempotent.
+-- ============================================================================
+
+-- ----------------------------------------------------------------------------
+-- 1. The allowlist. A read model that is not in here cannot be queried, full
+--    stop. Registering is a migration-time act, never a runtime one.
+-- ----------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS public.plg_analytics_read_models (
+  name          text PRIMARY KEY,
+  -- The time spine. Taken from HERE and not from the client: the read model is
+  -- the authority on which of its columns is "when this happened".
+  date_column   text NOT NULL DEFAULT 'created_at',
+  tenant_column text NOT NULL DEFAULT 'tenant_id',
+  description   text
+);
+
+ALTER TABLE public.plg_analytics_read_models ENABLE ROW LEVEL SECURITY;
+
+DROP POLICY IF EXISTS plg_analytics_read_models_read ON public.plg_analytics_read_models;
+CREATE POLICY plg_analytics_read_models_read ON public.plg_analytics_read_models
+  FOR SELECT TO authenticated USING (true);
+
+GRANT SELECT ON public.plg_analytics_read_models TO authenticated;
+GRANT ALL    ON public.plg_analytics_read_models TO service_role;
+
+-- ----------------------------------------------------------------------------
+-- 7. Identifier guard. Every column name from the client passes through here
+--    before it can reach a statement. Raises rather than returning false so a
+--    typo in a card definition fails loudly at the call instead of silently
+--    dropping a dimension and returning a wrong-shaped answer.
+-- ----------------------------------------------------------------------------
+CREATE OR REPLACE FUNCTION public.analytics_assert_column(p_source text, p_column text)
+RETURNS text
+LANGUAGE plpgsql
+STABLE
+AS $$
+BEGIN
+  IF p_column IS NULL OR p_column !~ '^[a-z_][a-z0-9_]*$' THEN
+    RAISE EXCEPTION 'analytics: malformed column name %', p_column USING ERRCODE = '22023';
+  END IF;
+
+  IF NOT EXISTS (
+    SELECT 1 FROM information_schema.columns
+    WHERE table_schema = 'public' AND table_name = p_source AND column_name = p_column
+  ) THEN
+    RAISE EXCEPTION 'analytics: column % does not exist on %', p_column, p_source USING ERRCODE = '42703';
+  END IF;
+
+  RETURN p_column;
+END;
+$$;
+
+-- ----------------------------------------------------------------------------
+-- 8. analytics_run — the whole engine.
+--
+--    p_dimensions  [{"key":"created_at","grain":"day"}, {"key":"product_name"}]
+--    p_measures    [{"key":"net_sales","agg":"sum","column":"net_sales"}]
+--    p_filters     {"financial_status":"paid","category_id":["uuid","uuid"]}
+--
+--    Returns {"rows":[...], "total":n, "summary":{...}} where `summary` is the
+--    same measures rolled up over the WHOLE range with no group-by. The summary
+--    is what a KPI card reads and what a report's total row shows — computed
+--    once, from the same filters, so they cannot disagree.
+--
+--    SECURITY INVOKER (the default, stated for the reader): RLS on the base
+--    tables decides visibility; the tenant predicate below is belt and braces.
+-- ----------------------------------------------------------------------------
+CREATE OR REPLACE FUNCTION public.analytics_run(
+  p_source     text,
+  p_tenant_id  uuid    DEFAULT NULL,
+  p_from       timestamptz DEFAULT NULL,
+  p_to         timestamptz DEFAULT NULL,
+  p_dimensions jsonb   DEFAULT '[]'::jsonb,
+  p_measures   jsonb   DEFAULT '[]'::jsonb,
+  p_filters    jsonb   DEFAULT '{}'::jsonb,
+  p_search     text    DEFAULT NULL,
+  p_search_columns text[] DEFAULT NULL,
+  p_sort       text    DEFAULT NULL,
+  p_dir        text    DEFAULT 'desc',
+  p_limit      int     DEFAULT 500,
+  p_offset     int     DEFAULT 0
+)
+RETURNS jsonb
+LANGUAGE plpgsql
+STABLE
+AS $$
+DECLARE
+  v_model      public.plg_analytics_read_models%ROWTYPE;
+  v_where      text[] := ARRAY[]::text[];
+  v_where_sql  text;
+  v_select     text[] := ARRAY[]::text[];
+  v_group      text[] := ARRAY[]::text[];
+  v_agg_only   text[] := ARRAY[]::text[];
+  v_dim        jsonb;
+  v_meas       jsonb;
+  v_key        text;
+  v_col        text;
+  v_grain      text;
+  v_agg        text;
+  v_expr       text;
+  v_filter_key text;
+  v_filter_val jsonb;
+  v_search_ors text[] := ARRAY[]::text[];
+  v_sort_sql   text := '';
+  v_rows       jsonb;
+  v_summary    jsonb;
+  v_total      bigint;
+  v_limit      int := LEAST(GREATEST(COALESCE(p_limit, 500), 1), 5000);
+  v_offset     int := GREATEST(COALESCE(p_offset, 0), 0);
+BEGIN
+  -- 8.1 The source must be registered. Not "look like a read model" — registered.
+  SELECT * INTO v_model FROM public.plg_analytics_read_models WHERE name = p_source;
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'analytics: % is not a registered read model', p_source USING ERRCODE = '42P01';
+  END IF;
+
+  -- 8.2 Tenant + date window. The date column comes from the registry, so a
+  --     caller cannot redirect the range onto some other timestamp.
+  IF p_tenant_id IS NOT NULL THEN
+    v_where := v_where || format('%I = %L', v_model.tenant_column, p_tenant_id);
+  END IF;
+  IF p_from IS NOT NULL THEN
+    v_where := v_where || format('%I >= %L', v_model.date_column, p_from);
+  END IF;
+  IF p_to IS NOT NULL THEN
+    v_where := v_where || format('%I <= %L', v_model.date_column, p_to);
+  END IF;
+
+  -- 8.3 Equality / IN filters.
+  FOR v_filter_key, v_filter_val IN SELECT key, value FROM jsonb_each(COALESCE(p_filters, '{}'::jsonb))
+  LOOP
+    CONTINUE WHEN v_filter_val IS NULL OR jsonb_typeof(v_filter_val) = 'null';
+    v_col := public.analytics_assert_column(p_source, v_filter_key);
+
+    IF jsonb_typeof(v_filter_val) = 'array' THEN
+      CONTINUE WHEN jsonb_array_length(v_filter_val) = 0;
+      v_where := v_where || format(
+        '%I::text = ANY (SELECT jsonb_array_elements_text(%L::jsonb))', v_col, v_filter_val);
+    ELSE
+      v_where := v_where || format('%I::text = %L', v_col, v_filter_val #>> '{}');
+    END IF;
+  END LOOP;
+
+  -- 8.4 Free-text search across the caller's declared text columns.
+  IF p_search IS NOT NULL AND length(btrim(p_search)) > 0 AND p_search_columns IS NOT NULL THEN
+    FOREACH v_col IN ARRAY p_search_columns LOOP
+      v_col := public.analytics_assert_column(p_source, v_col);
+      v_search_ors := v_search_ors || format('%I::text ILIKE %L', v_col, '%' || btrim(p_search) || '%');
+    END LOOP;
+    IF array_length(v_search_ors, 1) > 0 THEN
+      v_where := v_where || ('(' || array_to_string(v_search_ors, ' OR ') || ')');
+    END IF;
+  END IF;
+
+  v_where_sql := CASE WHEN array_length(v_where, 1) > 0
+                      THEN ' WHERE ' || array_to_string(v_where, ' AND ')
+                      ELSE '' END;
+
+  -- 8.5 Dimensions. A grain turns a timestamp into a bucket; without one the
+  --     raw column value is the group.
+  FOR v_dim IN SELECT * FROM jsonb_array_elements(COALESCE(p_dimensions, '[]'::jsonb))
+  LOOP
+    v_key   := v_dim ->> 'key';
+    v_col   := public.analytics_assert_column(p_source, v_key);
+    v_grain := v_dim ->> 'grain';
+
+    IF v_grain IS NULL THEN
+      v_expr := format('%I', v_col);
+    ELSIF v_grain IN ('hour','day','week','month','quarter','year') THEN
+      v_expr := format('date_trunc(%L, %I)', v_grain, v_col);
+    ELSE
+      RAISE EXCEPTION 'analytics: unsupported time grain %', v_grain USING ERRCODE = '22023';
+    END IF;
+
+    v_select := v_select || format('%s AS %I', v_expr, v_key);
+    v_group  := v_group  || v_expr;
+  END LOOP;
+
+  -- 8.6 Measures. Fixed aggregate vocabulary — anything else is rejected rather
+  --     than passed through, which is the difference between a parameter and an
+  --     injection point. 'ratio' is deliberately absent: it is derived on the
+  --     client from two real measures so ratio-of-sums never degrades into
+  --     avg-of-ratios.
+  FOR v_meas IN SELECT * FROM jsonb_array_elements(COALESCE(p_measures, '[]'::jsonb))
+  LOOP
+    v_key := v_meas ->> 'key';
+    IF v_key IS NULL OR v_key !~ '^[a-z_][a-z0-9_]*$' THEN
+      RAISE EXCEPTION 'analytics: malformed measure key %', v_key USING ERRCODE = '22023';
+    END IF;
+    v_agg := lower(COALESCE(v_meas ->> 'agg', 'sum'));
+
+    IF v_agg = 'count' THEN
+      v_expr := 'count(*)';
+    ELSE
+      v_col := public.analytics_assert_column(p_source, COALESCE(v_meas ->> 'column', v_key));
+      v_expr := CASE v_agg
+        WHEN 'sum'            THEN format('sum(%I)', v_col)
+        WHEN 'avg'            THEN format('avg(%I)', v_col)
+        WHEN 'min'            THEN format('min(%I)', v_col)
+        WHEN 'max'            THEN format('max(%I)', v_col)
+        WHEN 'count_distinct' THEN format('count(DISTINCT %I)', v_col)
+        ELSE NULL
+      END;
+      IF v_expr IS NULL THEN
+        RAISE EXCEPTION 'analytics: unsupported aggregate %', v_agg USING ERRCODE = '22023';
+      END IF;
+    END IF;
+
+    v_select   := v_select   || format('%s AS %I', v_expr, v_key);
+    v_agg_only := v_agg_only || format('%s AS %I', v_expr, v_key);
+  END LOOP;
+
+  -- 8.7 No measures ⇒ a raw detail listing (the classic tabular report).
+  IF array_length(v_agg_only, 1) IS NULL AND array_length(v_group, 1) IS NULL THEN
+    v_select := ARRAY['*'];
+  END IF;
+
+  -- 8.8 Sort. Must be one of the things actually selected — an alias, not an
+  --     arbitrary expression.
+  IF p_sort IS NOT NULL AND p_sort ~ '^[a-z_][a-z0-9_]*$' THEN
+    IF EXISTS (SELECT 1 FROM jsonb_array_elements(COALESCE(p_measures,'[]'::jsonb)) m WHERE m->>'key' = p_sort)
+       OR EXISTS (SELECT 1 FROM jsonb_array_elements(COALESCE(p_dimensions,'[]'::jsonb)) d WHERE d->>'key' = p_sort)
+       OR (array_length(v_agg_only,1) IS NULL AND array_length(v_group,1) IS NULL)
+    THEN
+      IF array_length(v_agg_only,1) IS NULL AND array_length(v_group,1) IS NULL THEN
+        PERFORM public.analytics_assert_column(p_source, p_sort);
+      END IF;
+      v_sort_sql := format(' ORDER BY %I %s NULLS LAST',
+                           p_sort,
+                           CASE WHEN lower(COALESCE(p_dir,'desc')) = 'asc' THEN 'ASC' ELSE 'DESC' END);
+    END IF;
+  END IF;
+
+  -- 8.9 Page of rows.
+  EXECUTE format(
+    'SELECT COALESCE(jsonb_agg(t), ''[]''::jsonb) FROM (SELECT %s FROM public.%I%s%s%s LIMIT %s OFFSET %s) t',
+    array_to_string(v_select, ', '),
+    p_source,
+    v_where_sql,
+    CASE WHEN array_length(v_group, 1) > 0
+         THEN ' GROUP BY ' || array_to_string(v_group, ', ') ELSE '' END,
+    v_sort_sql,
+    v_limit,
+    v_offset
+  ) INTO v_rows;
+
+  -- 8.10 Row count for pagination. This must count what the MAIN query returns,
+  --      not what it reads: grouping ⇒ number of groups; aggregating with no
+  --      dimensions ⇒ exactly one row, however many rows fed it; otherwise the
+  --      underlying rows. Counting reads here made a 1-row KPI claim two pages.
+  IF array_length(v_group, 1) > 0 THEN
+    EXECUTE format(
+      'SELECT count(*) FROM (SELECT %s FROM public.%I%s GROUP BY %s) c',
+      array_to_string(v_group, ', '), p_source, v_where_sql, array_to_string(v_group, ', ')
+    ) INTO v_total;
+  ELSIF array_length(v_agg_only, 1) > 0 THEN
+    v_total := 1;
+  ELSE
+    EXECUTE format('SELECT count(*) FROM public.%I%s', p_source, v_where_sql) INTO v_total;
+  END IF;
+
+  -- 8.11 The summary: identical filters, identical measures, no group-by. This
+  --      is the KPI headline AND the report's total row — one number, one place.
+  IF array_length(v_agg_only, 1) > 0 THEN
+    EXECUTE format(
+      'SELECT to_jsonb(s) FROM (SELECT %s FROM public.%I%s) s',
+      array_to_string(v_agg_only, ', '),
+      p_source,
+      v_where_sql
+    ) INTO v_summary;
+  END IF;
+
+  RETURN jsonb_build_object(
+    'rows',    COALESCE(v_rows, '[]'::jsonb),
+    'total',   COALESCE(v_total, 0),
+    'summary', COALESCE(v_summary, '{}'::jsonb)
+  );
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.analytics_run(text, uuid, timestamptz, timestamptz, jsonb, jsonb, jsonb, text, text[], text, text, int, int) FROM public;
+GRANT EXECUTE ON FUNCTION public.analytics_run(text, uuid, timestamptz, timestamptz, jsonb, jsonb, jsonb, text, text[], text, text, int, int) TO authenticated, service_role;
+
+REVOKE ALL ON FUNCTION public.analytics_assert_column(text, text) FROM public;
+GRANT EXECUTE ON FUNCTION public.analytics_assert_column(text, text) TO authenticated, service_role;

package/migrations/025_created_by.sql

@@ -0,0 +1,75 @@
+-- ============================================================================
+-- 025_created_by.sql — quem cadastrou.
+--
+-- Toda tabela do core já nasceu com `created_at` e `updated_at` (001_core,
+-- 004_archetypes) e um gatilho que mantém o segundo em dia. Nenhuma nasceu com
+-- QUEM. A ficha de um cliente sabia dizer o dia em que foi criada e não sabia
+-- dizer por quem — a pergunta que sempre vem depois de "esse cadastro está
+-- errado" é "quem cadastrou", e ela não tinha resposta em lugar nenhum: o
+-- `audit_logs` de 001_core existe como tabela e nunca recebeu uma linha.
+--
+-- A coluna é NULÁVEL e fica assim de propósito:
+--
+--   • as linhas que já existem não têm autor, e nunca terão — inventar um
+--     (o dono do tenant, o primeiro membro) seria fabricar procedência, que é
+--     exatamente o oposto do que a coluna serve para dar. Elas ficam em branco
+--     e a interface omite a frase.
+--
+--   • nem toda escrita tem gente atrás. Importação de CSV, webhook, seed,
+--     job do agente: `auth.uid()` é NULL nesses caminhos, e NULL aqui quer
+--     dizer "o sistema", que é a verdade.
+--
+-- O DEFAULT vem por gatilho e não por `DEFAULT auth.uid()` na coluna porque o
+-- `service_role` (edge functions, backfills) precisa poder gravar um autor
+-- explícito; com o default na coluna, escrever NULL de propósito e "não
+-- escrever nada" viram a mesma coisa e o COALESCE não teria onde morar.
+--
+-- Aditivo e idempotente: ADD COLUMN IF NOT EXISTS de coluna nulável não
+-- reescreve a tabela (PG 11+), e os gatilhos são recriados por DROP IF EXISTS.
+-- ============================================================================
+
+CREATE OR REPLACE FUNCTION public.handle_created_by()
+RETURNS trigger
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+BEGIN
+  -- COALESCE e não atribuição direta: uma migração de dados ou uma função de
+  -- servidor que JÁ sabe o autor (importou em nome de alguém) manda o valor
+  -- certo, e o gatilho não o sobrescreve com o NULL de um contexto sem sessão.
+  NEW.created_by := COALESCE(NEW.created_by, auth.uid());
+  RETURN NEW;
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.handle_created_by() FROM public;
+REVOKE ALL ON FUNCTION public.handle_created_by() FROM anon;
+
+DO $$
+DECLARE
+  t text;
+  -- As bases de arquétipo (004_archetypes) mais as tabelas de core que um CRUD
+  -- desenha como ficha. Tabelas de junção, ledger e evento ficam de fora: elas
+  -- já carregam o ator no próprio corpo ou não têm ficha para mostrá-lo.
+  tables text[] := ARRAY[
+    'people', 'categories', 'products', 'services', 'locations',
+    'orders', 'transactions', 'schedules', 'appointments'
+  ];
+BEGIN
+  FOREACH t IN ARRAY tables LOOP
+    IF to_regclass('public.' || t) IS NULL THEN
+      CONTINUE;
+    END IF;
+
+    EXECUTE format(
+      'ALTER TABLE public.%I ADD COLUMN IF NOT EXISTS created_by uuid REFERENCES auth.users(id) ON DELETE SET NULL',
+      t
+    );
+    EXECUTE format('DROP TRIGGER IF EXISTS %I ON public.%I', t || '_created_by', t);
+    EXECUTE format(
+      'CREATE TRIGGER %I BEFORE INSERT ON public.%I FOR EACH ROW EXECUTE FUNCTION public.handle_created_by()',
+      t || '_created_by', t
+    );
+  END LOOP;
+END $$;

package/migrations/026_audit_trail.sql

@@ -0,0 +1,73 @@
+-- ============================================================================
+-- 026_audit_trail.sql — audit_logs vira leitura, não só depósito.
+--
+-- A tabela existe desde o 001_core e hoje recebe linhas de um lugar só: os RPCs
+-- do agente (`agent_forms_upsert_template` e irmãos). Tudo que uma PESSOA faz
+-- pela tela — criar cliente, corrigir um telefone, excluir um serviço — não
+-- deixava rastro nenhum. O resultado é que "quem mudou isso, e quando" não tinha
+-- resposta em lugar nenhum do produto.
+--
+-- Esta migração NÃO põe gatilho de auditoria em tabela nenhuma. A escrita passa
+-- a sair do único ponto por onde todo cadastro do app já passa — o store de CRUD
+-- (packages/admin/src/stores/createCrudStore.ts), que hoje já emite os eventos
+-- de domínio de created/updated/deleted. Um gatilho por tabela pegaria também as
+-- escritas fora do app, mas custaria uma migração a cada cadastro novo, e
+-- "auditoria funciona pra qualquer cadastro" viraria "funciona nos cadastros de
+-- que alguém lembrou". No chokepoint, um cadastro novo já nasce auditado.
+--
+-- Aqui só fica o que é do banco: a permissão para gravar, quem gravou, e os
+-- índices que fazem essa tabela ser lida sem varredura.
+-- ============================================================================
+
+-- ── Quem gravou ─────────────────────────────────────────────────────────────
+-- Mesma escolha do 025: por gatilho, e não `DEFAULT auth.uid()` na coluna,
+-- para o service_role (edge function, backfill) poder gravar um autor explícito
+-- sem que "escrever NULL de propósito" e "não escrever nada" virem a mesma coisa.
+CREATE OR REPLACE FUNCTION public.handle_audit_actor()
+RETURNS trigger
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $fn$
+BEGIN
+  NEW.user_id := COALESCE(NEW.user_id, auth.uid());
+  RETURN NEW;
+END;
+$fn$;
+
+REVOKE ALL ON FUNCTION public.handle_audit_actor() FROM public;
+REVOKE ALL ON FUNCTION public.handle_audit_actor() FROM anon;
+
+DROP TRIGGER IF EXISTS audit_logs_actor ON public.audit_logs;
+CREATE TRIGGER audit_logs_actor BEFORE INSERT ON public.audit_logs
+  FOR EACH ROW EXECUTE FUNCTION public.handle_audit_actor();
+
+-- ── Permissão de escrita ────────────────────────────────────────────────────
+-- A política de INSERT estava em `WITH CHECK (true)`: qualquer usuário
+-- autenticado podia gravar uma linha de auditoria em QUALQUER tenant do pool —
+-- inclusive forjando ação em nome de outro. Numa tabela cujo propósito é ser
+-- prova do que aconteceu, isso é o defeito mais caro possível.
+--
+-- `user_id` fica de fora da checagem de propósito: o gatilho acima o preenche
+-- DEPOIS que a política roda, e o RPC do agente grava em nome do ator que o
+-- broker injetou.
+DROP POLICY IF EXISTS "audit_insert" ON public.audit_logs;
+CREATE POLICY "audit_insert" ON public.audit_logs
+  FOR INSERT TO authenticated
+  WITH CHECK (tenant_id IN (SELECT public.user_tenant_ids()));
+
+-- Auditoria não se corrige e não se apaga pela aplicação. Sem política de
+-- UPDATE/DELETE para `authenticated`, a RLS nega — que é o comportamento certo:
+-- um registro de auditoria editável não prova nada. Correção e expurgo por
+-- retenção são trabalho de service_role.
+
+-- ── Leitura ─────────────────────────────────────────────────────────────────
+-- A linha do tempo de uma ficha pergunta sempre a mesma coisa: "os eventos
+-- DESTE registro, do mais novo para o mais velho". Sem este índice é varredura
+-- na tabela inteira do tenant a cada abertura de ficha.
+CREATE INDEX IF NOT EXISTS idx_audit_logs_entity
+  ON public.audit_logs (tenant_id, entity_type, entity_id, created_at DESC);
+
+-- E o feed geral ("o que andou acontecendo"), que ordena só por data.
+CREATE INDEX IF NOT EXISTS idx_audit_logs_recent
+  ON public.audit_logs (tenant_id, created_at DESC);