timerise-ai/island-mode-server

Servidor Modo Ilha

Um pequeno servidor Node executa no local físico segurando uma réplica RxDB ativa da fatia do Firestore referente ao local. Enquanto a internet está no ar, ele é invisível; quando a internet cai, os terminais de quiosque/funcionários na LAN fazem failover para ele e o local continua recebendo pedidos, movimentando estoque e alternando hardware. Na reconexão, o trabalho offline é enviado de volta para a nuvem. A percepção central que molda tudo: sincronização são dois sistemas, não um — replicação RxDB no nível de documento para estado, mais um flush HTTP de eventos de negócios que a nuvem deve aplicar com sua própria lógica (incrementos de estoque, ingestão de auditoria). Nenhum dos dois é suficiente sozinho.

Quando usar

• Um local precisa sobreviver a quedas de internet com gravações reais (reservas, estoque, controle de hardware), não apenas leituras em cache.
• Os terminais são baseados em navegador (PWA/quiosque) e devem fazer failover transparentemente.
• Firestore é a fonte de verdade na nuvem e assim permanece.

Quando NÃO usar

• Cache de leitura puro ou um PWA que só precisa da persistência offline nativa do Firestore — o SDK do Firebase já faz isso; nenhum servidor é necessário.
• Um banco de dados de nuvem diferente (Supabase/Postgres): o conceito de camada de replicação se aplica, mas todo template aqui é específico do Firestore.
• Sincronização multimestre entre locais pares — este design é estritamente hub-and-spoke com a nuvem como fonte de verdade e conflitos resolvidos por última gravação vence.

Arquitetura

            Internet
               |
      +--------+---------+
      | Nuvem (SSoT)     |  Firestore + API pública + marcador de status cron
      +--------+---------+
        |             |
   Replicação RxDB  Flush HTTP (reconexão)
        |             |
      +-+-------------+-+
      | Servidor local   |  Node/NestJS + RxDB, LAN :443 via nginx TLS
      +--------+--------+
               |
     LAN — PWA quiosque, PWA funcionários, controladores de hardware

Fatos críticos

1. Toda gravação na nuvem em uma coleção replicada DEVE carimbar o campo de checkpoint (serverTimestamp: FieldValue.serverTimestamp()) e _deleted: false — o plugin RxDB Firestore puxa por serverTimestamp > checkpoint; um documento sem carimbo nunca é puxado pela replicação.
2. Três níveis de replicação, escolhidos por coleção: pull-only (configuração que o local consome), bidirecional (estado operacional que o local modifica), push-only (logs que o local produz). Escolher o nível errado de uma coleção é o principal erro de design.
3. Armazenamento RxDB em memória significa que uma reinicialização offline perde todo o trabalho offline. A réplica se repovoa do Firestore, mas os documentos criados offline desaparecem. Decida explicitamente a troca de armazenamento — veja replication.md.
4. O flush é pelo menos uma vez, então a ingestão na nuvem deve ser idempotente — chaveie cada aplicação pelo ID gerado pelo cliente e pule as já aplicadas.
5. Filtros push evitam eco: pushes bidirecionais só enviam documentos marcados _offlineCreated / _locallyModified, para que documentos puxados da nuvem não voltem.
6. Terminais preferem a nuvem — o failover só engata após N falhas de saúde consecutivas e, enquanto offline, eles devem continuar escaneando o servidor local, não apenas uma vez na transição.

Regras rígidas

Nunca exponha os endpoints de sincronização de ingestão da nuvem sem autenticação. Eles aplicam incrementos de estoque e injetam pedidos. Um cabeçalho com segredo compartilhado é o mínimo.

Nunca verifique tokens de funcionários offline de forma branda enquanto online. A alternativa de decodificar sem verificação é uma troca aceita apenas em LAN; ela deve ser bloqueada quando o servidor estiver realmente online, ou se torna um bypass da verificação de assinatura.

Nunca redefina deltas de estoque locais para transações que não confirmaram sincronização. Redefina por ID no reconhecimento, ou as vendas offline serão contadas em dobro ou desaparecerão da disponibilidade.

Nunca deixe o servidor local inventar regras de negócio que a nuvem possui (horário de funcionamento, preços). Replique a configuração e calcule a partir dela, ou o comportamento do modo ilha divergirá do site.

Início rápido

1. Modele as coleções em níveis e nomeie as junções — architecture.md.
2. Configure RxDB + replicação com autenticação de token personalizado e regras de segurança — replication.md.
3. Adicione o flush de reconexão e a ingestão idempotente na nuvem — sync-flush.md.
4. Conecte a cadeia de heartbeat/status e failover do cliente — network-failover.md.
5. Proteja a API local (staff / quiosque / hardware HMAC / token estático) — auth.md.
6. Espelhe os endpoints da nuvem que os terminais precisam — local-api.md.
7. Implante no local: systemd, nginx TLS, mDNS, monitoramento — operations.md.

Diretório de referências

Cenário	Palavras-chave	Referência
Topologia, níveis, junções, renomear tabela	pull-only, bidirecional, push-only, dual-path, locationId, conflito	architecture.md
Configuração da réplica, esquemas, armadilha do checkpoint	RxDB, replicateFirestore, serverTimestamp, token personalizado, storage-memory, firestore.rules	replication.md
Flush de reconexão, deltas de estoque, ingestão	flushAll, idempotente, FieldValue.increment, localDelta, syncedIds	sync-flush.md
Detecção de queda e alternância de API	heartbeat, lastHeartbeatAt, cron, NetworkManager, apiBaseUrl, failover	network-failover.md
Autenticação da API local	AuthGuard, HMAC, janela de repetição, fallback JWT offline, chave de quiosque	auth.md
Endpoints e gravações offline	availability, mutex, reserva offline, check-in, filtro de estoque de preços	local-api.md
Implantação no local e runbook	systemd, nginx, TLS autoassinado, mDNS, avahi, journalctl, rollback	operations.md
O livro-razão: o que a auditoria mudou, manteve, adicionou	proveniência, auditoria, desvios, mantido deliberadamente	provenance.md

Suite vitest para a lógica crítica de confiança (verificação HMAC, decodificação de token offline, dobra de delta no RxDB real, rescaneamento de failover): assets/behavior.test.ts — leve-o para o projeto alvo como cobertura de regressão.