Reestrutura para API multi-cliente com payload cifrado

A API deixa de ser especifica da Scardua e passa a atender varios
clientes pela rota /v1/holmes/{cliente}/...

Camada de clientes:
- app/clientes/base.py: ClienteBase (comportamento) + ClienteConfig (dado),
  separados de proposito — config sai do configs.json hoje e pode sair do
  banco amanha sem o resto mudar
- app/clientes/registry.py: resolve o {cliente} da rota pra instancia
- cada cliente traz a propria conta do Holmes; o cache de token virou um
  arquivo por cliente (antes era constante de modulo e dois clientes
  sobrescreveriam o token um do outro)

Holmes:
- funcoes de modulo viraram a classe HolmesAPI, amarrada a uma conta
- exposta pronta em cliente.holmes (cached_property)
- as funcoes de parsing puro (extrair_*) ficaram fora da classe

Config:
- app/schemas.py: modulo folha, so pydantic. Config e services usam os
  mesmos modelos sem um importar o outro
- app/config.py: so o carregamento do configs.json
- configs.json passa a ter "clientes": {"<nome>": {...}}

Compras:
- schemas aceitam o payload real do Holmes (PEDIDO_LINX vem como numero,
  NUMERO NF ENTRADA so existe depois da fase da nota)
- parcelas viram dict[int, Parcela], pareando parcelaN com o vencimento
  correspondente e pulando os slots vazios
- payload de saida carrega id_processo como chave de deduplicacao: o
  Holmes reentrega webhook e sem isso duplica linha no destino

Criptografia:
- app/services/cripto.py: envelope AES-256-GCM + RSA-OAEP-SHA256. RSA
  sozinho nao serve (cifra ~190 bytes; o payload passa disso)
- ciframos com a publica do conector e nao conseguimos desfazer

Deploy:
- Dockerfile e .dockerignore vieram da VPS pro repo
- docs/deploy.md: runbook, incluindo que --format docker e obrigatorio
  (em OCI o podman ignora o HEALTHCHECK silenciosamente)

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

app/clientes/base.py

@@ -1,55 +1,31 @@
 import os
 import tempfile
-from abc import ABC, abstractmethod
-from typing import Any
+from abc import ABC
+from functools import cached_property
 
-from fastapi import HTTPException
+from app.schemas import HolmesCliente
+from app.services.holmes import HolmesAPI
 from pydantic import BaseModel
 
 
-class HolmesCliente(BaseModel):
-    """Credenciais do Holmes. Cada cliente tem a propria conta de integracao."""
-
-    token_api: str
-    usuario: str
-    senha: str
-
-
 class ClienteConfig(BaseModel):
-    """
-    Os DADOS do cliente.
-
-    Fica separado da classe de proposito: dado da pra carregar do banco,
-    classe nao. No dia que cliente novo deixar de exigir deploy, e daqui
-    que a config vai sair — o resto do codigo nao muda.
-    """
-
     nome: str
     razao_social: str
     cnpj: str
     holmes: HolmesCliente
+    # Chave publica (PEM) da API do cliente. Ciframos com ela; so a privada,
+    # que fica com eles, abre.
+    chave_publica: str
 
 
 class ClienteBase(ABC):
-    """
-    Base de todo cliente atendido pela API.
+    # A subclasse atribui direto: config = ClienteConfig(...)
+    config: ClienteConfig
 
-    Regra de ouro: aqui so entra o que muda de COMPORTAMENTO entre clientes.
-    Valor (CNPJ, token, id de fluxo) vai em `config`, nao em atributo de classe
-    solto — senao a heranca vira dicionario com passos extras.
-
-    A subclasse satisfaz `config` e `modulos` como atributo de classe mesmo,
-    nao precisa escrever @property.
-    """
-
-    @property
-    @abstractmethod
-    def config(self) -> ClienteConfig: ...
-
-    @property
-    @abstractmethod
-    def modulos(self) -> dict[str, Any]:
-        """Processos habilitados: {"compras": ScarduaCompras(), ...}"""
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        if not hasattr(cls, "config"):
+            raise TypeError(f"{cls.__name__} precisa definir `config`")
 
     # --- comum a todos: ninguem sobrescreve ---
 
@@ -57,13 +33,18 @@ class ClienteBase(ABC):
     def nome(self) -> str:
         return self.config.nome
 
