@fayz-ai/db 0.16.0 → 0.17.0

package/migrations/116_o_sdr_agrupa_a_empresa_que_ele_prospecta.sql

@@ -0,0 +1,84 @@
+-- ---------------------------------------------------------------------------
+-- 116_o_sdr_agrupa_a_empresa_que_ele_prospecta.sql — a chave que faltava no
+-- recorte da 071.
+--
+-- ── o buraco ────────────────────────────────────────────────────────────
+--
+-- A 071 desenhou o SDR: leads, funil, orçamento, conversa. Não deu
+-- `crm.companies`, e na época isso parecia certo — prospectar é falar com
+-- gente, não manter cadastro de empresa.
+--
+-- Depois vieram os grupos: raiz de CNPJ (015), bandeira e federação (crm/039).
+-- A proposta é automática e ERRA — é um palpite sobre nome e raiz, e cinco
+-- Abrasel com cinco raízes distintas são a mesma instituição enquanto
+-- `RESTAURANTE` com onze empresas não é parentesco nenhum. Quem vê o erro é
+-- quem trabalha a lista, e quem trabalha a lista é o SDR.
+--
+-- E a tela de Grupos não é uma rota própria: mora DENTRO de Empresas, cuja
+-- rota pede `crm.companies.read`. Sem esta chave o SDR não só não agrupa —
+-- ele não chega à tela. Medido no cluster: 20 papéis `sdr`, nenhum com
+-- qualquer permissão `crm.companies`.
+--
+-- ── por que um arquivo novo e não uma correção na 071 ───────────────────
+--
+-- A 071 já rodou, e está no ledger com o checksum do que rodou. Reescrevê-la
+-- faria a linha do ledger descrever um arquivo que ninguém aplicou — é o
+-- mesmo defeito que o `check-ledger-drift` chama de DRIFT e que faz um
+-- `fayz db apply` parar no meio.
+--
+-- ── `edit` e não `manage` ───────────────────────────────────────────────
+--
+-- Agrupar, desagrupar e corrigir o nome do grupo: sim. Apagar empresa: não.
+-- Uma empresa apagada leva junto os contatos que penduram nela, e isso é
+-- decisão de quem responde pela carteira, não de quem prospecta.
+-- ---------------------------------------------------------------------------
+
+-- ── primeiro: `crm.companies` NÃO ESTÁ NO CATÁLOGO ─────────────────────────
+--
+-- Medido antes de escrever isto: `app.permissions` tem 15 chaves `crm.*` —
+-- `leads`, `pipeline` e `quotes`, cinco ações cada — e NENHUMA de `companies`.
+-- Mas a rota de Empresas do plugin-crm pede `crm.companies.read`, e as telas
+-- do app concedem `crm.companies` a owner, gerente e vendas.
+--
+-- Ou seja: a chave é exigida pela rota e concedida pelo app, e o catálogo do
+-- banco nunca soube dela. Conceder a alguém uma chave que o catálogo não tem
+-- é escrever numa linha que ninguém lê — a 071 já se protege disso com o
+-- `WHERE EXISTS` logo abaixo, e é por isso que este arquivo registra antes de
+-- conceder.
+--
+-- As cinco ações, como os irmãos `crm.leads` e `crm.quotes` têm. Registrar
+-- todas mantém o vocabulário parelho; quem recebe cada uma é decisão de papel,
+-- não de catálogo.
+INSERT INTO app.permissions (key, plugin)
+SELECT 'crm.companies.' || a, 'crm'
+  FROM unnest(ARRAY['read', 'create', 'edit', 'delete', 'manage']) AS a
+ON CONFLICT (key) DO NOTHING;
+
+-- ── depois: o recorte do SDR ───────────────────────────────────────────────
+INSERT INTO app.role_templates (template, role_key, role_name, sort_order, permission)
+SELECT 'generic', 'sdr', 'SDR', 3, p
+  FROM unnest(ARRAY['crm.companies.read', 'crm.companies.edit']) AS p
+ -- Só o que o catálogo realmente tem: uma chave inventada aqui vira uma
+ -- permissão que nenhuma tela consulta — silenciosa, e por isso pior que um
+ -- erro. Mesma guarda da 071.
+ WHERE EXISTS (SELECT 1 FROM app.permissions perm WHERE perm.key = p)
+ON CONFLICT DO NOTHING;
+
+-- ── quem já tem o papel recebe a chave agora ───────────────────────────────
+--
+-- Sem isto a migration só serve a quem nascer depois dela, e os 20 SDR que já
+-- existem seguem sem alcançar a tela — que é exatamente o defeito em aberto.
+DO $$
+DECLARE v_perms integer;
+BEGIN
+  INSERT INTO app.role_permissions (tenant_id, role_id, permission)
+  SELECT r.tenant_id, r.id, t.permission
+    FROM app.roles r
+    JOIN app.role_templates t ON t.template = 'generic' AND t.role_key = 'sdr'
+   WHERE r.key = 'sdr'
+     AND t.permission LIKE 'crm.companies.%'
+  ON CONFLICT DO NOTHING;
+  GET DIAGNOSTICS v_perms = ROW_COUNT;
+
+  RAISE NOTICE '116: % permissão(ões) crm.companies concedida(s) a papéis SDR', v_perms;
+END $$;

