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>

docs/deploy.md

@@ -0,0 +1,91 @@
+# Deploy — Conector Scardua
+
+> ⚠️ O runbook da **VPS da FLS** (Podman/Quadlet/Caddy, `api-scardua.flstecnologia.tech`)
+> **saiu daqui** — ele pertence ao repositório da API. Este doc é do conector,
+> que roda no **servidor da Scardua**.
+
+## Onde ele roda
+
+No servidor do cliente, com acesso à rede privada `10.16.x` onde está o Oracle.
+Precisa ser **alcançável pela VPS** (`179.197.230.154`) — é a VPS que faz o `POST`.
+
+## Pré-requisitos
+
+| Item | Detalhe |
+|---|---|
+| Python | ≥3.10, ou Podman/Docker se for containerizado |
+| Rede | porta de entrada liberada **só** pro IP da VPS |
+| TLS | proxy na frente (Caddy/nginx) — a VPS manda payload financeiro |
+| Oracle | usuário de **privilégio mínimo**: só `INSERT`/`MERGE` nas tabelas do fluxo |
+
+## configs.json
+
+Nunca versionado. Ver `configs.example.json`. Os campos críticos:
+
+```json
+"vps": {
+    "chave_privada": "-----BEGIN PRIVATE KEY-----\n...",
+    "token": "<segredo compartilhado com a VPS>",
+    "ips_permitidos": ["179.197.230.154"]
+}
+```
+
+- **`chave_privada`** — o segredo mais sensível do projeto. Quem tem ela lê todo
+  payload. Permissão `600`, nunca em repo, nunca em imagem.
+- **`token`** — tem que ser **o mesmo** configurado na VPS (header `X-Token`).
+- **`ips_permitidos`** — deixar vazio só em teste local. **Em produção, preencher.**
+
+## As chaves
+
+Par RSA-2048. A **privada** fica aqui; a **pública** vai no `configs.json` da VPS.
+Para gerar um par novo:
+
+```bash
+openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out privada.pem
+openssl rsa -in privada.pem -pubout -out publica.pem
+```
+
+O par em uso hoje é de **homologação** — trocar antes de produção, e trocar os
+dois lados juntos (senão a VPS cifra com uma pública que este conector não abre).
+
+## Subir
+
+```bash
+uvicorn main:app --host 0.0.0.0 --port 8000 --workers 2
+```
+
+Se for container, o `Dockerfile` da raiz serve — mas o `configs.json` tem que ser
+montado por **volume**, nunca copiado pra imagem (o `.dockerignore` já barra).
+
+```bash
+podman build --format docker -t conector-scardua:latest .
+```
+
+> ⚠️ **`--format docker` é obrigatório**: no formato OCI (padrão do Podman) o
+> `HEALTHCHECK` do Dockerfile é **silenciosamente ignorado**.
+
+## Verificar que está de pé
+
+```bash
+curl -s http://localhost:8000/health           # -> {"status":"ok"}
+```
+
+E o caminho real, com o token:
+
+```bash
+curl -X POST http://localhost:8000/v1/compras/dados \
+  -H "X-Token: <o token do configs.json>" \
+  -H "Content-Type: application/json" \
+  -d '<envelope gerado pela API da VPS>'
+```
+
+Respostas esperadas: **200** recebido · **401** token errado · **403** IP fora da
+allowlist · **400** envelope não abriu (chave errada ou adulterado) · **422**
+payload fora do contrato.
+
+## Comandos úteis
+
+```bash
+journalctl -u conector-scardua -f       # se rodar via systemd
+podman logs -f conector-scardua         # se rodar em container
+```