Z-Flow

┌──────────── Z-FLOW ─────────────┐
│                                  │
│  Formulário                      │
│      │                           │
│      │ resposta enviada          │
│      ▼                           │
│  ┌──────────┐                    │
│  │  Step 1  │ Aprovação técnica  │
│  │ SLA: 4h  │ → grupo "Engenh."  │
│  └────┬─────┘                    │
│       │  aprovado                │
│       ▼                          │
│  ┌──────────┐                    │
│  │  Step 2  │ Triagem IA          │
│  │ Agente   │ → autoclassifica   │
│  └────┬─────┘                    │
│       │ se alta criticidade      │
│       ▼                          │
│  ┌──────────┐                    │
│  │  Step 3  │ Visita de campo    │
│  │ SLA: 24h │ + Z-Schedule       │
│  └────┬─────┘                    │
│       ▼                          │
│  ┌──────────┐                    │
│  │  Step 4  │ Documento + Z-Sign │
│  └──────────┘                    │
└──────────────────────────────────┘

4.1. Editor de fluxos (XYFlow)

• Onde: /forms/:formId/workflow/steps/new (nova etapa) e /forms/:formId/workflow/steps/:stepId/edit (editar).
• O que faz: modela o fluxo com nós (etapas) e arestas (transições) em tela visual. Cada nó configura responsáveis, SLA, formulário de subetapa, ações disponíveis.
• Dica: desenhe o fluxo no papel antes. O editor é poderoso, mas a clareza vem da modelagem prévia.

4.2. Tipos de responsável por etapa

• Usuário fixo — sempre João.
• Grupo / Cargo — primeira pessoa do grupo que assumir.
• Campo do formulário — "o gerente da unidade que aparece no campo X".
• Agente IA — etapa autônoma (ver §4.7).

4.3. SLA e escalonamento

• Cada etapa tem prazo configurável (horas, dias).
• Escalonamento: ao vencer, notifica o líder; ao vencer de novo, escala para o nível seguinte.
• Pontuação Z-Score: SLA cumprido pontua positivamente; vencido desconta.

4.4. Ações disponíveis por etapa

• Aprovar — segue para a próxima.
• Reprovar — encerra ou devolve.
• Corrigir / Pedir correção — devolve para o originador com observação.
• Pedir mais informação — pausa o SLA até resposta.
• Reabrir — reopen com histórico preservado.
• Encaminhar — passa para outro usuário/grupo.

4.5. Transições configuráveis

• Componente: WorkflowTransitionEditor.
• O que faz: define quando e para onde a etapa transita.
• Gatilhos: start (entrada do fluxo), step_completed, condition_met, evento de outro módulo.
• Condições: construídas com ConditionsBuilder ou WhenExpressionBuilder — combinam campos do formulário, dados do usuário, contexto da empresa.
• Bifurcação: uma transição pode ter múltiplos destinos com condição diferente.

4.6. Inbox do usuário

• URL: /workflow.
• O que vê: ações pendentes para mim e assumidas por mim.
• Filtros: WorkflowActionsFilter por status, formulário, criticidade, prazo.
• Ações em lote: assumir, devolver, aprovar várias de uma vez.

4.7. Etapa executada por agente IA

• Em vez de "responsável humano", a etapa tem um agente IA cadastrado em Z-IA.
• O agente roda automaticamente ao chegar na etapa, analisa o contexto e:
• completa a etapa (aprovar, reprovar);
• cria nova ação de workflow (create_workflow_action);
• dispara notificação, agenda, assinatura;
• escala para humano somente se houver dúvida.
• Detalhamento: `10-agentes-autonomos.md`.

4.8. Notificações multicanal

• WhatsApp, e-mail, in-app, push.
• Templates personalizáveis com variáveis Mustache do formulário e da empresa.
• Auditoria em /notifications-audit — quem recebeu, quando, abriu, agiu.

4.9. Página de processamento (/workflow/process/:responseId/:stepId)

• Mostra ao executor:
• resposta completa do formulário;
• histórico das etapas anteriores;
• botões de ação disponíveis;
• formulários adicionais da etapa (subformulários);
• anexos, fotos com mapa;
• timeline de notificações e tentativas anteriores.

4.10. Histórico imutável

