Comercial-Scardua/conector-scardua
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
conector-scardua/docs/known-issues.md
Ricardo f902ccbecb Conector Scardua — recebe da API da FLS e entrega no Oracle do cliente 
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>
2026-08-18 06:05:03 -03:00

2.6 KiB
Raw Blame History

Problemas conhecidos / TODO — Conector Scardua

Bloqueadores da fase 4 (gravar no Oracle)

  • Não existe camada de conexão. app/infra/database.py é referenciado por app/security.py mas nunca existiu. Nada abre pool no caminho que roda.
  • O conector não persiste nada. Hoje ele recebe, decifra, valida e descarta (responde persistido: false). O circuito está homologado; o INSERT não.
  • Quando o INSERT entrar, tem que ser MERGE por id_processo — o Holmes reentrega webhook e sem isso cada reentrega duplica linha.

Resíduo do papel antigo

Este repo era a API que roda na VPS. Sobrou código que o conector não usa:

  • app/services/holmes.py — o conector não fala com o Holmes
  • app/v1/holmes/ — pasta vazia; os .py já foram apagados, o git ainda registra as remoções como pendentes
  • app/services/controle_api.py — telemetria no Oracle; só volta a fazer sentido na fase 4
  • app/security.py — JWT + auth via Oracle. Não é usado; a autenticação do conector é o app/seguranca.py (token + IP). Continua com os defeitos antigos: importa db_instance (inexistente) e usa settings.api.jwt_secret (que não existe no Settings novo).

Nada disso é importado no boot, então não quebra — mas é peso morto a limpar.

Segurança

  • ips_permitidos está vazio no configs.json atual (desligado, pra teste local). Preencher com 179.197.230.154 antes de produção.
  • O par de chaves é de homologação. Gerar um definitivo e trocar nos dois lados juntos.
  • Sem TLS ainda — depende de como o conector for publicado. A VPS manda CNPJ, notas e vencimentos; o envelope protege o conteúdo, mas o token viaja no header.
  • Sem rate limiting.
  • /docs, /redoc e /openapi.json ficam expostos quando ambiente != prod (atrás de basic auth). Fechar com ambiente = prod se não precisar.
  • Se entrar proxy na frente, o IP de origem vira o do proxy — a allowlist para de funcionar. Aí o uvicorn precisa de --proxy-headers e o app/seguranca.py passa a ler X-Forwarded-For.

Middleware

  • block_scanners é denylist + heurística, não allowlist estrita: qualquer path fora da blocklist com User-Agent normal passa e vira 404 na app. Não vaza nada, mas é mais permissivo do que parece.

Empacotamento

  • pyproject.toml aponta readme = "README.md" — o arquivo existe, mas confira se pip install . funciona; o Docker usa requirements.txt justamente pra não depender disso.
  • PyJWT está nas dependências mas só era usado pelo app/security.py, que saiu de circulação.