# 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.