@fayz-ai/db 0.14.0 → 0.16.0

package/migrations/046_the_tick_advances_the_flows.sql

@@ -0,0 +1,77 @@
+-- 046_the_tick_advances_the_flows.sql
+--
+-- A cadence needs a clock, and the database already has one: `fayz_event_runner`
+-- is a pg_cron job calling `event_runner_tick(200)` every minute. What it does
+-- not have is a call to the thing that advances a multi-step flow.
+--
+-- Fifth call, same shape as the other four: guarded by `to_regprocedure`, so a
+-- pool without plugin-automations ticks exactly as it does today. The guard is
+-- the whole reason this belongs in the spine rather than in the plugin — the
+-- tick is one function, and a plugin cannot append to it.
+--
+-- ORDER MATTERS, AND IT IS DELIBERATE. The flows run AFTER `notifications_drain`
+-- and not before. A step enqueues with `scheduled_for = now()`, so draining
+-- first means a step enqueued on this tick waits for the next one — sixty
+-- seconds, once, at the start of a cadence that spans days. Running the flows
+-- first would instead let a step be enqueued and drained in the same tick,
+-- which sounds better and is not: the drain would be doing work the advisory
+-- lock is already holding the whole database's tick for, and a slow provider
+-- would then delay every other plugin's due work behind it. Cheap latency,
+-- bought with predictable tick length.
+--
+-- The limit is 50 rather than the caller's `p_limit`. A cadence step is a write
+-- plus an enqueue; two hundred of them in one tick is a long transaction under
+-- an advisory lock that stops everything else. `marketing_run_due(20)` made the
+-- same trade for the same reason.
+
+CREATE OR REPLACE FUNCTION public.event_runner_tick(p_limit integer DEFAULT 200) RETURNS jsonb
+    LANGUAGE plpgsql SECURITY DEFINER
+    SET search_path TO ''
+    AS $_$
+DECLARE
+  v_lock    boolean;
+  v_events  record;
+  v_notif   record;
+  v_out     jsonb := '{}'::jsonb;
+  v_extra   jsonb;
+  v_start   timestamptz := clock_timestamp();
+BEGIN
+  -- 1 tick at a time per database. A second caller returns immediately rather
+  -- than waiting, so a cron that fires while the previous one is still going
+  -- does not queue up behind it.
+  SELECT pg_try_advisory_xact_lock(hashtextextended('fayz.event_runner', 0)) INTO v_lock;
+  IF NOT v_lock THEN
+    RETURN jsonb_build_object('skipped', 'another tick is running');
+  END IF;
+
+  SELECT * INTO v_events FROM public.consume_event_log(p_limit);
+  v_out := v_out || jsonb_build_object('events', to_jsonb(v_events));
+
+  -- The notification queue drains in its OWN pass. A provider timing out costs
+  -- a retry there and must never hold up the event log — which is why these are
+  -- two functions and not one loop.
+  IF to_regprocedure('public.notifications_drain(integer)') IS NOT NULL THEN
+    EXECUTE 'SELECT * FROM public.notifications_drain($1)' INTO v_notif USING p_limit;
+    v_out := v_out || jsonb_build_object('notifications', to_jsonb(v_notif));
+  END IF;
+
+  -- Campaigns, scheduled reports and cadence flows ENQUEUE; they never send. So
+  -- they run on the same tick as the log and drain through the same
+  -- notification queue.
+  IF to_regprocedure('public.marketing_run_due(integer)') IS NOT NULL THEN
+    EXECUTE 'SELECT public.marketing_run_due(20)' INTO v_extra;
+    v_out := v_out || jsonb_build_object('marketing', v_extra);
+  END IF;
+
+  IF to_regprocedure('public.reports_deliver_due(integer)') IS NOT NULL THEN
+    EXECUTE 'SELECT public.reports_deliver_due(50)' INTO v_extra;
+    v_out := v_out || jsonb_build_object('reports', v_extra);
+  END IF;
+
+  IF to_regprocedure('public.automations_flows_run_due(integer)') IS NOT NULL THEN
+    EXECUTE 'SELECT public.automations_flows_run_due(50)' INTO v_extra;
+    v_out := v_out || jsonb_build_object('flows', v_extra);
+  END IF;
+
+  RETURN v_out || jsonb_build_object('took_ms', (extract(epoch FROM clock_timestamp() - v_start) * 1000)::integer);
+END $_$;

