Este documento serve como apresentação técnica e gerencial do ecossistema de integração do Agente Fiscal Extendra. Ele detalha os serviços atualmente em execução, seu endereçamento, as propostas de evolução arquitetural e a solução estratégica de mensageria assíncrona.
O ambiente atual roda sobre a rede Docker gpt-sap-network, gerenciado de forma declarativa e centralizada através do Portainer.
graph TD
SAP[SAP ERP / ABAP] -->|Outbound REST| Proxy[Traefik Proxy]
subgraph "1. Camada de Borda & API"
Proxy --> API[Gravitee API Gateway]
Proxy --> Console[Gravitee Console/Portal]
end
subgraph "2. Camada de Automação & IA"
API --> N8N[N8N Orchestrator]
N8N --> Qdrant[(Qdrant Vector DB)]
N8N --> Ollama[Ollama Local LLM]
N8N --> SEFAZ[SEFAZ / Focus NFe]
end
subgraph "3. Mensageria & Persistência"
N8N <--> MQ[RabbitMQ]
N8N <--> Redis[(Redis Cache)]
N8N <--> DB[(PostgreSQL)]
N8N <--> Storage[SeaweedFS Storage]
end
subgraph "4. Observabilidade & Gestão"
Grafana[Grafana / Prometheus]
Kibana[Kibana / ElasticSearch]
Vault[Hashicorp Vault - Segredos]
Taiga[Taiga - PM/Ticketing]
end
| Serviço |
Função |
Endereço (Traefik) |
Status de Saúde |
| Traefik |
Reverse Proxy e Edge Router (SSL/TLS). |
traefik.saphana.dev |
🟢 UP |
| Portainer |
Gestor centralizado de Containers. |
portainer.saphana.dev |
🟢 UP |
| Gravitee Gateway |
API Gateway (Rate Limit, Auth, Roteamento). |
dev-api.saphana.dev |
🟢 UP |
| Gravitee Portal/Mgmt |
Portal de APIs e Gestão do Gateway. |
extendra.saphana.dev |
🟢 UP |
| N8N (Web/Worker) |
Orquestrador de Fluxos (Mensageria e Integração). |
extendran8n.saphana.dev |
🟢 UP |
| Ollama Local |
Motor Local de Inteligência Artificial (LLM). |
Uso Interno / Sem Rota Externa |
🟢 UP |
| Qdrant |
Banco de Dados Vetorial para IA (RAG). |
qdrant.saphana.dev |
🟢 UP |
| Postgres / Redis |
Bancos de dados relacionais e em memória. |
Uso Interno / Sem Rota Externa |
🟢 UP |
| RabbitMQ |
Filas Assíncronas (AMQP). |
extendramq.saphana.dev |
🟢 UP |
| SeaweedFS |
Armazenamento de objetos (Anexos, PDFs, XMLs). |
Uso Interno / Sem Rota Externa |
🟢 UP |
| Grafana / Kibana |
Dashboards de Negócios e Logs centralizados. |
extendragrafana.saphana.dev |
🟢 UP |
| Hashicorp Vault |
Cofre seguro de credenciais e senhas (Tokens). |
extendravault.saphana.dev |
🚨 RESTARTING |
| Taiga |
Gestão de Projetos e Abertura de Chamados (Tickets). |
backlog.saphana.dev |
🟢 UP |
Apesar da infraestrutura ser de grau corporativo (Enterprise), as seguintes ações táticas prepararão o ecossistema para escala e venda do produto:
- Correção do Vault e Injeção de Segredos: Consertar o Crash Loop do Vault. Ganho: Removeremos senhas em texto puro de variáveis de ambiente. O n8n e o SAP poderão rotacionar e buscar chaves da Sefaz diretamente do cofre.
- Consolidação de Recursos (Databases e Filas): Unificar os contêineres segregados de Dev/Prod do RabbitMQ, Redis e Postgres em instâncias únicas (separadas logicamente por Databases ou VHosts). Ganho: Economia de até 6GB de memória RAM, alocando mais poder de processamento para o motor do Ollama (LLM).
- Ocultação do Qdrant da Borda Pública: Remover a regra do Traefik para o Qdrant. O acesso deve ser estritamente interno via rede Docker (
http://qdrant:6333). Ganho: Blindagem de segurança de dados sensíveis e conhecimento do Agente (RAG).
- Política de Retenção no ElasticSearch: Configurar o Index Lifecycle Management (ILM). Ganho: Evita que os logs de sistema congelem o disco do servidor a longo prazo.
- Automação de Suporte com o Taiga: Integrar falhas do n8n (ex: erro de schema XML) para criarem tickets automaticamente no sistema de Backlog (Taiga). Ganho: Atendimento preventivo e visibilidade técnica para a equipe.
O desafio: O ambiente SAP opera atrás de Firewalls/NAT que impedem requisições de entrada (Inbound Webhooks), causando erros de timeout (Dumps) quando a SEFAZ demora a responder uma requisição HTTP longa.
A solução: A adoção do Asynchronous Polling Pattern (Padrão de Consulta Assíncrona via Ticket) utilizando RabbitMQ.
sequenceDiagram
participant SAP as SAP ABAP
participant Gravitee as Gravitee API Gateway
participant N8N as N8N (Web Webhook)
participant MQ as RabbitMQ
participant Worker as N8N (Worker Interno)
participant Redis as Redis / DB
participant SEFAZ as Focus NFe / Prefeitura
Note over SAP, SEFAZ: FASE 1: Despacho Rápido (Milissegundos)
SAP->>Gravitee: 1. POST /api/nfse (Payload SAP)
Gravitee->>N8N: 2. Roteia Requisição
N8N->>MQ: 3. Publica Evento na Fila de Emissão
MQ-->>N8N: 4. Confirma Gravação
N8N-->>Gravitee: 5. HTTP 202 Accepted + {Ticket_ID}
Gravitee-->>SAP: 6. Retorna {Ticket_ID}
Note right of SAP: Conexão HTTP Fechada.<br/>Fim do risco de Timeout no SAP.
Note over Worker, SEFAZ: FASE 2: Processamento Pesado em Fundo (Segundos/Minutos)
Worker->>MQ: 7. Consome Evento da Fila
Worker->>SEFAZ: 8. Transmite e Assina NFS-e
SEFAZ-->>Worker: 9. Resposta Sefaz (XML Aprovado/Rejeitado)
Worker->>Redis: 10. Salva Status + XML de Retorno (Chave: Ticket_ID)
Note over SAP, Redis: FASE 3: Polling via Job de Background (O SAP no controle)
SAP->>Gravitee: 11. GET /api/nfse/status?ticket={Ticket_ID}
Gravitee->>N8N: 12. Roteia Requisição
N8N->>Redis: 13. Busca Dados do Ticket
Redis-->>N8N: 14. Retorna (Processando ou XML Pronto)
N8N-->>Gravitee: 15. Formata Resposta JSON
Gravitee-->>SAP: 16. HTTP 200 OK (XML gravado no SAP)
Note left of SAP: Processo Concluído com Segurança Absoluta.
- Resiliência a Quedas de Rede: Se a SEFAZ estiver fora do ar, a mensagem da NF-e não é perdida; ela fica na fila do RabbitMQ esperando tentativas automáticas (Retries).
- Alta Disponibilidade para o Usuário: O usuário final do SAP não fica com a tela travada com a ampulheta do Windows rodando. Ele solicita a emissão e a tela é liberada na hora. O status atualiza sozinho quando o Job buscar o retorno.
- Respeito à Infraestrutura Local: Não precisamos de túneis, VPNs de entrada ou expor portas do SAP para a internet. O SAP é quem sempre toma a iniciativa de perguntar (Outbound Polling).