• `WorkflowHistoryTab`: registro completo de cada decisão, cada transição, cada observação, com autor e timestamp.
• Por que isso importa: auditoria, disputa, perícia, conformidade ISO/SOX.

4.11. Tabs de gestão do workflow

[ Usuário envia resposta ]
         │
         ▼
[ Z-Flow cria instância de workflow ]
         │
         ▼
[ Step 1 — agente IA classifica ]
         │
   ┌─────┴─────┐
   ▼           ▼
[ Baixa     [ Alta criticidade ]
criticidade] notifica gerente WPP
   │           │
   │           ▼
   │      [ Gerente abre /workflow/process/... ]
   │           │
   │      Aprova → Step 2 (Manutenção)
   │           │
   │           ▼
   │      [ Z-Schedule cria visita ]
   │           │
   │           ▼
   │      [ Técnico executa via Z-Field ]
   │           │
   │           ▼
   │      [ Z-Sign gera termo de fechamento ]
   │           │
   ▼           ▼
[ Resolvido ] [ Resolvido + assinado + pontuado + auditado ]

Cenário A — Não-conformidade em auditoria de loja

Resposta de auditoria identifica 4 NCs. Z-Flow gera 4 ações distintas, cada uma roteada ao gerente daquela loja, com SLA de 5 dias. Vencendo, escala para regional. Resolvendo, dispara termo de aceite (Z-Sign) e pontua o gerente que cumpriu (Z-Score).

Cenário B — Aprovação de despesa

Funcionário preenche formulário de reembolso com nota fiscal. Z-Flow:

• Step 1: agente IA lê a nota fiscal por imagem, valida valor e categoria.
• Step 2: aprovador direto (campo do formulário "gestor imediato") aprova em 24h.
• Step 3: financeiro recebe, valida e libera.

Cenário C — Tratativa de incidente

Operador reporta incidente em campo. Z-Flow:

• Step 1: triagem por agente (criticidade).
• Step 2 (se crítico): dispara alerta para grupo de emergência por WhatsApp imediatamente.
• Step 3: abertura de ação corretiva, execução, evidência.
• Step 4: termo de fechamento assinado pelo gerente local.

7.1. Pitch 5 minutos

7.2. Apresentação 15 minutos

Objetivos

• Modelar um workflow com 4 etapas, 2 condições e 1 etapa com agente IA.
• Configurar SLA, escalonamento, notificações.
• Operar a inbox: assumir, aprovar, devolver.
• Ler o histórico e auditar uma decisão.

Agenda

Exercício 1 — Fluxo simples de aprovação

Crie um fluxo no formulário "Reembolso" com:

• Step 1: aprovação do gestor imediato (campo do formulário).
• Step 2: validação do financeiro (grupo "Financeiro").
• Step 3: pagamento (responsável fixo).
• Notificação por e-mail em cada transição.

Exercício 2 — Bifurcação e SLA

Adicione no fluxo de "Reembolso":

• Se valor > R$ 1.000, etapa extra de aprovação do diretor.
• SLA de 24h por etapa, escalonamento ao líder em 48h.

Exercício 3 — Etapa com agente IA

Crie um agente que valida a nota fiscal anexa (consistência de CNPJ e valor) e:

• aprova automaticamente se tudo bater;
• abre ação de correção para o operador se faltar dado.

Exercício 4 — Operação real

• Submeta 3 respostas com valores diferentes.
• Atravesse o fluxo todo na pele do aprovador.
• Audite a 3ª resposta no histórico — explique o que aconteceu.

Quiz (8 perguntas)

1. Onde o operador vê suas ações pendentes?
2. O que significa "assumir" uma ação?
3. Qual o componente que define quando e para onde uma transição vai?
4. Que tipos de responsável existem?
5. Onde vejo as notificações enviadas e abertas?
6. O que acontece se uma etapa vence o SLA?
7. Como uma etapa pode ser executada por IA?
8. Posso reabrir um fluxo encerrado?

Setup inicial

• [ ] Mapear os 5 fluxos críticos da operação.
• [ ] Definir SLA por etapa em conjunto com o gestor.
• [ ] Criar grupos e cargos antes de modelar.
• [ ] Configurar templates de notificação por canal.
• [ ] Validar com 3 respostas reais antes de publicar.

Revisão mensal

