LBCA — ambientes¶

A plataforma de cobrança LBCA é o sistema de recuperação de crédito para instituições de ensino: importa a carteira de inadimplentes, separa o que vale cobrar do que provavelmente prescreveu, negocia com desconto parametrizado por instituição, coleta a assinatura do acordo e concilia o pagamento dando baixa nos títulos. É produto da LBCA, construído pela Bravonix.

Desde agosto de 2026 ele tem três ambientes padronizados — dev, homolog e prod —, gerenciados por uma instalação própria do Coolify, em br-sao (São Paulo).

Esta página descreve esses ambientes: o que cada um serve, como o código chega neles e o que muda de um para o outro.

Multi-instituição — a ideia que organiza tudo¶

A plataforma atende várias instituições na mesma aplicação, e cada uma tem a própria gaveta no banco: tabelas separadas, cadastros de usuário separados. A instituição é resolvida pelo endereço — quem entra por fmu.… está na FMU, e não existe consulta que traga dado de outra instituição, porque ele não está lá.

Isso não é capricho de arquitetura: cada instituição é controladora distinta sob a LGPD, e a Bravonix é operadora. Com uma tabela só, o isolamento dependeria de todo filtro do sistema estar certo para sempre; com gavetas separadas, ele vira ausência de dado.

Endereço não cadastrado devolve 404 em tudo

A instituição sai do hostname. Um endereço que não esteja na tabela de domínios da aplicação recebe "não encontrado" em toda requisição — inclusive nos webhooks de provedores externos, que veriam um 404 onde esperavam um 200. Quando um ambiente ganha endereço novo, ele precisa ser cadastrado na aplicação, não só no DNS.

Os três ambientes¶

A FMU é a primeira instituição atendida, e por isso é ela que aparece nos endereços:

Ambiente	Endereço da FMU	Serve para
Dev	fmu.dev.bravonix.ia.br	Integração contínua do time; base vazia
Homologação	fmu.homolog.bravonix.ia.br	Validação antes de produção; base vazia ou com amostra anonimizada
Produção	fmu.bravonix.ia.br	Ambiente-alvo, no ar e ainda sem dados

Produção está no ar, mas ainda não recebeu a carteira

O ambiente responde normalmente e a base está vazia. A carga da carteira é um passo à parte, feito pela equipe responsável.

Por que os internos usam bravonix.ia.br

Ambientes internos ficam todos na zona bravonix.ia.br, no mesmo padrão dos demais serviços. O endereço comercial que a instituição vai usar é decisão separada.

O que compõe um ambiente¶

Os três têm o mesmo desenho: duas aplicações (build por Dockerfile) e um banco (recurso do Coolify, sem porta publicada na internet).

flowchart TB
    U["Usuário"]

    subgraph AMB["Um ambiente (dev / homolog / prod)"]
        FE["Frontend<br>nginx — serve as telas e encaminha"]
        API["API<br>Django + gunicorn"]
        DB[("PostgreSQL<br>uma gaveta por instituição")]
    end

    EXT["Serviços externos<br>assinatura eletrônica · modelo de linguagem"]

    U --> FE
    FE --> API
    API --> DB
    API --> EXT

Peça	Papel
Frontend (nginx)	Serve as telas e encaminha `/api/`, `/admin/` e `/static/` para a API — o navegador fala só com ele
API (Django + gunicorn)	Regras do produto, autenticação, importação da carteira, política de desconto e conciliação
PostgreSQL	Dados da aplicação, com um schema por instituição

Só o frontend fica exposto na internet

A API não tem endereço público. Ela é alcançada apenas pelo frontend, por dentro da rede do ambiente. Quem precisa do admin do Django entra por /admin/ no mesmo endereço.

Os três ambientes dividem a mesma máquina

Como no SmartITBI, e diferente do Adapter, onde cada ambiente tem servidor próprio. A separação aqui é lógica: aplicações, bancos e endereços são independentes, mas o hardware é o mesmo — uma carga pesada em um ambiente pode ser sentida nos outros.

Branches — uma por ambiente¶

Branch	Ambiente
`dev`	Dev
`homolog`	Homologação
`main`	Produção

Um merge na branch dispara o deploy das duas aplicações daquele ambiente.

Como o código chega no ambiente¶

flowchart LR
    A["Merge na branch<br>do ambiente"] --> B["Webhook<br>para o Coolify"]
    B --> C["Build na máquina<br>dedicada de build"]
    C --> D["Imagem publicada<br>no registry privado"]
    D --> E["Servidor do ambiente<br>baixa e sobe o container"]

