Etapa 05 — Resetar Powersync¶

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-06-15

Esta página é o desenho (porquê e como funciona). O procedimento operacional passo a passo vive no runbook operacao/resetar-powersync. O sinal que os clientes leem está na etapa 06.

1. Contexto e escopo¶

Mudanças estruturais ou estados corrompidos exigem, de vez em quando, zerar o estado replicado (slot de replicação no Postgres + base do PowerSync no MongoDB) e forçar um re-sync limpo nos clientes móveis. É destrutivo e arriscado à mão — encapsulado num serviço auditável, com confirmação anti-acidente e sinal para os clientes reconectarem.

Dentro do escopo: o serviço de reset (9 steps); os dois gatilhos (REST + tela); restart opcional do PowerSync via Coolify; audit por step em xls_resetar_powersync.

Fora do escopo: o consumo do sinal pelos clientes (chave ultimo_nuke) → etapa 06.

2. Componentes e modelo de dados¶

flowchart TD
    rest[POST /api/transporte/admin/resetar-powersync<br/>Bearer + X-Confirm-Nuke]
    tela[POST /admin/resetar-powersync<br/>modal RESETAR + login Google]
    rest --> svc[ResetarPowersyncService]
    tela --> svc
    svc --> pg[(Postgres: RESET_SLOT)]
    svc --> mongo[(MongoDB PowerSync: DROP_MONGO)]
    svc --> coolify[Coolify API<br/>restart opcional]
    svc --> audit[(xls_resetar_powersync<br/>audit por step)]

Audit em xls_resetar_powersync (xls_*, local, não sincroniza; ex-xls_nuke_replication, renomeada em V14). Colunas-chave: id (PK), status (VARCHAR(20)), iniciado_em/ concluido_em, iniciado_por, motivo, step_atual, steps_completados (JSONB, default []), atividade_atual (TEXT — polling de 2s pela tela), detalhes (JSONB), erro_mensagem. Garantias de schema:

CHECK chk_resetar_powersync_status: status ∈ {PENDENTE, EM_ANDAMENTO, SUCESSO, ERRO}.
Índice unique parcial uq_xls_resetar_powersync_em_andamento WHERE status = 'EM_ANDAMENTO': no máximo um reset em andamento — um 2º disparo recebe 409.
O audit nunca grava a URI do Mongo — só o nome do DB dropado.

3. Fluxos e estados¶

stateDiagram-v2
    [*] --> EM_ANDAMENTO: criar (lança 409 se já houver)
    EM_ANDAMENTO --> SUCESSO: FINALIZAR
    EM_ANDAMENTO --> ERRO: falha em qualquer step
    SUCESSO --> [*]

Os 9 steps idempotentes (executor dedicado reset-, single-thread):

flowchart TB
    V[VALIDAR] --> L[LOCK] --> P[PAUSE] --> SP[SNAPSHOT_PRE]
    SP --> RS[RESET_SLOT] --> DM[DROP_MONGO] --> R[RESUME]
    R --> SA[SAMPLE_POST] --> F[FINALIZAR]

Por que o estado pode ficar parcial (e o recovery é por step): RESET_SLOT roda antes de DROP_MONGO — falha no reset deixa o Mongo intacto. O drop do slot roda com autoCommit ligado (o Postgres proíbe pg_drop_replication_slot dentro de transação), então uma falha no meio deixa estado parcial — daí o recovery ser passo a passo, não rollback transacional. Reset órfão (JVM morreu no meio — deploy/OOM) é marcado ERRO no próximo boot, preservando o step onde parou. No FINALIZAR, grava o sinal ultimo_nuke (etapa 06).

4. Contratos¶

4.1 Gatilhos REST (Bearer)¶

Método/rota	Confirmação	Status
`POST /api/transporte/admin/resetar-powersync`	header `X-Confirm-Nuke` = token; `X-Operator-Id` opcional; query `wait_secs`; body `{motivo}`	`202` · `403` confirmação errada · `409` já em andamento · `503` desabilitado
`GET …/resetar-powersync/{id}`	—	status + steps
`GET …/resetar-powersync`	query `limit`/`offset`	lista

A tela /admin/resetar-powersync (modal anti-acidente, palavra RESETAR + CSRF, protegida por login Google — etapa 07) chama o mesmo serviço. Contrato completo: dev/api-rest.

4.2 Contratos preservados do rename Nuke→ResetarPowersync (NÃO mudar)¶

A feature se chama Resetar Powersync, mas estes identificadores mantêm o nome antigo "nuke" por serem contrato externo (lidos por clientes Dart/deploy):

Contrato	Valor	Papel
Chave de dado	`ultimo_nuke` (em `bi_configuracao`, `sistema=TRUE`)	sinal de reset (etapa 06)
Env	`POWERSYNC_NUKE_CONFIRMATION` → `powersync.nuke.confirmation-token`	habilita o endpoint; vazio → 503
Env	`POWERSYNC_BOOTSTRAP_WAIT` → `powersync.nuke.bootstrap-wait-secs`	espera de bootstrap (default 60)
Header	`X-Confirm-Nuke`	confirmação; errado → 403
Config path	`powersync.nuke.*`	mantido com o nome antigo

5. Configuração¶

Env	Property	Default	Papel
`POWERSYNC_MONGODB_URI`	`powersync.mongodb.uri`	vazio → stub (simula o drop)	conexão Mongo do PowerSync
`POWERSYNC_MONGODB_DATABASE`	`powersync.mongodb.database`	derivado da URI	DB a dropar
`POWERSYNC_SLOT`	`powersync.slot`	auto-discover	slot de replicação
`POWERSYNC_PLUGIN`	`powersync.plugin`	`pgoutput`	plugin do slot
`COOLIFY_API_TOKEN`	—	vazio → restart manual	habilita restart automático no `RESUME`
`POWERSYNC_COOLIFY_*` / `COOLIFY_API_URL` / `POWERSYNC_HEALTH_URL` / `POWERSYNC_RESTART_TIMEOUT`	`powersync.coolify.*`	—	alvo e health do restart

Config de restart incompleta → PAUSE/RESUME viram no-op com WARNING (operador reinicia o PowerSync na mão). Runbook: operacao/resetar-powersync.

6. Decisões¶

Nº	Decisão
0009	Resetar Powersync em 9 steps
0010	Sinal de reset via `bi_configuracao`

7. Riscos¶

Reset disparado por engano → modal anti-acidente + header de confirmação + token configurável; audit por step permite recovery.
PowerSync não sobe sync_rules ACTIVE (ex.: GRANT faltando, decisão 0013) → o reset morre em SNAPSHOT_PRE; conferir privilégios antes.