T-072 - Implementar o cliente SSE com reconexão e deduplicação

[pedro-fs-garcia]

T-072 - Implementar o cliente SSE com reconexão e deduplicação

• Componente: frontend

• Estimativa: 3

• Depende de: T-071

• Data máxima: 2026-09-22 (ter)

Descrição

Implementar o cliente SSE do frontend, com reconexão automática de recuo progressivo, deduplicação por identificador sequencial e reconciliação de estado por GET /jobs/{id} na reconexão.

O job pode durar minutos e a conexão pode cair - rede instável, suspensão da máquina, proxy. O cliente SSE precisa reconectar sozinho e não confundir o usuário quando um evento chegar duas vezes depois da reconexão.

Camada de transporte, separada das telas que a consomem.

Escopo

Dentro do escopo

• Cliente SSE que abre o stream de um job_id e entrega eventos à store do job.
• Reconexão automática com recuo progressivo.
• Deduplicação por identificador sequencial do evento.
• Consulta a GET /jobs/{id} na reconexão, para recuperar o estado que se perdeu enquanto desconectado.
• Encerramento limpo do stream ao sair da tela.

Fora do escopo

• Infraestrutura SSE no servidor (T-043).
• Renderização do progresso (T-073) e do resultado (T-075).
• Cliente REST (T-071), que é insumo.

Requisitos

• Queda de conexão no meio de um job reconecta sozinha, sem ação do usuário.
• O mesmo evento entregue duas vezes não produz efeito duplicado na tela.
• Na reconexão, o estado é reconciliado por GET /jobs/{id} - o stream entrega o que vem a partir de agora, e a lacuna é preenchida pela consulta.
• Sair da tela encerra o stream: nada de conexões acumuladas.

Contexto técnico

• Entradas: GET /jobs/{id}/events (T-043) e GET /jobs/{id} (T-042); cliente REST e sessão (T-071).
• Saídas: cliente SSE e store do job atualizada por ele.
• Componentes afetados: frontend/.
• Restrições: o job vive na api, não na aba - desconectar não interrompe o processamento, e o cliente pode assumir isso.
• Referências: ARCHITECTURE.md §3.1 (cliente SSE com reconexão e deduplicação) e §6.4.

Critérios de aceitação

• Derrubar a conexão no meio de um job faz o cliente reconectar sozinho.
• O mesmo evento entregue duas vezes não aparece duplicado na store.
• Na reconexão, o estado é reconciliado por GET /jobs/{id}.
• Sair da tela encerra o stream, verificado por ausência de conexão remanescente.
• Reconexões sucessivas usam recuo progressivo, sem laço apertado.

Definição de concluído (DoD)

• Todos os critérios de aceitação foram atendidos.
• Testes automatizados foram adicionados ou atualizados quando aplicável.
• Os testes existentes passam.
• O código segue as convenções e padrões de qualidade do projeto.
• Documentação, migrações, contratos ou configurações exigidos foram atualizados.
• Nenhuma regressão conhecida ou problema não resolvido foi introduzido pela tarefa.
• As alterações foram confirmadas e estão prontas para revisão/mesclagem.
• A implementação foi verificada no ambiente apropriado.

Observações / Decisões

Fronteira com T-043: lá é o transporte no servidor, aqui é o transporte no cliente. A deduplicação depende do identificador sequencial que T-043 emite - as duas metades do mesmo mecanismo, em componentes diferentes.

Efeito cascata: destrava T-073 e T-075.