O que Refatoração com Autoridade no Backend faz?
Refatore apenas depois de poder dizer exatamente onde a verdade de execução reside e como a UI a lê.
Quando Usar
- A UI sintetiza gráficos, fases ou escolhas de provedor que o backend não entende.
- Reiniciar ou reconectar altera o estado visível de execução porque o frontend armazenou autoridade.
- Schemas antigos e novos, formatos de inicialização ou tipos de nó coexistem no caminho ativo de criação.
- Aprovação, revisão ou execução downstream depende de reconstrução apenas do frontend.
NÃO Serve para
- Limpeza visual cosmética sem alteração na propriedade de execução.
- Refatorações de componentes isolados onde o contrato do backend já é autoritativo.
- Entregar novas funcionalidades de negócio antes de eliminar a costura de autoridade dividida.
- Trabalho puro de desempenho do backend quando a arquitetura já possui uma única fonte de verdade.
Pontos de Decisão
flowchart TD
A[Solicitação de refatoração de workflow] --> B{A UI ainda pode inventar verdade de execução?}
B -->|Não| C[Use uma skill de domínio ou UI mais restrita]
B -->|Sim| D[Inventarie comandos, consultas e costuras de eventos]
D --> E{Cada ação do usuário pode ser mapeada para comando, consulta ou evento?}
E -->|Não| F[Congele o contrato antes de trabalhar em funcionalidades]
E -->|Sim| G[Separe estado de projeção do estado de propriedade do backend]
G --> H{Caminhos legados de compatibilidade ainda estão ativos?}
H -->|Sim| I[Mova-os para arestas de migração ou remova-os]
H -->|Não| J[Adicione avaliadores, consultas seguras de inicialização e assinaturas de evento]
I --> J
J --> K[Valide prontidão para reconexão, aprovação e execução downstream]
Use este modelo de roteamento primeiro:
- Se a UI não puder ser descrita como
comando -> transição do backend -> projeção de consulta ou evento, a costura ainda está errada. - Se um caminho de "compatibilidade temporária" estiver no caminho crítico, trate-o como dívida de refatoração, não como funcionalidade.
- Se reiniciar ou reconectar não puder reconstruir o estado visível apenas a partir da verdade do backend, a refatoração está incompleta.
Método de Trabalho
1. Inventarie o cérebro dividido
Encontre todos os lugares onde a UI:
- gera ou muta a verdade de execução
- inventa fases que o backend desconhece
- simula execução em caminhos de código ativos
- preserva schemas antigos e novos no mesmo caminho de criação
- mistura camadas de roteamento abstratas com IDs exatos de provedor
2. Congele o contrato
Defina apenas três classes:
- Comandos: iniciar, parar, aprovar, retomar, mutar
- Consultas: estado de inicialização, payload de revisão, snapshot de execução, saúde do provedor
- Eventos: transições autoritativas, vereditos de avaliadores, status de portão, marcadores de replay
Se uma ação da UI não puder ser expressa como uma destas, a arquitetura ainda está turva.
3. Normalize a propriedade de estado
Divida stores em:
- estado de entrada de contrato
- estado de projeção de snapshot do backend
- estado de layout da UI
Não permita que nenhuma store possua tanto verdade de execução quanto preocupações de layout.
4. Remova costuras de compatibilidade ativas
Prefira remoção a "suportar ambos por enquanto".
Remoções típicas:
- compatibilidade de schema singular e plural na criação ativa
- simulação de navegador ou demo no runtime ativo de desktop
- tipos de nó obsoletos no caminho principal
- sumários de revisão duplicados
- múltiplos formatos de inicialização ou importação
5. Adicione avaliadores antes de confiar na refatoração
Cada nó de implementação deve ter:
- um avaliador de saída local para correção
- um avaliador de prontidão downstream para segurança de contrato
- um caminho de reinicialização ou reconexão que reidrate da verdade do backend, não de suposições do frontend
Modos de Falha
Projeção disfarçada de autoridade
Sintoma: a UI parece "apenas leitura", mas silenciosamente monta fase, gráfico ou verdade de provedor localmente.
Correção: mova essa lógica para comandos ou consultas do backend e trate o frontend como um projetor.
Calcificação da costura de compatibilidade
Sintoma: "suportar ambos por enquanto" permanece no caminho crítico por semanas e se torna a arquitetura real.
Correção: empurre a compatibilidade para arestas de migração unidirecionais com uma data explícita de remoção ou remova agora.
Aprovação sem inspecionabilidade
Sintoma: um humano pode aprovar trabalho que não pode inspecionar porque o payload de revisão é parcial ou sintetizado pelo frontend.
Correção: o backend deve emitir o payload de revisão exato; a UI apenas o renderiza.
Inicialização hostil a replay
Sintoma: reiniciar o app altera o estado visível ou perde a posição do portão porque o frontend armazenou autoridade.
Correção: a inicialização deve ser uma consulta contra a verdade do backend mais replay de evento, não reconstrução de store.
Xibolete
Se reiniciar o app altera o estado de execução visível sem nenhum novo evento do backend, a autoridade ainda está dividida.
Exemplo Trabalhado
Editor de workflow Tauri com lógica de fase de propriedade do frontend
Problema:
- Stores React criaram o gráfico, inferiram estado de fase e normalizaram camadas de provedor.
- A execução do backend usava um contrato diferente, então os fluxos de revisão e reinicialização divergiram.
Caminho de refatoração:
- Inventarie cada lugar onde a UI inventou a verdade de execução.
- Colapse interações de runtime para comandos, consultas e eventos.
- Mova normalização de provedor e transições de fase para comandos do backend.
- Remova uniões de formato de inicialização do caminho ativo de criação.
- Adicione portões de avaliador para que o trabalho downstream prossiga apenas de saídas validadas pelo backend.
Condição de sucesso:
- Ao reiniciar, a UI reconstrói o mesmo estado visível a partir do snapshot do backend mais eventos.
- Telas de aprovação renderizam um payload de revisão emitido pelo backend, não uma recomposição React.
Orientação para Fork
Bifurque quando o trabalho se separar limpidamente:
- Pista de contrato: inventarie costuras de autoridade dividida e defina comandos, consultas e eventos.
- Pista de remoção: remova camadas de compatibilidade, tipos de nó obsoletos e uniões de formato de inicialização.
- Pista de verificação: adicione portões de avaliador, testes de replay e cobertura de reinicialização ou reconexão.
Mantenha as decisões finais de propriedade na pista pai para que um ator decida o que o backend realmente possui.
Portões de Qualidade
- A UI não pode fabricar verdade de gráfico, fase, provedor ou portão localmente.
- Cada ação do usuário mapeia para um comando, consulta ou evento.
- O estado de execução sobrevive a reinicialização e reconexão apenas a partir da verdade do backend.
- Payloads de revisão e aprovação são emitidos pelo backend e renderizados pela UI.
- A lógica de compatibilidade reside apenas em arestas de migração, não no caminho ativo.
- A execução downstream para em falha de contrato upstream.
- IDs exatos de provedor e escolhas de modelo são visíveis no limite do contrato.
- Testes cobrem caminhos de reinicialização, reconexão, aprovação e falha de avaliador.
Mapa de Referência
references/architecture-patterns.md— padrões de contrato de workflow de propriedade do backend e divisões de propriedade de estado.references/windags-lessons.md— lições concretas de uma migração real de runtime de autoridade dividida.