@fayz-ai/db 0.16.0 → 0.18.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/migrations/120_o_servico_diz_se_ele_se_agenda.sql

@@ -0,0 +1,76 @@
+-- ---------------------------------------------------------------------------
+-- 120_o_servico_diz_se_ele_se_agenda.sql — nem todo serviço se marca na agenda.
+-- ---------------------------------------------------------------------------
+-- O formulário de agendamento do V2 oferece o catálogo inteiro. No BeautySoft
+-- ele oferece TRÊS — Avaliação, Revisão e Compra Antecipada —, e a regra está
+-- escrita na própria tela dele:
+--
+--   "Somente Avaliação, Revisão, Compra Antecipada e serviços com contrato
+--    assinado + avaliação vinculada podem ser agendados."
+--
+-- Não é detalhe de estética. É o desenho do negócio: o tratamento é VENDIDO
+-- (um pacote, um contrato), e o que se marca na agenda é o passo do processo —
+-- a consulta que avalia, o retorno que revisa, a entrega do que foi comprado
+-- antes. Oferecer os 122 no agendamento faz a recepção escolher entre "Ácido
+-- Hialurônico" e "Avaliação" como se fossem a mesma coisa, e marcar o
+-- tratamento em vez do passo é como o histórico do cliente deixa de fechar com
+-- o que ele pagou.
+--
+-- ── A forma no V2 ──────────────────────────────────────────────────────────
+-- Uma coluna, não um enum copiado do V1. `service_kind` de lá tem quatro
+-- valores dos quais três respondem à MESMA pergunta ("isto se marca?"), e o
+-- quarto — o serviço com contrato assinado + avaliação vinculada — depende de
+-- um contrato que o V2 ainda não modela. Um enum importado inteiro carregaria
+-- uma classificação que ninguém aqui sabe ler.
+--
+-- `is_bookable` é a pergunta, e é a MESMA palavra que `people.is_bookable` já
+-- usa para separar quem atende de quem trabalha na casa. Duas tabelas, uma
+-- pergunta, um nome.
+--
+-- ── Nasce TRUE, e isso é deliberado ────────────────────────────────────────
+-- Uma conta que nunca pensou no assunto continua marcando o que sempre marcou.
+-- A regra do ByDesign: pergunta não respondida cai no padrão, não em "não" —
+-- e o contrário esvaziaria o agendamento de toda conta no dia do deploy.
+--
+-- Quem vem do V1 responde na importação (`services.service_kind`) ou na tela
+-- de Serviços, no interruptor "Aparece na agenda".
+--
+-- Idempotente.
+-- ---------------------------------------------------------------------------
+
+-- ── Onde a coluna mora ─────────────────────────────────────────────────────
+-- Em `products`. A 191 aposentou o espelho `public.services` e um serviço
+-- passou a ser produto de `kind='service'` — é de lá que o SDK lê, e medido no
+-- cluster do salão os dois lados batem (122 e 122).
+--
+-- Nos pools que ainda têm a tabela antiga viva, a coluna vai nos DOIS: a tela
+-- de Serviços lê o espelho, e uma coluna que só existe de um lado seria um
+-- interruptor que se desliga e volta sozinho.
+ALTER TABLE public.products
+  ADD COLUMN IF NOT EXISTS is_bookable boolean NOT NULL DEFAULT true;
+
+COMMENT ON COLUMN public.products.is_bookable IS
+  'Este serviço pode ser MARCADO na agenda. Falso = vendido, não agendado (o '
+  'tratamento que se compra em pacote; o que se marca é a avaliação, a revisão '
+  'ou a entrega). Espelha o `service_kind` do V1. Só significa algo para '
+  'kind=service. Padrão true.';
+
+CREATE INDEX IF NOT EXISTS products_bookable_idx
+  ON public.products (tenant_id, is_bookable)
+  WHERE is_bookable;
+
+DO $$
+DECLARE
+  -- O oid guardado, e não `'public.services'::regclass` dentro do IF: o cast
+  -- LANÇA quando a relação não existe, e o `AND` não o protege — o planejador
+  -- avalia a subconsulta antes de decidir. Num banco do zero (sem o espelho
+  -- legado) isto derrubava a migration inteira com "relation does not exist",
+  -- que é exatamente o caso que o guarda existia para cobrir.
+  v_oid oid := to_regclass('public.services');
+BEGIN
+  IF v_oid IS NOT NULL
+     AND (SELECT relkind FROM pg_class WHERE oid = v_oid) = 'r' THEN
+    EXECUTE 'ALTER TABLE public.services ADD COLUMN IF NOT EXISTS is_bookable boolean NOT NULL DEFAULT true';
+    EXECUTE 'CREATE INDEX IF NOT EXISTS services_bookable_idx ON public.services (tenant_id, is_bookable) WHERE is_bookable';
+  END IF;
+END $$;

