Pular para conteúdo

Backend Development Standard

Objetivo

Definir o padrão oficial para desenvolvimento Backend da CoreFlow Platform.

Este documento é obrigatório para todos os produtos da plataforma.

Stack Oficial

Linguagem

  • Python 3.12+

Framework

  • Django 5+

APIs

  • Django REST Framework

Banco

  • PostgreSQL

Cache

  • Redis

Processamento Assíncrono

  • Celery

Containers

  • Docker

Arquitetura

Todo backend deverá seguir obrigatoriamente:

  • Clean Architecture
  • Domain Driven Design
  • SOLID
  • DRY
  • KISS
  • API First

Organização do Projeto

backend/

apps/

config/

tests/

requirements/

scripts/

Cada App deverá ser independente.

Estrutura de um App

app/

admin.py

apps.py

models.py

views.py

urls.py

serializers.py

permissions.py

selectors.py

services.py

repositories.py

validators.py

signals.py

tasks.py

exceptions.py

tests/

Todos os Apps seguirão exatamente esta estrutura.

Responsabilidades

Models

Persistência.

Nunca conter regra de negócio complexa.

Views

Receber requisições.

Validar permissões.

Delegar processamento.

Nunca implementar regra de negócio.

Serializers

Conversão entre JSON e objetos.

Nunca consultar banco diretamente.

Services

Toda regra de negócio deverá estar aqui.

Selectors

Consultas complexas.

Leitura apenas.

Repositories

Persistência especializada.

Isolar consultas complexas.

Signals

Eventos internos.

Nunca implementar processos pesados.

Tasks

Processamentos assíncronos.

Obrigatoriamente utilizando Celery.

Convenções

Classes

PascalCase

LeadService

Métodos

snake_case

create_lead()

Variáveis

snake_case

lead_status

APIs

Toda API deverá seguir:

/api/v1/

Nunca criar endpoints fora deste padrão.

Respostas

Formato padrão:

{
  "success": true,
  "data": {},
  "errors": [],
  "message": ""
}

Transações

Sempre utilizar:

transaction.atomic()

quando houver múltiplas operações relacionadas.

Logs

Utilizar logging estruturado.

Nunca utilizar:

print()

Tratamento de Erros

Criar exceções específicas.

Nunca capturar Exception genericamente sem tratamento adequado.

Banco de Dados

Toda alteração deverá utilizar:

  • migrations
  • constraints
  • índices
  • chaves estrangeiras

Nunca alterar banco manualmente em produção.

Performance

Priorizar:

  • select_related()
  • prefetch_related()
  • bulk_create()
  • bulk_update()

Evitar:

  • N+1 Queries
  • consultas repetidas
  • loops realizando consultas

Segurança

Obrigatório:

  • autenticação JWT
  • autorização RBAC
  • validação de permissões
  • proteção CSRF quando aplicável
  • validação de entrada
  • sanitização de dados

Testes

Obrigatórios:

  • Unitários
  • Integração
  • APIs

Toda funcionalidade nova deverá possuir testes.

Documentação

Toda alteração deverá atualizar a documentação correspondente.

Código sem documentação será considerado incompleto.

Anti-patterns

É proibido:

  • lógica de negócio em Views
  • consultas complexas em Serializers
  • regras de negócio em Models
  • acesso direto ao banco fora dos padrões
  • duplicação de código
  • SQL sem necessidade
  • funções com múltiplas responsabilidades

Objetivo Final

Todo backend da CoreFlow Platform deverá possuir arquitetura previsível, desacoplada, escalável e consistente entre todos os produtos.