@fayz-ai/db 0.13.0 → 0.15.0

package/migrations/022_the_line_says_which_document_it_belongs_to.sql

@@ -0,0 +1,109 @@
+-- ---------------------------------------------------------------------------
+-- 022_the_line_says_which_document_it_belongs_to.sql — `items.document_id`
+-- deixa de ser uma conta e vira uma coluna, para que exista índice sobre ela.
+--
+-- O SINTOMA: `GET /rest/v1/v_orders?select=id,total,status,fulfillment_status
+-- &id=in.(três ids)` devolvendo 500 com `57014: statement timeout`. Três
+-- pedidos por id — a consulta mais seletiva que existe.
+--
+-- ── A medição ──────────────────────────────────────────────────────────────
+--     ->  Index Scan using items_tenant_id_id_key on items i
+--           Index Cond: (tenant_id = …)                  ← só o tenant
+--           Filter: … AND (COALESCE(order_id, invoice_id, fulfillment_id,
+--                                   quote_id) = o.id)
+--           Rows Removed by Filter: 11560
+--           SubPlan 22  loops=34683   0,243ms            ← RLS por linha
+--           SubPlan 30  loops=34683   0,337ms
+--     Execution Time: 20368 ms
+--
+-- 11.561 itens do tenant varridos POR PEDIDO — 34.683 voltas — cada uma pagando
+-- duas funções de política. O `LEFT JOIN LATERAL` de `v_orders` até empurrou o
+-- filtro para dentro; o que não havia era por onde entrar.
+--
+-- ── Por que não havia índice possível ──────────────────────────────────────
+-- `v_items.document_id` era uma EXPRESSÃO:
+--
+--     COALESCE(order_id, invoice_id, fulfillment_id, quote_id) AS document_id
+--
+-- Uma linha de item aponta para o documento que a contém, e qual das quatro
+-- colunas está preenchida depende de `parent_kind`. A view unificava as quatro
+-- na leitura, o que é a modelagem certa — só que o filtro `document_id = X`
+-- passava a ser um filtro sobre uma conta, e nenhum índice de coluna atende.
+--
+-- Um índice de EXPRESSÃO resolve com constante — medido, 0,159ms — mas não foi
+-- usado quando o valor chega como parâmetro de um LATERAL através de duas views
+-- empilhadas (`v_orders` → `v_item_balances` → `v_items`): o planejador deixa
+-- de casar a expressão em algum ponto do empilhamento e cai para a varredura.
+--
+-- Depender de o planejador reconhecer a mesma expressão através de três níveis
+-- de view é uma aposta, e esta é a segunda vez que ela sai cara.
+--
+-- ── A correção ─────────────────────────────────────────────────────────────
+-- A conta vira coluna: `items.document_id`, GENERATED ALWAYS … STORED. O valor
+-- é exatamente o mesmo — o Postgres é quem o mantém, e não há caminho de
+-- escrita que possa discordar dele. Sobre uma coluna real o índice é trivial e
+-- o planejador não precisa reconhecer nada.
+--
+-- `v_items` passa a ler a coluna em vez de recalcular. Mesmo nome, mesma
+-- posição, mesmo tipo: nada a jusante percebe.
+--
+-- Resultado, mesma consulta: 20.368ms → 192ms, com
+--     Index Cond: ((document_id = o.id) AND (parent_kind = 'order'))
+-- e as políticas de `items` saindo do laço junto com as 11.560 linhas que
+-- deixaram de ser lidas.
+-- ---------------------------------------------------------------------------
+
+-- A coluna. `IF NOT EXISTS` porque a migration é reaplicável; GENERATED porque
+-- o valor não é opinião de quem escreve — é derivado, e derivar no banco impede
+-- que uma porta de escrita nova esqueça de preencher.
+ALTER TABLE public.items
+  ADD COLUMN IF NOT EXISTS document_id uuid
+  GENERATED ALWAYS AS (COALESCE(order_id, invoice_id, fulfillment_id, quote_id)) STORED;
+
+COMMENT ON COLUMN public.items.document_id IS
+  'O documento que contém esta linha (#022), derivado de order_id/invoice_id/fulfillment_id/quote_id conforme parent_kind. Coluna e não expressão porque `v_orders` filtra por ela através de duas views empilhadas, e um índice de expressão deixa de ser reconhecido nesse caminho — era uma varredura de 11.561 itens por pedido.';
+
+-- (tenant_id, document_id, parent_kind): o tenant primeiro como todo índice
+-- daqui, o documento em seguida porque é o que a busca conhece, e o parent_kind
+-- por último porque é o que desempata.
+CREATE INDEX IF NOT EXISTS items_tenant_document_col_idx
+  ON public.items (tenant_id, document_id, parent_kind);
+
+-- O índice de expressão da primeira tentativa, se ficou para trás.
+DROP INDEX IF EXISTS public.items_tenant_document_idx;
+
+-- A view lê a coluna. Mesmas colunas, mesma ordem, mesmos tipos.
+-- `WITH (security_invoker = true)` explícito: `CREATE OR REPLACE VIEW` NÃO
+-- herda as opções da view que substitui, e sem isto ela volta a rodar com os
+-- direitos do dono — as políticas de quem lê deixam de valer. É o que a
+-- asserção N16 da postura grada, e foi ela que pegou.
+CREATE OR REPLACE VIEW public.v_items WITH (security_invoker = true) AS
+ SELECT id,
+    tenant_id,
+    unit_id,
+    parent_kind,
+    document_id,
+    order_id,
+    invoice_id,
+    fulfillment_id,
+    quote_id,
+    product_id,
+    variant_id,
+    -- `service_id` NÃO entra: ele existe no cluster onde esta migration foi
+    -- escrita e não na corrente canônica, então redeclarar a view com ele
+    -- quebrava o `apply` com "column service_id does not exist". A view
+    -- reproduz o conjunto de colunas do baseline, mais `document_id`.
+    name,
+    description,
+    quantity,
+    unit_price,
+    discount,
+    total,
+    sort_order,
+    metadata,
+    custom_fields,
+    created_at,
+    updated_at
+   FROM items i;
+
+ANALYZE public.items;

