Ricardo f902ccbecb 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>

2026-08-18 06:05:03 -03:00

2.3 KiB

Raw Blame History

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.

⚠️ 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.

2.3 KiB Raw Blame History