Pular para conteúdo

Especificação Técnica

Especificação original (02/07/2026) vs. implementação real

Este documento foi escrito antes do início do desenvolvimento e descrevia uma stack (DRF + React/Next.js/TypeScript/Tailwind) e uma arquitetura em camadas (Clean Architecture/DDD/Event Driven) que não correspondem ao MVP entregue (finalizado 10/09/2026, v1.0.0, 100% em produção). A stack real é Django Templates server-rendered puro — decisão formalizada nos ADRs 002-drf-posmvp.md e 005-nextjs-posmvp.md do próprio repositório coreflow-crm (categoria "Pós-MVP"). A seção Stack Oficial abaixo foi corrigida nesta revisão; as demais seções (multiempresa, UUID, soft delete, event-driven etc.) refletem a especificação original e podem divergir do código real — consultar o repositório coreflow-crm para o detalhe granular de cada convenção.

Objetivo

Definir os padrões técnicos oficiais para implementação do CoreFlow CRM.

Este documento serve como referência para desenvolvimento, revisão de código, automação por IA e evolução do produto.

Stack Real (implementada)

Backend

  • Python 3.12+
  • Django 5+ (Django Templates server-rendered — MTV clássico, sem camada de apresentação desacoplada)
  • Celery
  • Redis

Banco de Dados

  • PostgreSQL 16+

Frontend

  • Django Templates + Bootstrap 5, tema Dracula at Night (padrão Django-only, ver Standards Frontend)
  • Não usa React, Next.js, TypeScript nem Tailwind CSS — essa stack foi avaliada e descartada para o MVP (ADR-005-nextjs-posmvp)

API REST (adicionada pós-MVP)

Django REST Framework foi incorporado depois do MVP (14/09/2026, skill hx-implementar-api), cobrindo 3 domínios com TokenAuthentication — não é a base arquitetural do produto, é uma camada adicional (ADR-002-drf-posmvp).

Infraestrutura

  • Docker
  • Docker Compose
  • Nginx Proxy Manager
  • GitHub Actions

Arquitetura Original Planejada (não seguida integralmente)

A especificação original previa:

  • Clean Architecture
  • DDD
  • SOLID
  • API First
  • Event Driven
  • AI First Documentation

O MVP real segue Django MTV pragmático — models/views/templates por app de domínio (accounts, contas, contatos, leads, oportunidades, atividades, tarefas, anotacoes, auditoria), sem separação formal em camadas application/domain/infrastructure/presentation.

Organização Original Planejada (não implementada)

crm/

application/

domain/

infrastructure/

presentation/

Backend

Cada módulo deverá possuir:

  • Models
  • Services
  • Repositories
  • Serializers
  • Views
  • URLs
  • Permissions
  • Validators
  • Tests

API REST

Padrões:

  • JSON
  • UTF-8
  • HTTPS
  • JWT
  • OpenAPI

Versionamento

/api/v1/

Identificadores

Todos os registros utilizarão:

  • UUID

Nunca utilizar ID sequencial nas APIs públicas.

Datas

Sempre utilizar:

  • UTC

Formato:

ISO-8601

Soft Delete

Obrigatório.

Campos:

  • deleted_at
  • deleted_by

Auditoria

Obrigatória.

Campos mínimos:

  • created_at
  • updated_at
  • created_by
  • updated_by

Multiempresa

Todas as entidades deverão possuir:

company_id

Toda consulta deverá respeitar o tenant ativo.

Segurança

Obrigatório:

  • JWT
  • RBAC
  • HTTPS
  • Auditoria
  • LGPD

Cache

Redis será utilizado para:

  • Sessões
  • Cache
  • Filas
  • Rate Limit

Arquivos

Uploads utilizando serviço centralizado do Core.

Não armazenar arquivos diretamente no módulo CRM.

Eventos

Publicar apenas Domain Events.

Nunca disparar integrações diretamente pela camada de apresentação.

Logs

Registrar:

  • Erros
  • Auditoria
  • Eventos
  • Integrações

Testes

Obrigatórios:

  • Unitários
  • Integração
  • API
  • Permissões

Qualidade

Ferramentas:

  • Ruff
  • Black
  • Pytest
  • Coverage
  • mypy

Performance

Objetivos:

  • APIs < 300 ms
  • Paginação obrigatória
  • Lazy Loading
  • Índices adequados
  • Consultas otimizadas

Convenções

Seguir integralmente os Standards do CoreFlow Docs.

Não criar exceções locais.

Compatibilidade (visão original, não implementada)

O CRM deveria integrar-se nativamente com um Core compartilhado e demais produtos da plataforma (ver status real). Hoje não há integração implementada entre CoreFlow CRM e outros produtos do ambiente hauxtech.

Objetivo Final

Estabelecer uma base técnica consistente, escalável e padronizada para implementação e evolução contínua do CoreFlow CRM.