Componente de Geração de Relatórios

Descrição

Este é um componente reutilizável para geração de relatórios em formatos CSV e Excel, implementado seguindo o Padrão de Interface de Componente (Component Interface Pattern) e os princípios SOLID.

Estrutura do Projeto

report-generator-component/
├── src/
│   ├── provided/                    # Interface pública do componente
│   │   ├── interfaces/
│   │   │   └── IReportGenerator.ts  # Interface principal
│   │   ├── ReportGeneratorPort.ts   # Porta do componente
│   │   └── ReportGeneratorConcreteInterface.ts # Interface concreta
│   ├── internal/                    # Implementação interna
│   │   └── ReportGenerator.ts       # Lógica de geração de relatórios
│   └── index.ts                     # Arquivo de índice para exportações
├── tests/                           # Testes unitários e de integração
│   ├── index.test.ts               # Testes de uso do componente
│   ├── ReportGeneratorPort.test.ts # Testes da porta
│   ├── report_output.csv           # Arquivo de saída CSV (gerado pelos testes)
│   └── report_output.xlsx          # Arquivo de saída Excel (gerado pelos testes)
├── examples/                        # Exemplos de uso
│   ├── usage-example.ts            # Exemplo completo de uso
│   ├── relatorio_vendas.csv        # Arquivo gerado pelo exemplo
│   ├── relatorio_vendas.xlsx       # Arquivo gerado pelo exemplo
│   └── dados_complexos.csv         # Arquivo gerado pelo exemplo
├── dist/                           # Código compilado (gerado pelo build)
├── package.json                    # Dependências e scripts
├── tsconfig.json                   # Configuração TypeScript
├── jest.config.js                  # Configuração Jest
└── README.md                       # Esta documentação

Arquitetura

Padrão de Interface de Componente

O componente segue o Padrão de Interface de Componente com as seguintes camadas:

1. Interface Pública (IReportGenerator): Define o contrato do componente
2. Porta (ReportGeneratorPort): Implementa a interface e delega para a lógica interna
3. Interface Concreta (ReportGeneratorConcreteInterface): Gerencia as portas do componente
4. Implementação Interna (ReportGenerator): Contém a lógica de negócio

Princípios SOLID Aplicados

• S - Single Responsibility: Cada classe tem uma responsabilidade específica
• O - Open/Closed: O componente é extensível sem modificação
• L - Liskov Substitution: As implementações podem ser substituídas
• I - Interface Segregation: Interface específica para geração de relatórios
• D - Dependency Inversion: Depende de abstrações, não de implementações

Instalação

npm install

Uso

Exemplo Básico

import { ReportGeneratorConcreteInterface } from './src/provided/ReportGeneratorConcreteInterface';

// Instanciar o componente
const component = new ReportGeneratorConcreteInterface();

// Obter a porta de geração de relatórios
const reportPort = component.getPort('reportPort');

// Dados para o relatório
const data = [
  { mes: 'Janeiro', produto: 'Notebook', vendas: 150, regiao: 'Sudeste' },
  { mes: 'Fevereiro', produto: 'Monitor', vendas: 230, regiao: 'Sudeste' }
];

// Gerar relatório CSV
const csvBuffer = await reportPort!.generateReport(data, 'csv');

// Gerar relatório Excel
const excelBuffer = await reportPort!.generateReport(data, 'excel');

Exemplo Completo

Execute o exemplo completo incluído no projeto:

npx ts-node examples/usage-example.ts

Este exemplo demonstra:

• Instanciação do componente
• Geração de relatórios CSV e Excel
• Tratamento de dados vazios
• Processamento de dados complexos
• Salvamento de arquivos

Formatos Suportados

• CSV: Gera arquivos CSV com cabeçalhos automáticos
• Excel: Gera arquivos XLSX com formatação básica

API

IReportGenerator

interface IReportGenerator {
  /**
   * Gera um relatório a partir de dados JSON
   * 
   * @param data - Array de objetos com os dados a serem convertidos em relatório
   * @param format - Formato de saída do relatório ('csv' ou 'excel')
   * @returns Promise<Buffer> - Buffer contendo o relatório gerado
   */
  generateReport(data: Record<string, any>[], format: 'csv' | 'excel'): Promise<Buffer>;
}

ReportGeneratorPort

class ReportGeneratorPort implements IReportGenerator {
  public readonly id: string;
  
  constructor(id: string);
  
  /**
   * Gera um relatório delegando para a implementação interna
   */
  public async generateReport(data: Record<string, any>[], format: 'csv' | 'excel'): Promise<Buffer>;
}

ReportGeneratorConcreteInterface

class ReportGeneratorConcreteInterface {
  public readonly id: string;
  
  constructor();
  
  /**
   * Obtém uma porta específica do componente
   */
  public getPort(id: string): ReportGeneratorPort | undefined;
}

Scripts Disponíveis

# Executar testes
npm test

# Executar testes em modo watch
npm run test:watch

# Compilar o projeto
npm run build

# Limpar arquivos compilados
npm run clean

Testes

Executar Testes

npm test

Cobertura de Testes

O projeto inclui:

1. Testes Unitários: Verificação de funcionalidades individuais
2. Testes de Integração: Verificação do uso completo do componente
3. Testes de Acoplamento: Verificação da integração entre camadas
4. Testes de Edge Cases: Verificação de casos extremos

Tipos de Teste

• Testes de CSV: Verificação da geração de relatórios CSV
• Testes de Excel: Verificação da geração de relatórios XLSX
• Testes de Dados Vazios: Verificação do comportamento com dados vazios
• Testes de Interface: Verificação da implementação da interface
• Testes de Dados Complexos: Verificação com objetos aninhados
• Testes de Validação: Verificação de tratamento de erros

Dependências

Produção

• exceljs: Geração de arquivos Excel
• json2csv: Conversão de JSON para CSV
• typescript: Linguagem de programação

Desenvolvimento

• jest: Framework de testes
• ts-jest: Suporte TypeScript para Jest
• @types/*: Definições de tipos TypeScript

Build e Deploy

Compilação TypeScript

npm run build

Estrutura de Build

O TypeScript está configurado para:

• Target: ES2021
• Module: CommonJS
• Output: ./dist
• Strict mode habilitado

Pontuações dos Critérios

CR3 - Padrão de Interface de Componente (1,5 pontos)

✅ Implementado corretamente

• Interface pública bem definida (IReportGenerator)
• Porta implementando a interface (ReportGeneratorPort)
• Interface concreta gerenciando portas (ReportGeneratorConcreteInterface)
• Separação clara entre interface pública e implementação interna
• Documentação JSDoc completa para todas as interfaces

CR4 - Princípios SOLID (3,0 pontos)

✅ Aplicados adequadamente

• S: Cada classe tem responsabilidade única
• O: Componente extensível sem modificação
• L: Implementações substituíveis
• I: Interface específica e coesa
• D: Dependência de abstrações
• Tratamento de erros robusto implementado

CR5 - Sistema de Build/Dependências (1,5 pontos)

✅ Configurado corretamente

• Package.json com dependências apropriadas
• TypeScript configurado
• Jest configurado para testes
• Scripts de build e teste definidos
• Arquivo de índice para exportações

CR6 - Testes (1,0 ponto)

✅ Implementados adequadamente

• Testes unitários para funcionalidades
• Testes de integração com acoplamento
• Cobertura de casos de uso principais
• Verificação de saída de arquivos
• Testes de edge cases e validação
• Exemplo de uso completo incluído

Licença

ISC License