Manter backend e frontend de um app de geração sincronizados via OpenAPI

## Regenerar tipos e clientes do OpenAPI após cada mudança na API do backend Após cada alteração em uma API do backend, execute o comando de atualização do OpenAPI do repositório. Trate o schema gerado e os tipos do frontend como parte da mesma alteração, não como uma limpeza posterior. O código do frontend deve chamar os endpoints do backend por meio do cliente OpenAPI gerado. Não adicione wrappers de service escritos manualmente que dupliquem os contratos gerados de requisição e resposta. Mantenha uma separação rigorosa das responsabilidades do backend: - a camada de API analisa a entrada, executa autenticação e autorização e organiza as respostas; - a camada de service é responsável pelas regras de negócio, transições de estado e orquestração de dados. Coloque os contratos de geração que atravessam camadas, incluindo DTOs de entrada e saída e configurações de provedores, em um módulo contracts compartilhado. Os módulos task devem conter apenas encapsulamento, distribuição e orquestração da execução de tarefas, não definições de DTOs compartilhados. Os módulos integration podem depender dos contracts compartilhados, mas não devem depender de módulos de tipos internos de task. Quando uma API, um tipo ou um modelo de estado mudar, atualize em conjunto a implementação do backend, o documento OpenAPI, os tipos gerados do frontend, o uso do cliente e a documentação diretamente relacionada. ## Comentar cada função e separar na documentação os fatos atuais dos planos futuros Quando um estilo do frontend se repetir mais de uma vez, prefira um componente reutilizável ou uma estrutura de estilos compartilhada a outra cópia. Toda função, classe ou bloco de código equivalente precisa de um comentário que explique o que faz e por que existe. Lógicas complexas também devem documentar parâmetros relevantes, o comportamento do retorno e decisões internas essenciais. Mantenha os comentários sincronizados com a implementação. Classifique a documentação antes de escrever: - `guide` explica como executar uma tarefa ou integrar uma capacidade; - `architecture` registra o sistema implementado atualmente; - `plans` registra trabalhos futuros, tarefas em etapas e alterações propostas; - `reference` contém fatos estáveis destinados à consulta; - `blog` contém notas de versão. Coloque limites atuais, transições de estado implementadas e comportamento real na documentação de architecture. Coloque em plans o trabalho que ainda está sendo projetado ou executado. Coloque procedimentos operacionais e fluxos de desenvolvimento em guide. Não misture fatos atuais e intenções futuras em um único guia prático. Separe-os entre architecture e plans, mesmo quando tratarem do mesmo assunto. Não altere uma nota histórica de versão já finalizada, a menos que a tarefa exija isso explicitamente. ## Manter a central de tarefas leve e dar a cada tela do fluxo sua própria função Divida o fluxo principal do usuário em superfícies com responsabilidades claras: - uma página de preparação extrai dados do domínio, confirma candidatos, corrige informações básicas e avança o item para `ready`; - um espaço de geração verifica a prontidão da saída, gerencia recursos e parâmetros principais, inicia a geração e apresenta os resultados; - uma central de tarefas mostra apenas informações leves e genéricas, como estado, progresso, sucesso, falha, cancelamento e um link de retorno. Não coloque resumos específicos do domínio, contexto de depuração de prompts, mapeamentos de recursos nem outros detalhes extensos na central de tarefas genérica. Mantenha-os no painel correspondente de preparação, geração, execução ou diagnóstico. Se as ferramentas de extração continuarem disponíveis no espaço de geração, ofereça-as apenas como atalhos ou instrumentos de diagnóstico. Elas não devem substituir a página de preparação como superfície principal de confirmação. Quando um limite de responsabilidade mudar, atualize tanto a UI relacionada quanto a documentação de architecture. Uma reformulação da central de tarefas não deve transformá-la em uma nova página de detalhes de negócio. ## Usar o estado do item só para a confirmação, não para o progresso da geração Use o estado principal do item de domínio somente para representar o estado de confirmação das informações: - `pending` significa que ainda há trabalho de extração ou confirmação; - `ready` significa que as informações obrigatórias foram confirmadas e a preparação posterior pode começar. Não use esse estado para representar a geração durante a execução. Valores como `generating` pertencem ao sistema de tarefas e ao resumo de execução. Represente a prontidão da saída como uma dimensão separada. Um item estar `ready` para a preparação posterior não garante que todas as condições de geração estejam satisfeitas. Toda interface de usuário deve distinguir: 1. estado de confirmação das informações; 2. estado da tarefa durante a execução; 3. prontidão para gerar a saída. Quando a semântica dos estados mudar, sincronize o comportamento do backend, o OpenAPI, os tipos gerados do frontend, os rótulos de estado, as condições de navegação e a documentação de desenvolvimento. ## Levar o usuário da página de preparação ao espaço de geração após confirmar O fluxo padrão é: 1. extrair itens de trabalho do conteúdo de origem; 2. confirmar e corrigir, na página de preparação, os recursos, diálogos ou outras informações obrigatórias extraídas; 3. avançar para o espaço de geração a fim de verificar recursos principais, material de referência, parâmetros de saída e prontidão; 4. iniciar a geração no espaço de geração; 5. revisar os resultados no espaço do domínio, usando a central de tarefas apenas para acompanhar o progresso genérico. A página de preparação é responsável pela extração, confirmação e correção. O espaço de geração é responsável pela preparação e execução da geração e pela revisão dos resultados. Após concluir a preparação, direcione claramente o usuário para o espaço de geração. Se o espaço detectar que um item não está `ready`, direcione o usuário de volta à preparação com uma explicação clara. Priorize esse fluxo ao alterar interações. Atalhos de conveniência não devem ocultar a próxima etapa canônica nem combinar preparação e geração em uma superfície ambígua. ## Atualizar os documentos de architecture a cada mudança e incluir passos de migração prontos nas notas de versão A documentação de architecture contém somente o comportamento atualmente verdadeiro. Plans contém trabalhos em andamento, tarefas em etapas, prioridades e caminhos de execução futuros. Quando o comportamento do código, a semântica dos estados ou as responsabilidades de uma página mudarem, atualize a documentação de architecture no mesmo trabalho. Quando o escopo, a prioridade ou a ordem de um plano mudar, atualize plans. Um plano implementado deve passar para architecture ou se tornar uma nota de versão. Considere incompleto qualquer trabalho que deixe desatualizada a documentação de architecture ou plans. As notas de versão devem incluir metadados iniciais para `title`, `date`, `description`, `tags` e `authors`. Use uma ordem estável de seções e omita apenas as que não se aplicarem: 1. Destaques; 2. Adicionado, alterado e corrigido; 3. Alterações incompatíveis e descontinuações; 4. Segurança e problemas conhecidos; 5. Guia de migração e instruções de reversão; 6. Matriz de compatibilidade, comandos de validação e lista de atualização; 7. Referências, notas para colaboradores e agradecimentos. Escreva as notas de versão com a voz de quem mantém o projeto: apresente primeiro as conclusões e as informações executáveis, use parágrafos curtos e listas e mantenha a terminologia estável. Separe claramente novas capacidades, mudanças de comportamento, riscos de compatibilidade e problemas conhecidos. As etapas de migração, as etapas de reversão e os comandos de validação devem poder ser usados diretamente, sem ambiguidade. ## Concluir só quando os tipos gerados e a documentação estiverem de acordo com o código O trabalho só está concluído quando todas as condições aplicáveis forem atendidas: 1. a implementação está presente, sem marcadores provisórios evidentes nem resíduos de compatibilidade obsoletos; 2. funções e classes novas ou alteradas têm comentários precisos e úteis; 3. as alterações de API atualizaram o OpenAPI, os tipos gerados do frontend e o uso do cliente gerado; 4. o comportamento atual está refletido na documentação de architecture e o trabalho futuro em plans; 5. as responsabilidades de preparação, geração e central de tarefas permanecem separadas; 6. as alterações do frontend passam na verificação TypeScript sem emissão do repositório; 7. as alterações do backend passam nos testes relevantes ou, no mínimo, nas verificações documentadas de sintaxe e importações; 8. o relatório de conclusão informa o que mudou e quais verificações passaram; 9. o trabalho restante ou as recomendações posteriores são listados separadamente. Não declare o trabalho concluído enquanto houver divergência entre código, contratos, tipos gerados, documentação, semântica de estados ou superfícies do fluxo de trabalho.