Ricardo f902ccbecb Conector Scardua — recebe da API da FLS e entrega no Oracle do cliente

Servico que roda dentro da rede da Comercial Scardua e faz a ponte entre a
API publica da FLS (na VPS) e o Oracle privado (10.16.x), inalcancavel pela
internet.

Fluxo: Holmes -> API na VPS (trata e cifra) -> ESTE conector (abre e valida)
-> Oracle.

Recebimento:
- app/v1/compras.py: POST /v1/compras/dados
- app/services/cripto.py: abre o envelope AES-256-GCM + RSA-OAEP-SHA256 com a
  chave privada. O GCM autentica: corpo adulterado levanta InvalidTag em vez
  de devolver lixo
- app/schemas.py: modulo folha (so pydantic) com a config e o contrato
  PayloadCompras, que espelha o da API. Fora de sincronia devolve 422 de
  proposito, pra falhar explicito em vez de gravar dado torto

Seguranca:
- app/seguranca.py: header X-Token com compare_digest (nao vaza por tempo de
  resposta) + allowlist de IP da VPS
- .gitignore barra configs.json.*, *.bak-*, *.pem e *.key

Config:
- app/config.py e so o carregamento do configs.json
- o bloco "vps" guarda chave privada, token e ips permitidos

Estado: ainda NAO persiste. Recebe, valida e descarta (persistido: false).
O INSERT no Oracle e a proxima fase, e tem que ser MERGE por id_processo
porque o Holmes reentrega webhook.

Docs em docs/ — arquitetura, a decisao do conector (opcao A, com as
alternativas descartadas), deploy e problemas conhecidos.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-08-18 06:05:03 -03:00

3.3 KiB

Raw Blame History

Arquitetura e Visão — Conector Scardua

Documento da ideia: o quê, o porquê e o roadmap. Salvo pra não reexplicar toda sessão. Atualizar quando a visão evoluir.

Em uma frase

O conector roda dentro da rede da Scardua, recebe da API da FLS o dado já tratado e cifrado, abre e grava no Oracle privado do cliente.

Os atores

FLS Tecnologia (dev / nós) — hospeda a API na própria VPS (api-scardua.flstecnologia.tech). Ela recebe o webhook do Holmes, trata e cifra.
Comercial Scardua (cliente) — tem a conta no Holmes e o Oracle (IP privado 10.16.x, inalcançável pela internet). Este conector roda no servidor dele.
Holmes — SaaS de workflow de documentos; dispara o webhook pra API da FLS.

O fluxo completo

Holmes
  │ webhook (público, TLS)
  ▼
API na VPS da FLS                     ← repositório da API
  │  · valida o payload do Holmes
  │  · traduz pro contrato do cliente
  │  · CIFRA com a chave pública do conector
  │ POST + X-Token (público, TLS)
  ▼
CONECTOR no servidor da Scardua       ← ESTE repositório
  │  · confere token e IP de origem
  │  · ABRE com a chave privada
  │  · valida o contrato
  │  · MERGE por id_processo
  ▼
Oracle 10.16.x (rede privada)

As decisões e o PORQUÊ

Por que a API fica na VPS da FLS, e não no servidor do cliente:

O Holmes precisa de endpoint público e estável pros webhooks. Damos isso nós, com domínio e TLS próprios — sem depender de o cliente ter.
O código Python fica sob nosso controle, na nossa infra.

Consequência técnica: o Oracle está em rede privada, então a VPS não alcança o banco direto. Daí este conector — a ponte entre o público e o privado.

Por que o payload vai cifrado ponta a ponta, mesmo já tendo TLS: o conteúdo é financeiro (CNPJ, notas, parcelas, vencimentos). Cifrando com a chave pública do conector, só ele abre — nem proxy no caminho, nem log de corpo de requisição, nem quem tiver acesso à VPS consegue ler. Detalhes em conector.md.

Por que id_processo viaja no payload: o Holmes reentrega webhook. Sem chave de deduplicação, cada reentrega vira linha duplicada no Oracle.

Estado atual

#	Fase	Estado
1	API na VPS — recebe do Holmes, trata, cifra	✅ no ar
2	Conector recebe — token, decifra, valida, loga	✅ feito
3	API envia — `POST` da VPS pro conector (`app/services/api_cliente.py` lá)	⬜ a fazer
4	Conector grava — pool Oracle + `MERGE` por `id_processo`	⬜ a fazer
5	CI/CD — Forgejo Actions + registry + auto-update	⬜ desenhado

Hoje o dado chega, é validado e descartado (persistido: false na resposta). Serve pra homologar o circuito; não persiste nada ainda.

Pontos em aberto

Onde o conector é publicado — precisa ser alcançável pela VPS. Porta liberada no firewall da Scardua? Domínio? IP fixo?
Política de retry do Holmes — quantas vezes reentrega e em quais status. A estratégia atual (erro sobe → Holmes reenvia) depende disso; sem retry dele, vai ser preciso persistência intermediária.
Usuário Oracle de privilégio mínimo — só INSERT/MERGE nas tabelas do fluxo, nada de SELECT geral nem DDL.

3.3 KiB Raw Blame History