# 5. Uso do Modo Editor

Use o **Modo Editor** para ajustes “cirúrgicos” no que a IA gerou. Use o **Chat AI** para mudanças maiores, com várias telas e regras.

{% hint style="info" %}
Se você quer a referência completa (tipos de campo, eventos e estrutura), veja também [**Modo Editor**](https://docs.madrix.dev/br/documentacao/modo-editor).
{% endhint %}

### Pré-requisitos

* Você tem permissão de edição no projeto.
* Seu app abre no **Preview**.

### Backend (exemplo final)

Objetivo do exemplo: um módulo **Gestor de Tarefas** com entidade **Tarefa**, campos comuns, relacionamento e regra de status.

{% stepper %}
{% step %}

### 1) Ajuste o módulo e menus

No Editor, abra **Módulos** e edite (ou crie) um módulo:

* **Nome do módulo:** `Tarefas`
* **Ícone:** escolha um que facilite identificar o card.
* **Display Name Translations:**
  * `pt-BR`: `Tarefas`

Crie um menu dentro do módulo:

* **Nome:** `Minhas tarefas`
* **URL Path:** `/tarefas`

{% hint style="warning" %}
Evite trocar **URL Path** depois. Isso quebra links e favoritos.
{% endhint %}

**Resultado esperado:** o card do módulo aparece na Home. O menu navega.
{% endstep %}

{% step %}

### 2) Crie/ajuste o componente (entidade)

Crie um **Componente**:

* **Nome (lowercase):** `tarefa`
* **Módulo:** `Tarefas`
* **Display Name Translations:**
  * `pt-BR`: `Tarefa`

Ao salvar, use estas opções (quando aparecerem):

* **Create frontend files:** sim (se você quer scaffold de telas)
* **Create menu automatically:** opcional (se você já criou o menu manualmente)

**Resultado esperado:** o componente existe e já tem estrutura de UI (se marcado).
{% endstep %}

{% step %}

### 3) Modele campos (com exemplos prontos)

Dentro de `tarefa`, crie os campos abaixo:

* `titulo`
  * **Tipo:** `String`
  * **Obrigatório:** sim
* `descricao`
  * **Tipo:** `Text`
* `status`
  * **Tipo:** `Picklist`
  * **Opções:** `Novo | Em Progresso | Revisão | Concluído`
  * **Obrigatório:** sim
* `prioridade`
  * **Tipo:** `Picklist`
  * **Opções:** `Baixa | Média | Alta`
* `dataVencimento`
  * **Tipo:** `Date`
* `atribuidoA`
  * **Tipo:** `User`
* `anexos`
  * **Tipo:** `Attachments`

Dica rápida:

* Se a lista ficar “apertada”, ajuste a **Largura na grid** por campo.

**Resultado esperado:** o form de Tarefa tem todos os campos. A lista exibe os principais.
{% endstep %}

{% step %}

### 4) Adicione um relacionamento (1-N) com Projeto

Crie um segundo componente:

* **Nome:** `projeto`
* Campos mínimos:
  * `nome` (`String`, obrigatório, único)

Agora volte para `tarefa` e crie um campo:

* `projeto`
  * **Tipo:** `Component`
  * **Componente relacionado:** `projeto`
  * **Cardinalidade:** 1 (uma tarefa pertence a um projeto)
  * **Display Field:** `nome`

{% hint style="danger" %}
Só marque `deleteCascade` se você aceitar apagar dados em massa.
{% endhint %}

**Resultado esperado:** no form de Tarefa, você seleciona um Projeto.
{% endstep %}

{% step %}

### 5) Crie uma consulta reaproveitável (opcional, mas útil)

Em `tarefa`, crie uma **Consulta** chamada `Atrasadas`:

* Filtro: `dataVencimento` menor que hoje
* E `status` diferente de `Concluído`

**Resultado esperado:** você reaproveita esse filtro em listas e relatórios.
{% endstep %}

{% step %}

### 6) Regra de negócio via Script (sem “código” no frontend)

Regra do exemplo: **não permitir voltar status**.

Implemente como script no evento do componente `tarefa`:

* Evento recomendado: **Before Update**
* Validação:
  * Permitir apenas avanço: `Novo → Em Progresso → Revisão → Concluído`
  * Bloquear qualquer regressão
* Mensagem de erro clara:
  * “Não é permitido voltar o status.”

Teste no Preview:

* Crie uma tarefa em `Novo`
* Avance para `Em Progresso`
* Tente voltar para `Novo` e valide o bloqueio

**Resultado esperado:** a regra funciona no backend. Vale para UI e API.
{% endstep %}
{% endstepper %}

### Frontend (scaffold gerado)

O scaffold só existe se você marcou **Create frontend files** ao salvar o componente.

#### O que você ganha (resumo)

* Rotas base do app.
* Páginas protegidas por módulo.
* Forms e listas gerados por componente.
* Tema e estilos base.

<details>

<summary>Onde normalmente ficam as telas do seu módulo</summary>

Procure por uma estrutura como:

* `pages/protected/`
  * `{modulo}/` (ex: `tarefas/`)
    * telas de listar, criar e editar

</details>

#### O que editar vs o que evitar

Edite com segurança:

* Páginas do módulo (telas).
* Componentes de UI do seu app.
* Tema (cores, tipografia).

Evite editar:

* Arquivos marcados como **locked** (gerenciados pela plataforma).

#### Checklist de validação (Preview)

* [ ] Card do módulo aparece na Home.
* [ ] Menu abre a listagem.
* [ ] Criar/editar Tarefa funciona.
* [ ] Picklists têm as opções corretas.
* [ ] Relacionamento com Projeto seleciona e salva.
* [ ] Regra de status bloqueia regressão.

{% hint style="info" %}
Se o objetivo é mexer só em tema e textos, isso costuma ser mais rápido em **Configurações do Projeto**.
{% endhint %}