vendaweb-api/docs/architecture.md

Arquitetura do Sistema DRE Gerencial

Visão Geral da Arquitetura

O sistema DRE Gerencial segue uma arquitetura moderna baseada em Next.js com App Router, utilizando uma abordagem de componentes React funcionais e TypeScript para type safety.

Padrões Arquiteturais

1. Arquitetura em Camadas

┌─────────────────────────────────────┐
│           Frontend Layer            │
│  (React Components + Tailwind CSS) │
├─────────────────────────────────────┤
│           API Layer                 │
│        (Next.js API Routes)         │
├─────────────────────────────────────┤
│         Database Layer              │
│    (PostgreSQL + Drizzle ORM)      │
└─────────────────────────────────────┘

2. Estrutura de Componentes

Componente Principal (teste.tsx)

• Responsabilidade: Orquestração da interface DRE hierárquica
• Estado: Gerencia expansão/colapso, ordenação, filtros analíticos
• Padrão: Container Component com lógica de negócio

Componente Analítico (analitico.tsx)

• Responsabilidade: Visualização detalhada de transações
• Estado: Dados analíticos, ordenação, loading
• Padrão: Presentational Component com funcionalidades específicas

3. Gerenciamento de Estado

Estados Locais por Componente

// Estados de expansão hierárquica
const [expandedGroups, setExpandedGroups] = useState<Set<string>>(new Set());
const [expandedSubgrupos, setExpandedSubgrupos] = useState<Set<string>>(new Set());
const [expandedCentros, setExpandedCentros] = useState<Set<string>>(new Set());

// Estados de ordenação
const [sortConfig, setSortConfig] = useState<SortConfig>({
  field: 'descricao',
  direction: 'asc',
});

// Estados de filtros analíticos
const [analiticoFiltros, setAnaliticoFiltros] = useState({
  dataInicio: '',
  dataFim: '',
  centroCusto: '',
  codigoGrupo: '',
  codigoSubgrupo: '',
  codigoConta: '',
});

4. Padrões de Dados

Hierarquia de Dados

interface HierarchicalRow {
  type: 'grupo' | 'subgrupo' | 'centro_custo' | 'conta';
  level: number;
  grupo?: string;
  subgrupo?: string;
  centro_custo?: string;
  conta?: string;
  codigo_conta?: number;
  total?: number;
  isExpanded?: boolean;
  valoresPorMes?: Record<string, number>;
  percentuaisPorMes?: Record<string, number>;
}

Transformação de Dados

• Agregação: Dados brutos → Hierarquia estruturada
• Cálculos: Valores por mês e percentuais automáticos
• Ordenação: Por descrição ou valor total

Fluxo de Dados

1. Carregamento Inicial

API /api/dre → Dados brutos → buildHierarchicalData() → Interface hierárquica

2. Interação do Usuário

Clique em linha → handleRowClick() → setAnaliticoFiltros() → AnaliticoComponent

3. Análise Analítica

Filtros → API /api/analitico → Dados detalhados → Tabela analítica

Padrões de Design

1. Component Composition

• Componentes pequenos e focados
• Props tipadas com TypeScript
• Separação de responsabilidades

2. Custom Hooks (Potencial)

// Exemplo de hook customizado para dados DRE
const useDREData = () => {
  const [data, setData] = useState<DREItem[]>([]);
  const [loading, setLoading] = useState(true);
  
  const fetchData = useCallback(async () => {
    // Lógica de fetch
  }, []);
  
  return { data, loading, fetchData };
};

3. Error Boundaries

• Tratamento de erros em componentes
• Estados de loading e error
• Fallbacks visuais

Performance

1. Otimizações Implementadas

• useCallback para funções de fetch
• useMemo para cálculos pesados (potencial)
• Lazy loading de componentes (potencial)

2. Estratégias de Renderização

• Renderização condicional baseada em estado
• Virtualização para listas grandes (potencial)
• Debounce para filtros (potencial)

Escalabilidade

1. Estrutura Modular

• Componentes reutilizáveis em /components/ui
• APIs separadas por funcionalidade
• Schema de banco bem definido

2. Extensibilidade

• Fácil adição de novos níveis hierárquicos
• Suporte a novos tipos de filtros
• Integração com outras fontes de dados

Segurança

1. Validação de Dados

• TypeScript para type safety
• Validação de parâmetros nas APIs
• Sanitização de queries SQL

2. Controle de Acesso

• Autenticação (a implementar)
• Autorização por níveis (a implementar)
• Logs de auditoria (a implementar)

Monitoramento

1. Logs

• Console logs para debugging
• Error tracking (a implementar)
• Performance monitoring (a implementar)

2. Métricas

• Tempo de carregamento de dados
• Uso de filtros
• Exportações realizadas

Próximos Passos Arquiteturais

1. Implementar Context API para estado global
2. Adicionar React Query para cache de dados
3. Implementar Error Boundaries robustos
4. Adicionar testes unitários e de integração
5. Implementar autenticação e autorização
6. Adicionar monitoramento e analytics