package/migrations/047_the_tick_sweeps_the_offers.sql

@@ -0,0 +1,74 @@
+-- 047_the_tick_sweeps_the_offers.sql
+--
+-- Sixth call on the minute tick: expiring a lead offer that nobody took.
+--
+-- A five-minute window means the sweep's resolution has to be finer than the
+-- window, and one minute is what the runner already gives. A rep therefore gets
+-- their full five minutes and loses the lead within sixty seconds of the window
+-- closing — which is the behaviour the rota is sold on.
+--
+-- It runs LAST, after the flows. Both write, and the offer sweep can cascade —
+-- one expiry creating the next offer — so it is the call most likely to be slow
+-- on a busy tenant. Last means a slow sweep delays nothing but itself.
+--
+-- The whole function is restated because a plugin cannot append to it, and
+-- `CREATE OR REPLACE` needs the entire body. Migration 046 added the flows call
+-- immediately before this one; if this file is ever reordered ahead of it, the
+-- flows call disappears.
+
+CREATE OR REPLACE FUNCTION public.event_runner_tick(p_limit integer DEFAULT 200) RETURNS jsonb
+    LANGUAGE plpgsql SECURITY DEFINER
+    SET search_path TO ''
+    AS $_$
+DECLARE
+  v_lock    boolean;
+  v_events  record;
+  v_notif   record;
+  v_out     jsonb := '{}'::jsonb;
+  v_extra   jsonb;
+  v_start   timestamptz := clock_timestamp();
+BEGIN
+  -- 1 tick at a time per database. A second caller returns immediately rather
+  -- than waiting, so a cron that fires while the previous one is still going
+  -- does not queue up behind it.
+  SELECT pg_try_advisory_xact_lock(hashtextextended('fayz.event_runner', 0)) INTO v_lock;
+  IF NOT v_lock THEN
+    RETURN jsonb_build_object('skipped', 'another tick is running');
+  END IF;
+
+  SELECT * INTO v_events FROM public.consume_event_log(p_limit);
+  v_out := v_out || jsonb_build_object('events', to_jsonb(v_events));
+
+  -- The notification queue drains in its OWN pass. A provider timing out costs
+  -- a retry there and must never hold up the event log — which is why these are
+  -- two functions and not one loop.
+  IF to_regprocedure('public.notifications_drain(integer)') IS NOT NULL THEN
+    EXECUTE 'SELECT * FROM public.notifications_drain($1)' INTO v_notif USING p_limit;
+    v_out := v_out || jsonb_build_object('notifications', to_jsonb(v_notif));
+  END IF;
+
+  -- Campaigns, scheduled reports and cadence flows ENQUEUE; they never send. So
+  -- they run on the same tick as the log and drain through the same
+  -- notification queue.
+  IF to_regprocedure('public.marketing_run_due(integer)') IS NOT NULL THEN
+    EXECUTE 'SELECT public.marketing_run_due(20)' INTO v_extra;
+    v_out := v_out || jsonb_build_object('marketing', v_extra);
+  END IF;
+
+  IF to_regprocedure('public.reports_deliver_due(integer)') IS NOT NULL THEN
+    EXECUTE 'SELECT public.reports_deliver_due(50)' INTO v_extra;
+    v_out := v_out || jsonb_build_object('reports', v_extra);
+  END IF;
+
+  IF to_regprocedure('public.automations_flows_run_due(integer)') IS NOT NULL THEN
+    EXECUTE 'SELECT public.automations_flows_run_due(50)' INTO v_extra;
+    v_out := v_out || jsonb_build_object('flows', v_extra);
+  END IF;
+
+  IF to_regprocedure('public.crm_offers_sweep(integer)') IS NOT NULL THEN
+    EXECUTE 'SELECT public.crm_offers_sweep(100)' INTO v_extra;
+    v_out := v_out || jsonb_build_object('offers', v_extra);
+  END IF;
+
+  RETURN v_out || jsonb_build_object('took_ms', (extract(epoch FROM clock_timestamp() - v_start) * 1000)::integer);
+END $_$;

package/migrations/052_fullcontrol_joins_the_family.sql

