📑 NF-e Reader — Leitor & Copiloto IA de Notas Fiscais Eletrônicas

Aplicação de alto desempenho para ingestão, leitura, armazenagem relacional, busca vetorial/textual avançada (Hybrid Search) e análise inteligente com IA RAG (Retrieval-Augmented Generation) em arquivos XML de Nota Fiscal Eletrônica (NF-e v4.00).

O sistema combina banco de dados relacional PostgreSQL 16, motor de busca vetorial/textual Elasticsearch 8.12, microsserviço de IA RAG em FastAPI + Google Gemini / OpenAI e interface web moderna em Vue 3 + TypeScript com estilo Liquid Glass.

---

📐 Arquitetura da Solução

O repositório está organizado como um Monorepo:

xml-reader/
├── backend/                  # API REST .NET 8 (Clean Architecture & DDD)
│   ├── src/
│   │   ├── FiscalEngine.Domain/          # Entidades e regras de negócio de NF-e
│   │   ├── FiscalEngine.Application/     # DTOs, Interfaces e Parsers de XML
│   │   ├── FiscalEngine.Infrastructure/  # Repositórios PostgreSQL (EF Core) + Elasticsearch 8
│   │   └── FiscalEngine.Api/             # API REST (Endpoints de Upload, Busca, Histórico e Deleção)
│   └── tools/
│       └── Generator/                # Gerador utilitário de arquivos XML de NF-e sintéticos
├── ai-rag/                   # Microsserviço de Inteligência Artificial & RAG (Python + FastAPI)
│   ├── app/
│   │   ├── main.py                   # Servidor FastAPI (Endpoints /chat, /insights, /sync)
│   │   ├── config.py                 # Configurações Pydantic (Gemini, OpenAI, Ollama)
│   │   ├── services/
│   │   │   ├── elastic_service.py    # Elasticsearch 8 Client (Hybrid Search: BM25 + kNN)
│   │   │   ├── embedding_service.py  # Gerador de Dense Vector Embeddings (384 dimensões)
│   │   │   ├── rag_engine.py         # Motor RAG com injeção dinâmica de contexto fiscal
│   │   │   └── insights_service.py   # Gerador de relatórios (Variação de Preços, Tributos)
│   │   └── schemas/                  # DTOs Pydantic
│   ├── requirements.txt              # Dependências Python
│   └── Dockerfile                    # Containerização Docker
├── frontend/                 # Aplicação Web Modular em Vue 3 (Composition API + TypeScript)
│   ├── src/
│   │   ├── types/                    # Interfaces TypeScript (nfe.ts, rag.ts)
│   │   ├── utils/                    # Formatadores de moeda (BRL), datas e Markdown
│   │   ├── services/                 # Clientes API REST (nfeService.ts, ragService.ts)
│   │   ├── composables/              # Estado reativo e regras (useNfe.ts, useRag.ts)
│   │   ├── components/               # Componentes Modulares por domínio
│   │   │   ├── layout/               # Topbar com estilo Liquid Glass (AppHeader.vue)
│   │   │   ├── upload/               # Hero & Drag and Drop de XML (XmlDropzone.vue)
│   │   │   ├── dashboard/            # Cards estatísticos (NfeDashboard.vue, StatCard.vue)
│   │   │   ├── search/               # Barra de pesquisa com suporte a Enter (NfeSearchBar.vue)
│   │   │   ├── table/                # Tabela ordenada e paginada (NfeTable.vue, NfeTableRow.vue)
│   │   │   ├── modal/                # Modal de detalhes com abas (NfeDetailModal.vue)
│   │   │   └── rag/                  # Copiloto IA (RagCopilotDrawer.vue, RagChatTab.vue, RagInsightsTab.vue)
│   │   └── App.vue                   # Orquestrador declarativo da aplicação
├── samples/                  # 50 Arquivos XML de exemplo para testes de upload
├── docker-compose.yml        # Orquestração Docker (PostgreSQL 16, Elasticsearch 8.12 e AI-RAG)
└── README.md

---

🛠️ Tecnologias Utilizadas

Backend (.NET 8)

• C# / .NET 8 Web API
• Entity Framework Core 8 (PostgreSQL)
• Elastic.Clients.Elasticsearch 8.12
• Clean Architecture & DDD
• Swagger / OpenAPI

