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/known-issues.md

@@ -0,0 +1,55 @@
+# Problemas conhecidos / TODO — Conector Scardua
+
+## Bloqueadores da fase 4 (gravar no Oracle)
+
+- **Não existe camada de conexão.** `app/infra/database.py` é referenciado por
+  `app/security.py` mas **nunca existiu**. Nada abre pool no caminho que roda.
+- **O conector não persiste nada.** Hoje ele recebe, decifra, valida e **descarta**
+  (responde `persistido: false`). O circuito está homologado; o `INSERT` não.
+- Quando o `INSERT` entrar, **tem que ser `MERGE` por `id_processo`** — o Holmes
+  reentrega webhook e sem isso cada reentrega duplica linha.
+
+## Resíduo do papel antigo
+
+Este repo era a API que roda na VPS. Sobrou código que o conector **não usa**:
+
+- `app/services/holmes.py` — o conector não fala com o Holmes
+- `app/v1/holmes/` — **pasta vazia**; os `.py` já foram apagados, o git ainda
+  registra as remoções como pendentes
+- `app/services/controle_api.py` — telemetria no Oracle; só volta a fazer sentido
+  na fase 4
+- `app/security.py` — JWT + auth via Oracle. **Não é usado**; a autenticação do
+  conector é o `app/seguranca.py` (token + IP). Continua com os defeitos antigos:
+  importa `db_instance` (inexistente) e usa `settings.api.jwt_secret` (que não
+  existe no `Settings` novo).
+
+Nada disso é importado no boot, então não quebra — mas é peso morto a limpar.
+
+## Segurança
+
+- **`ips_permitidos` está vazio** no `configs.json` atual (desligado, pra teste
+  local). **Preencher com `179.197.230.154` antes de produção.**
+- **O par de chaves é de homologação.** Gerar um definitivo e trocar nos dois
+  lados juntos.
+- **Sem TLS ainda** — depende de como o conector for publicado. A VPS manda CNPJ,
+  notas e vencimentos; o envelope protege o conteúdo, mas o token viaja no header.
+- **Sem rate limiting.**
+- `/docs`, `/redoc` e `/openapi.json` ficam expostos quando `ambiente != prod`
+  (atrás de basic auth). Fechar com `ambiente = prod` se não precisar.
+- Se entrar proxy na frente, o IP de origem vira o do proxy — a allowlist para de
+  funcionar. Aí o uvicorn precisa de `--proxy-headers` e o `app/seguranca.py`
+  passa a ler `X-Forwarded-For`.
+
+## Middleware
+
+- `block_scanners` é **denylist + heurística**, não allowlist estrita: qualquer
+  path fora da blocklist com User-Agent normal **passa** e vira 404 na app.
+  Não vaza nada, mas é mais permissivo do que parece.
+
+## Empacotamento
+
+- `pyproject.toml` aponta `readme = "README.md"` — o arquivo existe, mas confira
+  se `pip install .` funciona; o Docker usa `requirements.txt` justamente pra
+  não depender disso.
+- `PyJWT` está nas dependências mas só era usado pelo `app/security.py`, que
+  saiu de circulação.