# 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)**.