-    def modulo(self, nome: str) -> Any:
-        """Pega um processo habilitado do cliente, ou 404 se ele nao tem."""
-        if modulo := self.modulos.get(nome):
-            return modulo
-        raise HTTPException(
-            status_code=404,
-            detail=f"modulo '{nome}' nao habilitado para {self.nome}",
+    @cached_property
+    def holmes(self) -> HolmesAPI:
+        """
+        API do Holmes ja amarrada nas credenciais deste cliente.
+
+        cached_property e nao property: uma instancia por cliente, criada no
+        primeiro uso. Com @property comum sairia uma HolmesAPI nova a cada
+        acesso, e qualquer estado em memoria (token) se perderia.
+        """
+        return HolmesAPI(
+            credenciais=self.config.holmes,
+            cache_token=self.cache_token_holmes,
         )
 
     @property
@@ -71,8 +52,8 @@ class ClienteBase(ABC):
         """
         Arquivo de cache do token do Holmes, um por cliente.
 
-        Sem isso dois clientes com contas diferentes sobrescrevem o token
-        um do outro (ver _TOKEN_FILE em app/services/holmes.py).
+        Sem isso dois clientes com contas diferentes sobrescreveriam o token
+        um do outro — era o caso quando isso era uma constante de modulo.
         """
         return os.path.join(
             tempfile.gettempdir(), f"holmes_token_{self.nome}.json"

app/config.py

@@ -1,45 +1,6 @@
 from pathlib import Path
 
-from pydantic import BaseModel
-
-
-class BancoConfig(BaseModel):
-    user: str
-    password: str
-    dns: str
-    instant_client: str
-
-
-class HolmesConfig(BaseModel):
-    token_api: str
-    usuario: str
-    senha: str
-
-
-class ApolloConfig(BaseModel):
-    subscription_key: str
-    ambiente: str
-
-
-class ApiConfig(BaseModel):
-    port: int
-    ambiente: str
-    workers: int
-
-
-class DocsConfig(BaseModel):
-    user: str
-    password: str
-
-
-class Settings(BaseModel):
-    banco: BancoConfig
-    holmes: HolmesConfig
-    api: ApiConfig
-    apollo: ApolloConfig
-    docs: DocsConfig
-    log_level: str = "INFO"
-
+from app.schemas import Settings
 
 _PATH = Path(__file__).resolve().parent.parent / "configs.json"
 settings = Settings.model_validate_json(_PATH.read_text(encoding="utf-8"))

app/schemas.py

@@ -0,0 +1,32 @@
+from pydantic import BaseModel
+
+
+class HolmesCliente(BaseModel):
+    """Credenciais do Holmes. Cada cliente tem a propria conta de integracao."""
+
+    token_api: str
+    usuario: str
+    senha: str
+
+
+class ApiConfig(BaseModel):
+    port: int
+    ambiente: str
+    workers: int
+
+
+class DocsConfig(BaseModel):
+    user: str
+    password: str
+
+
+class ClienteSettings(BaseModel):
+    holmes: HolmesCliente
+    chave_publica: str
+
+
+class Settings(BaseModel):
+    api: ApiConfig
+    clientes: dict[str, ClienteSettings]
+    docs: DocsConfig
+    log_level: str = "INFO"

app/services/cripto.py

@@ -0,0 +1,99 @@
+"""
+Criptografia do payload enviado pra API do cliente.
+
+Envelope (hibrida): AES-256-GCM nos dados, RSA-OAEP na chave AES.
+
+Por que nao RSA puro: RSA-2048 com OAEP-SHA256 cifra no maximo 190 bytes.
+Um payload de compras passa disso facil. O padrao — mesmo do TLS, PGP e JWE —
+e sortear uma chave simetrica por mensagem, cifrar os dados com ela e mandar
+essa chave cifrada com a publica do destinatario.
+
+So o dono da chave privada abre. Nos ciframos e nao conseguimos desfazer,
+que era o objetivo.
+"""
+
+import base64
+import json
+import os
+
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import padding, rsa
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+ALGORITMO = "RSA-OAEP-256+A256GCM"
+
+_OAEP = padding.OAEP(
+    mgf=padding.MGF1(algorithm=hashes.SHA256()),
+    algorithm=hashes.SHA256(),
+    label=None,
+)
+
+
+def carregar_chave_publica(pem: str):
+    """Le a chave publica do cliente (formato PEM, vinda do configs.json)."""
+    return serialization.load_pem_public_key(pem.encode())
+
+
+def carregar_chave_privada(pem: str, senha: bytes | None = None):
+    """So usada em teste. Em producao a privada fica com o cliente."""
+    return serialization.load_pem_private_key(pem.encode(), password=senha)
+
+
+def criptografar(dados: dict, chave_publica) -> dict:
+    """
+    Cifra o dict e devolve o envelope pronto pra mandar no corpo do POST.
+
+    Sai assim:
+        {
+          "alg":   "RSA-OAEP-256+A256GCM",
+          "chave": "<chave AES cifrada com a publica, base64>",
+          "nonce": "<nonce do GCM, base64>",
+          "dados": "<json cifrado + tag de autenticacao, base64>"
+        }
+    """
+    chave_aes = AESGCM.generate_key(bit_length=256)
+    nonce = os.urandom(12)
+    corpo = json.dumps(dados, ensure_ascii=False, separators=(",", ":")).encode()
+
+    cifrado = AESGCM(chave_aes).encrypt(nonce, corpo, None)
+    chave_cifrada = chave_publica.encrypt(chave_aes, _OAEP)
+
+    return {
+        "alg": ALGORITMO,
+        "chave": base64.b64encode(chave_cifrada).decode(),
+        "nonce": base64.b64encode(nonce).decode(),
+        "dados": base64.b64encode(cifrado).decode(),
+    }
+
+
+def descriptografar(envelope: dict, chave_privada) -> dict:
+    """
+    O lado do cliente. Fica aqui pra testar o round-trip e pra servir de
+    referencia de implementacao pra quem for escrever a API que recebe.
+    """
+    chave_aes = chave_privada.decrypt(base64.b64decode(envelope["chave"]), _OAEP)
+    corpo = AESGCM(chave_aes).decrypt(
+        base64.b64decode(envelope["nonce"]),
+        base64.b64decode(envelope["dados"]),
+        None,
+    )
+    return json.loads(corpo)
+
+
+def gerar_par_de_chaves() -> tuple[str, str]:
+    """Gera um par RSA-2048 em PEM. Util pra homologacao: (privada, publica)."""
+    chave = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+    privada = chave.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    ).decode()
+    publica = (
+        chave.public_key()
+        .public_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PublicFormat.SubjectPublicKeyInfo,
+        )
+        .decode()
+    )
+    return privada, publica

