Ricardo Leite 15c89c9038 Deploy inicial: API FastAPI + infra Podman/Caddy + docs

- App FastAPI (main.py, app/): rotas /health e /dados_retorno, middleware anti-scanner, logging configurado
- Config via configs.json (Pydantic); segredos fora do codigo e do git (.gitignore)
- Dockerfile (oracledb thin, HEALTHCHECK) + requirements.txt + .dockerignore
- Deploy Podman/Quadlet + Caddy em deploy/
- Docs: CLAUDE.md + docs/ (arquitetura, deploy, known-issues)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-07-28 16:37:13 -03:00

3 KiB

Raw Permalink Blame History

Arquitetura e Visão — API-Scardua

Documento da ideia do projeto: o quê, o porquê e o roadmap. Salvo pra não reexplicar toda sessão. Atualizar quando a visão evoluir.

Em uma frase

Uma API que recebe dados do Holmes do cliente, trata, e envia de volta pro banco do cliente — hospedada na infra do dev (FLS), não na do cliente.

Os atores

FLS Tecnologia (dev / nós) — constrói e hospeda a API na própria VPS (api-scardua.flstecnologia.tech). A infra e o código são nossos.
Comercial Scardua (cliente) — tem a conta no Holmes e um banco Oracle (IP privado, 10.16.x — não acessível pela internet).
Holmes — SaaS externo de workflow de documentos; dispara os dados (webhook) pra nossa API.

O fluxo

Holmes  --webhook-->  [API na VPS da FLS]  --trata-->  [Conector no server do cliente]  -->  [Oracle do cliente]

O Holmes envia os dados pra nossa API (URL pública, TLS).
A API recebe e trata os dados.
A API fala com o banco do cliente através de um conector que roda no servidor do cliente (que tem acesso à rede privada do Oracle).

As decisões e o PORQUÊ (o mais importante)

A API fica na nossa VPS, e não no servidor do cliente, por 2 motivos:

Não depender de o cliente ter domínio / rota pública. O Holmes precisa de um endpoint público e estável pra mandar os webhooks — damos isso nós, com domínio + TLS próprios.
Não deixar nosso código Python no servidor do cliente. A lógica fica sob nosso controle, na nossa infra.

Consequência técnica: como o Oracle do cliente está numa rede privada (10.16.x), a VPS não alcança o banco direto. Por isso existe o conector no server do cliente — ele é a ponte entre a API (pública) e o Oracle (privado).

Roadmap

#	Fase	Estado
1	Receber dados — esqueleto da API, rota de teste, deploy na VPS	✅ feito
2	Lógica do Holmes — ligar os endpoints `/v1/holmes/...` ao serviço `app/services/holmes.py` (hoje `obter_dados_compras` é stub)	⏳ em andamento (dev)
3	Conector no cliente — a ponte API (VPS) ↔ Oracle do cliente (rede privada)	⬜ a fazer
4	CI/CD — Forgejo Actions (valida no PR/main) + registry + auto-update pull-based (ver deploy.md)	⬜ desenhado

Pontos em aberto

Como o conector no cliente vai funcionar — duas abordagens possíveis:
- Túnel/VPN reverso: o server do cliente abre um túnel e a VPS passa a alcançar o 10.16.x → a API conecta no Oracle direto (é o que o código de hoje assume: oracledb com o DSN privado em configs.json).
- Agente HTTP no cliente: um serviço no server do cliente que a API chama; ele consulta o Oracle localmente e devolve o resultado (aí a API nunca toca no Oracle direto).
Essa escolha decide o destino do app/infra/database.py (hoje faltando): conexão direta via túnel, ou um cliente HTTP pro agente.

3 KiB Raw Permalink Blame History