Dicionário de dados para um banco de protótipo que evita quebras

Por que protótipos quebram relatórios e cobrança tão facilmente

Bancos de dados de protótipo mudam rápido. Você adiciona uma coluna para fazer algo funcionar, renomeia um campo para a interface ficar mais legível, ou troca um tipo para corrigir um bug. O app continua rodando, então parece seguro.

Relatórios, cobrança e exportações são menos tolerantes. Eles dependem de pressupostos silenciosos: o que um valor inclui, qual timestamp define um mês, o que um status realmente significa. Quando essas hipóteses mudam sem que ninguém perceba, os números desviam e nada gera erro.

Um erro comum parece com isto: um relatório soma amount, mas um conserto rápido muda amount de “preço antes de imposto” para “preço após descontos.” Os totais ainda somam, mas significam algo diferente. Cobranças saem erradas, gráficos de receita deixam de bater e leva semanas para achar a causa porque o banco de dados está fazendo exatamente o que você pediu.

Protótipos são frágeis porque o significado das colunas costuma ficar obscuro. Nomes como status, type, value ou total podem esconder ideias diferentes em lugares distintos. O status de uma tabela pode significar “fatura enviada”, outra “pagamento recebido” e uma terceira “assinatura ativa”. Some código gerado por IA e frequentemente aparece nomenclatura inconsistente, campos duplicados e lógica espalhada por várias tabelas.

A maioria das quebras vem de edições pequenas e “óbvias”:

• renomear colunas que dashboards ou exportações dependem
• reaproveitar uma coluna para um novo propósito em vez de criar outra
• misturar unidades (centavos vs dólares, UTC vs horário local)
• mudar comportamento de nulls ou defaults
• preencher dados retroativamente sem seguir as regras originais

Um dicionário de dados é a guarda mais simples contra isso. É uma anotação em linguagem comum para cada tabela e coluna: o que representa, de onde vem e como deve ser usada. O objetivo não é documentação perfeita. É poder mudar o esquema sem alterar o significado dos números do negócio.

O que é um dicionário de dados (e o que não é)

Um dicionário de dados é um mapa em inglês claro do seu banco. Ele foca em significado e regras, não apenas em estrutura.

A mudança importante é ir de “o que armazena” para “o que significa”. Uma coluna chamada amount pode armazenar um número, mas o significado pode ser “subtotal em centavos, antes de imposto, na moeda de cobrança do cliente, excluindo reembolsos.” Sem esse significado escrito, duas pessoas usarão o mesmo campo de formas diferentes e os totais não baterão.

O que deveria incluir

Mantenha pequeno, mas completo o suficiente para que alguém novo possa fazer uma alteração segura:

• uma descrição para cada tabela e coluna (significado de negócio, não só tipo)
• regras e restrições (obrigatório vs opcional, valores permitidos, arredondamento, fuso horário)
• propriedade (quem decide o significado e quem aprova mudanças)
• fontes e destinos (de onde os dados vêm e onde são usados)
• notas sobre dados sensíveis (PII, tokens, expectativas de retenção)

O que não é

Um dicionário de dados não é um diagrama ER, uma lista de queries SQL ou um despejo de comentários gerados automaticamente pelo schema. Esses podem ajudar, mas normalmente explicam forma, não significado.

Também não é uma tarefa única. Ele precisa acompanhar seu esquema.

Onde deve ficar

Coloque onde as pessoas realmente vão atualizar: um doc, uma planilha compartilhada ou uma página wiki. A ferramenta importa menos do que a consistência. Escolha um lugar, um formato e um dono.

Trate-o como parte da mudança. Se você adicionar uma coluna, renomear ou mudar como um valor é calculado, atualize o dicionário no mesmo dia.

Comece pelos outputs dos quais as pessoas dependem

É mais fácil documentar um banco de dados de protótipo de fora para dentro: comece pelo que o negócio depende hoje. Tabelas podem mudar semanalmente, mas faturas, dashboards, exportações e e-mails ao cliente tendem a virar “verdade” na cabeça das pessoas.

Primeiro, identifique quem é prejudicado quando os números mudam:

• finanças se preocupa com totais, impostos e reembolsos
• operações com cumprimento e status de entrega
• produto com o que o app faz em casos de borda
• analytics com definições e janelas de tempo
• suporte com o que os clientes veem e o que os agentes conseguem explicar

Então escolha alguns outputs críticos e trate cada um como um contrato, escrito em palavras simples. Exemplos:

• “Invoice total = sum(line items) + tax - discounts.”
• “Monthly active users excludes internal accounts.”

Essas sentenças viram âncoras para as definições de tabelas e colunas.

Não adivinhe. Colete alguns artefatos reais que sua equipe já confia:

• uma fatura paga recente ou recibo
• um CSV que um cliente ou colega realmente usa
• um screenshot de dashboard que as pessoas tratam como “fonte da verdade”
• um template de e-mail de suporte que inclui números (fim de trial, valor devido)
• uma resposta de API de exemplo usada por outro sistema

Escolha um escopo inicial pequeno: as 5–10 tabelas que alimentam dinheiro e métricas centrais. Se você conseguir traçar “Subtotal”, “Tax” e “Total” de uma fatura até a query exata que os calcula, encontrou o conjunto inicial.

O que documentar para cada tabela e coluna

Comece com o que seu banco já sabe, depois acrescente o significado humano que impede que “pequenos” consertos quebrem relatórios, cobrança ou exportações.

Para cada tabela

Escreva uma frase de propósito que remova ambiguidade.

Exemplo: invoices armazena uma linha por fatura de cliente, não por tentativa de pagamento.

Essa linha única economiza horas quando alguém usa a tabela errada ou assume a granularidade errada.

Para cada coluna

Capture duas camadas:

• Fatos do schema: tipo, nullable, default e se é único ou indexado.
• Significado em linguagem simples: o que representa, mais 2–3 valores de exemplo.

Depois acrescente as regras que mantêm os números estáveis:

• Regras de dados: valores permitidos, unidades, arredondamento e suposições de fuso horário.
• Lineagem: de onde vem, quem escreve e quando atualiza.
• Notas de privacidade: se contém PII e o que nunca deve ser exportado.

Regras de dados são onde os protótipos escondem as piores armadilhas:

• Se você tem amount, diga dólares ou centavos, moeda e arredondamento.
• Se tem created_at, informe o fuso horário e se é definido pelo app ou pelo banco.
• Se tem status, liste os valores permitidos e o que cada valor significa.

Lineagem importa ainda mais em protótipos bagunçados. Uma coluna pode ser escrita por um job em background, um webhook ou um formulário cliente. Se ninguém responder “o que cria esse valor?”, os relatórios vão divergir.

Por fim, marque privacidade claramente. Aponte email, endereço, IP e quaisquer tokens ou segredos, e indique o que jamais deve aparecer em exportações.

Um template simples de dicionário de dados para reutilizar

Escolha um formato que você realmente manterá. Para protótipos pequenos, uma planilha é suficiente: uma aba por tabela, ou uma aba única onde as linhas são agrupadas por nome da tabela.

Um dicionário útil ajuda a responder duas perguntas rapidamente:

• O que este campo significa?
• O que vai quebrar se ele mudar?

Template (copiar/colar)

Use o mesmo conjunto de colunas para cada tabela, mesmo que algumas células fiquem em branco no início:

Table:

| Column | Type | Null? | Description | Example | Key/Relation | Used by (report/billing/export) | Owner | Notes / Warnings |
|--------|------|-------|-------------|---------|--------------|----------------------------------|-------|------------------|
| id     | uuid | no    | Primary identifier for this row | 8f... | PK | internal joins | Eng | DO NOT CHANGE format |

Em “Key/Relation,” escreva dicas simples de join, não ensaios. Exemplo: “FK -> users.id (many invoices belong to one user).”

Se uma relação está apenas implícita no código (comum em protótipos gerados por IA), ainda documente como “logical FK” para que a próxima pessoa não perca isso.

Adicione avisos somente onde importam. Se uma coluna alimenta totais de fatura, impostos, relatórios de receita ou uma exportação voltada ao cliente, marque-a claramente (por exemplo, “alimenta totais de fatura - não mude nome/tipo sem atualizar exportações”).

Regras de nomenclatura que evitam confusão

Você não precisa de um guia enorme. Algumas convenções consistentes evitam a maior parte da deriva do schema:

• escolha nomes de tabelas no singular ou plural e mantenha-se nessa escolha
• escolha um formato de chave primária (id ou <table>_id) e mantenha consistente
• nomeie chaves estrangeiras referenced_table_id (exemplo: customer_id)
• armazene dinheiro em centavos inteiros quando possível (ex: amount_cents) e documente arredondamento
• padronize timestamps (created_at, updated_at) e documente o fuso horário

Construa a primeira versão em uma tarde

Você não precisa de doc perfeita. Precisa de algo que impeça quebrar dinheiro e métricas.

1) Exporte o esquema que você já tem

Liste cada tabela e coluna como existem hoje. A maioria dos bancos e ORMs pode produzir isso rapidamente (UI administrativa, arquivo de schema, dump SQL). Cole em uma planilha ou doc, uma linha por coluna.

Faça um triagem rápida e marque as tabelas que tocam:

• invoices, payments, subscriptions, discounts, refunds
• dashboards de métricas e relatórios semanais
• qualquer exportação CSV ou integração que sai do seu sistema