package/migrations/117_o_instagram_e_um_canal_de_contato.sql

@@ -0,0 +1,41 @@
+-- ---------------------------------------------------------------------------
+-- 117_o_instagram_e_um_canal_de_contato.sql
+--
+-- ── por que coluna, e não `custom_fields` ───────────────────────────────
+--
+-- `people` já tem `custom_fields` e `metadata`, e a tentação é pôr o Instagram
+-- num deles para não mexer na espinha. Este repo já pagou por essa escolha: a
+-- importação do Salão Abrasel pôs as 46 respostas do credenciamento em
+-- `custom_fields` e o resultado foram 297 fichas com os dados no banco e três
+-- campos na tela — porque NENHUMA tela de pessoa lê `custom_fields`. Está
+-- escrito no cabeçalho do `import_crm.py`: um dado que o produto não abre não
+-- está importado, está arquivado.
+--
+-- Coluna também é o que torna o campo buscável, exportável e ordenável sem
+-- nenhum trabalho a mais — e um vendedor que preenche um handle quer achar a
+-- ficha por ele depois.
+--
+-- ── e por que na ESPINHA, e não só no CRM ───────────────────────────────
+--
+-- Instagram é canal de contato, do mesmo tipo de `email` e `phone`, que já
+-- moram aqui. Não é um conceito de vendas: a clínica tem o Instagram da
+-- paciente, o salão tem o da cliente, o restaurante tem o do fornecedor.
+-- Pôr no plugin-crm obrigaria toda vertical que quisesse o campo a instalar um
+-- CRM, e a segunda que precisasse criaria a sua própria coluna com outro nome.
+--
+-- ── texto simples, sem CHECK ────────────────────────────────────────────
+--
+-- Quem digita vai escrever `@fulano`, `fulano`, `instagram.com/fulano` e
+-- `https://www.instagram.com/fulano/`. Uma restrição que recusasse três dessas
+-- formas transformaria um campo opcional numa briga — e o vendedor pararia de
+-- preencher, que é o único modo de este campo falhar de verdade.
+--
+-- A normalização acontece na ESCRITA, na tela, onde há quem corrigir. O banco
+-- guarda o que chegou.
+-- ---------------------------------------------------------------------------
+
+ALTER TABLE public.people
+  ADD COLUMN IF NOT EXISTS instagram text;
+
+COMMENT ON COLUMN public.people.instagram IS
+  'O @ da pessoa, preenchido à mão por quem fala com ela. Canal de contato, ao lado de email e phone — não é conceito de vendas (117).';

