# API-Scardua

API FastAPI de integração da Scardua com serviços externos (Holmes, Apollo) e banco Oracle.
No ar: **https://api-scardua.flstecnologia.tech**

## Visão e roadmap
Ideia, arquitetura e roadmap completos: **[docs/arquitetura.md](docs/arquitetura.md)**.
Resumo: a API roda na **nossa VPS (FLS)**, não na do cliente — recebe dados do Holmes do cliente (Scardua), trata, e devolve pro Oracle dele via um **conector no server do cliente** (o Oracle está em rede privada `10.16.x`, inalcançável direto da VPS).

## Stack
- Python ≥3.10 · FastAPI + Uvicorn (ASGI)
- Pydantic v2 (validação e config)
- httpx (chamadas às APIs externas)
- oracledb — driver Oracle em **thin mode** (sem Instant Client)
- Deps em `pyproject.toml` (extra `dev`: pytest, ruff). `requirements.txt` = só runtime (usado no Dockerfile).

## Estrutura
- `main.py` — app FastAPI, middleware, rotas raiz (`/health`, `/dados_retorno`, `/docs` protegido), config de logging
- `app/config.py` — carrega `configs.json` (Pydantic) **no import** (precisa existir ou a app não sobe)
- `app/middleware.py` — `block_scanners`: denylist + heurística anti-scanner (NÃO é allowlist estrita)
- `app/security.py` — JWT + auth via Oracle (⚠️ incompleto — ver docs/known-issues.md)
- `app/services/holmes.py` — integração com a API do Holmes
- `app/services/controle_api.py` — grava telemetria/contadores no Oracle
- `app/v1/` — router versionado (`/v1/...`)

## 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 `.dockerignore` — **nunca commitar**.
- Template seguro e versionável: `configs.example.json`.

## Deploy
Container Podman na VPS (Debian 13, rootless + Quadlet + Caddy). Runbook: **[docs/deploy.md](docs/deploy.md)**.

## 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 é configurado em `main.py` via `settings.log_level`.

## Problemas conhecidos
Lista completa em **[docs/known-issues.md](docs/known-issues.md)**. (A senha do Holmes já saiu do código pro `configs.json` — feito em 2026-07-23.)