{"id":31443936,"url":"https://github.com/fabiodelllima/processador-csv-fullstack","last_synced_at":"2026-05-06T03:33:21.126Z","repository":{"id":317115287,"uuid":"883382653","full_name":"fabiodelllima/processador-csv-fullstack","owner":"fabiodelllima","description":"Aplicação fullstack para processamento e validação de grandes volumes de dados financeiros em CSV (~30 GB). Leitura via streaming, validação de CPF/CNPJ com algoritmo próprio (sem bibliotecas externas), verificação de consistência contratual e formatação monetária BRL.","archived":false,"fork":false,"pushed_at":"2026-05-05T23:53:47.000Z","size":531,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-06T01:35:07.770Z","etag":null,"topics":["csv-processing","express","nodejs","postgresql","react","tailwindcss","typescript","vite"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fabiodelllima.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-11-04T21:41:24.000Z","updated_at":"2026-05-05T23:53:50.000Z","dependencies_parsed_at":"2025-09-29T00:18:35.032Z","dependency_job_id":"f95dbac1-a059-4df8-93d0-1b309a062d61","html_url":"https://github.com/fabiodelllima/processador-csv-fullstack","commit_stats":null,"previous_names":["fabiodelllima/processador-csv-fullstack"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/fabiodelllima/processador-csv-fullstack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabiodelllima%2Fprocessador-csv-fullstack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabiodelllima%2Fprocessador-csv-fullstack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabiodelllima%2Fprocessador-csv-fullstack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabiodelllima%2Fprocessador-csv-fullstack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fabiodelllima","download_url":"https://codeload.github.com/fabiodelllima/processador-csv-fullstack/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabiodelllima%2Fprocessador-csv-fullstack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32677928,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-06T02:33:58.958Z","status":"ssl_error","status_checked_at":"2026-05-06T02:33:39.611Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["csv-processing","express","nodejs","postgresql","react","tailwindcss","typescript","vite"],"created_at":"2025-09-30T20:06:28.483Z","updated_at":"2026-05-06T03:33:21.109Z","avatar_url":"https://github.com/fabiodelllima.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Processador CSV\n\n![Node.js](https://img.shields.io/badge/Node.js-22-339933?logo=nodedotjs\u0026logoColor=white)\n![TypeScript](https://img.shields.io/badge/TypeScript-5.6-3178C6?logo=typescript\u0026logoColor=white)\n![React](https://img.shields.io/badge/React-18-61DAFB?logo=react\u0026logoColor=white)\n![PostgreSQL](https://img.shields.io/badge/PostgreSQL-17-4169E1?logo=postgresql\u0026logoColor=white)\n![Tests](https://img.shields.io/badge/Tests-35%20passed-brightgreen)\n![Docker](https://img.shields.io/badge/Docker-Compose-2496ED?logo=docker\u0026logoColor=white)\n\nDesafio técnico fullstack para processamento e validação de grandes volumes de dados financeiros em CSV (~30 GB). A aplicação lê registros de contratos via streaming, valida o CPF/CNPJ com algoritmo próprio (sem bibliotecas externas), verifica a consistência entre valor total e prestações, e formata valores monetários em BRL — exibindo os resultados em uma interface web com indicadores visuais por registro.\n\n\u003c!-- TODO: Adicionar screenshot da interface com dados processados --\u003e\n\u003c!-- ![Preview](docs/assets/preview.png) --\u003e\n\n---\n\n## Sumário\n\n- [O Problema](#o-problema)\n- [A Solução](#a-solução)\n  - [Backend](#backend)\n  - [Frontend](#frontend)\n- [Estrutura do CSV](#estrutura-do-csv)\n- [Stack](#stack)\n- [Testes](#testes)\n- [Uso](#uso)\n\n---\n\n## O Problema\n\nO desafio propunha a construção de uma aplicação capaz de processar aproximadamente **30 GB** de dados financeiros em formato CSV — registros de contratos com campos como CPF/CNPJ, valores totais, prestações, mora, multa, IOF e descontos. Cada registro deveria ser validado individualmente, e os resultados deveriam ser apresentados em uma interface web ao final do processamento.\n\nParte dos dados é intencionalmente inválida: CPFs e CNPJs gerados por um script com dígitos verificadores incorretos, valores de prestação inconsistentes com o total do contrato e campos financeiros em formato bruto que exigem conversão monetária. O objetivo era avaliar a construção de uma solução capaz de lidar com esse volume sem comprometer a memória, mantendo validações rigorosas e retorno visual claro para o usuário.\n\n### Restrições do Desafio\n\n- **Processamento em larga escala:** ~30 GB de dados sem estouro de memória — leitura obrigatoriamente via streaming, sem carregamento integral.\n- **Validação de CPF/CNPJ sem bibliotecas externas:** algoritmo próprio que implementa o cálculo dos dígitos verificadores conforme regras da Receita Federal, tanto para o CPF (11 dígitos) quanto para o CNPJ (14 dígitos). O objetivo era avaliar o raciocínio algorítmico, não o uso de dependências.\n- **Formatação monetária:** todos os campos financeiros (`vlTotal`, `vlPresta`, `vlMora`, `vlMulta`, `vlOutAcr`, `vlIof`, `vlDescon`, `vlAtual`) convertidos para Real Brasileiro (BRL) com `Intl.NumberFormat`.\n- **Verificação de consistência contratual:** divisão de `vlTotal` por `qtPrestacoes` e comparação com `vlPresta` para cada registro, garantindo que os valores de prestação sejam matematicamente coerentes com o valor total do contrato.\n- **Critérios de avaliação:** tratamento de dados em larga escala, comunicação assíncrona, gerenciamento de estado, escolha adequada de tecnologias e boas práticas de desenvolvimento.\n\n---\n\n## A Solução\n\n### Backend\n\nO servidor é construído em **Node.js com TypeScript** e processa os arquivos CSV via streaming com `fs` (File System) e `csv-parser`, convertendo cada linha em um objeto JavaScript sem carregar o arquivo inteiro em memória. Essa abordagem permite que a aplicação suporte arquivos de dezenas de gigabytes sem degradação de desempenho, processando registro por registro em um fluxo assíncrono.\n\nA arquitetura separa responsabilidades em camadas bem definidas: os controllers recebem as requisições HTTP (upload, download, status), delegam ao serviço de processamento que orquestra as validações, e cada tipo de validação reside em seu próprio módulo com interface tipada:\n\n```\nbackend/src/\n├── controllers/                      # Upload, download, status de processamento\n├── database/\n│   ├── migrations/                   # Scripts SQL de criação do schema\n│   └── repository.ts                 # Camada de acesso ao PostgreSQL\n├── services/\n│   ├── csv.service.ts                # Orquestração do fluxo de processamento\n│   └── validations/\n│       ├── document.validation.ts    # CPF/CNPJ (algoritmo próprio)\n│       ├── contract.validation.ts    # Consistência contratual\n│       ├── installment.validation.ts # Verificação de prestações\n│       └── file.validation.ts        # Validação de formato do CSV\n├── interfaces/                       # Tipagem TypeScript (records, results, errors)\n├── errors/                           # Hierarquia de erros (AppError, ValidationError, etc.)\n├── middlewares/                      # Error handler global, upload handler (multer)\n├── config/                           # Database, variáveis de ambiente, upload\n├── utils/                            # Formatação monetária (BRL)\n└── routes/                           # Endpoints REST\n```\n\nA validação de documentos implementa, do zero, o algoritmo de dígitos verificadores da Receita Federal. Para o **CPF**, os multiplicadores [10,9,8…2] geram o primeiro dígito verificador e [11,10,9…2] geram o segundo, com resto de divisão por 11 determinando o dígito esperado. Para o **CNPJ**, a mesma lógica se aplica com multiplicadores [5,4,3,2,9,8,7,6,5,4,3,2] e [6,5,4,3,2,9,8,7,6,5,4,3,2]. Ambos os algoritmos tratam os casos limite definidos pela Receita — sequências repetidas (111.111.111-11), restos iguais a zero e restos iguais a um.\n\nO sistema persiste os resultados de cada validação em **PostgreSQL**, permitindo que o frontend consulte o status e os resultados de processamentos anteriores sem reprocessar o arquivo.\n\n### Frontend\n\nA interface consiste em uma **SPA construída com React 18 e TypeScript**, com build gerenciado pelo **Vite** e estilização via **Tailwind CSS**. O usuário faz upload de um arquivo CSV e acompanha o processamento em tempo real. Ao final, os resultados aparecem em uma tabela com indicadores visuais de aprovação ou reprovação para cada validação — documento válido/inválido, prestação consistente/inconsistente, formatação aplicada.\n\nO gerenciamento de estado do processamento está encapsulado no hook `useCsvProcessor`, que abstrai as chamadas à API e expõe estados de carregamento, progresso e resultados para os componentes de apresentação.\n\n```\nfrontend/src/\n├── components/         # Loader, StatusDots (indicadores visuais por validação)\n├── hooks/              # useCsvProcessor (estado do processamento)\n├── pages/              # Home (upload + tabela de resultados)\n├── services/           # Comunicação com a API backend\n└── interfaces/         # Tipagem compartilhada com o backend\n```\n\n---\n\n## Estrutura do CSV\n\nOs arquivos de entrada contêm registros de contratos financeiros com as seguintes colunas:\n\n| Campo                                                | Descrição                                                               |\n| ---------------------------------------------------- | ----------------------------------------------------------------------- |\n| `nrInst`                                             | Número da Instituição                                                   |\n| `nrAgencia`                                          | Número da Agência                                                       |\n| `cdClient` / `nmClient`                              | Código e nome do cliente                                                |\n| `nrCpfCnpj`                                          | CPF ou CNPJ (alvo de validação)                                         |\n| `nrContrato` / `dtContrato`                          | Número e data do contrato                                               |\n| `qtPrestacoes`                                       | Quantidade de prestações                                                |\n| `vlTotal`                                            | Valor total do contrato                                                 |\n| `vlPresta`                                           | Valor da prestação (comparado com `vlTotal / qtPrestacoes`)             |\n| `vlMora`, `vlMulta`, `vlOutAcr`, `vlIof`, `vlDescon` | Componentes financeiros (mora, multa, outros acréscimos, IOF, desconto) |\n| `vlAtual`                                            | Valor atual                                                             |\n| `idSituac` / `idSitVen`                              | Situação e situação de vencimento                                       |\n\n---\n\n## Stack\n\n| Camada   | Tecnologias                                          |\n| -------- | ---------------------------------------------------- |\n| Backend  | Node.js, TypeScript, Express, csv-parser, PostgreSQL |\n| Frontend | React 18, TypeScript, Vite, Tailwind CSS             |\n| Testes   | Vitest, @vitest/coverage-v8                          |\n| Lint     | Biome, ESLint (type-aware)                           |\n| Infra    | Docker Compose, dotenv                               |\n\n---\n\n## Testes\n\nO backend possui 35 testes unitários cobrindo as regras de negócio centrais do processamento, executados com **Vitest**:\n\n```bash\ncd backend\nnpm test              # Executa todos os testes\nnpm run test:coverage # Executa com relatório de cobertura\n```\n\n| Suite                  | Testes | Cobertura |\n| ---------------------- | ------ | --------- |\n| Validação de CPF/CNPJ  | 12     | 96%       |\n| Validação de prestação | 7      | 100%      |\n| Validação de contrato  | 6      | 100%      |\n| Parsing numérico (BRL) | 10     | 65%       |\n| **Total**              | **35** |           |\n\n---\n\n## Uso\n\n### Pré-requisitos\n\n- Node.js 22+\n- Docker e Docker Compose\n\n### Banco de Dados\n\n```bash\ndocker compose up -d   # Sobe o PostgreSQL na porta 5434\n```\n\n### Backend\n\n```bash\ncd backend\ncp .env.example .env   # Credenciais já configuradas para dev\nnpm install\nnpm run dev            # http://localhost:3000\n```\n\n### Frontend\n\n```bash\ncd frontend\nnpm install\nnpm run dev            # http://localhost:5173\n```\n\n### Fluxo\n\n1. Acesse `http://localhost:5173`\n2. Faça upload de um arquivo CSV\n3. Aguarde o processamento\n4. Visualize os resultados na tabela de validações\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabiodelllima%2Fprocessador-csv-fullstack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffabiodelllima%2Fprocessador-csv-fullstack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabiodelllima%2Fprocessador-csv-fullstack/lists"}