f902ccbecb
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>
81 lines
3.3 KiB
Markdown
81 lines
3.3 KiB
Markdown
# 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:**
|
|
|
|
1. **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.
|
|
2. **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](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.
|