Saúde e readiness
GET /health reporta liveness. GET /readyz executa a probe de cada dependência e reporta um status único.
GET /readyz/tenant/{id} reporta o mesmo detalhe para uma instituição. READYZ_PROBE_TIMEOUT_SEC limita cada probe a 5 segundos. READYZ_DEP_SLOW_THRESHOLD_MS marca uma dependência lenta em 500 milissegundos.
Um Reporter inacessível remove a instância de serviço. Comece o Reporter primeiro.
Configuração em tempo de execução
Um pequeno conjunto de parâmetros muda sem reinício. Defina
SYSTEMPLANE_ENABLED=true para montar o runtime plane.
Cada grupo é um namespace sob o prefixo de configuração deste serviço.
Leia um namespace com
GET /system/{namespace} e uma chave com GET /system/{namespace}/{key}. Grave uma chave com PUT /system/{namespace}/{key}. Apenas um administrador de plataforma pode chamar essas rotas.
Tudo o mais vem do ambiente e exige um reinício: strings de conexão, pools, material TLS, listeners e o gate de autenticação. Veja Systemplane para o contrato do runtime plane.
Credenciais e chaves
Defina
PLUGIN_AUTH_ENABLED=true e PLUGIN_AUTH_HOST para ativar o gate da API. O mesmo par conduz a autenticação de saída.
Cada upstream carrega sua própria credencial. O Lerian STA usa STA_CLIENT_ID e STA_CLIENT_SECRET. O Lerian Reporter usa REPORTER_CLIENT_ID e REPORTER_CLIENT_SECRET. Não há credencial compartilhada nem fallback.
Com o gate ativado, um par ausente interrompe o boot e nomeia a variável exata. O Lerian CCS emite cada token por meio de OAuth2 client credentials e o armazena em cache por M2M_CREDENTIAL_CACHE_TTL_SEC segundos, 300 por padrão. Deploys multi-instituição leem, em vez disso, credenciais por instituição a partir do AWS Secrets Manager.
CCS_CRYPTO_MASTER_KEY guarda a chave mestra AES-256-GCM para os dados criptografados em repouso. Ela recebe 64 caracteres hexadecimais. Um valor vazio interrompe o boot.
O Lerian CCS pode verificar uma assinatura em cada evento de entrada do Lerian STA. Defina STA_EVENT_HMAC_VERIFY_ENABLED=true, carregue o catálogo de chaves em STA_EVENT_HMAC_MASTER_KEYS, e nomeie a versão ativa em STA_EVENT_HMAC_MASTER_KEY_VERSION. Carregue o catálogo primeiro. STA_EVENT_HMAC_TOLERANCE_SECONDS limita o desvio de relógio a 300 segundos.
Armazenamento, outbox e retenção
Dois buckets de armazenamento de objetos guardam o XML regulatório:
OBJECT_STORAGE_STA_BUCKET de entrada e OBJECT_STORAGE_CCS_BUCKET de saída. Apenas referências de arquivo trafegam pela rede.
O trabalho de saída sai por meio de uma tabela de outbox transacional. O dispatcher a lê a cada OUTBOX_DISPATCH_INTERVAL_SEC segundos, 2 por padrão, em lotes de OUTBOX_BATCH_SIZE, 50 por padrão, e desiste de um evento após OUTBOX_MAX_DISPATCH_ATTEMPTS tentativas, 10 por padrão. Defina CCS_OUTBOX_OVERRIDES_ENABLED=true para mover o dispatcher, em vez disso, para o intervalo, tamanho de lote e orçamento de tentativas de CCS_OUTBOX_*. Uma mensagem que esgota seu orçamento de tentativas move para a dead-letter queue sob CCS_OUTBOX_DLQ_ROUTING_KEY, e essa chave se aplica em ambos os casos.
CCS_OUTBOUND_RETENTION_DAYS e CCS_ACCS009_RETENTION_DAYS usam 30 dias como padrão. Um monitor verifica se há uma remessa ausente a cada CCS_NON_SUBMISSION_SCAN_INTERVAL_SEC segundos, 3600 por padrão.
O serviço nunca aplica seu próprio schema de banco de dados. Um job de migração separado o aplica antes da inicialização.
Respostas estacionadas do STA
Um arquivo de entrada que o Lerian CCS não pode aplicar fica estacionado em uma dead-letter queue, com seu payload intacto. Um estacionamento mantém uma pendência em aberto. O arquivo estacionado costuma ser a única cópia de um fato do BACEN, então precisa de um alerta e de uma decisão humana.
POST /v1/batches/{id}/drain-parked-response aplica um ACCS003 atrasado a um lote que já alcançou um estado terminal. Quem chama fornece apenas identificadores. O Lerian CCS busca o arquivo novamente, deriva novamente os veredictos, e recusa quando o lote nomeado não corresponde. Ele grava uma entrada de auditoria na mesma transação.
Não drene quando dois lotes corresponderem a um arquivo, ou quando a correlação se contradiz. Estabeleça primeiro qual lote produziu o arquivo. Trate a divergência como o achado.
Métricas e tracing
GET /metrics serve as métricas de readiness no formato de texto Prometheus. Defina ENABLE_TELEMETRY=true para exportar traces e métricas via OTLP para OTEL_EXPORTER_OTLP_ENDPOINT. Veja Observabilidade para a visão de plataforma.
Postura de deploy
DEPLOYMENT_MODE aceita local, byoc, saas ou onprem. Em saas, o serviço impõe TLS em cada dependência. CCS_RUN_MODE aceita manager, worker ou all, e seleciona quais subsistemas rodam.
A produção adiciona estes requisitos.
PLUGIN_AUTH_ENABLED=truecomPLUGIN_AUTH_HOST.LICENSE_KEYeORGANIZATION_IDS.CIRCUIT_BREAKER_ENABLED=true, que a integração com o Reporter exige.REPORTER_URLeCCS_CRYPTO_MASTER_KEY, sempre obrigatórios.