AI-RAG Service (Python 3.11+)

• FastAPI & Uvicorn
• Elasticsearch 8 Python Client (Hybrid Search com BM25 + dense vectors kNN)
• Google Gemini API / OpenAI API / Ollama Local
• Dense Vector Embeddings (Vetorização $L_2$ normalizada de 384 dimensões)
• Sanitização UTF-8 imune a falhas de codificação surrogate

Frontend (Vue 3 + TypeScript)

• Vue 3 (Composition API + Script Setup)
• TypeScript & Vite 8
• Tailwind CSS v4 (Design System Liquid Glassmorphism, fontes Inter & JetBrains Mono)
• Formatador Markdown Dinâmico para respostas enriquecidas da IA

Infraestrutura

• PostgreSQL 16 (Persistência relacional oficial)
• Elasticsearch 8.12 (Indexação vetorial e textual híbrida)
• Docker & Docker Compose

---

🚀 Como Executar o Projeto

Pré-requisitos

• .NET 8 SDK instalado
• Node.js v18+ instalado
• Python 3.11+ instalado
• Docker Desktop rodando

---

Step 1: Subir a Infraestrutura (PostgreSQL + Elasticsearch)

Na raiz do projeto:

docker compose up -d postgres elasticsearch

---

Step 2: Executar o Backend .NET 8 (Terminal 1)

Navegue até a pasta backend/ e inicie a API:

cd backend
dotnet run --project src/FiscalEngine.Api/FiscalEngine.Api.csproj

📌 API Backend em: http://localhost:5210
📖 Documentação Swagger em: http://localhost:5210/swagger

---

Step 3: Executar o Serviço RAG de IA (Terminal 2)

Navegue até a pasta ai-rag/, configure seu arquivo .env com a sua chave de API (GEMINI_API_KEY ou OPENAI_API_KEY) e inicie o serviço:

cd ai-rag
pip install -r requirements.txt
python -m uvicorn app.main:app --port 8000 --reload

📌 API RAG em: http://localhost:8000
📖 Documentação Swagger em: http://localhost:8000/docs

---

Step 4: Executar a Aplicação Frontend Vue 3 (Terminal 3)

Em outro terminal, navegue até a pasta frontend/ e inicie o servidor de desenvolvimento:

cd frontend
npm install
npm run dev

📌 Aplicação Web em: http://localhost:5173

---

✨ Funcionalidades Principais

1. Upload Múltiplo (Batch Import): Importe um ou 50 arquivos XML de uma só vez com sincronização automática de vetores RAG em segundo plano.
2. Copiloto IA Fiscal & RAG Conversacional:
   • Faça perguntas em linguagem natural (ex: "Qual a alíquota média de ICMS?", "Qual o preço médio do café?").
   • Busca Híbrida (BM25 + Vetores kNN) no Elasticsearch 8.
   • Fontes Clicáveis: As notas fiscais utilizadas como fonte pela IA aparecem como badges. Clicar no badge abre o modal de detalhes da NF-e no frontend.
   • Formatação Markdown Rica: Respostas com negritos, marcadores e listas ordenadas claras.
3. Insights Automáticos com IA:
   • Discrepância de Preços: Identifica variações de preços unitários em produtos idênticos entre fornecedores.
   • Consolidado Tributário: Alíquota efetiva acumulada de ICMS, PIS e COFINS.
   • Ranking de Emitentes: Maiores fornecedores ordenados por volume financeiro.
4. Dashboard & Tabela Paginada Interativa:
   • Métricas de volume total, ICMS e PIS/COFINS.
   • Seleção de 5, 10, 20 ou 50 itens por página com ordenação por cabeçalho.
5. Modal de Detalhes em Abas:
   • 📋 Visão Geral, 💰 Tributos, 📦 Produtos e 💻 JSON Raw.
6. Massa de Testes Pronta: 50 arquivos XML sintéticos disponíveis na pasta samples/.

---

🧪 Gerar Novos XMLs de Teste

Para gerar novos arquivos XML de exemplo automaticamente:

dotnet run --project backend/tools/Generator/Generator.csproj

Os arquivos serão salvos na pasta samples/.