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>

CLAUDE.md

@@ -0,0 +1,52 @@
+# Conector Scardua
+
+Serviço que roda **dentro da rede da Comercial Scardua**, recebe da API da FLS
+(na VPS) o payload tratado e cifrado, abre e — na fase 4 — grava no Oracle privado.
+
+Visão completa e o porquê das decisões: **[docs/arquitetura.md](docs/arquitetura.md)**.
+
+> ⚠️ Este repo **mudou de papel**: era a API que roda na VPS. Essa parte saiu
+> daqui. Se você achar código do Holmes (`app/services/holmes.py`, `app/v1/holmes/`),
+> é resíduo — o conector **não fala com o Holmes**.
+
+## Stack
+- Python ≥3.10 · FastAPI + Uvicorn (ASGI)
+- Pydantic v2 (validação e config)
+- **cryptography** — abre o envelope (RSA-OAEP-SHA256 + AES-256-GCM)
+- oracledb — driver Oracle em **thin mode** (fase 4)
+- `requirements.txt` = só runtime (usado no Dockerfile)
+
+## Estrutura
+- `main.py` — app FastAPI, middleware, rotas raiz (`/health`, `/docs` protegido), logging
+- `app/schemas.py` — **módulo folha** (só pydantic): config + contrato (`Envelope`, `PayloadCompras`)
+- `app/config.py` — carrega o `configs.json` **no import** (precisa existir ou a app não sobe)
+- `app/seguranca.py` — `X-Token` + allowlist de IP; dependência das rotas
+- `app/services/cripto.py` — abre o envelope; espelho do lado que cifra, na API
+- `app/v1/compras.py` — `POST /v1/compras/dados`
+- `app/middleware.py` — `block_scanners`: denylist + heurística (NÃO é allowlist estrita)
+
+## O contrato com a API
+`PayloadCompras` em `app/schemas.py` **espelha** o da API da VPS. Se um lado
+mudar e o outro não, o conector devolve **422** — de propósito, pra falhar
+explícito em vez de gravar dado torto.
+
+## Rodar local (Windows)
+Precisa do `configs.json` na raiz (NÃO versionado — ver `configs.example.json`).
+```
+uvicorn main:app --reload --port 8000
+```
+
+## Config e segredos
+- Tudo vem de `configs.json`, lido em `app/config.py`. Está no `.gitignore` e no
+  `.dockerignore` — **nunca commitar**.
+- Ele guarda a **chave privada** do conector. É o segredo mais sensível do projeto:
+  quem tem ela lê todo payload que a VPS manda.
+- Template versionável: `configs.example.json`.
+
+## Convenções
+- Código, nomes e comentários em **português**.
+- Lint/format: **ruff** (config no `pyproject.toml` — linha 120, aspas duplas).
+- Logging: use `logging.info/error`; o nível vem de `settings.log_level`.
+
+## Problemas conhecidos
+**[docs/known-issues.md](docs/known-issues.md)**.