aplimoramento de agent

DOCUMENTACAO/templates/fluxo-usuario.md.template

@@ -0,0 +1,62 @@
+---
+type: template
+name: fluxo-usuario
+description: Template canônico para mapeamento de fluxos operacionais e jornadas do usuário
+updatedAt: "2026-09-02"
+---
+
+<!--
+DESTINO CANÔNICO NO PROJETO:
+- Wiki do Usuário (Pilar 3): ../../wiki/<modulo-id>/fluxos/{nome-do-fluxo}.md
+- Wiki de Desenvolvimento (Pilar 4 - Fluxos Técnicos/Jobs): ../../wiki/dev/<modulo-id>/fluxos/{nome-do-fluxo}.md
+-->
+
+# Fluxo de Usuário: [Nome da Jornada / Processo]
+
+- **Módulo:** `<modulo-id>`
+- **Atores Envolvidos:** `<Ex: Gestor Ambiental, Técnico de Campo, Consultor>`
+- **Objetivo Final:** `<O que é alcançado com sucesso ao término deste fluxo>`
+
+---
+
+## Pré-condições
+- [ ] Usuário devidamente autenticado com permissão de acesso ao módulo.
+- [ ] Entidade pai previamente cadastrada.
+
+---
+
+## Jornada Principal (Caminho Feliz)
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor U as Usuário
+    participant UI as Interface (Vue)
+    participant API as Backend Fastify/Express
+    participant DB as PostgreSQL
+
+    U->>UI: Acessa formulário de cadastro
+    UI->>U: Exibe campos com validação Zod preventiva
+    U->>UI: Preenche dados e clica em Salvar
+    UI->>API: POST /recurso (payload validado)
+    API->>DB: Persiste registro no banco
+    DB-->>API: Retorna ID gerado
+    API-->>UI: 201 Created com dados criados
+    UI-->>U: Exibe toast de sucesso e redireciona
+```
+
+### Passo a Passo Detalhado
+1. **Acesso à Tela:** O usuário navega até a rota `<modulo-caminho>recurso`.
+2. **Preenchimento:** Preenche os campos obrigatórios (validação visual imediata).
+3. **Submissão:** Clica em "Salvar". O botão entra em estado `loading`.
+4. **Confirmação:** Toast de sucesso exibido e lista atualizada sem recarregar a página.
+
+---
+
+## Fluxos Alternativos e Tratamento de Exceções
+
+### Alternativa 1: Cancelamento
+- O usuário clica em "Cancelar". Se houver alterações pendentes, um modal de confirmação de descarte é exibido.
+
+### Exceção 1: Falha de Conexão ou Validação
+- Se a API retornar erro de validação ou indisponibilidade, a interface exibe banner com mensagem amigável no vocabulário do usuário (sem expor stack traces técnicos).