O build não roda no servidor do ambiente: existe uma máquina só para isso — a mesma que atende o Adapter e o SmartITBI — e a imagem pronta vai para o registry privado da Bravonix.
Nome da imagem: <aplicação>-<ambiente>, com a tag sendo o commit. Cada ambiente tem seu próprio repositório de imagem.
Deploy bem-sucedido troca o container, e a troca tem alguns segundos de 502. Deploy que falha não derruba nada: o container antigo só sai depois que o novo sobe.
O banco se resolve no boot: o passo de inicialização espera o banco responder, roda as migrations de todas as instituições e coleta os estáticos antes de a aplicação atender. Qualquer passo que falhe derruba o container — de propósito, para que ninguém fique atendendo com o banco pela metade.

As duas variáveis que decidem tudo¶

Cada ambiente diz duas coisas sobre si mesmo: em que máquina o processo está e qual configuração carregar. Elas têm que concordar, e o processo não sobe se discordarem.

A combinação que essa trava existe para impedir é "estou em produção" com a configuração de desenvolvimento: as outras quebram alguma coisa logo, essa funciona — e liga o modo de depuração, que mostra a configuração inteira, credencial de banco junto, para quem provocar um erro.

Dados — o que cada ambiente contém¶

Ambiente	Origem dos dados	Contém dado pessoal?
Dev	Nasceu vazio	Não
Homologação	Vazio; recebe amostra anonimizada quando precisar	Não
Produção	Vazio até a carga da carteira	Ainda não

A carteira tem dado pessoal de mais de cem mil pessoas

Nome, documento, telefone e endereço de devedores reais. Esse dado entra só em produção. Homologação e desenvolvimento trabalham com dado de teste ou amostra anonimizada — nunca com a base real.

A chave de cifra é diferente em cada ambiente, e isso é deliberado

Os dados pessoais são guardados cifrados, e cada ambiente tem a própria chave. Com chaves iguais, restaurar um backup de produção em homologação funcionaria — e a base real passaria a viver no ambiente onde mais gente tem acesso e ninguém audita. Com chaves diferentes, essa restauração falha imediatamente, com erro claro.

Consequência que vale saber antes de precisar: restaurar um backup exige a mesma chave que o cifrou. Ela não é trocada depois que existe dado, e é guardada separada do backup do banco.

Backup¶

O que é salvo	Frequência	Onde
O banco de cada ambiente	Diário, horários escalonados	Bucket de backup por ambiente
Configuração do Coolify (variáveis e acessos dos três)	Diário	Bucket próprio

Um bucket por ambiente, com credencial restrita a ele — backup de produção não é alcançável por credencial de dev.
Alerta por e-mail quando um backup falha, quando o arquivo não chega ao destino e também quando o backup deixa de rodar — a falha silenciosa é a que mais engana.
O backup existe desde o primeiro dia do ambiente, não depois da primeira carga.

O backup mais importante não é o dos ambientes

É o da configuração do Coolify: ele guarda as variáveis e os acessos dos três ambientes de uma vez. A cópia só é útil junto com a chave que decifra essas variáveis — por isso as duas viajam juntas.

Convenção de nomes¶

Servidores seguem lbca-<papel>-<YYMM>: o papel no meio (controle, ambientes) e a data de criação no fim — nessa ordem porque só assim a listagem alfabética fica em ordem cronológica. É a mesma regra do SmartITBI e do Adapter.

O nome do servidor não diz quem está servindo o endereço

Quem responde por um domínio é o DNS, não o nome da máquina.

Troubleshooting¶

Sintoma	Causa provável	O que fazer
O endereço devolve 404 em tudo, inclusive na verificação de saúde	Hostname não cadastrado na tabela de domínios da aplicação — a instituição sai do endereço	Cadastrar o endereço na instituição; sem isso nem o webhook de assinatura chega
A aplicação parece de pé, mas o painel a marca como não saudável	A verificação de saúde bate no endereço interno, que também precisa estar cadastrado	Cadastrar o endereço interno junto com os demais
As telas abrem e a API responde 404 num caminho	Caminho não encaminhado pelo frontend	Conferir a lista encaminhada (`/api/`, `/admin/`, `/static/`)
Um usuário criado não consegue entrar no admin da instituição	Usuário criado na gaveta errada — o comando padrão cria no cadastro da plataforma, não no da instituição	Recriar o usuário dentro da gaveta da instituição
Merge não dispara deploy nenhum	Branch sem ambiente correspondente	Usar `dev`, `homolog` ou `main`
Erro 502 por alguns segundos	Troca de container em deploy bem-sucedido	Comportamento esperado; escolher a janela de deploy
Uma variável mudou no painel e a tela continua igual	Variável de build fica congelada dentro do JavaScript — mudá-la no painel não faz efeito	Refazer o build; e nunca colocar segredo em variável de build, ela é baixada por qualquer visitante
O container não sobe e o log não diz nada útil	Segredo colado com espaço no fim: o painel não limpa o valor, e uma chave de cifra com um caractere a mais é recusada	Recolar o valor sem espaço

Onde estão as credenciais

Acessos ao painel, aos bancos e às contas de serviço ficam com a equipe de desenvolvimento — nunca nesta wiki. Solicite ao responsável pelo ambiente.