package/migrations/029_o_administrador_enxerga_o_que_existe.sql

@@ -0,0 +1,167 @@
+-- 029_o_administrador_enxerga_o_que_existe.sql
+--
+-- O rail do LeadControl abria com duas linhas — Painel e Análises — enquanto o
+-- painel logo abaixo mostrava "Total de Leads: 20". Os dados estavam lá, os
+-- plugins montados, o console limpo. Só o MENU estava vazio.
+--
+-- A causa não é do app. É esta assimetria, no `app.seed_role_template`:
+--
+--     -- o Owner recebe o CATÁLOGO, e o catálogo cresce sozinho
+--     INSERT INTO app.role_permissions
+--     SELECT p_tenant, v_owner, p.key FROM app.permissions p;
+--
+--     -- todos os outros recebem uma LISTA, escrita à mão, que não cresce
+--     INSERT INTO app.role_permissions
+--     SELECT p_tenant, r.id, t.permission FROM app.role_templates t ...
+--
+-- Um plugin publicado depois que aquela lista foi escrita registra as suas
+-- permissões em `app.permissions` e, a partir daí, chega ao Owner de graça e
+-- **a mais ninguém, nunca**. Não há aviso: `AdminShell` esconde a linha do rail
+-- quando a negação é por PAPEL (negação por PLANO manteria a linha com a coroa),
+-- então o sintoma é um menu curto, que parece escolha de produto.
+--
+-- Medido no cluster antes desta migration, em 10 tenants:
+--
+--     Administrator/Manager que enxergam crm.*            0 de 10
+--     Administrator/Manager que enxergam conversations.*  0 de 10
+--
+-- E não são só esses dois. Comparando Owner com Administrator num tenant real,
+-- faltavam ao Administrator DEZENOVE features: appointments, automations, blog,
+-- config, conversations, courses, crm, custom_forms, dashboard, marketing,
+-- menu, reputation, sales, scribe, shop, sites, tables e mais. Ou seja: quase
+-- todo plugin que o SDK ganhou desde que a lista foi escrita.
+--
+-- Por isso a correção NÃO é acrescentar quatro linhas à lista. Acrescentar
+-- quatro linhas conserta a queixa de hoje e reprograma a mesma queixa para o
+-- próximo plugin. A correção é tirar o Administrador da lista e colocá-lo no
+-- CATÁLOGO, como o Owner — menos o que é do dono.
+--
+-- O que continua sendo lista, de propósito: manager, staff e viewer. Esses são
+-- recortes deliberados — um "Viewer" que enxerga tudo o que existe deixou de
+-- ser viewer. Eles vão continuar precisando de decisão a cada plugin novo; a
+-- diferença é que agora ALGUÉM abaixo do dono enxerga o plugin no dia em que
+-- ele registra as permissões, e o buraco aparece na hora em vez de meses depois.
+
+-- ── o que é do dono ────────────────────────────────────────────────────────
+--
+-- Precisa ser uma marca no catálogo, não uma lista no meio de uma função: quem
+-- registra uma permissão nova é o plugin, e é ele que sabe se ela é do dono.
+ALTER TABLE app.permissions
+  ADD COLUMN IF NOT EXISTS owner_only boolean DEFAULT false NOT NULL;
+
+COMMENT ON COLUMN app.permissions.owner_only IS
+  'Permissão que só o Owner recebe. O Administrador recebe todo o resto do catálogo automaticamente (029).';
+
+-- Assinatura, cartão e cancelamento são do dono. E `admin.*` é o painel da
+-- PLATAFORMA — não é papel de tenant nenhum, nem do dono da loja.
+--
+-- `owner_only` governa o que se CONCEDE daqui para frente; não revoga o que já
+-- foi concedido. Um Administrador que hoje tem `billing.read` porque a lista
+-- antiga o deu continua tendo: tirar permissão de quem já trabalha com ela é
+-- uma quebra, e esta migration veio consertar um menu vazio, não estreitar
+-- ninguém.
+UPDATE app.permissions SET owner_only = true
+ WHERE key ~ '^(billing|admin)\.' AND owner_only = false;
+
+-- ── o administrador passa a ler o catálogo ─────────────────────────────────
+CREATE OR REPLACE FUNCTION app.seed_role_template(p_tenant uuid, p_template text DEFAULT 'generic'::text) RETURNS uuid
+    LANGUAGE plpgsql SECURITY DEFINER
+    SET search_path TO ''
+    AS $$
+DECLARE v_owner uuid;
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM app.role_templates WHERE template = p_template) THEN
+    RAISE EXCEPTION 'seed_role_template: unknown template %', p_template;
+  END IF;
+
+  INSERT INTO app.roles (tenant_id, key, name, is_system)
+  VALUES (p_tenant, 'owner', 'Owner', true)
+  ON CONFLICT (tenant_id, key) DO NOTHING;
+  SELECT id INTO v_owner FROM app.roles WHERE tenant_id = p_tenant AND key = 'owner';
+
+  INSERT INTO app.role_permissions (tenant_id, role_id, permission)
+  SELECT p_tenant, v_owner, p.key FROM app.permissions p
+  ON CONFLICT DO NOTHING;
+
+  INSERT INTO app.roles (tenant_id, key, name, is_system)
+  SELECT DISTINCT ON (t.role_key) p_tenant, t.role_key, t.role_name, true
+    FROM app.role_templates t WHERE t.template = p_template
+   ORDER BY t.role_key
+  ON CONFLICT (tenant_id, key) DO NOTHING;
+
+  INSERT INTO app.role_permissions (tenant_id, role_id, permission)
+  SELECT p_tenant, r.id, t.permission
+    FROM app.role_templates t
+    JOIN app.roles r ON r.tenant_id = p_tenant AND r.key = t.role_key
+   WHERE t.template = p_template
+  ON CONFLICT DO NOTHING;
+
+  -- A linha que faltava. O papel `admin` ganha o catálogo menos o que é do
+  -- dono, DEPOIS da lista — o que a lista já deu continua dado, e o que ela
+  -- esqueceu deixa de importar. Só age se o template realmente tiver um papel
+  -- `admin`: um template sem administrador não passa a ter um por isto.
+  INSERT INTO app.role_permissions (tenant_id, role_id, permission)
+  SELECT p_tenant, r.id, p.key
+    FROM app.roles r
+    CROSS JOIN app.permissions p
+   WHERE r.tenant_id = p_tenant AND r.key = 'admin' AND p.owner_only = false
+  ON CONFLICT DO NOTHING;
+
+  RETURN v_owner;
+END $$;
+
+COMMENT ON FUNCTION app.seed_role_template(uuid, text) IS
+  'Semeia os papéis do template. Owner e Administrador leem o CATÁLOGO (o admin sem o que é do dono); manager/staff/viewer seguem sendo recortes deliberados (029).';
+
+-- ── as casas que já nasceram cegas ─────────────────────────────────────────
+--
+-- A função acima conserta quem nascer daqui para frente. Os dez tenants que já
+-- existem precisam da mesma conta, aplicada agora.
+DO $$
+DECLARE v_admin integer; v_mgr integer;
+BEGIN
+  INSERT INTO app.role_permissions (tenant_id, role_id, permission)
+  SELECT r.tenant_id, r.id, p.key
+    FROM app.roles r
+    CROSS JOIN app.permissions p
+   WHERE r.key = 'admin' AND p.owner_only = false
+  ON CONFLICT DO NOTHING;
+  GET DIAGNOSTICS v_admin = ROW_COUNT;
+
+  -- O gerente é recorte, não catálogo: ele opera a casa, não a administra.
+  -- Recebe ler/criar/editar do que o LeadControl põe no rail, e não recebe
+  -- apagar nem gerir — apagar conversa e gerir integração continuam acima
+  -- dele. `regexp_replace` pega o último segmento porque as chaves têm dois
+  -- formatos no catálogo: `sales.read` e `crm.leads.read`.
+  INSERT INTO app.role_permissions (tenant_id, role_id, permission)
+  SELECT r.tenant_id, r.id, p.key
+    FROM app.roles r
+    CROSS JOIN app.permissions p
+   WHERE r.key = 'manager'
+     AND p.owner_only = false
+     AND p.key ~ '^(crm|sales|conversations|marketing|automations)\.'
+     AND regexp_replace(p.key, '^.*\.', '') IN ('read', 'create', 'edit')
+  ON CONFLICT DO NOTHING;
+  GET DIAGNOSTICS v_mgr = ROW_COUNT;
+
+  RAISE NOTICE '029: % permissões devolvidas ao Administrador, % ao Gerente', v_admin, v_mgr;
+END $$;
+
+-- E o mesmo recorte entra no TEMPLATE do gerente, para o próximo tenant nascer
+-- com ele. O administrador não precisa de linha aqui: ele passou a ler o
+-- catálogo, e uma linha de template para ele seria a lista voltando pela porta
+-- dos fundos.
+INSERT INTO app.role_templates (template, role_key, role_name, sort_order, permission)
+SELECT m.template, 'manager', m.role_name, m.sort_order, p.key
+  FROM (SELECT DISTINCT ON (template) template, role_name, sort_order
+          FROM app.role_templates WHERE role_key = 'manager'
+         ORDER BY template) m
+  CROSS JOIN app.permissions p
+ WHERE p.owner_only = false
+   AND p.key ~ '^(crm|sales|conversations|marketing|automations)\.'
+   AND regexp_replace(p.key, '^.*\.', '') IN ('read', 'create', 'edit')
+   -- NOT EXISTS em vez de ON CONFLICT: esta tabela é um catálogo sem chave
+   -- única declarada, e ali ON CONFLICT DO NOTHING não protege de nada.
+   AND NOT EXISTS (
+     SELECT 1 FROM app.role_templates x
+      WHERE x.template = m.template AND x.role_key = 'manager' AND x.permission = p.key);

