f902ccbecb
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>
52 lines
2.3 KiB
Markdown
52 lines
2.3 KiB
Markdown
# 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)**.
|