---
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).