package/migrations/121_a_liberacao_pergunta_uma_vez_e_nao_cento_e_vinte_mil.sql

@@ -0,0 +1,109 @@
+-- A liberação pergunta uma vez, e não cento e vinte mil.
+--
+-- Qualquer lista de Pessoas do Espaço Facial levava ~6,4 s e às vezes estourava
+-- o `statement_timeout` — a tela voltava vazia, que é como o PostgREST entrega
+-- o 57014. Medido no cluster, como `authenticated`, tenant Espaço Facial:
+--
+--     select count(*) from people where kind='customer'     6.206 ms  331.301 buffers
+--     lista com name ilike '%test%', limit 20               6.459 ms  336.521 buffers
+--
+-- ── Não era a busca ─────────────────────────────────────────────────────────
+--
+-- O primeiro suspeito é o `ilike '%test%'`: curinga à esquerda, e a suspeita é
+-- razoável. Mas o `count(*)` acima não tem busca nenhuma e custa o MESMO. O que
+-- os dois têm em comum é a política.
+--
+-- (Sobre o ILIKE, de passagem, porque ele volta: com RLS ligada ele NUNCA vai
+-- virar condição de índice. `texticlike` não é `leakproof`, e um qual que não é
+-- leakproof não desce abaixo da barreira de segurança — então o índice trigrama
+-- `people_name_trgm_idx`, que sozinho responde em 13 ms, fica de fora por
+-- construção. Isso não é um defeito a corrigir aqui; é o preço da barreira.)
+--
+-- ── Era esta linha ──────────────────────────────────────────────────────────
+--
+-- A política `people_available_in` (migration 087) tem quatro cláusulas em OU, e
+-- a terceira é:
+--
+--     NOT app.has_release_tuple('people.person', id)
+--
+-- `has_release_tuple` é barata: uma função SQL simples, inlinável, que faz um
+-- EXISTS num índice. O 087 a escreveu assim de propósito, porque a versão
+-- anterior era SECURITY DEFINER e o Postgres não inlina essas — cada linha
+-- pagava a montagem de um executor inteiro.
+--
+-- O que o 087 não viu é que barata **vezes cento e vinte mil** não é barata. A
+-- cláusula só é alcançada quando as duas anteriores falham, e no Espaço Facial
+-- elas falham SEMPRE:
+--
+--     pessoas no tenant                     120.808
+--     com unit_id NULL                      120.455   (99,7%)
+--     grants de people.person                 1.446   (grants_exist → verdadeiro)
+--
+-- Cliente de salão não mora numa filial — ela é da rede, e o V1 nem tem coluna
+-- de unidade em `clients`. Então `unit_id IS NOT NULL` é falso, e a sonda ao
+-- índice roda uma vez por linha: 2,8 buffers × 120 mil = os 331.301 do plano.
+--
+-- ── A correção ──────────────────────────────────────────────────────────────
+--
+-- A mesma pergunta, feita UMA vez. `NOT IN` sobre uma subconsulta NÃO
+-- correlacionada é resolvida como *hashed SubPlan*: o Postgres lê as 1.446
+-- linhas de grant, monta uma tabela hash e depois cada pessoa custa uma sondagem
+-- de hash em vez de uma descida de índice.
+--
+-- É o mesmo movimento que o funil do CRM já tinha feito por outro motivo: o que
+-- é correlacionado não desce para dentro da barreira, e o que não é, desce uma
+-- vez só.
+--
+--     select count(*) ...                   6.206 ms → 115 ms   (54×)
+--     lista com ilike, limit 20             6.459 ms → 467 ms   (14×)
+--
+-- O resultado é o MESMO — as duas formas devolvem 119.518 linhas. A quarta
+-- cláusula (`available_in_my_units`) continua depois do NOT IN e é ela que
+-- deixa passar quem tem tupla de liberação para a unidade de quem lê.
+--
+-- `resource_id IS NOT NULL` não é decoração: `NOT IN` com um NULO na lista
+-- devolve NULO para todo mundo, e NULO numa política esconde a linha. Sem essa
+-- cláusula, um grant órfão apagaria a agenda inteira de todo mundo.
+--
+-- ── E o índice da lista ─────────────────────────────────────────────────────
+--
+-- Com a política corrigida, o que sobra é a varredura ordenada por nome, e ela
+-- volta ao heap só para ler `is_active`, `unit_id`, `owner_id` e `id`. Pendurar
+-- essas quatro no índice que já existe transforma o `count` num Index Only Scan
+-- (255 ms → 115 ms). A chave não muda — é o mesmo índice, com carga.
+--
+-- Idempotente.
+
+ALTER POLICY people_available_in ON public.people USING (
+  (NOT (SELECT app.grants_exist('people.person', ARRAY['available_in', 'unavailable_in'])))
+  OR (unit_id IS NOT NULL)
+  -- A pergunta de sempre, resolvida uma vez: "esta pessoa tem tupla de
+  -- liberação?". Não correlacionada de propósito — é isso que a torna um hash.
+  OR (people.id NOT IN (
+        SELECT g.resource_id
+          FROM app.resource_grants g
+         WHERE g.tenant_id = (SELECT app.current_tenant_id())
+           AND g.resource_type = 'people.person'
+           AND g.relation IN ('available_in', 'unavailable_in')
+           AND g.resource_id IS NOT NULL))
+  OR (SELECT app.available_in_my_units('people.person', people.id)));
+
+-- Um índice novo em `resource_grants` foi tentado aqui e NÃO entrou. A ideia era
+-- ler por recurso em vez de por sujeito, porque o plano gasta 921 buffers para
+-- devolver 1.446 linhas. Medido: o planejador continuou escolhendo
+-- `resource_grants_subject_idx` — cuja chave já começa por
+-- (tenant_id, …, relation, resource_type) — e a subconsulta custa 0,95 ms de um
+-- total de 130. Índice que o planejador não escolhe é peso de escrita sem
+-- leitura, e fica registrado aqui em vez de no catálogo.
+
+-- A lista de pessoas: mesma chave do índice que já existia, com as quatro
+-- colunas que a política lê penduradas. O antigo sai depois do novo entrar,
+-- para nenhum plano ficar sem índice no meio.
+CREATE INDEX IF NOT EXISTS people_tenant_kind_name_cover_idx
+  ON public.people USING btree (tenant_id, kind, name)
+  INCLUDE (id, is_active, unit_id, owner_id);
+
+DROP INDEX IF EXISTS public.people_tenant_kind_name_idx;
+
+COMMENT ON INDEX public.people_tenant_kind_name_cover_idx IS
+  'A lista de Pessoas por tipo, em ordem de nome. As colunas penduradas são as que people_available_in e people_authz_select leem — sem elas o count volta ao heap linha a linha (121).';