package/migrations/031_ticketcontrol_joins_the_family.sql

@@ -0,0 +1,109 @@
+-- ---------------------------------------------------------------------------
+-- 031_ticketcontrol_joins_the_family.sql — a casa de shows ganha uma linha.
+--
+-- O registro tem seis produtos: quatro TRADES (cozinha, loja, estúdio, escola),
+-- uma FUNÇÃO que transbordou de aba para app (LeadControl, 011) e o painel da
+-- própria casa (control-admin, 028). Este é o sétimo, e é um trade — mas um
+-- trade que o ChefControl já toca pela metade.
+--
+-- ── Por que não é uma aba do ChefControl ───────────────────────────────────
+-- Um bar que faz evento já cadastra o cardápio, o estoque e o caixa no Chef. O
+-- que ele NÃO tem lá é o evento: a noite com data, capacidade por setor, lote
+-- que vira lote, ingresso que precisa ser recusado na porta quando já entrou.
+-- Isso não é uma tela a mais num app de restaurante — é outro turno, outra
+-- equipe (guichê, portaria, promoter) e outro fechamento.
+--
+-- E é justamente por serem o MESMO TENANT que os dois convivem: `people`,
+-- `orders`, `items` e o financeiro são os mesmos dos dois lados do switcher. A
+-- pessoa que comprou o ingresso é a que abre comanda no bar, na mesma linha.
+-- Nenhum concorrente brasileiro entrega isso porque nenhum é dono dos dois
+-- lados: a bilheteria (Sympla, Ingresse) larga na porta, e o cashless (Zig)
+-- começa nela.
+--
+-- ── `serves_verticals` fica VAZIO, de propósito ────────────────────────────
+-- A 010 fez dessa coluna o gatilho de semeadura automática: um tenant que
+-- declara um ramo ganha todo app que serve aquele ramo. Listar 'food' e
+-- 'restaurant' aqui seria quase verdade — muito bar faz evento — e significaria
+-- que TODO restaurante criado a partir de amanhã cresceria um segundo produto
+-- no switcher que ninguém pediu e ninguém configurou. Um app que chega sem ser
+-- convidado não é uma funcionalidade, é um chamado de suporte sobre uma tela
+-- vazia. Este é opt-in: `tenant_app_set('ticket', ...)`.
+--
+-- ── `requires` nomeia cinco plugins ────────────────────────────────────────
+-- `menu` e `inventory` são o bar; `orders` é o pedido (do ingresso E da
+-- comanda, na mesma tabela); `financial` é o caixa onde a noite fecha;
+-- `conversations` é por onde o público pergunta a hora de abrir. Sem esses
+-- cinco o app abre num rail com Painel e placeholders.
+--
+-- O que NÃO está aqui: um plugin `events`. Ele nasce em M1 (ver
+-- fayz-app/ticket-control/docs/ROADMAP.md) e é quando esta linha ganha o sexto
+-- nome — a migration que criar as tabelas de evento é a mesma que atualiza este
+-- array.
+-- ---------------------------------------------------------------------------
+
+-- ── §1  a linha do registro ────────────────────────────────────────────────
+--
+-- O nome é o nome de FORA (ADR: "Control" é a família, não o app). O rail
+-- dentro diz só "Ticket"; a lista do switcher é de fora, então carrega inteiro.
+--
+-- #820AD1 e não outro roxo: a ficha É o produto num lançador, e o violeta claro
+-- (#7C3AED) já é do StudioControl. Este é 18° adiante na roda e 23 pontos mais
+-- escuro — lado a lado eles leem como duas cores, não como dois degraus de uma.
+-- O dividendo prático de escolher o degrau ESCURO: branco sobre ele dá 7,2:1, e
+-- a marca pode simplesmente ser o botão (o ouro do Chef não pode).
+--
+-- `url` é a origem de dev enquanto o app não é publicado, e é deliberadamente
+-- visível: a coluna É a allow-list do handoff de sessão, então trocá-la é o
+-- passo de deploy, não um detalhe.
+INSERT INTO app.apps (id, name, icon, accent_color, url, requires, serves_verticals, active) VALUES
+  ('ticket', 'TicketControl', 'Ticket', '#820AD1', 'http://localhost:5308',
+   ARRAY['menu', 'inventory', 'orders', 'financial', 'conversations'],
+   ARRAY[]::text[], true)
+ON CONFLICT (id) DO UPDATE
+  SET name = EXCLUDED.name, icon = EXCLUDED.icon, accent_color = EXCLUDED.accent_color,
+      requires = EXCLUDED.requires, active = true,
+      -- A URL NÃO é sobrescrita numa reaplicação: quem publicar o app aponta a
+      -- coluna para o endereço real, e uma migration que reaplica não pode
+      -- devolver a frota para localhost. (Mesma regra da 028.)
+      url = coalesce(app.apps.url, EXCLUDED.url);
+
+-- ── §2  quem recebe agora ──────────────────────────────────────────────────
+--
+-- Só as contas de creators@fayalabs.com que JÁ têm cardápio ativo — ou seja, as
+-- casas que já operam um bar nesta plataforma, que é a evidência honesta de que
+-- "o bar que também faz evento" é a história delas.
+--
+-- Restrito ao dono do dogfood de propósito, e isto é o que difere da 011: a
+-- LeadControl estava pronta quando ganhou a linha. Este app está em M0 — o rail
+-- é real, metade das telas ainda é placeholder que diz de qual marco é. Ligá-lo
+-- para todo restaurante do cluster seria distribuir um produto pela metade.
+-- Quando M2 fechar (o ingresso vira dinheiro), a regra geral entra numa
+-- migration própria, que é onde ela pode ser revista sozinha.
+INSERT INTO app.tenant_apps (tenant_id, app_id, status, source)
+SELECT DISTINCT m.tenant_id, 'ticket', 'active', 'manual'
+  FROM app.memberships m
+  JOIN auth.users u ON u.id = m.user_id
+ WHERE u.email = 'creators@fayalabs.com'
+   AND m.active
+   AND EXISTS (
+     SELECT 1 FROM app.tenant_plugins tp
+      WHERE tp.tenant_id = m.tenant_id AND tp.plugin_id = 'menu'
+        AND tp.facet = '' AND tp.status = 'active'
+   )
+ON CONFLICT (tenant_id, app_id) DO NOTHING;
+
+-- E os plugins que ele precisa, para exatamente essas contas — senão o app abre
+-- num rail com Painel e nada mais, porque a shell monta o rail com o que
+-- app_config() devolve em `plugins`.
+--
+-- O teto do plano ganha do padrão, sempre: uma conta cujo plano não inclui o
+-- plugin não o acende, e a semeadura não falha por isso.
+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 = 'ticket'
+   AND ta.status = 'active'
+   AND public.plan_permits(r.plugin_id, '', ta.tenant_id)
+ON CONFLICT (tenant_id, plugin_id, facet) DO NOTHING;