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/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}