Organizações

Onde mora o módulo

A tela vive em app/(main)/companies/, sob o route group com header global. A entrada é autenticada (middleware exige sessão Supabase) e o Server Component faz o gate de papel — VIEWER é redirecionado direto para /surveys. ADMIN e SURVEYOR chegam à mesma página, mas com payloads distintos (ver Cap. 05).

Modelo de dados

A tabela mydb.companies tem 12 colunas. Os campos marcados NOT NULL são exigidos no INSERT mas nenhum tem default no banco — a obrigatoriedade aparece na Zod e no formulário antes de chegar ao Postgres.

id

bigint, PK. Default nextval('mydb.companies_id_seq'). É o company_id referenciado por outras tabelas (sem FK declarada — ver Cap. 07).

trade_name

varchar(255), NOT NULL. Nome fantasia. Exibido no card como título.

corporate_name

varchar(255), NOT NULL. Razão social.

tax_id

varchar(255), nullable. CNPJ no formato XX.XXX.XXX/XXXX-XX. Coberto por UNIQUE index idx_30652_companies_tax_id_unique.

email

varchar(255), nullable. Coberto por UNIQUE index idx_30652_companies_email_unique.

administrator

varchar(255), NOT NULL. Nome do responsável pelo cadastro. Texto livre — não é referência a uma tabela de usuários.

founding_date

timestamptz, nullable. Data de fundação da empresa.

phone, address, website

Todos opcionais (varchar(255) / text / varchar(255)). website recebe auto-prefixo https:// na Zod se faltar protocolo.

created_at, updated_at

timestamptz, NOT NULL, default CURRENT_TIMESTAMP. A coluna updated_at é atualizada pela própria RPC update_company com now(); não há trigger.

População atual

15 linhas em mydb.companies (consulta MCP em 2026-05-22). Distribuição em mydb.surveys: 8 empresas distintas respondem por todas as pesquisas — 7 das 15 não têm nenhuma pesquisa associada. Entre as registradas convivem dados reais e teste (“Empresa_50”, “Teste Criar Empresa22333”, “Magic Link Corporation Teste”, “Pet Love (Teste)”).

Composição da tela

CompaniesClient monta um layout em dois painéis. O esquerdo é a lista de organizações; o direito é um modal contextual que aparece quando o usuário clica em um card (modo editing) ou no botão de adicionar (modo creating). O modo idle esconde o painel direito.

Validação (Zod)

companyValidationSchema em lib/zod/company.validation.ts é a única camada de validação semântica. A edge companies-crud só checa “campos obrigatórios” de forma trivial; as RPCs do banco não validam nada além do tipo da coluna. Vale tanto na entrada quanto na edição.

const cnpjRegex = /^\d{2}\.\d{3}\.\d{3}\/\d{4}-\d{2}$/;

export const companyValidationSchema = z.object({
  trade_name: z.string().min(1, 'Nome fantasia é obrigatório.'),
  corporate_name: z.string().min(1, 'Razão social é obrigatória.'),
  administrator: z.string().min(1, 'Administrador é obrigatório.'),
  email: z.email('E-mail inválido.').optional().or(z.literal('')),
  tax_id: z.string().optional().or(z.literal(''))
    .refine((val) => !val || cnpjRegex.test(val),
            'CNPJ deve estar no formato XX.XXX.XXX/XXXX-XX'),
  // website: auto-prefixa https:// e valida com new URL()
});

Três campos são obrigatórios: trade_name, corporate_name, administrator. Os demais (email, tax_id, phone, address, website, founding_date) aceitam string vazia ou undefined. O website tem comportamento peculiar: a Zod aplica transform que prefixa https:// se faltar protocolo e em seguida valida com new URL().

Fluxos

Listar

Server Component em page.tsx lê o cookie user_profile. VIEWER é redirecionado imediatamente para /surveys. ADMIN e SURVEYOR seguem para getCompaniesRpc(profile), que despacha por papel:

• ADMIN → supabase.rpc('get_companies_paginated', { p_schema: 'mydb', p_search: null, p_page: 1, p_per_page: 100 }). Devolve até 100 organizações ordenadas por created_at desc.
• SURVEYOR com profile.company_id definido → supabase.rpc('get_company_by_id', { p_schema: 'mydb', p_id: profile.company_id }). Devolve uma única linha.
• SURVEYOR sem company_id, ou qualquer outro caso → array vazio.