app/v1/api.py

@@ -1,9 +1,12 @@
-from app.v1.holmes.holmes import holmes_router
+import app.v1.scardua.cliente  # noqa: F401  (registra o Scardua no registry)
+from app.v1.scardua.scardua import holmes_router
 from fastapi import APIRouter
 
 api_router = APIRouter()
 
+# O {cliente} vira path param e cai no get_cliente por Depends.
+# Rota final: POST /v1/holmes/scardua/compras/dados
 api_router.include_router(
     holmes_router,
-    prefix='/holmes'
+    prefix="/holmes/{cliente}",
 )

app/v1/scardua/cliente.py

@@ -0,0 +1,16 @@
+from app.clientes.base import ClienteBase, ClienteConfig
+from app.clientes.registry import registrar
+from app.config import settings
+
+
+class Scardua(ClienteBase):
+    config = ClienteConfig(
+        nome="scardua",
+        razao_social="Comercial Scardua",
+        cnpj="",
+        holmes=settings.clientes["scardua"].holmes,
+        chave_publica=settings.clientes["scardua"].chave_publica,
+    )
+
+
+registrar(Scardua())

app/v1/scardua/modules/compras/router.py

@@ -1,4 +1,6 @@
-from fastapi import APIRouter
+from app.clientes.base import ClienteBase
+from app.clientes.registry import get_cliente
+from fastapi import APIRouter, Depends
 
 from .schemas import DadosCompras
 from .service import processar_compras
@@ -6,5 +8,8 @@ from .service import processar_compras
 router = APIRouter(prefix="/compras", tags=["compras"])
 
 @router.post("/dados")
-async def dados_compras(dados: DadosCompras):
-    return await processar_compras(dados)
+async def dados_compras(
+    dados: DadosCompras,
+    cli: ClienteBase = Depends(get_cliente),
+):
+    return await processar_compras(dados, cli)