package/migrations/118_a_view_mascarada_acompanha_a_tabela.sql

@@ -0,0 +1,46 @@
+-- ---------------------------------------------------------------------------
+-- 118_a_view_mascarada_acompanha_a_tabela.sql
+--
+-- ── o que o teste pegou ─────────────────────────────────────────────────
+--
+-- A 117 acrescentou `people.instagram` e `v_people` — a view mascarada — ficou
+-- para trás. O `N16d` reclamou na hora, e o cabeçalho dele diz exatamente por
+-- que a regra existe: uma coluna que existe na tabela e falta na view lê, do
+-- lado do cliente, como "não existe esse campo" — não como um erro (#222).
+--
+-- Foi o teste que achou, não eu. Eu tinha conferido `v_leads` e `v_crm_leads`
+-- e parado ali, satisfeito por ter lembrado das views. `v_people` é uma
+-- terceira, gerada por outro mecanismo, e nenhuma leitura minha do código
+-- teria mostrado isso — `app.masked_views` é um registro, não um `CREATE VIEW`
+-- que se encontra buscando por nome.
+--
+-- ── e `phone_digits` já estava atrás ────────────────────────────────────
+--
+-- `app.masked_views_stale()` aponta duas colunas, não uma: `instagram` (minha)
+-- e `phone_digits`, que entrou antes e passou pelo mesmo buraco. Regenerar
+-- resolve as duas — e esta é a diferença entre corrigir a view à mão e chamar
+-- quem a gera: à mão eu consertaria só a que me incomoda.
+--
+-- ── por isso `masked_view_refresh`, e não um CREATE VIEW ────────────────
+--
+-- A view é DERIVADA: as colunas mascaradas saem de `app.masked_columns` e do
+-- contexto registrado. Escrevê-la à mão aqui congelaria a saída de hoje e a
+-- próxima coluna voltaria a ficar para trás — com a diferença de que, aí, o
+-- gerador e o arquivo discordariam sobre quem manda.
+-- ---------------------------------------------------------------------------
+
+DO $$
+DECLARE r record;
+BEGIN
+  -- Toda view mascarada atrasada, e não só a de `people`: a regra é "nenhuma
+  -- fica para trás", e consertar uma de cada vez é como se acumulam as outras.
+  FOR r IN
+    SELECT m.table_schema, m.table_name, m.context, m.reference
+      FROM app.masked_views m
+      JOIN app.masked_views_stale() s ON s.table_name = m.table_name
+  LOOP
+    PERFORM app.masked_view_refresh(
+      format('%I.%I', r.table_schema, r.table_name)::regclass, r.context, r.reference);
+    RAISE NOTICE 'db/118: % regenerada', r.table_name;
+  END LOOP;
+END $$;

package/migrations/119_a_reuniao_tem_mais_de_uma_pessoa.sql

@@ -0,0 +1,155 @@
+-- ---------------------------------------------------------------------------
+-- 119_a_reuniao_tem_mais_de_uma_pessoa.sql
+--
+-- ── o buraco ────────────────────────────────────────────────────────────
+--
+-- Um compromisso tem UMA pessoa responsável (`appointments.assignee_id`) e UM
+-- cliente (`party_id`). Isso descreve bem um corte de cabelo e uma consulta:
+-- um profissional atende uma pessoa.
+--
+-- Não descreve uma reunião comercial. Ali sentam o vendedor, o dono do
+-- restaurante, às vezes o sócio dele e alguém do time que entra só para a
+-- parte técnica. Hoje não há onde escrever isso, e quem tenta acaba pondo
+-- nome no campo de observações — que ninguém consegue filtrar depois.
+--
+-- ── por que não usar o que já existe ────────────────────────────────────
+--
+-- `appointment_items.assignee_id` aceita N profissionais. Parece servir, e não
+-- serve: cada linha ali é um ITEM DE SERVIÇO, com preço e duração. Pôr uma
+-- pessoa na reunião exigiria inventar um serviço para ela, e um cadastro que
+-- existe só para satisfazer uma validação é pior que o campo que faltava.
+--
+-- Alargar `assignee_id` para uma lista seria o outro caminho, e é o caminho
+-- que quebra todo mundo: toda vertical lê essa coluna esperando uma pessoa.
+--
+-- ── por que isto não muda nada para quem já usa a agenda ────────────────
+--
+-- Tabela NOVA, nenhum ALTER. `appointments` sai daqui com exatamente as
+-- colunas com que entrou, e `agenda_booking_create` não é tocada — acrescentar
+-- parâmetro a uma função no Postgres cria uma SEGUNDA função, e as duas
+-- convivendo deixam a chamada ambígua para todo mundo que já chamava.
+--
+-- Salão, clínica e restaurante nunca inserem uma linha aqui. Uma tabela sem
+-- linhas é invisível: o comportamento deles continua idêntico.
+--
+-- ── espinha, e não plugin ───────────────────────────────────────────────
+--
+-- "Quem está neste compromisso" é pergunta de agenda, não de CRM. A relação é
+-- `appointments` → `people`, as duas da espinha. Um `plg_crm_*` aqui obrigaria
+-- qualquer outra vertical a instalar o CRM para poder convidar alguém.
+--
+-- Idempotente e replay-safe.
+-- ---------------------------------------------------------------------------
+
+CREATE TABLE IF NOT EXISTS public.appointment_attendees (
+  id          uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id   uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
+  -- `booking_id`, e não `appointment_id`: é o nome que `appointment_items` já
+  -- usa para apontar para a mesma tabela. Duas colunas irmãs com nomes
+  -- diferentes para a mesma coisa é o tipo de detalhe que faz alguém escrever
+  -- o JOIN errado às duas da manhã.
+  booking_id  uuid NOT NULL REFERENCES public.appointments(id) ON DELETE CASCADE,
+  -- CASCADE e não SET NULL: convidado sem pessoa não é convidado, é lixo. Se a
+  -- pessoa sai da base, a linha sai junto.
+  person_id   uuid NOT NULL REFERENCES public.people(id) ON DELETE CASCADE,
+  -- `required` | `optional`. Texto livre com CHECK em vez de enum: a agenda do
+  -- Google fala a mesma língua, e o dia em que precisarmos de `organizer` a
+  -- mudança é um CHECK, não um tipo com dependentes.
+  --
+  -- NÃO pode se chamar `kind`: esse nome é reservado às colunas de espécie, e
+  -- toda coluna `kind` tem que ter um registro `*_kinds` com chave estrangeira
+  -- atrás dela (check-kind-registry). Isto aqui não é uma espécie.
+  role        text NOT NULL DEFAULT 'required',
+  metadata    jsonb NOT NULL DEFAULT '{}'::jsonb,
+  created_at  timestamptz NOT NULL DEFAULT now(),
+  updated_at  timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT appointment_attendees_role_check
+    CHECK (role IN ('required', 'optional'))
+);
+
+-- A mesma pessoa duas vezes na mesma reunião não quer dizer nada. O formulário
+-- já evita, mas o formulário não é a última palavra: duas abas abertas, um
+-- clique duplo e um retry de rede chegam aqui sem passar por ele.
+CREATE UNIQUE INDEX IF NOT EXISTS appointment_attendees_booking_person_idx
+  ON public.appointment_attendees (booking_id, person_id);
+
+-- Ler os convidados DE UMA reserva é a única pergunta que a tela faz.
+CREATE INDEX IF NOT EXISTS appointment_attendees_booking_idx
+  ON public.appointment_attendees (tenant_id, booking_id);
+
+-- "Em que reuniões esta pessoa está" — a pergunta do outro lado, que a tela do
+-- lead vai querer quando alguém abrir o perfil.
+CREATE INDEX IF NOT EXISTS appointment_attendees_person_idx
+  ON public.appointment_attendees (tenant_id, person_id);
+
+COMMENT ON TABLE public.appointment_attendees IS
+  'Quem mais está no compromisso, além do responsável. `assignee_id` continua sendo UM profissional — convidado é adição, não substituição (119).';
+COMMENT ON COLUMN public.appointment_attendees.role IS
+  'required | optional — quem precisa estar e quem é bem-vindo.';
+
+-- ---------------------------------------------------------------------------
+-- O escopo herdado do compromisso
+--
+-- Quem grava um convidado sabe a reunião e a pessoa; não tem por que saber o
+-- tenant nem a unidade. Deixar isso a cargo do cliente é como o `tenant_id`
+-- errado entra numa tabela — e com RLS ligada o erro não aparece como erro,
+-- aparece como linha que sumiu.
+--
+-- Cópia fiel de `trg_appointment_items_inherit_scope`, a irmã ao lado.
+-- ---------------------------------------------------------------------------
+
+CREATE OR REPLACE FUNCTION public.trg_appointment_attendees_inherit_scope()
+RETURNS trigger
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = ''
+AS $$
+BEGIN
+  IF NEW.tenant_id IS NULL OR NEW.unit_id IS NULL THEN
+    SELECT coalesce(NEW.tenant_id, a.tenant_id), coalesce(NEW.unit_id, a.unit_id)
+      INTO NEW.tenant_id, NEW.unit_id
+      FROM public.appointments a
+     WHERE a.id = NEW.booking_id;
+  END IF;
+  RETURN NEW;
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.trg_appointment_attendees_inherit_scope() FROM public, anon, authenticated;
+
+DROP TRIGGER IF EXISTS appointment_attendees_inherit_scope ON public.appointment_attendees;
+CREATE TRIGGER appointment_attendees_inherit_scope
+  BEFORE INSERT ON public.appointment_attendees
+  FOR EACH ROW EXECUTE FUNCTION public.trg_appointment_attendees_inherit_scope();
+
+-- ---------------------------------------------------------------------------
+-- RLS, políticas, `unit_id`/`owner_id`, índices de escopo e registro
+--
+-- Escrever as quatro políticas à mão aqui seria escrever de novo, pior, o que
+-- `scaffold_table` gera igual para as outras. E as asserções de postura do
+-- pgtap são escritas contra exatamente o que ele produz.
+--
+-- `p_owner_scoping = false`: convidado não tem dono próprio. Quem enxerga a
+-- reunião enxerga quem está nela — esconder metade da sala de quem já está na
+-- sala não protege nada e quebra a tela.
+--
+-- As permissões são as da agenda (`agenda.read/create/edit/delete`), que já
+-- existem no catálogo. Nenhuma chave nova para ninguém conceder.
+-- ---------------------------------------------------------------------------
+
+SELECT app.scaffold_table(
+  'public.appointment_attendees'::regclass,
+  'agenda.appointment_attendee',
+  'agenda',
+  false,
+  'enforce'
+);
+
+GRANT SELECT, INSERT, UPDATE, DELETE ON public.appointment_attendees TO authenticated;
+GRANT ALL ON public.appointment_attendees TO service_role;
+
+-- A espinha declara o que é dela, para que nenhum plugin crie uma tabela com
+-- este nome mais adiante achando que o terreno estava vazio.
+INSERT INTO app.base_owned_tables (table_name, note)
+VALUES ('appointment_attendees', 'Quem comparece a um Compromisso.')
+ON CONFLICT (table_name) DO NOTHING;

package/package.json

@@ -3,7 +3,7 @@
   "fayz": {
     "status": "beta"
   },
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Fayz SDK database layer — Drizzle schema primitives, spine references, and migration helpers shared across plugins.",
   "type": "module",
   "sideEffects": false,