15c89c9038
- 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>
64 lines
3 KiB
Markdown
64 lines
3 KiB
Markdown
# 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]
|
|
```
|
|
|
|
1. O Holmes envia os dados pra nossa API (URL pública, TLS).
|
|
2. A API recebe e **trata** os dados.
|
|
3. 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:
|
|
|
|
1. **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.
|
|
2. **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](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.
|