Database Development Standard¶

Objetivo¶

Definir o padrão oficial para modelagem, implementação, evolução e manutenção do banco de dados da CoreFlow Platform.

Este documento é obrigatório para todos os produtos.

Banco Oficial¶

A plataforma utilizará exclusivamente:

• PostgreSQL

Versão mínima:

• PostgreSQL 16

ORM Oficial¶

Toda persistência deverá utilizar:

• Django ORM

É proibido utilizar SQL bruto sem justificativa técnica.

Convenções de Nomenclatura¶

Tabelas¶

Plural.

Exemplos:

users
companies
contacts
sales_orders

Colunas¶

snake_case.

Exemplo:

created_at
updated_at
company_id

Chaves Primárias¶

Todas as tabelas utilizarão:

id

Tipo:

BigAutoField

Chaves Estrangeiras¶

Sempre utilizar:

*_id

Exemplo:

company_id
user_id
contact_id

Campos Obrigatórios¶

Toda entidade deverá possuir:

id
created_at
updated_at
created_by
updated_by
is_active
company_id

Quando aplicável:

deleted_at
deleted_by

Multiempresa¶

Toda entidade de negócio deverá possuir:

company_id

É proibido compartilhar dados entre empresas.

Auditoria¶

Toda alteração relevante deverá registrar:

• usuário
• data
• operação
• valores anteriores
• novos valores

Soft Delete¶

Sempre que possível utilizar:

deleted_at
deleted_by

Evitar exclusão física.

Índices¶

Criar índices para:

• Foreign Keys
• Campos de pesquisa
• Campos utilizados em filtros
• Campos utilizados em ordenação

Constraints¶

Obrigatório utilizar:

• NOT NULL
• UNIQUE
• CHECK
• FOREIGN KEY

Nunca confiar apenas na aplicação.

Migrations¶

Toda alteração estrutural deverá ocorrer através de migrations.

É proibido alterar banco manualmente em produção.

Integridade¶

Utilizar:

• CASCADE
• PROTECT
• SET NULL

conforme a regra de negócio.

Nunca utilizar CASCADE sem análise.

Normalização¶

Objetivo mínimo:

Terceira Forma Normal (3FN).

Desnormalizações somente mediante justificativa documentada.

Performance¶

Priorizar:

• índices adequados
• consultas otimizadas
• paginação
• select_related()
• prefetch_related()

Evitar:

• consultas N+1
• JOINs desnecessários
• SELECT *

Tipos de Dados¶

Utilizar tipos apropriados.

Exemplos:

UUID
BigInteger
Decimal
Date
DateTime
Boolean
JSONB
Text
Char

Valores Monetários¶

Nunca utilizar:

Float

Sempre utilizar:

Decimal

Datas¶

Obrigatório utilizar:

Timezone UTC.

Conversão para horário local apenas na camada de apresentação.

Arquivos¶

Nunca armazenar arquivos no banco.

Armazenar apenas:

• caminho
• URL
• metadados

JSON¶

Utilizar JSONB apenas quando houver justificativa arquitetural.

Não substituir modelagem relacional por JSON.

Segurança¶

Nunca armazenar:

• senhas em texto
• tokens sem criptografia
• dados sensíveis sem proteção

Versionamento¶

Toda alteração de estrutura deverá possuir:

• migration
• documentação
• revisão

Backup¶

Obrigatório possuir estratégia para:

• Backup diário
• Restore
• Teste periódico de recuperação

Anti-patterns¶

É proibido:

• SQL sem necessidade
• ausência de índices
• tabelas sem auditoria
• duplicação de dados
• uso de Float para valores financeiros
• exclusão física indiscriminada
• lógica de negócio no banco

Objetivo Final¶

Garantir uma base de dados consistente, íntegra, escalável, auditável e preparada para suportar toda a CoreFlow Platform durante sua evolução.