• [ ] Quais etapas têm maior tempo médio? Há gargalo.
• [ ] Quais usuários acumulam mais ações? Sobrecarga.
• [ ] Há ações abertas há mais de X dias? Escalar.
• [ ] As notificações estão sendo abertas?
• [ ] Há etapas que poderiam virar IA?

Posso ter o mesmo formulário com fluxos diferentes para empresas diferentes? Sim — multi-tenant. Cada empresa modela o seu.

Como diferenciar grupo de cargo? Grupo é uma lista nomeada de pessoas. Cargo é um papel hierárquico.

E se ninguém do grupo assumir? Configurar escalonamento por SLA. Vencendo, notifica o líder.

Posso devolver e re-rodar a partir de qualquer etapa? Sim — devolução com observação, reabertura preservando histórico.

O histórico pode ser editado? Não. É imutável por design para auditoria.

Como sei se a notificação chegou? /notifications-audit — prova de envio, abertura e ação.

Posso testar o fluxo sem afetar a produção? Sim — duplicar o formulário em ambiente de teste e modelar lá.

A sequência visual do Z-Flow parte da caixa de tarefas e percorre aprovação, modelagem de etapas, condições, histórico e indicadores. Ela evidencia que cada encaminhamento tem contexto, prazo e rastreabilidade, inclusive quando uma etapa incorpora inteligência artificial.

As telas internas foram capturadas no sandbox em 24/05/2026. O quadro da mensagem móvel é uma ilustração conceitual identificada na legenda, usada para representar a extensão do fluxo fora da aplicação web.

Print 01 - Inbox de ações e tarefas

Ampliar

Leitura do print: A caixa de trabalho concentra pendências e filtros que direcionam a operação diaria.

Evidência capturada; desktop / 1440 x 980; origem: `/workflow`.

Print 02 - Processamento de aprovação

Ampliar

Leitura do print: O registro real aberto mostra a etapa que deve ser analisada e decidida pelo responsável.

Evidência capturada; desktop / 1440 x 980; origem: `/workflow/process/:responseId/:stepId`.

Print 03 - Editor de etapa

Ampliar

Leitura do print: A edição do passo reúne nome, descrição operacional, campos de referência, tipo de revisão e grupo responsável pelo tratamento da ocorrência.

Evidência capturada; desktop / 1440 x 980; origem: `/forms/:formId/workflow/steps/:stepId/edit`.

Print 04 - Condições e bifurcacoes

Ampliar

Leitura do print: A condição status = pending controla quando a rota aciona o agente, enquanto o mapa vivo deixa visível o percurso resultante até a saída.

Evidência capturada; desktop / 1440 x 980; origem: `WorkflowTransitionEditor`.

Print 05 - Timeline de decisões

Ampliar

Leitura do print: O histórico registra a sequência cronológica de início, aprovação, assunção da próxima etapa e criação de agendamento, com identificação das decisões tomadas.

Evidência capturada; desktop / 1440 x 980; origem: `WorkflowHistoryTab`.

Print 06 - KPIs de fluxo

Ampliar

Leitura do print: O painel consolida pendências, expirados, processados e tempo médio, além de acompanhar a atividade ao longo do tempo e o resumo de ações do workflow.

Evidência capturada; desktop / 1440 x 980; origem: `WorkflowStatsDashboard`.

Print 07 - Auditoria de notificações

Ampliar

Leitura do print: A auditoria apresenta o ponto de comprovacao dos disparos associados ao fluxo.

Evidência capturada; desktop / 1440 x 980; origem: `/notifications-audit`.

Print 08 - Notificação no WhatsApp

Ampliar

Leitura do print: A mensagem leva uma aprovação pendente diretamente ao celular, identifica a inspeção associada e oferece uma ação imediata para abrir a tarefa.

Imagem ilustrativa gerada com GPT Image a partir da marca oficial ZIINP; representa o conceito de entrega por WhatsApp, não uma captura real de conversa.

Print 09 - Etapa com agente IA

Ampliar

Leitura do print: A rota define quais dados do formulário entram no agente e visualiza o encadeamento completo entre origem, disparo, análise e saída do fluxo.

Evidência capturada; desktop / 1440 x 980; origem: `Workflow + agente`.

🏭 Indústria — Tratativa de não-conformidade

Resposta de auditoria gera 4 NCs. Z-Flow:

• Step 1: gerente da unidade aprova plano de ação (SLA 48h).
• Step 2: agente IA valida se o plano descreve causa-raiz, prazo e responsável.
• Step 3: execução em campo (formulário ligado).
• Step 4: validação por SST.
• Step 5: termo de fechamento assinado (Z-Sign).

Resultado: zero NCs perdidas no e-mail, auditoria ISO sem disputa.

💰 Backoffice — Reembolso com agente IA

Z-Flow:

• Step 1: agente IA lê NF anexa, valida CNPJ + valor + categoria.
• Step 2 (somente se valor > R$ 1.000): aprovação do diretor.
• Step 3: financeiro libera.
• Step 4: webhook empurra pra ERP gerar pagamento.

Resultado: reembolso de R$ 200 fechado em 4 horas, sem humano envolvido até o financeiro.

⚡ Telecom — Escalonamento de incidente

Cliente abre chamado por form público. Z-Flow:

• Step 1: triagem por IA → criticidade.
• Step 2 (se Crítico): notifica plantão por WhatsApp imediatamente.
• Step 3: técnico atende via Z-Schedule.
• Step 4: cliente assina aceite (Z-Sign).
• Z-Score pontua tempo de atendimento.

Resultado: SLA de 4h cumprido em 87% dos casos (era 52% antes).

🏥 Saúde — Autorização de procedimento

Z-Flow:

• Step 1: solicitação preenchida pelo médico.
• Step 2: validação documental por IA (resumo + checklist).
• Step 3: aprovação da operadora.
• Step 4: agendamento (Z-Schedule).
• Step 5: termo de consentimento (Z-Sign).

🛒 Varejo — Aprovação de promoção

Loja preenche solicitação. Z-Flow:

• aprovação do gerente regional (SLA 24h);
• validação de margem pela IA (query_sql no ERP);
• aprovação comercial;
• registro no sistema com webhook.

🏗️ Construção civil — Liberação de serviço crítico

Z-Flow:

• check-list de pré-operação;
• assinatura do líder (Z-Sign);
• bloqueio físico do equipamento até liberação;
• aprovação de SST.

📦 Logística — Devolução de mercadoria

Z-Flow:

• recepção registra avaria (Z-Field);
• IA classifica gravidade;
• aprovação de descarte ou retrabalho;
• webhook para ERP de estoque;
• nota de crédito gerada (Z-Sign).

🎓 RH — Onboarding de colaborador

Z-Flow:

• documentos enviados;
• IA valida (RG, CPF, comprovante de residência);
• contrato gerado (Z-Sign);
• treinamento atribuído (Z-Score);
• acesso provisionado via webhook em AD/LDAP.

Padrão 1 — Aprovação em duas etapas com escalonamento

[Resposta] → [Aprovação imediata (24h)]
              │
              ├── aprovado → [Execução]
              ├── reprovado → [Devolver para correção]
              └── não respondido em 24h → escala para líder
                       │
                       └── não respondido em 48h → escala para diretor

Padrão 2 — Triagem IA + revisão humana

[Resposta] → [Agente IA classifica]
              │
              ├── baixa criticidade → fecha automático
              ├── média → cria ação para gestor (sem urgência)
              └── alta → cria ação + notifica WhatsApp + abre via Z-Schedule

Padrão 3 — Aprovação paralela (múltiplos pareceres)

[Resposta] ──┬──► [Parecer Técnico]
             ├──► [Parecer Financeiro]
             └──► [Parecer Jurídico]
                    │
                    ▼
                 [Consolidação] → Decisão

Padrão 4 — Pipeline com retry

[Resposta] → [Execução]
              │
              ├── sucesso → [Validação] → [Fechamento + Z-Sign]
              └── falha → [Devolver] → retry até 3×
                                       │
                                       └── 3× falhou → escalar diretor

Padrão 5 — Bifurcação por valor

[Resposta]
   │
   ├── valor < R$ 1.000  → [Aprovação simples]
   ├── R$ 1.000 – 10.000 → [Aprovação + 2ª assinatura]
   └── > R$ 10.000        → [Comitê + auditoria]

• Integrar com Z-Schedule para que etapas de campo já criem visita.
• Substituir 1 etapa humana por agente IA para validar a fluência.
• Conectar ao Z-Sign em etapas que precisam formalizar a decisão.
• Cruzar com Z-Score — aprovações no prazo viram pontuação.