Se estiver em dúvida, pesquise o código por “invoice”, “total”, “export”, “report” e “balance” e note quais tabelas essas queries acessam.

2) Preencha significado e regras, começando por dinheiro

Escreva definições para os campos que dirigem totais e mudanças de status. Comece por moeda e tempo porque pequenos mal-entendidos criam grandes problemas.

Foque primeiro em:

• campos de valor (moeda, imposto incluído ou não, centavos vs decimais)
• campos de status (valores permitidos e significado exato)
• timestamps (qual evento representa e o fuso horário)
• chaves estrangeiras (o que a relação significa na vida real)
• identificadores (o que é visível ao usuário vs interno)

Coloque a regra ao lado da coluna, não em uma seção separada de “regras”.

Exemplos:

• “invoice.status = paid somente após o pagamento ser capturado, não quando há tentativa.”
• “line_item.amount_cents exclui descontos; discount_cents é separado.”

Depois valide com uma pessoa não técnica que depende dos números (finanças ou operações). Percorra um cenário real: “Se um cliente é reembolsado, quais colunas mudam e qual relatório deve continuar batendo?” Ajuste a redação até que concordem.

Mantenha um pequeno log de mudanças (data, o que mudou, por quê) e atribua um dono de revisão.

Vincule colunas a métricas, faturas e exportações

Um dicionário é mais valioso quando protege os outputs de que as pessoas dependem. Cada métrica chave, linha de fatura e coluna de exportação deve apontar para os campos exatos que a produzem.

Para cada output “não pode estar errado” (MRR, faturas pagas, saldo em aberto, assinantes ativos, exports de clientes), registre:

• o que significa (uma frase que um colega não técnico concordaria)
• a regra de tempo (data da fatura vs data do pagamento, e qual fuso usar)
• os filtros (valores de status incluídos, contas de teste excluídas)
• dependências (lista table.column, incluindo chaves de join)
• a “fonte da verdade” quando valores discordam

Seja explícito quando o esquema oferece duas fontes concorrentes. Se o relatório poderia usar payments.amount ou invoices.paid_amount, decida qual vence e escreva se a outra é derivada (pode ser recalculada) ou autoritativa (não deve ser sobrescrita).

Documente casos de borda que frequentemente causam desencontros:

• reembolsos como pagamentos negativos vs linhas separadas de refund
• pagamentos parciais e múltiplos pagamentos por fatura
• assinaturas canceladas que ainda faturam até o fim do período
• faturas com data retroativa ou dados históricos migrados
• clientes duplicados criados por fluxos de inscrição “mágicos”

Não precisa colar SQL em todo lugar. Registrar a lógica em palavras geralmente basta:

• “Some payments where status is succeeded, grouped by invoice month, excluding refunds, using paid_at.”

Erros comuns que levam a surpresas caras

Bancos de dados de protótipo “funcionam” porque o app é tolerante. A surpresa vem depois, quando uma pequena mudança quebra um relatório, um total de fatura ou um CSV que um cliente depende.

Renomear sem checar uso a jusante

O app pode continuar rodando, mas planilhas financeiras, dashboards de BI e scripts de exportação ainda podem procurar o nome antigo.

Campos de dinheiro vagos

Uma coluna chamada amount pode significar centavos ou dólares, líquido ou bruto, antes de imposto ou depois, com reembolsos incluídos ou não. Se ninguém anotar isso, você vai discutir “por que os totais não batem”.

Timestamps misturados

Protótipos frequentemente misturam created_at, paid_at, fulfilled_at e “quando o job terminou” no mesmo gráfico. Se um relatório agrupa por criação e outro por pagamento, os números de fim de mês podem oscilar.

Tipos de ID inconsistentes

Se customer_id é string numa tabela e inteiro em outra, joins falham, duplicatas aparecem e exportações perdem linhas.

“Status” virando gaveta de lixo

Novos valores são adicionados na pressa e ninguém documenta o que significam. Depois, alguém filtra pelo conjunto errado de statuses e muda uma métrica silenciosamente.

Se quiser um conjunto rápido de cheiros para sinalizar antes de mandar uma mudança:

• um nome de coluna mudou mas relatórios/exportações não foram verificados
• campos de dinheiro não especificam moeda e se incluem imposto
• múltiplos timestamps existem mas só um é usado “porque estava lá”
• IDs não compartilham o mesmo tipo entre tabelas
• valores de status não estão listados com significado em linguagem simples

Checklist rápido antes de mudar o banco

Antes de renomear uma coluna ou “só adicionar mais um campo”, pause e verifique as partes que mantêm caixa e relatórios corretos.

