Persistência de dados
Regra central
Todo acesso ao banco de dados passa pelo app backoffice.
Nenhum outro app do monorepo deve ter drizzle.config.ts, conexão direta com PostgreSQL ou migrations próprias. Dados são lidos e gravados exclusivamente via HTTP para os endpoints do backoffice.
Por que centralizar?
| Problema sem centralização | Solução com backoffice centralizado |
|---|---|
| Migrations desconexas entre apps | Um único histórico de migrations em ordem garantida |
| Schema duplicado / divergente | Um schema Drizzle canônico para toda a base |
Scripts setup:local múltiplos | Um único pnpm setup:local para toda a infraestrutura |
Conflitos de drizzle_migrations | Tabela de controle compartilhada, sem duplicatas |
Diagrama
graph TD
subgraph Calculadoras
A[prev-tc]
B[prev-rvt]
C[prev-atrasados]
D[prev-rpps]
end
subgraph APIs de cálculo
E[prev-api]
F[rmi-api]
end
subgraph Backoffice
G[APIs públicas /indices/api/v1]
H[APIs públicas /apps/api/v1]
I[Painel privado e serviços internos]
N[(PostgreSQL)]
end
subgraph Apps full stack
O[base-servicos — proxies server-side]
end
A -->|useFetch| G
B -->|useFetch| G
C -->|useFetch| G
D -->|useFetch| G
E -->|HTTP| G
F -->|HTTP| G
A -->|useFetch| O
O -->|HTTP autenticado| I
G --> N
H --> N
I --> N
Estrutura de endpoints
Públicos (CORS habilitado)
| Prefixo | Responsabilidade |
|---|---|
GET /indices/api/v1/** | Indexadores monetários, reajustes, tábua de mortalidade |
GET /apps/api/v1/calculadoras | Catálogo público de calculadoras e URLs por ambiente |
POST /apps/api/v1/exchange | Criar token de exchange (X-Api-Key) |
Persistência de cálculos salvos, pastas e preferências exige autenticação e autorização. A central de Arquivos online e as calculadoras com esse recurso usam os serviços da plataforma; o navegador não acessa diretamente o banco.
Persistência no navegador
Cada aba trabalha em um workspace isolado. Antes de o Pinia hidratar as stores, a camada base-ui carrega do IndexedDB os estados daquele workspace para um cache síncrono. Uma fila preserva a ordem das escritas, e presença/heartbeat evitam que duas abas assumam acidentalmente o mesmo workspace.
Na abertura individual de .calc, parâmetros inválidos com uma regra de recuperação conhecida podem receber valores padrão numa cópia, com aviso e revisão por campo. As revisões pendentes acompanham o cálculo no navegador após recarregar a página. Arquivos corrompidos ou sem recuperação segura continuam recusados, preservando o cálculo aberto. A importação em lote é estrita: importa apenas os válidos após as migrações conhecidas e separa os demais, com o motivo, para abertura e análise individual.
O IndexedDB é o armazenamento principal e permite recuperação depois de reload, fechamento do navegador ou reinício do computador. Se estiver indisponível, o sistema tenta sessionStorage e depois memória da aba. Esses fallbacks mantêm o trabalho durante a sessão corrente, mas não garantem recuperação após encerramento; por isso o aviso ostensivo permanece visível.
Há dois ciclos locais distintos:
- um Rascunho local preserva automaticamente um Cálculo offline assim que aparecem dados relevantes;
- um Rascunho de recuperação preserva alterações de um Arquivo online ainda não confirmadas pela nuvem, mantendo identificador, revisão-base, geração e prova de completude.
O Rascunho de recuperação não aparece na lista de Rascunhos locais. Em uma queda de rede, ele permite continuar editando na mesma aba e volta a sincronizar quando a conexão retorna. Depois de um reinício, a abertura do Arquivo online oferece retomar a cópia local ou descartá-la e usar a versão da nuvem. Uma cópia incompleta é preservada, mas não entra em autosave e não é transformada em .calc aparentemente completo.
Ao exportar ou abrir um arquivo .calc, o vínculo de nuvem é sempre removido. A cópia passa a ser um Cálculo offline independente; salvá-la depois na nuvem cria outro Arquivo online.
Abrir um arquivo .calc tem quatro etapas, nesta ordem: conferir o envelope, migrar, validar e hidratar. Confere-se que o arquivo se identifica como um cálculo da plataforma e que pertence àquela calculadora; ele é levado ao formato atual pela cadeia de migradores da calculadora; seu conteúdo é validado; e só então substitui o cálculo em edição. Nenhum dado da aba é descartado antes de a validação passar. As calculadoras e os endpoints que recebem arquivo usam o mesmo percurso e, portanto, aceitam o mesmo arquivo.
Isso separa dois modos de falha. Um arquivo malformado é aquele cujo envelope sequer identifica um cálculo. Um arquivo recusado é íntegro e foi migrado, mas contém um valor que a calculadora não aceita: a mensagem indica o registro e o parâmetro, e o cálculo aberto permanece inalterado.
Cálculos online usam controle otimista por revisao: o registro salvo no backoffice incrementa a revisão a cada atualização. Ao salvar, a calculadora envia a revisão que abriu; se outra aba ou outro usuário já tiver salvo uma versão mais nova, o backoffice retorna 409 Conflict. A interface oferece salvar as alterações como novo Arquivo online ou descartá-las e usar a versão da nuvem.
Links de compartilhamento usam token opaco de alta entropia com lookup direto no banco.
Integração externa
Use as rotas e os schemas publicados no portal de APIs. Para consultar índices, utilize o contrato público de /indices/api/v1/. Para entregar dados a uma calculadora, a operação de exchange recebe a identificação da aplicação e o payload previsto no schema e devolve a URL de abertura. Não deduza a URL de abertura a partir do token nem acesse rotas internas para consumir o conteúdo.
A autenticação e os escopos necessários estão declarados no OpenAPI. Chaves devem permanecer no ambiente responsável pela integração, conforme o fluxo autorizado para ela.
Banco de dados
O PostgreSQL é compartilhado por todos os domínios em um único banco. As migrations são aplicadas em sequência pelo backoffice e cobrem famílias de tabelas para: indexadores e taxas (com auditoria por linha), administração e log de acessos, cálculos em nuvem (com soft delete e controle otimista), pastas e grupos de compartilhamento, comunicados e documentos legais, telemetria de uso e cadastro de chaves de API (armazenadas como hash).
As alterações administrativas sujeitas a auditoria mantêm rastreabilidade. O catálogo de tabelas, suas colunas e as regras de migração pertencem à documentação interna do projeto.
Inicialização local
bash
cd apps/backoffice
cp .env.example .env
# Preencher as variáveis obrigatórias no .env
pnpm setup:localO script setup:local verifica o Docker, valida o .env, sobe os containers, aplica migrations, popula o banco com dados iniciais e atualiza os índices com dados atuais do Banco Central e IBGE.