0014 — bi_configuracao (KV) e sinal de nuke¶
Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-07-06 · Decidido em: 2026-05-26
Contexto¶
O nuke da replicação PowerSync recria o slot do zero; o cliente Flutter precisa saber que aconteceu para descartar seu estado local e ressincronizar. Além disso, há configs globais (ex.: timeout de slow query) que devem chegar ao cliente sem outro canal. Faltava um caminho de config sincronizado backend → cliente.
Decisão¶
Uma tabela KV bi_configuracao (migration V12, spec 007), sincronizada via
PowerSync no stream recent_data (priority 0, sem filtro). PK é id TEXT — a
própria chave semântica (ex.: ultimo_nuke, slow_query_timeout_ms) — exceção
consciente à regra UUID v7 das bi_* (ver 0008):
PowerSync aceita TEXT single-column PK e a KV fica mais legível assim que com um
surrogate UUID + UNIQUE(chave). Backend lê via service/ConfigService (cache
TTL 30s); UI em /admin/configuracoes.
Cada linha tem uma flag sistema: sistema=TRUE (ex.: ultimo_nuke, escrito
pelo NukeReplicationService) só é editável por código backend — UI/HTTP retornam
403. Chaves criadas pela tela nascem sistema=FALSE; só migration marca TRUE.
Serialização por tipo: STRING/JSON cru, INT Integer.toString, BOOL lowercase,
TIMESTAMP ISO 8601.
Consequências¶
- O
ultimo_nuke(TIMESTAMP) replica para o cliente Flutter, que detecta o reset e ressincroniza — fecha o loop do nuke sem canal paralelo. - Configs globais (
slow_query_timeout_ms, INT) chegam ao cliente pelo mesmo mecanismo, editáveis pela UI admin. - A flag
sistemaprotege chaves de máquina de edição acidental pela tela.
Alternativas consideradas¶
- UUID v7 +
UNIQUE(chave)(como as outrasbi_*): consistente com a regra, mas a KV fica menos legível — oidseria surrogate sem uso. Descartado para esta tabela específica. - Canal separado para o sinal de nuke (push/endpoint): mais infra para algo que o PowerSync já entrega replicando uma linha. Descartado.