Enfileira mutações do usuário enquanto offline com identidade durável, regras de ordenação, políticas de repetição e conflito, e estado da fila visível ao usuário para que a reconexão não reproduza ou descarte trabalho de forma imprevisível.
Status do pacote: Pacote de referência assistido por IA. A validação estática do pacote foi aprovada; cenários de implementação ainda não foram executados e revisão humana do domínio é necessária antes da adoção estável.
Decisão
Quando a conectividade não está disponível, persista as mutações do usuário em uma fila durável com transições explícitas de estado em vez de descartar silenciosamente o trabalho ou aplicar duas vezes na reconexão. As políticas de envio respeitam a ordenação por entidade, confirmação idempotente do servidor e status da fila visível ao usuário.
Escopo
- Detecção offline, regras de enfileiramento, armazenamento e limites de profundidade da fila.
- Agendamento de envio, retentativas com backoff e estados terminais definidos em
queue-states.yaml. - Tratamento de conflitos quando a verdade do servidor diverge das mutações enfileiradas.
- Integração com UI otimista onde ambos são adotados.
Fora deste bloco
- Replicação completa local-first de banco de dados.
- Sincronização em segundo plano para caches somente leitura.
- Infraestrutura de fila do lado do servidor.
Contrato
- Cada mutação enfileirada tem um id de mutação do cliente persistido antes da UI reportar sucesso offline.
- A ordenação FIFO por entidade é preservada durante o envio, a menos que uma regra de mesclagem documentada se aplique.
- Tentativas de repetição incrementam a partir dos estados flushing e awaiting_ack; falhas transitórias re-enfileiram, falhas terminais movem para failed ou tombstoned sem repetição silenciosa.
- Mutações de exclusão enfileiradas tombstone o estado local e substituem atualizações pendentes para a mesma entidade.
- Exclusão de entidade reportada pelo servidor tombstone atualizações enfileiradas para essa entidade.
- Após expirar a janela de deduplicação, a reprodução é rejeitada até que uma busca explícita de reconciliação confirme o estado do servidor.
- Respostas de conflito transitam para estado de conflito com ações do usuário documentadas; descarte silencioso é proibido.
- A profundidade da fila não pode exceder o máximo do perfil sem bloquear novos enfileiramentos e informar o usuário.
- Mutações aplicadas são removidas da fila ativa dentro da janela de retenção do perfil após confirmação.
Orientação de implementação
- Implemente a máquina de estados de
queue-states.yamlcomo a única autoridade para transições da fila. - Use armazenamento durável que sobreviva a reinícios de processo; verifique testes de recuperação após simulação de falha.
- Coordene com atualizações otimistas para que a UI provisória reflita honestamente o estado enfileirado em vez de implicar confirmação do servidor.
- Alinhe ids de mutação do cliente com suporte à idempotência da API no servidor e documente tipos de mutação elegíveis para fila nas especificações de recurso.
Tratamento de falhas e salvaguardas
- Em caso de corrupção do armazenamento, coloque a fila em quarentena e ofereça exportação antes do reset.
- Evite envio paralelo da mesma entidade além das regras documentadas de paralelismo.
- Não exclua automaticamente mutações falhadas sem ação explícita do usuário.
Verificação e operações
- Monitore profundidade da fila, latência de envio, contagem de retentativas e taxa de conflito.
- Teste enfileiramento offline, envio na reconexão, recuperação de falhas e cenários de deduplicação.
- Alerta quando entradas falhadas na fila excederem os limites do perfil; vincule a diagnósticos com controle de acesso por id de correlação opaco em vez de copiar payloads de mutação ou identificadores de usuário no alerta.
Os exemplos executáveis neste pacote são fixtures e contratos de aceitação. Valide a estrutura do pacote antes da adoção; depois implemente e execute os cenários no repositório alvo.
Suposições para adoção
- Limites de profundidade, arrays de backoff e tecnologia de armazenamento em
example.yamlsão escolhas de perfil para um app móvel de anotações de campo, não padrões universais. - As equipes devem classificar quais mutações são elegíveis para fila versus somente online.
Referências
- Nenhuma fonte normativa externa é requerida; combine com especificações de idempotência da API quando disponíveis.