package/migrations/122_o_email_da_pessoa_e_um_email_nao_uma_lista.sql

@@ -0,0 +1,80 @@
+-- O e-mail da pessoa é um e-mail, não uma lista.
+--
+-- A ficha do profissional mostrava, no campo E-mail:
+--
+--     ["marataizes@espacofacial.com.br"]
+--
+-- e, no Telefone, `[]`. Não é defeito de tela: `people.email` e `people.phone`
+-- são `text`, e o porte do V1 gravou ali o JSON do array que o V1 mantém —
+-- lá uma pessoa pode ter vários e-mails, aqui a coluna guarda um.
+--
+-- Medido em 21/09/2026 (klvfxzreepavcpyjiwla, 123.484 pessoas, 25 contas):
+--
+--     e-mail em forma de array      456   (451 com um valor, 4 vazios, 1 com dois)
+--     telefone em forma de array    277   (233 com um valor, 43 vazios, 1 com dois)
+--
+-- ── Por que reparar o dado e não formatar na tela ──────────────────────────
+--
+-- Um `JSON.parse` na hora de desenhar esconderia o problema nos lugares que
+-- ainda não existem: a busca por e-mail não acha `["x@y"]` procurando `x@y`, o
+-- disparo de mensagem manda para um endereço com colchete, e o `unique` que um
+-- dia entrar nessa coluna vai tratar `x@y` e `["x@y"]` como pessoas diferentes.
+-- Campo estranho na tela é sintoma; a cura é onde o dado foi escrito.
+--
+-- ── O que sobra não se perde ───────────────────────────────────────────────
+--
+-- O primeiro valor sobe para a coluna; os demais descem para
+-- `metadata.contact.extra_emails` / `extra_phones`. São dois registros no
+-- cluster inteiro, mas apagar o segundo e-mail de alguém para deixar a coluna
+-- bonita é o tipo de perda que só aparece quando a pessoa não recebe o aviso.
+--
+-- Array vazio vira NULL: `[]` na tela diz que existe um telefone e não diz
+-- qual; vazio diz a verdade.
+
+DO $$
+DECLARE
+  v_emails integer := 0;
+  v_phones integer := 0;
+BEGIN
+  -- Guarda o que exceder ANTES de sobrescrever a coluna.
+  UPDATE public.people p
+     SET metadata = jsonb_set(
+           coalesce(p.metadata, '{}'::jsonb),
+           '{contact,extra_emails}',
+           (SELECT jsonb_agg(v) FROM jsonb_array_elements(p.email::jsonb) WITH ORDINALITY t(v, i) WHERE i > 1),
+           true)
+   WHERE p.email ~ '^\[.*\]$'
+     AND jsonb_typeof(p.email::jsonb) = 'array'
+     AND jsonb_array_length(p.email::jsonb) > 1;
+
+  UPDATE public.people p
+     SET metadata = jsonb_set(
+           coalesce(p.metadata, '{}'::jsonb),
+           '{contact,extra_phones}',
+           (SELECT jsonb_agg(v) FROM jsonb_array_elements(p.phone::jsonb) WITH ORDINALITY t(v, i) WHERE i > 1),
+           true)
+   WHERE p.phone ~ '^\[.*\]$'
+     AND jsonb_typeof(p.phone::jsonb) = 'array'
+     AND jsonb_array_length(p.phone::jsonb) > 1;
+
+  -- O primeiro valor vira o valor. `#>>'{0}'` devolve NULL no array vazio, que
+  -- é exatamente o que se quer guardar ali.
+  UPDATE public.people p
+     SET email = nullif(btrim(p.email::jsonb #>> '{0}'), '')
+   WHERE p.email ~ '^\[.*\]$'
+     AND jsonb_typeof(p.email::jsonb) = 'array';
+  GET DIAGNOSTICS v_emails = ROW_COUNT;
+
+  UPDATE public.people p
+     SET phone = nullif(btrim(p.phone::jsonb #>> '{0}'), '')
+   WHERE p.phone ~ '^\[.*\]$'
+     AND jsonb_typeof(p.phone::jsonb) = 'array';
+  GET DIAGNOSTICS v_phones = ROW_COUNT;
+
+  RAISE NOTICE 'people: % e-mail(s) e % telefone(s) saíram da forma de lista', v_emails, v_phones;
+END $$;
+
+COMMENT ON COLUMN public.people.email IS
+  'UM e-mail. O V1 guarda lista; o porte tem de escolher o principal e mandar o resto para metadata.contact.extra_emails (ver migration 122).';
+COMMENT ON COLUMN public.people.phone IS
+  'UM telefone. Mesma regra do e-mail — o excedente vai para metadata.contact.extra_phones (ver migration 122).';