nova-tabela

name	nova-tabela
description	Cria uma tabela PostgreSQL no padrão obrigatório do projeto — chave dupla, carimbos temporais, territorialização, RLS, índices apropriados e migração versionada. Use ao adicionar qualquer tabela a um domínio existente ou novo.

Procedimento

1. Confirmar o domínio no catálogo (docs/catalogo-dominios.md). A tabela deve pertencer a um dos 20 domínios; se não pertence, é decisão de arquitetura — registrar ADR antes.
2. Nomear seguindo a regra banco.md: snake_case, singular, em português para entidade de domínio.
3. Modelar colunas obrigatórias:

   id              bigserial PRIMARY KEY,
   uuid            uuid NOT NULL DEFAULT gen_random_uuid() UNIQUE,
   criado_em       timestamptz NOT NULL DEFAULT now(),
   atualizado_em   timestamptz NOT NULL DEFAULT now(),
   excluido_em     timestamptz NULL,
   

4. Territorialização (quando aplicável): microrregiao_id bigint NOT NULL REFERENCES territorio.microrregiao(id). Alimenta a RLS.
5. Taxonomia: usar FK para tabela de referência, nunca texto livre onde existe vocabulário controlado.
6. Busca textual (se houver conteúdo pesquisável): busca tsvector GENERATED ALWAYS AS (to_tsvector('portuguese', ...)) STORED + índice GIN.
7. Particionamento (se tabela for de alto volume — auditoria, eventos, feed): definir partição por criado_em desde o início.
8. Classificação LGPD de cada coluna pessoal: comentário SQL COMMENT ON COLUMN ... IS 'PESSOAL' ou SENSIVEL.
9. Índices: criar para chaves estrangeiras e colunas de consulta frequente. Em tabela grande usar CREATE INDEX CONCURRENTLY.
10. Política RLS: aplicar skill politica-rls se a tabela tem dado territorial ou pessoal — sem exceção.
11. Migração: aplicar skill nova-migracao para gerar o arquivo versionado.
12. Atualizar docs/catalogo-dominios.md com a tabela criada.

Modelo de referência

-- d16_execucao_001_prestacao_conta.sql

CREATE TABLE execucao.prestacao_conta (
  id              bigserial PRIMARY KEY,
  uuid            uuid NOT NULL DEFAULT gen_random_uuid() UNIQUE,
  ator_id         bigint NOT NULL REFERENCES atores.ator(id),
  microrregiao_id bigint NOT NULL REFERENCES territorio.microrregiao(id),  -- territorialização
  periodo         text NOT NULL,                  -- INTERNO ex. "2026-02"
  valor_total     numeric(14,2) NOT NULL,         -- INTERNO
  status          text NOT NULL REFERENCES configuracao.item_taxonomia(chave),
  criado_em       timestamptz NOT NULL DEFAULT now(),
  atualizado_em   timestamptz NOT NULL DEFAULT now(),
  excluido_em     timestamptz NULL,
  CHECK (valor_total >= 0)
);

CREATE INDEX prestacao_conta_microrregiao_idx ON execucao.prestacao_conta(microrregiao_id);
CREATE INDEX prestacao_conta_ator_idx         ON execucao.prestacao_conta(ator_id);

ALTER TABLE execucao.prestacao_conta ENABLE ROW LEVEL SECURITY;
-- política RLS criada por nova-tabela acionando politica-rls

Antipatterns rejeitados em revisão

• Tabela sem uuid.
• Tabela com dado territorial sem microrregiao_id ou sem política RLS.
• Campo text onde existe taxonomia.
• Ausência de carimbo temporal.
• DELETE físico esperado em tabela com excluido_em.

Saída

Migração versionada em db/migracoes/, com UP e DOWN, política RLS associada, índices, classificação LGPD comentada e atualização do catálogo.