Skip to content

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:

  1. A nuvem está acessível? Se não, encerra em silêncio (ficar offline é normal).
  2. Autentica o node — credencial própria do node (X-Node-Id + X-Node-Secret), não um usuário.
  3. Adquire um lock — impede dois syncs simultâneos para o mesmo node.
  4. Push — envia os eventos pendentes da outbox em ordem e reconcilia as confirmações.
  5. Pull — baixa eventos da nuvem desde o último checkpoint e aplica de forma idempotente.
  6. 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/status

Retorna: ú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/run

A 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.