Resumo
Plataforma demonstrativa de automações para processamento de dados, consolidação de arquivos e geração de relatórios com Python.
Case de projeto
- Projeto demonstrativo
- Automação com Python
- Dados de exemplo
- Repositório privado
- Aplicação funcional
Python Automation: Operational Intelligence
Plataforma demonstrativa que apresenta como rotinas de tratamento de dados, consolidação e geração de relatórios podem ser automatizadas com Python e integradas a uma aplicação web.
A aplicação publicada funciona em Next.js e TypeScript. Python é executado somente no ambiente local para gerar artefatos versionados; o deploy não inicia um runtime Python.
- Geração local de dados
- Validação de payloads
- Análise de qualidade
- Relatórios de exemplo
- Interface web demonstrativa
Repositório privado; referência auditada na branch main, commit 3ded093.
Código-fonte privadoAs evidências técnicas verificáveis estão documentadas neste case.
Visão geral
Problema
Rotinas manuais de limpeza, consolidação e produção de relatórios podem consumir tempo, gerar inconsistências e dificultar a rastreabilidade.
Meu papel
Estruturação dos fluxos, desenvolvimento dos scripts e da interface, definição das validações e documentação das entradas, saídas e limitações.
- Automações modeladas
- 8
- Demo publicada / contagem em /api/executions, cenário sintético / 13 out. 2026
- Registros processados
- 12.290
- Demo publicada / soma de records em /api/executions, cenário sintético / 13 out. 2026
- Horas economizadas
- 90,2h
- Demo publicada / soma de hoursSaved, premissa fixa do gerador / 13 out. 2026
Entradas, dados e premissas
O deploy recebe identificadores e opções em JSON; ele não oferece upload de arquivos. Os CSV, JSON e HTML disponíveis são amostras estáticas geradas localmente e versionadas no repositório.
Os nomes, documentos e valores são fictícios. A amostra bruta contém quatro registros, e o gerador Python define oito automações demonstrativas sem conexão com dados empresariais. Os 12.290 registros e as 90,2 horas exibidos no case somam as oito execuções simuladas que o app publica em /api/executions.
- Entrada no deploy
- JSON com slug ou ID, regras e modo
- Entrada dos scripts
- Constantes e data/automations.json
- Formatos versionados
- CSV, JSON e HTML
- Dados pessoais
- Nomes e CPFs explicitamente fictícios
- Persistência
- Arquivos estáticos; sem banco de dados
- Limite explícito
- 100 KB no endpoint de qualidade de dados
Estrutura dos dados
Entidades modeladas
- Automation: catálogo e parâmetros do cenário demonstrativo.
- DatasetRecord: registro tabular usado nas amostras bruta e tratada.
- RuleDefinition: regra ativada na resposta simulada de execução.
- DataQualityIssue: problema detectado por coluna, tipo e severidade.
- AutomationRunResult: resposta JSON com logs, trilha e arquivos estáticos.
- GeneratedFile: metadado e caminho público de uma amostra versionada.
Arquitetura da automação
As fronteiras abaixo refletem a implementação pública: Python local gera artefatos; o deploy executa somente a aplicação Next.js e funções TypeScript leves.
Interface web
Next.js envia JSON e apresenta progresso e logs; o avanço visual usa timers.
Route Handlers
Funções TypeScript validam requisições e respondem com 200, 400, 404 ou 413.
Regras TypeScript
Módulos analisam JSON versionado; não chamam Python nem serviço externo.
Artefatos versionados
JSON, CSV e HTML guardam cenários e downloads; não há banco, fila ou persistência.
Python local
Dois scripts Python 3, sem dependências externas, geram os artefatos antes do deploy.
Fluxos automatizados
Cada fluxo é classificado pelo nível real de implementação, sem equiparar scripts locais, funções serverless e animações de interface.
| Fluxo / objetivo | Estado | Entrada e processamento | Saída | Validação / erro |
|---|---|---|---|---|
| Geração de dados e relatórios com PythonProduzir datasets e relatórios de exemplo para o cenário demonstrativo. | Executável pelo repositório | Usa constantes e data/automations.json para gravar JSON, CSV e HTML em data/ e public/samples/. | Amostras brutas, tratadas, logs e prévias de relatório. | Execução local, sem PDF, agendamento ou runtime Python no deploy; falhas encerram o script. |
| Execução estruturada de automaçãoDemonstrar seleção de regras, progresso, logs e arquivos associados a uma rotina. | Demonstração de interface | A UI envia JSON; um Route Handler TypeScript valida o payload e monta a resposta a partir de dados versionados. | Resposta com status, logs, trilha de auditoria e caminhos de amostras. | O progresso usa timers e não representa uma transformação Python ou processamento de arquivo em produção. |
| Análise de qualidade de dadosDetectar problemas em um dataset fictício identificado no catálogo. | Funcional na aplicação | O endpoint TypeScript aplica regras determinísticas sobre JSON importado no build e devolve o relatório. | Problemas por campo, completude, contagens e recomendações técnicas. | Trabalha somente com datasets internos; não aceita upload e limita o corpo da requisição a 100 KB. |
Geração de dados e relatórios com Python
Produzir datasets e relatórios de exemplo para o cenário demonstrativo.
- Estado
- Executável pelo repositório
- Entrada e processamento
- Usa constantes e data/automations.json para gravar JSON, CSV e HTML em data/ e public/samples/.
- Saída
- Amostras brutas, tratadas, logs e prévias de relatório.
- Validação / erro
- Execução local, sem PDF, agendamento ou runtime Python no deploy; falhas encerram o script.
Execução estruturada de automação
Demonstrar seleção de regras, progresso, logs e arquivos associados a uma rotina.
- Estado
- Demonstração de interface
- Entrada e processamento
- A UI envia JSON; um Route Handler TypeScript valida o payload e monta a resposta a partir de dados versionados.
- Saída
- Resposta com status, logs, trilha de auditoria e caminhos de amostras.
- Validação / erro
- O progresso usa timers e não representa uma transformação Python ou processamento de arquivo em produção.
Análise de qualidade de dados
Detectar problemas em um dataset fictício identificado no catálogo.
- Estado
- Funcional na aplicação
- Entrada e processamento
- O endpoint TypeScript aplica regras determinísticas sobre JSON importado no build e devolve o relatório.
- Saída
- Problemas por campo, completude, contagens e recomendações técnicas.
- Validação / erro
- Trabalha somente com datasets internos; não aceita upload e limita o corpo da requisição a 100 KB.
Regras de processamento
Regras confirmadas no código TypeScript e nos geradores Python. As transformações publicadas operam sobre dados de exemplo.
| Regra | Entrada | Transformação | Saída | Em caso de erro |
|---|---|---|---|---|
| Validação do payloadRestringe IDs, slugs, modos, formatos e listas de regras com schemas Zod. | JSON enviado aos Route Handlers. | Valida tamanho, expressão regular e enums antes de consultar o catálogo. | Objeto tipado aceito pela função de domínio. | Retorna 400 para payload inválido e 404 para automação ou relatório desconhecido. |
| Qualidade de dadosDetecta obrigatórios ausentes, datas e tipos inválidos, duplicidades, texto inconsistente e outliers. | Registros JSON do dataset fictício. | Percorre o schema, conta IDs, compara texto e aplica limites de 1,5 × IQR. | Ocorrências, impacto e recomendação por registro. | Não corrige a origem nem avalia campos não catalogados; dataset desconhecido retorna 404. |
| Seleção do relatórioLocaliza um relatório estático pelo slug e acrescenta timestamp e seções à resposta. | automationSlug e formato JSON ou HTML. | Consulta data/reports.json e monta um payload TypeScript. | Resposta JSON e link para amostra HTML versionada. | Não renderiza PDF nem persiste um novo relatório; slug desconhecido retorna 404. |
Validação do payload
Restringe IDs, slugs, modos, formatos e listas de regras com schemas Zod.
- Entrada
- JSON enviado aos Route Handlers.
- Transformação
- Valida tamanho, expressão regular e enums antes de consultar o catálogo.
- Saída
- Objeto tipado aceito pela função de domínio.
- Em caso de erro
- Retorna 400 para payload inválido e 404 para automação ou relatório desconhecido.
Qualidade de dados
Detecta obrigatórios ausentes, datas e tipos inválidos, duplicidades, texto inconsistente e outliers.
- Entrada
- Registros JSON do dataset fictício.
- Transformação
- Percorre o schema, conta IDs, compara texto e aplica limites de 1,5 × IQR.
- Saída
- Ocorrências, impacto e recomendação por registro.
- Em caso de erro
- Não corrige a origem nem avalia campos não catalogados; dataset desconhecido retorna 404.
Seleção do relatório
Localiza um relatório estático pelo slug e acrescenta timestamp e seções à resposta.
- Entrada
- automationSlug e formato JSON ou HTML.
- Transformação
- Consulta data/reports.json e monta um payload TypeScript.
- Saída
- Resposta JSON e link para amostra HTML versionada.
- Em caso de erro
- Não renderiza PDF nem persiste um novo relatório; slug desconhecido retorna 404.
Decisões técnicas
Python como gerador local de artefatos
- Motivo
- Mantém scripts reproduzíveis no repositório e evita declarar um runtime que o deploy não possui.
- Consequência / trade-off
- A aplicação publicada não processa arquivos nem executa Python sob demanda.
Route Handlers TypeScript com Zod
- Motivo
- Oferecem contratos de entrada e respostas verificáveis no mesmo ambiente Next.js.
- Consequência / trade-off
- As funções são adequadas a payloads pequenos e não substituem workers de processamento pesado.
Amostras versionadas para downloads
- Motivo
- CSV, JSON e HTML tornam o cenário público e reproduzível sem infraestrutura adicional.
- Consequência / trade-off
- Os downloads são estáticos e não comprovam uma execução individual do usuário.
Outras decisões técnicas
Separação explícita entre interface e processamento
- Motivo
- Evita apresentar timers, logs e métricas fictícias como uma automação Python em produção.
- Consequência / trade-off
- A demonstração comunica o fluxo, mas exige evolução arquitetural para cargas reais.
Evidências públicas
Aplicação verificada sem login; caminhos de código conferidos no repositório privado, branch main, commit 3ded093.
Aplicação pública
Aplicação publicada
Deploy funcional da interface Next.js e dos Route Handlers leves.
Abrir evidênciaCódigo-fonte privado
Repositório no commit 3ded093
Snapshot privado usado nesta auditoria, sem depender do estado futuro da branch.
Referências de implementação
Documentação pública
README e limites de execução
Documenta Python local, dados fictícios, downloads estáticos e ausência de runtime Python na produção.
Referência de códigoREADME.md
Referência de código
Gerador de datasets
Script Python que cria o catálogo e as amostras JSON e CSV versionadas.
Referência de códigoscripts/generate_datasets.py
Referência de código
Gerador de relatórios
Script Python que deriva data/reports.json e o HTML demonstrativo.
Referência de códigoscripts/generate_reports.py
Endpoint público
Endpoint de execução
Route Handler TypeScript que valida JSON e monta uma execução demonstrativa.
Referência de códigoapp/api/automations/run/route.ts
Endpoint público
Endpoint de qualidade
Endpoint público com limite de 100 KB, validação e respostas 400, 404 e 413.
Referência de códigoapp/api/data-quality/analyze/route.ts
Referência de código
Schemas de entrada
Contratos Zod para execução, relatório, qualidade e filtros de histórico.
Referência de códigolib/validators.ts
Referência de código
Teste do endpoint de execução
Cobre resposta estruturada e rejeição de automação inexistente.
Referência de códigotests/api-run.test.ts
Saídas geradas
- Dados de exemplo
- CSV
- Bases bruta e tratada
- Amostras pequenas geradas localmente e publicadas para download.
- Saída demonstrativa
- JSON + HTML
- Logs, checklist e relatório
- Artefatos estáticos e prévia criada pelos scripts locais.
- Resposta técnica
- 200 / 4xx
- Contratos de API
- Respostas verificáveis para sucesso, payload inválido, item ausente e excesso de tamanho.
Esta seção descreve formatos e respostas técnicas, não KPIs de negócio. Horas, economia, produtividade e ROI exibidos na demonstração são valores hipotéticos e não foram mantidos como resultados do case.
As amostras estão versionadas no repositório; as respostas dos endpoints podem ser reproduzidas com os identificadores fictícios documentados.
Competências demonstradas
- Automação de rotinas com Python para geração local de artefatos.
- Tratamento e transformação de dados fictícios.
- Validação de entradas e schemas com Zod.
- Consolidação de arquivos e relatórios demonstrativos.
- Integração entre scripts versionados e aplicação web.
- Documentação de fluxos, evidências e limitações.
Limitações e próximos passos
Limitações confirmadas
- Dados e métricas são fictícios; não há uso empresarial ou baseline de resultado.
- Python é executado somente localmente e não está conectado ao fluxo publicado.
- O deploy recebe JSON com identificadores; não existe upload de CSV, XLSX, PDF ou arquivo compactado.
- Não há banco de dados, retenção de uploads ou histórico persistente de novas execuções.
- Fila, worker, processamento assíncrono, autenticação e agendamento não foram implementados.
- A API de qualidade limita o corpo a 100 KB; os demais fluxos usam apenas o catálogo interno.
Evoluções coerentes
- Conectar um worker Python isolado para processamento real e assíncrono.
- Adicionar upload validado, armazenamento temporário seguro e política de descarte.
- Persistir histórico, logs e artefatos com autenticação e autorização.
- Instrumentar filas, observabilidade, alertas e limites operacionais.
- Ampliar testes de integração com arquivos e falhas do runtime Python.
Galeria
Capturas da aplicação publicada em português. Os valores operacionais visíveis pertencem ao cenário fictício e não representam resultados medidos.
Detalhes técnicos opcionais
Como executar
- O repositório é privado; com acesso, use a branch main no commit de referência 3ded093.
- Execute npm install e npm run dev para iniciar a aplicação Next.js.
- Execute python scripts/generate_datasets.py e python scripts/generate_reports.py para reproduzir os artefatos locais; não há dependências Python externas.
- Execute npm run test para validar os contratos e regras existentes.
Próximo projeto
Detecção de Anomalias Operacionais
Detecção não supervisionada de anomalias em métricas operacionais, com alertas por WebSocket e gráfico em D3.
Ver case completo