Central Utils - Documentação Completa

📋 Índice da Documentação

Bem-vindo ao guia de documentação da Central Utils, uma plataforma integrada de ferramentas contábeis e administrativas que automatiza diversos processos de empresas.

📚 Documentos Principais

01 - Arquitetura do Projeto
Visão geral da arquitetura
Stack tecnológico (Node.js + Python + Go)
Fluxo de dados e comunicação entre módulos
02 - Guia de Instalação
Pré-requisitos
Configuração do ambiente
Variáveis de ambiente (.env)
Instalação de dependências
03 - Guia de Uso
Como iniciar o projeto
Acesso da aplicação web
Uso básico das ferramentas
Resolução de problemas
04 - Contribuindo
Padrões de código
Como adicionar novas ferramentas
Processo de pull request
Testes e qualidade

🛠️ Ferramentas Disponíveis

API Python (Backend)

A API Python fornece os cores de processamento. Acesse docs/api/ para documentação detalhada:

Gerador de Atas - Geração automática de atas de reunião
Separador PDF - Relatório de Férias - Extração e separação de folhas de férias
Separador PDF - Holerites - Separação de holerites por empresa
Separador Férias por Funcionário - Organização de dados de férias
Separador CSV - Baixa Automática - Processamento de planilhas de baixa
Excel para PDF em Abas - Conversão de Excel em PDF estruturado
Compressor de PDF - Redução de tamanho de PDFs
Extrator ZIP/RAR - Extração de arquivos compactados
Importador de Recebimentos MADRE SCP - Integração com sistema MADRE
Ajuste Diário GFBR - Ajustes contábeis automáticos

📖 Runbooks Operacionais

Para suporte operacional e troubleshooting, acesse docs/runbooks/:

Runbook - Gerador de Atas - Sintomas, DEBUG, reprocesso
Runbook - Separador de Férias - PDF parsing, memory management
Runbook - Separador CSV Baixa - Formatação, locale issues
Runbook - Excel para PDF - COM issues, Windows-only warnings
Runbook - Relatório de Férias - Company detection, ZIP creation
Runbook - Holerites - pdfplumber extraction, normalization
Runbook - Compressor PDF - PyMuPDF quality, DPI settings
Runbook - Extrator ZIP/RAR - CRC errors, conflict resolution
Runbook - Importador MADRE - API auth, DB integrity
Runbook - Ajuste GFBR - Validation, audit, accounting rules

❓ FAQ Global

Para dúvidas transversais e troubleshooting consolidado:

FAQ Global - Central Utils (12 categorias)
Autenticação & Integrações
Problemas com Arquivos (PDF, Excel, CSV)
Formatação & Encoding
Performance & Memory
Permissões & Segurança
Validação & Dados
Problemas COM (Windows)
Arquivos Comprimidos
Banco de Dados
Conversão & Output
Troubleshooting Geral
Escalação & Contatos

Frontend (Aplicação Web)

Acesse docs/frontend/ para documentação:

Estrutura General - Organização de arquivos HTML/JS
Autenticação - Sistema de login e tokens
Componentes Comuns - Upload, logs, etc.
Integração API - Como integrar com backend

Servidor e Orquestração

Server.js - Express server principal
Worker.js - Processador background de tarefas
Autenticação SERPRO - Integração com API SERPRO

Deployment

Acesse docs/deployment/ para documentação:

Deploy em Produção - Instruções de deployment
Variáveis de Ambiente - Configuração completa
Monitoramento - Logs e health checks
Backup e Recuperação - Estratégia de dados

📖 Exemplos e Testes

Acesse docs/exemplos/ para:

Exemplos de API - Requisições cURL e Postman
Casos de Uso - Cenários reais de utilização
Testes Básicos - Scripts de teste

🚀 Quick Start

Instalação Rápida

# Clonar e entrar na pasta
cd central-utils

# Instalar dependências Node.js
npm install

# Instalar dependências Python
pip install -r api/requirements.txt

# Configurar .env
cp .env.example .env
# Edite o .env com suas configurações

# Iniciar desenvolvimento (Node.js + Python + Go)
npm run dev

Acessar a Aplicação

Frontend: http://localhost:3000
API Python: http://localhost:8001
API Go: http://localhost:8002

📁 Estrutura de Pastas

central-utils/
├── api/                    # Backend Python (FastAPI)
│   ├── *.py               # Cores de processamento
│   └── requirements.txt    # Dependências Python
├── src/                   # Backend Node.js
│   ├── server.js          # Express server
│   ├── worker.js          # Processador background
│   ├── serpro-auth.js     # Autenticação SERPRO
│   ├── queue.js           # Gerenciador de fila
│   └── parsers.js         # Utilitários de parse
├── public/                # Frontend
│   ├── *.html             # Páginas da aplicação
│   ├── js/                # Scripts JavaScript
│   ├── css/styles.css     # Estilos
│   └── img/               # Imagens e assets
├── go-api/                # Backend Go (opcional)
│   └── main.go
├── tools/                 # Ferramentas externas
│   ├── Calculadora Werbran/
│   └── formatador-bernardina/
├── data/                  # Dados e templates
│   ├── atas_modelos/
│   ├── atas_geradas/
│   └── ...
├── docs/                  # Documentação (este arquivo)
├── package.json           # Dependências Node.js
└── README.md             # Este arquivo

🔗 Tecnologias Utilizadas

Backend

Node.js + Express - Servidor web e API REST
Python + FastAPI - microserviços de processamento
Go (opcional) - Processamento de alta performance
Socket.io - Comunicação em tempo real
PostgreSQL - Banco de dados principal
Multer - Upload de arquivos

Frontend

HTML5 / CSS3 / JavaScript - Aplicação web
FormData API - Upload de arquivos
Fetch API - Requisições HTTP

Bibliotecas de Processamento

pdfplumber - Leitura e extração de PDFs
pandas + openpyxl - Processamento de Excel
PyPDF2 - Manipulação de PDFs
PyMuPDF - Renderização de PDFs
Archiver - Compressão de arquivos

📞 Suporte e Comunidade

Para dúvidas ou problemas:

Consulte os exemplos e troubleshooting
Verifique o log de erros em data/logs/
Abra uma issue no repositório

📄 Licença

ISC License - Veja package.json para detalhes

Última atualização: Fevereiro 2026
Versão da Documentação: 1.0.0