Tema
Sincronização e conflitos
Esta página explica, em linguagem de operador, o que o sync faz e o que você vê. Os detalhes de implementação ficam no spec de engenharia docs/sync.md.
A regra de ouro: todo write importante grava o dado + um evento de outbox na MESMA transação. Se a transação falha, nada fica pela metade — nenhuma operação se perde.
Outbox e inbox
Toda mudança feita no node local entra numa fila de saída, a outbox (pendente → sincronizado). Tudo que chega do outro lado entra numa fila de entrada, a inbox (recebido → aplicado). Cada evento tem um UUID global; a inbox deduplica por ele, então receber o mesmo evento duas vezes nunca duplica dado. É o backend que controla essas filas — sem Debezium/CDC/replicação.
O ciclo do Sync Worker (local → nuvem)
Cada ciclo faz, nesta ordem:
- A nuvem está acessível? Se não, encerra em silêncio (ficar offline é normal).
- Autentica o node — credencial própria do node (
X-Node-Id+X-Node-Secret), não um usuário. - Adquire um lock — impede dois syncs simultâneos para o mesmo node.
- Push — envia os eventos pendentes da outbox em ordem e reconcilia as confirmações.
- Pull — baixa eventos da nuvem desde o último checkpoint e aplica de forma idempotente.
- Libera o lock (sempre, mesmo em erro).
O sync roda automático em modo local (a cada SYNC_INTERVAL_MS, quando SYNC_ENABLED) e também pode ser manual (POST /api/sync/run). O transporte é HTTPS; o node só envia depois de autenticar.
Conflitos
Um conflito acontece quando a mesma entidade mudou de forma divergente nos dois lados. A detecção é por versão (previousVersion vs versão local), não por horário:
- aplica — a versão bate (em ordem) ou é um avanço limpo.
- ignora — evento velho / já incorporado (duplicado).
- conflito — divergência → registra e NÃO sobrescreve.
Não é “last-write-wins”. Para dado médico, sobrescrever silenciosamente é inaceitável; o conflito fica registrado com as duas versões para resolução explícita. Cada domínio define depois sua estratégia de resolução.
Liste os conflitos em aberto com GET /api/sync/conflicts e resolva com POST /api/sync/conflicts/:id/resolve (permissão sync:resolve_conflict).
Retry
Evento que falha não some: ele volta para a fila com backoff exponencial (1s, dobrando, até 5min). Depois de algumas tentativas (8 por padrão) o evento é estacionado como falha, para inspeção manual — em vez de tentar para sempre. Um conflito não entra em retry: fica parado até ser resolvido.
Status
bash
curl -H "authorization: Bearer <token>" http://localhost:3001/api/sync/statusRetorna: último sync, eventos locais pendentes, eventos com falha, eventos remotos aguardando, conflitos em aberto, status do node, conexão e versão do schema/app.
json
{
"mode": "local",
"pendingLocalEvents": 2,
"failedEvents": 0,
"remoteEventsWaiting": 0,
"openConflicts": 0,
"schemaVersion": "0001_init",
"appVersion": "0.1.0"
}Disparo manual
bash
# modo local: roda um ciclo push+pull agora (permissão sync:run)
curl -X POST -H "authorization: Bearer <token>" http://localhost:3001/api/sync/runA referência completa das rotas está em Sincronização (API).
Princípios para módulos médicos (futuro)
- Prontuários não são sobrescritos; correções são emendas.
- Documentos assinados são imutáveis.
- Financeiro usa movimentos e lançamentos de compensação.
- Estoque usa movimentos, não sobrescrita direta de saldo.
- Deleção é sempre lógica (
deletedAt), nunca física.