• Tabelas de cobrança têm donos. Se uma tabela afeta faturas, pagamentos, assinaturas, descontos ou reembolsos, alguém é responsável pelo significado e por quando deve mudar.
• Todo campo de dinheiro é inequívoco. Documente moeda, precisão (centavos?), e se é líquido ou bruto. Anote se inclui imposto, taxas ou créditos.
• Todo campo de tempo diz o evento e o fuso. “created_at” pode significar quando a linha foi inserida, quando o usuário clicou “Pagar” ou quando o dinheiro foi liquidado. Escolha um significado e documente.
• Joins principais são destacados. Liste os joins “caminho dourado” usados em relatórios (por exemplo: invoices -> invoice_items -> customers).
• Exportações descrevem contratos. Se uma exportação espera datas ISO, centavos inteiros ou nomes de coluna específicos, escreva isso para que um refactor não quebre ferramentas a jusante.

Mantenha um log simples de mudanças que responda:

• o que mudou (schema e definição)
• quem mudou e quando
• por que mudou e quais outputs re-checar

Um pequeno exemplo: renomear paid_at para paid_on pode parecer inofensivo, mas pode quebrar uma exportação contábil ou deslocar métricas de “pago hoje” se o novo campo começar a armazenar outro evento.

Exemplo: consertando um esquema de cobrança bagunçado sem quebrar totais

Um problema comum em protótipos: um app gerado por IA tem invoices e uma tabela transactions, mas ninguém sabe o que cada campo significa. Você vê amount, total, fee, status, type, notes e meta. Relatórios parecem corretos até você “limpar” o schema e totais de fatura, impostos ou reembolsos deixarem de bater com o que os clientes pagaram.

Comece pequeno: foque só em cobrança. Pegue uma fatura que você sabe que está correta (o valor que o cliente pagou bate com o processador). Trace como o total da UI foi calculado e escreva o significado de cada coluna envolvida.

Esclareça o que realmente dirige os totais

Seja explícito sobre a fonte da verdade e convenções de sinal:

• transactions.gross_amount_cents: cobrança completa antes de descontos e reembolsos (documente moeda e arredondamento).
• transactions.tax_cents: parcela de imposto, e se está inclusa no bruto ou somada.
• transactions.discount_cents: descontos aplicados no momento da cobrança, não depois.
• transactions.refund_cents: reembolsos registrados como centavos positivos (ou linhas negativas). Escolha uma regra e documente.
• invoices.total_cents: defina a fórmula (gross - discount - refunds + tax) e as linhas exatas que soma.

Com esses significados escritos, um “pequeno refactor” como renomear amount para total não pode acontecer casualmente. Se alguém muda tipos (centavos para reais), altera convenção de sinal ou filtra por outro status, você verá imediatamente que relatórios e faturas vão mudar.

Documente uma exportação de ponta a ponta

Escolha um CSV que finanças ou uma agência realmente use. Anote colunas esperadas, formatos e assunções. Exemplo:

• invoice_number (string)
• issued_at (ISO date)
• subtotal_cents (integer)
• tax_cents (integer)
• total_cents (integer)
• se reembolsos aparecem como linhas separadas

É aqui que quebras ocultas aparecem. Ferramentas a jusante muitas vezes esperam centavos, nomes de coluna estáveis e tratamento consistente de reembolsos. Um dicionário força manter esses contratos.

Se o schema está bagunçado ou é inseguro mexer (joins pouco claros, moedas inconsistentes, valores sensíveis no lugar errado), pause o refactor e faça um plano antes de mudar qualquer coisa.

Próximos passos: mantenha atualizado e peça ajuda quando o protótipo resistir

Um dicionário só protege se ficar atual. A regra mais simples funciona bem: nenhuma mudança de schema é lançada sem atualizar a entrada do dicionário.

Mantenha definições amigáveis para colegas não técnicos. Mire em uma frase, um significado. Se uma coluna significa duas coisas dependendo da tela ou fluxo, considere que relatórios ou cobrança já estão inconsistentes.

Adicione uma revisão leve para mudanças de alto risco

Você não precisa de um processo grande, mas precisa de um botão de pausa para qualquer coisa que mexa com dinheiro ou métricas centrais.

Antes de mesclar uma mudança que afeta cobrança ou relatórios, confirme:

• a entrada do dicionário foi atualizada (tabela, coluna, significado, exemplo)
• relatórios/exportações/cálculos de fatura dependentes foram identificados
• valores antigos foram tratados (plano de migração ou comportamento padrão)
• alguém é dono da definição (um nome concreto, não “engenharia”)

Se você herdou um protótipo gerado por IA e não tem certeza do que é seguro mudar, uma auditoria curta pode poupar dias de vai-e-vem. FixMyMess (fixmymess.ai) faz diagnóstico de base de código e reparos para apps gerados por IA, oferecendo uma auditoria de código gratuita para mapear problemas em cobrança, relatórios e lógica de banco antes de tocar dados de produção.