# 🔄 Sistema de Workflow (Human-Led) — Manual Técnico

O Sistema de Workflow do Fastapp permite a modelagem, visualização e monitoramento de processos manuais conduzidos por humanos. Ele é integrado ao Core para permitir que a interface se adapte ao estado atual de cada registro transacional.

---

## 🧬 1. Anatomia do Metadado (DNA)

Os fluxos de trabalho são definidos no nível de **App** através do array `workflows`.

### Interface: `WorkflowDefinition`
Localizada em `app/fastapp/manifest.ts`.

- **id**: Identificador único do fluxo (slug).
- **label**: Nome de exibição.
- **description**: Detalhamento do propósito do fluxo.
- **icon**: Ícone do PrimeIcons (pi pi-...).
- **steps**: Coleção de etapas que compõem o fluxo.

### Interface: `WorkflowStep`
Define cada "estação" de trabalho no fluxo:

- **id**: ID do passo (ex: `separacao_estoque`).
- **label**: Nome da etapa (ex: "Separação").
- **object**: Nome do objeto transacional governado (ex: `pedido`).
- **tone**: Acento visual para o nó no canvas (`emerald`, `cyan`, `amber`, `violet`).
- **pool_workers**: Métrica visual de capacidade (ex: `12` workers operando nesta fase).
- **position**: Coordenadas `{ x, y }` para o posicionamento no Vue Flow.
- **ui_config**: Configuração de interface para esta etapa.
    - **view_mode**: Modo de visualização (`form`, `list`, `kanban`).
    - **visible_fields**: Array de campos do objeto que devem ser exibidos/editáveis nesta etapa.
    - **action_label**: Nome do botão de transição (ex: "Confirmar Entrega").
- **next_step**: ID da próxima etapa (ou array de IDs para ramificações).

---

## 🎨 2. Visualização e Studio

A visualização ocorre na página `/fastapp/workflows`.

### Tecnologias Utilizadas
- **Vue Flow**: Biblioteca base para o canvas de grafos.
- **Componentes Customizados**:
    - `wf-step`: Nó customizado que renderiza os metadados da etapa em um card premium com blur e tons dinâmicos.
- **Tone Accents**: Sistema de cores consistente para estados do fluxo.

### Comportamento de Navegação
- O Studio detecta o `app_id` na URL e carrega os fluxos correspondentes do `systemStore`.
- A sidebar permite trocar entre fluxos da mesma aplicação.
- O canvas é interativo, permitindo zoom e movimentação (embora a persistência da posição dependa de um novo Snapshot).

---

## 🔄 3. Governança FADAP

O Sistema de Workflow segue rigorosamente o Protocolo FADAP v3:

1.  **Edição**: As alterações ocorrem via `PATCH /api/app/[id]`.
2.  **Snapshot**: O estado dos fluxos é consolidado no `static-manifest.ts`.
3.  **Persistência**: Os dados residem na coluna `workflows` (JSONB) da tabela `app`.

---

## 🛠️ 4. Como Adicionar um Workflow

### Exemplo de Payload via Meta-API (App ID 19)

```json
{
  "workflows": [
    {
      "id": "venda_filtros",
      "label": "Venda de Filtros",
      "steps": [
        {
          "id": "lead",
          "label": "Qualificação",
          "object": "cliente",
          "tone": "cyan",
          "position": { "x": 10, "y": 10 },
          "ui_config": {
             "view_mode": "form",
             "visible_fields": ["nome", "segmento"],
             "action_label": "Validar Lead"
          },
          "next_step": "proposta"
        }
      ]
    }
  ]
}
```

---

## 🚀 5. Roadmap e Integrações Futuras

- **Dynamic Field Filtering**: O `CoreDynamicForm` utilizará o array `visible_fields` do passo atual do workflow para esconder campos irrelevantes automaticamente.
- **Workflow State Management**: Uma propriedade no objeto (ex: `status`) marcada com `workflow_state: true` servirá de ponte para mover os registros entre as etapas do Studio.
- **Trigger Actions**: Execução de fluxos externos (n8n, webhook) ao completar uma etapa.

---
*Fastapp Engine — Automação de Processos Human-Led.*