O fetch é envolvido em cache() do React para deduplicar chamadas concomitantes dentro do mesmo request. mapRow normaliza null para string vazia em todos os campos opcionais — o card sempre recebe strings, mesmo quando o banco devolve NULL.

Criar

CreateCompanyForm valida com Zod no submit. Se passar, chama createCompanyAction(formData). A Server Action re-valida com Zod (segundo round, blindagem contra payload adulterado) e chama createCompanyRpc:

const { data, error } = await supabase.rpc('create_company', {
  p_schema: 'mydb',
  p_trade_name: payload.trade_name,
  p_corporate_name: payload.corporate_name,
  p_tax_id: payload.tax_id || null,
  p_founding_date: payload.founding_date || null,
  p_administrator: payload.administrator,
  p_address: payload.address || null,
  p_phone: payload.phone || null,
  p_email: payload.email || null,
  p_website: payload.website || null,
});

A RPC public.create_company é SECURITY DEFINER, executa um INSERT dinâmico montado com format('%I') (interpolação de identificador, à prova de injection no p_schema), e devolve a linha como jsonb. Sucesso → revalidatePath('/companies') + toast.

Editar

Idêntico ao criar, mas a RPC update_company usa coalesce por campo:

update %I.companies c set
  trade_name     = coalesce($2, c.trade_name),
  corporate_name = coalesce($3, c.corporate_name),
  tax_id         = coalesce($4, c.tax_id),
  -- ...demais campos
  updated_at     = now()
where c.id = $1
returning to_jsonb(c)

Excluir

Card → ícone de lixeira (apenas ADMIN) → handleDeleteCompany abre ConfirmDialog. Se o usuário confirmar, deleteCompanyAction(companyId) chama deleteCompanyRpc → delete_company → DELETE FROM mydb.companies WHERE id = $1. Sucesso → remoção otimista da lista local + toast.

export async function deleteCompanyAction(companyId: number) {
  try {
    const success = await deleteCompanyRpc(companyId);
    if (success) {
      revalidatePath('/companies');
      return { success: true, error: null };
    }
    return { success: false, error: 'Erro ao excluir organização.' };
  } catch (error) {
    return { success: false, error: error?.message ?? 'Erro interno.' };
  }
}

Edge companies-crud × RPCs diretas

Organizações foi um dos módulos convertidos no padrão RPC direto. A UI de companies usa exclusivamente as funções em rpc/companies/; nenhuma operação CRUD da própria tela passa pela edge. Mesmo assim, a edge continua deployada (verify_jwt: true desde 2026-06-10) e tem caller real em outro módulo.

A edge resolve o papel reconsultando o banco via get_user_by_id (com p_table = 'users' ou 'surveyors') e despacha para a mesma RPC do banco que a UI usaria. Ou seja: mesmo no caminho que ainda passa pela edge, o trabalho efetivo termina na RPC. A edge resta como camada intermediária — útil para isolar a checagem de papel do client, mas redundante com o gate que o Server Component já faz via cookie.

Cascata de exclusão e dependências

Em outras tabelas do mydb a exclusão dispara cascata (ver surveys.html Cap. 05 para o modelo da pesquisa). Em companies isso não acontece. A consulta information_schema.referential_constraints com ccu.table = 'companies' devolve lista vazia (consulta MCP em 2026-05-22): nenhuma foreign key declarada aponta para mydb.companies.

Os bigints/numerics que atuam como company_id em outras tabelas — mydb.surveys.company_id, mydb.surveyors.company_id, mydb.users.company_id — são colunas livres. O Postgres não impõe integridade referencial e delete_company é um DELETE FROM companies cru. Excluir empresa deixa surveys, surveyors e users órfãos com company_id apontando para uma linha que não existe mais.

Reordem caso a integridade vire requisito: ou declarar FKs explícitas em surveys/surveyors/users com ON DELETE CASCADE (ou RESTRICT), ou reescrever delete_company como cascata aplicativa em múltiplas etapas — análogo ao que delete-survey já faz para pesquisas (ver surveys.html Cap. 05 — Excluir).

Permissões, RLS e RPCs abertas