app/v1/scardua/modules/compras/schemas.py

@@ -1,6 +1,6 @@
 from datetime import datetime
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, ConfigDict, Field
 
 
 class Parcela(BaseModel):
@@ -8,13 +8,24 @@ class Parcela(BaseModel):
     vencimento: datetime | None = None
 
 
+class Autor(BaseModel):
+    id: str
+    name: str
+    email: str
+
+
 class ComprasProperties(BaseModel):
+    # O Holmes manda PEDIDO_LINX como numero (345, sem aspas). O Pydantic v2
+    # nao converte numero pra string sozinho, entao precisa habilitar.
+    model_config = ConfigDict(coerce_numbers_to_str=True)
+
     protocolo: str
     pedido_linx: str = Field(alias="PEDIDO_LINX")
     fornecedor: str = Field(alias="Fornecedores")
     tipo_compra: str = Field(alias="Tipo de Compra")
     cnpj: str = Field(alias="CNPJ")
-    nf_entrada: str = Field(alias="NUMERO NF ENTRADA")
+    # Chega vazio enquanto o processo nao passou pela fase da nota.
+    nf_entrada: str | None = Field(default=None, alias="NUMERO NF ENTRADA")
 
     num_parcelas: int | None = Field(default=None, alias="num. parcelas")
 
@@ -64,14 +75,21 @@ class ComprasProperties(BaseModel):
 
 class DadosCompras(BaseModel):
     id: str
+    author: Autor
     properties: ComprasProperties
 
+
 class PayloadCompras(BaseModel):
+    # Chave de deduplicacao: o id do processo no Holmes. Como ele reentrega
+    # webhook, sem isso todo reenvio vira linha duplicada no banco do cliente.
+    id_processo: str
+
+    protocolo: str
     cnpj: str
     pedido_linx: str
     fornecedor: str
     tipo: str
-    nf_entrada: str
+    nf_entrada: str | None
     aprovador: str
     valor_total: float
     parcelas: dict[int, Parcela]

app/v1/scardua/modules/compras/service.py

@@ -1,26 +1,41 @@
+from app.clientes.base import ClienteBase
+from app.services import cripto
+
 from .schemas import DadosCompras, PayloadCompras
-from .service import processar_compras
-from app.services.api_cliente import 
-from app.services.holmes import 
 
 
-async def processar_compras(
-    dados: DadosCompras
-) -> dict:
-    payload = montar_payload(dados)
-
-    ok, retorno = await apollo.enviar_compra(payload.model_dump(mode="json"), conn)
-    if not ok:
-        raise HTTPException(502, f"Falha ao enviar para a API externa: {retorno}")
-    return {"status": "enviado", "id_processo": dados.id, "retorno": retorno}
-
 def montar_payload(dados: DadosCompras) -> PayloadCompras:
+    """
+    Traduz o formato do Holmes pro formato que a API do cliente espera.
+
+    Funcao pura, sem I/O: da pra testar jogando o JSON do Holmes e conferindo
+    a saida, sem rede nem mock.
+    """
     p = dados.properties
     return PayloadCompras(
+        id_processo=dados.id,
+        protocolo=p.protocolo,
         cnpj=p.cnpj,
         pedido_linx=p.pedido_linx,
         fornecedor=p.fornecedor,
         tipo=p.tipo_compra,
+        nf_entrada=p.nf_entrada,
+        aprovador=dados.author.name,
         valor_total=p.total_parcelas,
         parcelas=p.parcelas,
     )
+
+
+def montar_envelope(dados: DadosCompras, cli: ClienteBase) -> dict:
+    """Monta o payload e cifra com a chave publica do cliente."""
+    payload = montar_payload(dados)
+    chave = cripto.carregar_chave_publica(cli.config.chave_publica)
+    return cripto.criptografar(payload.model_dump(mode="json"), chave)
+
+
+async def processar_compras(dados: DadosCompras, cli: ClienteBase) -> dict:
+    envelope = montar_envelope(dados, cli)
+
+    # TODO: POST do envelope pra API do cliente. Erro tem que subir (nao
+    # engolir), pra o Holmes reentregar — ele e a nossa fila.
+    return {"status": "pendente_envio", "id_processo": dados.id, "envelope": envelope}