Sistema robusto e escalável para importação, armazenamento, gerenciamento e análise de Notas Fiscais Eletrônicas (NFe) em formato XML.
Automatizar a extração de informações fiscais e comerciais de arquivos XML de NFe, permitindo a geração de relatórios analíticos customizáveis que auxiliem na tomada de decisões estratégicas, conformidade fiscal e gestão de compras e vendas.
O NFe-Analytics foi projetado considerando a evolução constante do padrão NFe, regulamentado pelo Manual de Orientação ao Contribuinte (MOC). A arquitetura híbrida combina:
- Dados Estruturados: Campos essenciais em colunas relacionais indexadas para máxima performance
- Dados Flexíveis (JSONB): Estrutura completa do XML armazenada em JSON para adaptabilidade total
✅ Resiliência a Mudanças: Novos campos do MOC são automaticamente capturados sem necessidade de migração de banco de dados
✅ Performance Otimizada: Consultas rápidas em campos estruturados para relatórios frequentes
✅ Manutenção Reduzida: 0-4 horas de trabalho para adicionar novos campos vs. dias na abordagem tradicional
✅ Sem Perda de Dados: Toda a estrutura do XML é preservada e consultável
✅ Código Simplificado: Parser 80% mais simples e robusto usando xmltodict
- Upload de múltiplos arquivos XML simultaneamente
- Processamento assíncrono para não bloquear a interface
- Validação e armazenamento em banco de dados híbrido
- Lista completa de produtos com todos os detalhes
- Agrupamento por NCM (Nomenclatura Comum do Mercosul)
- Agrupamento por CEST (Código Especificador da Substituição Tributária)
- Agrupamento por alíquota de ICMS com valores totais
- Identificação de produtos com IPI e respectivos valores
- Consultas customizadas em qualquer campo do XML via JSONB
┌─────────────┐
│ Frontend │ React/Vue.js (SPA)
│ (Client) │
└──────┬──────┘
│
▼
┌─────────────┐
│ Backend │ Python/Django (API RESTful)
│ API │
└──────┬──────┘
│
├────────► RabbitMQ (Fila de Tarefas)
│ │
│ ▼
│ ┌─────────────┐
│ │ Worker │ Celery (Processamento Assíncrono)
│ │ (Parser) │
│ └──────┬──────┘
│ │
▼ ▼
┌──────────────────────────┐
│ PostgreSQL │
│ (Relacional + JSONB) │
└──────────────────────────┘
- Campos estruturados: chave_acesso, número, série, data, valores, emitente, destinatário
- Campo flexível:
dados_completos(JSONB) - estrutura completa da NFe
- Campos estruturados: código, descrição, NCM, CFOP, quantidade, valores
- Campos flexíveis:
impostos_completos(JSONB) - ICMS, IPI, PIS, COFINS, etc.dados_adicionais(JSONB) - outros dados do produto
| Componente | Tecnologia |
|---|---|
| Frontend | React.js ou Vue.js |
| Backend | Python com Django ou Flask |
| Banco de Dados | PostgreSQL (com suporte a JSONB) |
| Fila de Tarefas | RabbitMQ ou Redis |
| Worker Assíncrono | Celery |
| Parsing de XML | xmltodict |
| Containerização | Docker e Docker Compose |
- Projeto Completo v2.0 - Especificação técnica detalhada
- Resumo das Mudanças - Evolução da v1.0 para v2.0
- Análise do MOC - Análise do Manual de Orientação ao Contribuinte
Veja um exemplo funcional do parser em examples/parser_example.py.
O parser converte automaticamente o XML para JSON e extrai dados estruturados:
import xmltodict
# Converte XML inteiro para dicionário
nfe_dict = xmltodict.parse(xml_content)
# Extrai campos estruturados
nota_fiscal = {
'numero': safe_get(inf_nfe, 'ide.nNF'),
'dados_completos': json.dumps(inf_nfe) # Salva tudo em JSONB
}Consultar impostos que não estão em colunas estruturadas:
SELECT
descricao,
impostos_completos -> 'PIS' -> 'PISAliq' ->> 'pPIS' as aliquota_pis,
impostos_completos -> 'PIS' -> 'PISAliq' ->> 'vPIS' as valor_pis
FROM produtos_nfe
WHERE impostos_completos -> 'PIS' -> 'PISAliq' ->> 'CST' = '01';- Docker e Docker Compose
- Git
- Clone o repositório:
git clone <url_do_repositorio> nfe-analytics
cd nfe-analytics- Configure as variáveis de ambiente:
cp .env.example .env
# Edite o arquivo .env com suas configurações- Inicie os containers:
docker-compose up --build -d- Execute as migrações do banco de dados:
docker-compose exec backend python manage.py migrate- Acesse a aplicação:
- Frontend: http://localhost:3000
- API Backend: http://localhost:8000/api/
| Fase | Descrição | Tempo |
|---|---|---|
| Setup Inicial | Configuração do ambiente e estrutura | 1 semana |
| Modelagem e BD | Implementação dos modelos com JSONB | 1 semana |
| Backend - Importação | Endpoint de upload e worker com parser | 2 semanas |
| Backend - API | Endpoints para relatórios | 2 semanas |
| Frontend - Base | Estrutura da SPA, login, layout | 2 semanas |
| Frontend - Upload | Funcionalidade de upload e listagem | 1,5 semanas |
| Frontend - Relatórios | Telas de visualização de relatórios | 2 semanas |
| Testes | Testes de integração e refinamento | 2 semanas |
| Deploy | Preparação e deploy em produção | 1 semana |
| Total | ~3,5 meses |
- Autenticação via JSON Web Tokens (JWT)
- Proteção contra SQL Injection, XSS, CSRF
- Senhas criptografadas com bcrypt/Argon2
- Comunicação via HTTPS em produção
- Logs de auditoria para ações críticas
- Implementação do backend (API + Worker)
- Desenvolvimento do frontend (SPA)
- Dashboards interativos com gráficos
- Integração com SEFAZ para validação de chaves
- Sistema de alertas e notificações
- Exportação de relatórios para PDF/Excel
- Gerenciamento avançado de usuários e permissões
Este projeto é um protótipo de engenharia de software desenvolvido para fins educacionais e de planejamento.
Manus AI - Especificação e Arquitetura do Sistema
Versão: 2.0
Data: Novembro de 2025