A matriz de papéis para Organizações é compacta: só ADMIN escreve, SURVEYOR lê a própria empresa, VIEWER nem chega à rota. Tudo derivado da gate em page.tsx e da condicional role === 'ADMIN' nos botões da UI.

A definição de papel em si — derivada da tabela-perfil onde o supabase_auth_id aparece, e não de uma coluna explícita — vive em auth.html Cap. 02. A matriz completa do produto está em auth.html Cap. 06.

RLS da tabela

mydb.companies tem relrowsecurity = true. Duas policies vigoram:

• Authenticated users can view companies — SELECT para {public}, qual (select auth.role()) = 'authenticated'. Qualquer login lê a tabela inteira via PostgREST com schema('mydb'). Já catalogado na lista “RLS habilitada não escopada” do backend.html Cap. 02.
• Service role can manage companies — ALL para service_role (edges, lambdas).

RPCs com EXECUTE para anon/authenticated

O parâmetro p_schema é interpolado via format('%I'), então não há vetor de SQL injection — mas ele permite que o caller escolha qualquer schema com tabela companies compatível. No projeto atual, só mydb serve.

Integração com outros módulos

• Pesquisas: cada pesquisa carrega company_id. ADMIN escolhe a empresa no stepper; SURVEYOR só consegue criar para a própria empresa. O dropdown do stepper é populado por getCompanies da edge, único caller real do companies-crud hoje (ver Cap. 06).
• Administradores: cada SURVEYOR tem company_id fixo. A página de criação também usa getCompaniesRpc para o dropdown de empresas.
• Autenticação & Papéis: ADMIN tem profile.company_id = null — ações que precisam de company_id de uma pesquisa específica (excluir, encerrar) usam o survey.empresa_id do recurso-alvo. O modelo está em auth.html Cap. 06.
• Backend (Supabase): as RPCs companies.* são parte do catálogo de funções no schema public (com SET search_path = public, mydb), padrão descrito em backend.html Cap. 05. A edge companies-crud entra no catálogo de edges em backend.html Cap. 03, com verify_jwt: true desde o endurecimento de 2026-06-10 (antes era false).

Pegadinhas

1. Cascade falso na exclusão. O ConfirmDialog afirma que excluir uma organização apaga em cascata pesquisas e administradores. Não apaga nada além da própria linha. Sem FK declarada, surveys e surveyors órfãos ficam apontando para um company_id inexistente (ver Cap. 07).
2. RPCs abertas a anon/authenticated. As cinco RPCs do módulo aceitam chamada direta via PostgREST com a chave pública. Nenhuma re-valida papel. Qualquer cliente com a chave anon pode criar/editar/excluir empresas arbitrariamente. A UI esconder os botões não é gate — só camuflagem (ver Cap. 08).
3. Filtro de data com label errado. “Fundada a partir de” e “Fundada até” filtram por created_at, não por founding_date. Bug de etiqueta em CompaniesClient.tsx.
4. Limpar campo opcional não apaga. A combinação de || null no adapter rpc/companies/update-company.ts com o coalesce dentro da RPC mantém o valor antigo quando o usuário apaga o conteúdo. Para apagar mesmo, falta um sentinel distinto de “não enviado”.
5. UNIQUE como índice, não como constraint. email e tax_id têm UNIQUE garantida por índices Laravel legados (idx_30652_*), invisíveis em pg_constraint. A Zod não valida unicidade no client; colisão volta como 23505 cru no toast.
6. Edge dormente mas viva. companies-crud continua deployada (verify_jwt: true desde 2026-06-10) e ainda atende o dropdown de empresas em surveys/create e surveys/[id]/edit. Mexer na edge afeta esses dois fluxos; mexer nas RPCs afeta o resto. Não é “a migração terminou e a edge pode sumir”.
7. Dados de teste em produção. 7 das 15 empresas não têm pesquisa associada e várias têm nome claramente de teste (“Empresa_50”, “Teste Criar Empresa22333”, “Magic Link Corporation Teste”, “Pet Love (Teste)”). Sem flag is_test nem distinção entre ambientes dentro do schema.
8. Strings vazias no lugar de null no client. mapRow em rpc/companies/get-companies.ts converte null para '' em todos os campos string. O card e os formulários sempre recebem string, o que simplifica o JSX mas perde a distinção entre “não informado” e “informado como vazio”.