@@ -0,0 +1,213 @@
+-- ---------------------------------------------------------------------------
+-- 052_fullcontrol_joins_the_family.sql — o funil vira a casa inteira.
+--
+-- A 011 deu uma linha ao LeadControl porque o funil tinha transbordado de uma
+-- aba dentro do app do ofício. O que transbordou agora é o app inteiro: a
+-- mesma base que guarda o lead guarda o título, o saldo de estoque e a nota, e
+-- o produto que olha tudo isso de uma vez não é um CRM — é um ERP. Este
+-- arquivo é o registro admitindo isso.
+--
+-- O recorte também mudou de público. Os outros Controls são OFÍCIOS (cozinha,
+-- loja, estúdio, escola, bilheteria, escritório de contabilidade). Este é para
+-- a empresa cujo RAMO não é o assunto do software — a distribuidora, a
+-- confecção, a prestadora, a indústria pequena. Elas não precisam de um app
+-- que entenda de comida; precisam de um que entenda de conta a pagar.
+--
+-- ── Por que um ID NOVO e não um UPDATE no 'crm' ────────────────────────────
+--
+-- `app.apps.id` é chave, e `app.tenant_apps.app_id` é a única FK que aponta
+-- para ela (001 §2, ON DELETE RESTRICT) — então trocar o id é ADITIVO e
+-- reversível, e custa as poucas linhas do §2. O que não é reversível é o que
+-- sobra se não trocarmos: um app cujo id é o nome de UM dos seus módulos,
+-- numa linha que passaria a ler `id = 'crm' … requires ARRAY['crm', …]` — um
+-- app que exige a si mesmo. `tenant_app_set('crm')`, `tenant_plugin_set('crm')`
+-- e `plan_permits('crm')` continuariam querendo dizer três coisas diferentes.
+--
+-- Hoje é o dia mais barato para fazer isso: `url` ainda é `localhost`, nenhum
+-- domínio de cliente aponta para cá, e não existe união de ids em TypeScript
+-- (packages/admin/src/directory/app-id.ts é explícito: "a rename is a row, not
+-- a release"). O que o app lê é `VITE_APP_ID`, e ele acompanha este arquivo.
+--
+-- A linha antiga NÃO é apagada — é APOSENTADA (§3). A FK a protege, as linhas
+-- de `app.tenant_apps` com app_id='crm' são o histórico de quem teve o produto,
+-- e enquanto elas existirem a volta atrás é um UPDATE e não um INSERT.
+--
+-- ── `serves_verticals` fica VAZIO, e agora o argumento é o OPOSTO ──────────
+--
+-- Nas 011/031/043 o array ficou vazio porque aquele app servia a um recorte.
+-- Aqui ele fica vazio porque o app serve a TODOS — e é exatamente por isso que
+-- semear por vertical (010) seria o pior erro possível: todo restaurante criado
+-- amanhã acordaria com um segundo produto no switcher, com financeiro e estoque
+-- acesos que ninguém configurou. Um app que chega sem ser convidado não é
+-- funcionalidade, é chamado de suporte. Opt-in via `tenant_app_set('full', …)`.
+--
+-- ── `requires` cresce em DEGRAUS, um marco por vez ─────────────────────────
+--
+-- Regra da 031/043: o array ganha um plugin no arquivo que traz as telas dele.
+-- Aqui ele nomeia o que o bundle do app JÁ monta hoje (src/config/app.tsx):
+-- crm, conversations, marketing, automations, notifications, reports,
+-- financial e inventory.
+--
+-- E há um motivo mais duro para não listar o resto de uma vez:
+-- **app.tenant_plugins não tem app_id**. Um plugin exigido aqui acende para o
+-- TENANT, e aparece em qualquer outro Control que aquele tenant rode e que
+-- empacote o mesmo plugin. Agenda, tasks, forms e orders entram quando este app
+-- desenhar as telas deles.
+--
+-- Os addons ficam de fora por definição: `fiscal-br` e `banking-br` são opt-in
+-- contratados, e o que entra em `requires` é ligado para todo mundo.
+--
+-- ── O que a 011 dizia sobre `financial`, e por que caiu ────────────────────
+--
+-- A 011 recusou `financial` com o argumento certo para o produto de então:
+-- "um negócio ganho neste produto passa a bola para o app que é dono do
+-- dinheiro; duplicar o razão aqui daria duas portas de entrada para a mesma
+-- fatura." O argumento não mudou — mudou de lado. **O FullControl É o app que
+-- é dono do dinheiro.** O orçamento aprovado no CRM vira título e aterrissa em
+-- /financial/receivables/detail/:id sem sair do app, e é a mesma linha de
+-- `plg_financial_invoices` que o ChefControl do mesmo tenant leria.
+-- ---------------------------------------------------------------------------
+
+-- ── §1  a linha nova ───────────────────────────────────────────────────────
+--
+-- #1E3A8A (blue-900) e não o teal que este arquivo carregou por uma tarde: o
+-- CourseControl está com #0D9488 no cluster — a linha divergiu do âmbar que a
+-- 001 deu a ele —, e dois teais no launcher leem como um produto em dois tons.
+-- Também não é o #2563EB do LeadControl por acaso: é ele um degrau mais grave.
+-- Para as nove contas que já tinham o ladrilho azul, o produto CRESCEU; a cor
+-- diz produção onde a antiga dizia vendas. Branco sobre ele dá 10,4:1.
+--
+-- 'Layers' existe no registro CURADO de ícones (packages/ui/src/icons.ts) —
+-- conferido, e não é zelo: 'Scissors', que a 001 deu ao StudioControl, NÃO
+-- existe lá, e aquele ladrilho desenha iniciais desde então, sem erro nenhum.
+-- Camadas sobre uma base é a figura literal de um ERP: vários módulos sobre um
+-- tenant só. Um FullControlMark próprio entra quando existir marca em livro —
+-- inventar um SVG que todos os irmãos passam a desenhar é pior que um glifo
+-- bem escolhido (foi o que a 012 pagou para o ChefControl, e só depois do
+-- brand book).
+--
+-- `url` é a origem de dev; a coluna é a allow-list do handoff, e o coalesce
+-- impede que uma reaplicação devolva uma frota publicada para localhost
+-- (regra da 031/043).
+INSERT INTO app.apps (id, name, icon, accent_color, url, requires, serves_verticals, active) VALUES
+  ('full', 'FullControl', 'Layers', '#1E3A8A', 'http://localhost:5307',
+   ARRAY['crm', 'conversations', 'marketing', 'automations', 'notifications',
+         'reports', 'financial', 'inventory'],
+   ARRAY[]::text[], true)
+ON CONFLICT (id) DO UPDATE
+  SET name = EXCLUDED.name, icon = EXCLUDED.icon, accent_color = EXCLUDED.accent_color,
+      active = true,
+      -- `requires` só CRESCE numa reaplicação: um marco posterior pode ter
+      -- somado um plugin depois deste arquivo, e sobrescrever aqui desfaria
+      -- aquele marco em silêncio.
+      requires = (SELECT array_agg(DISTINCT p ORDER BY p)
+                    FROM unnest(app.apps.requires || EXCLUDED.requires) AS p),
+      url = coalesce(app.apps.url, EXCLUDED.url);
+
+COMMENT ON TABLE app.apps IS
+  'Which applications exist on this cluster (001, 011, 043, 052). The registry the app switcher reads. An app is a LENS over a tenant''s rows — it never scopes them; two apps on one tenant share public.people by design. `requires` names the plugins the app cannot work without, and it is a SEEDING list, not a dependency check — app.tenant_plugins has no app_id, so a plugin required here is lit for the whole tenant. `url` doubles as the allow-list for the session handoff; NULL takes the app off every switcher. `active = false` retires a row without breaking the FK from app.tenant_apps.';
+
+-- ── §2  quem recebe: exatamente quem tinha o LeadControl ───────────────────
+--
+-- Carrega `status`, `source` e `added_by` da linha antiga: uma conta que tinha
+-- DESLIGADO o LeadControl não pode acordar com o FullControl aceso, e uma linha
+-- semeada pela plataforma ('default', 011 §3) não pode virar escolha de gente.
+INSERT INTO app.tenant_apps (tenant_id, app_id, status, source, added_by)
+SELECT ta.tenant_id, 'full', ta.status, ta.source, ta.added_by
+  FROM app.tenant_apps ta
+ WHERE ta.app_id = 'crm'
+ON CONFLICT (tenant_id, app_id) DO NOTHING;
+
+-- ── §3  a linha antiga é aposentada, não apagada ───────────────────────────
+--
+-- `active = false` já a tira do `app_config()` (008 filtra `a.active`), e
+-- `url = NULL` é o segundo cinto: o cliente também descarta app sem url
+-- (packages/admin/src/directory/directory.store.ts, normalize()). O nome fica,
+-- para que uma consulta de suporte sobre uma linha antiga ainda leia.
+UPDATE app.apps
+   SET active = false,
+       url    = NULL
+ WHERE id = 'crm';
+
+-- ── §4  o teto do plano passa a ter a linha do PLUGIN, não só das facets ───
+--
+-- Este bloco conserta um defeito que existia ANTES deste app e que só não
+-- apareceu porque as contas do dogfood não têm plano.
+--
+-- `plan_permits(plugin, facet, tenant)` casa a facet EXATAMENTE
+-- (000_baseline.sql), e "o plugin é a facet de nome vazio"
+-- (packages/core/src/types/plugins.ts). Todo caminho de semeadura chama com
+-- `facet = ''`: tenant_app_set (001), tenant_apply_vertical_defaults (010) e os
+-- backfills das migrations de app. Mas o seed de `app.plan_grants` só escreveu
+-- linhas de FACET (`financial.ledger`, `crm.contacts`, `inventory.stock`,
+-- `agenda.scheduling`) — com `facet = ''` existem apenas `tasks`, `forms` e
+-- `scale/marketing`.
+--
+-- Consequência: qualquer tenant COM plano é recusado no próprio plugin cujas
+-- facets o plano dele inclui, e `tenant_apply_plan` acende facets órfãs que a
+-- casca corretamente não lê como plugin (packages/core/src/app/app-config.ts).
+-- Sem este §4, o FullControl acende hoje (contas sem plano) e para de acender
+-- no dia em que alguém vender o primeiro plano — que é a pior hora possível
+-- para descobrir.
+--
+-- `included` só onde o plano JÁ inclui uma facet daquele plugin: ali a linha
+-- que falta é um defeito, não uma decisão de produto (é o "defeito 2" que a
+-- 010 §2 nomeia). Todo o resto entra como `optional`, e isso é deliberado:
+-- `plan_permits` NÃO lê o `mode`, então `optional` levanta o teto sem que
+-- `tenant_apply_plan` imponha o módulo a quem não pediu.
+DO $$
+DECLARE p text;
+BEGIN
+  IF to_regprocedure('public.register_plan_grant(text,text,text,text,text)') IS NULL THEN
+    RAISE NOTICE '052: register_plan_grant ausente — §4 pulado';
+    RETURN;
+  END IF;
+
+  -- 4.1 a linha do plugin para cada plugin cujas facets os planos já incluem.
+  FOREACH p IN ARRAY ARRAY['financial', 'inventory', 'crm', 'agenda'] LOOP
+    PERFORM public.register_plan_grant('essential', p, '', 'included',
+      'O plugin é a facet de nome vazio: sem esta linha o teto recusa o plugin cujas facets este plano inclui (052 §4).');
+    PERFORM public.register_plan_grant('pro',   p, '', 'included', NULL);
+    PERFORM public.register_plan_grant('scale', p, '', 'included', NULL);
+  END LOOP;
+
+  -- 4.2 o que o ERP soma, por plano. `optional` = permitido, não imposto.
+  -- No essential entram só os dois que atendem e cobram — um ERP inteiro não é
+  -- produto de plano básico.
+  PERFORM public.register_plan_grant('essential', 'conversations', '', 'optional', 'Onde o cliente e o fornecedor falam.');
+  PERFORM public.register_plan_grant('essential', 'notifications', '', 'optional', 'Toda cobrança e toda confirmação saem por aqui.');
+
+  FOREACH p IN ARRAY ARRAY['conversations', 'notifications', 'marketing', 'automations',
+                           'reports', 'tasks', 'forms'] LOOP
+    PERFORM public.register_plan_grant('pro',   p, '', 'optional', NULL);
+    PERFORM public.register_plan_grant('scale', p, '', 'optional', NULL);
+  END LOOP;
+
+  -- 4.3 os addons: permitidos só no topo, e nunca `included`.
+  PERFORM public.register_plan_grant('scale', 'fiscal-br',  '', 'optional', 'Addon: a emissão fiscal é contratada, não incluída.');
+  PERFORM public.register_plan_grant('scale', 'banking-br', '', 'optional', 'Addon: a conciliação bancária é contratada.');
+END $$;
+
+-- ── §5  os plugins que o app exige, com o teto do plano respeitado ─────────
+--
+-- DISTINCT porque um tenant que chega por dois caminhos faria o ON CONFLICT
+-- recusar tocar a linha duas vezes; `plan_permits` porque o teto do plano vence
+-- sempre sobre um padrão — uma conta cujo plano não inclui o plugin não o
+-- ganha aceso, e a semeadura não falha por isso (011 §3, mesma regra).
+INSERT INTO app.tenant_plugins (tenant_id, plugin_id, facet, status, source)
+SELECT DISTINCT ta.tenant_id, r.plugin_id, '', 'active', 'default'
+  FROM app.tenant_apps ta
+  JOIN app.apps a ON a.id = ta.app_id
+  CROSS JOIN LATERAL unnest(a.requires) AS r(plugin_id)
+ WHERE ta.app_id = 'full'
+   AND ta.status = 'active'
+   AND public.plan_permits(r.plugin_id, '', ta.tenant_id)
+ON CONFLICT (tenant_id, plugin_id, facet) DO NOTHING;
+
+-- ── §6  (comentado) o ramo órfão ───────────────────────────────────────────
+--
+-- 'agency' está em app.vertical_defaults desde o baseline e NENHUM app o serve:
+-- um tenant criado com vertical_id='agency' ganha plugins e zero apps. Se
+-- alguém decidir que o ERP genérico é a resposta honesta para esse ramo, é UMA
+-- linha — e ela merece uma migration própria, para poder ser revista sozinha:
+--   UPDATE app.apps SET serves_verticals = ARRAY['agency'] WHERE id = 'full';

package/migrations/053_o_erp_para_de_exigir_o_que_nao_desenha.sql

@@ -0,0 +1,37 @@
+-- ---------------------------------------------------------------------------
+-- 053_o_erp_para_de_exigir_o_que_nao_desenha.sql — o FullControl encolhe o
+-- `requires` para o que ele realmente monta.
+--
+-- A 052 registrou o app com oito plugins, e naquele dia ele montava os oito. No
+-- mesmo dia o recorte apertou: o FullControl é para a empresa que vende SERVIÇO
+-- e SOFTWARE — agência, software house, consultoria —, e duas coisas saíram do
+-- bundle por não existirem nessa casa:
+--
+--   `inventory`  prateleira. Quem tem estoque é atendido pelo StoreControl e
+--                pelo ChefControl, e um ERP que oferece contagem de inventário
+--                a quem não tem depósito é um formulário a mais.
+--   `marketing`  campanha e canal de aquisição. O funil fica (o orçamento é o
+--                começo do título), mas a máquina de aquisição é produto do
+--                LeadControl, que é justamente de onde este app veio.
+--
+-- ── Por que isso é uma migration, e não uma edição na 052 ──────────────────
+--
+-- A 052 já foi aplicada e o ledger guarda o sha256 dela; arquivo aplicado é
+-- congelado. E a 052 tem, de propósito, um `ON CONFLICT` que só faz `requires`
+-- CRESCER numa reaplicação — então nem reaplicá-la desfaria isto. Encolher é um
+-- ato explícito, e é este arquivo.
+--
+-- ── O que este arquivo NÃO faz: desligar plugin de ninguém ─────────────────
+--
+-- `requires` é lista de SEMEADURA, não de dependência: ele decide o que um
+-- tenant ganha ao ATIVAR o app daqui para a frente. As contas que já receberam
+-- `inventory` e `marketing` ficam com eles acesos, e isso está certo — a
+-- 052 §5 os acendeu para o TENANT (app.tenant_plugins não tem app_id), e o
+-- ChefControl e o StoreControl das mesmas contas estão de pé sobre `inventory`
+-- neste exato momento. Apagar a linha aqui apagaria o estoque do restaurante.
+-- ---------------------------------------------------------------------------
+
+UPDATE app.apps
+   SET requires = ARRAY['crm', 'conversations', 'automations', 'notifications',
+                        'reports', 'financial']
+ WHERE id = 'full';