claude-plugins/wordpress/skills/jetengine/SKILL.md

---
name: jetengine
description: Desenvolvimento com JetEngine (Crocoblock). Cobre CPT, CCT, Meta Boxes, Taxonomias, Relations, Query Builder, Listing Grid/Map, Dynamic Content, Dynamic Tags, Macros, Profile Builder, REST API e automação headless.
---

# /jetengine — JetEngine Development

JetEngine é o núcleo do ecossistema Crocoblock: cria CPT, CCT, Meta Boxes, Relations, Queries e Listings com conteúdo dinâmico para Elementor.

## CPT vs CCT — Escolha Crítica

| | Custom Post Type (CPT) | Custom Content Type (CCT) |
|--|----------------------|--------------------------|
| **Storage** | `wp_posts` + `wp_postmeta` | Tabela SQL própria `wp_jet_cct_{slug}` |
| **Performance** | Lenta em queries complexas | Muito rápida (colunas reais) |
| **Compatibilidade** | Total WP ecosystem | Limitada (sem taxonomies nativas) |
| **REST API** | `/wp-json/wp/v2/{slug}` | `/wp-json/jet-cct/{slug}` |
| **Automação** | `wp_insert_post()` | `CCT_Data_Handler` ou SQL directo |
| **Usar quando** | Conteúdo editorial, SEO, plugins WP | Alta performance, CRUD automatizado, dashboards |

**Regra prática:** CPT para conteúdo público/SEO; CCT para dados internos, integrações e alta escala.

## Criar CPT

```
JetEngine > Post Types > Add New
├── Slug (único, sem espaços, lowercase)
├── Labels (Singular / Plural)
├── Suporte: title, editor, thumbnail, excerpt, custom-fields
├── REST API: Activar para integração externa
├── Archive: Activar se precisar de página de listagem
└── Admin Columns: Mostrar meta fields na tabela admin
```

## Meta Boxes e Campos

### Tipos de Campos

| Tipo | Uso |
|------|-----|
| `text` | Texto simples |
| `textarea` | Texto longo |
| `wysiwyg` | Editor rich text |
| `number` | Valor numérico |
| `select` | Dropdown de opções |
| `checkbox` | Verdadeiro/falso |
| `checkbox-list` | Múltipla selecção |
| `radio` | Opção única |
| `date` | Data (timestamp) |
| `media` | Upload de ficheiro/imagem |
| `gallery` | Múltiplas imagens |
| `repeater` | Campo repetível (sub-campos) |
| `posts` | Relação simples (seleccionar posts) |
| `color-picker` | Cor HEX |
| `map` | Coordenadas geográficas |
| `html` | HTML estático (apenas display) |

### Repeater — Estrutura

```
Repeater Field "galeria_servicos":
  ├── sub-campo: imagem (media)
  ├── sub-campo: titulo (text)
  └── sub-campo: descricao (textarea)

Aceder em PHP:
$items = get_post_meta($post_id, 'galeria_servicos', true);
foreach ($items as $item) { ... }
```

## Relations

### Tipos de Relação

| Tipo | Exemplo |
|------|---------|
| One-to-Many | 1 Empresa → N Colaboradores |
| Many-to-Many | N Projectos ↔ N Tags custom |
| Self-relation | Artigo relacionado com outros artigos |
| User-to-Post | Utilizador → N Reservas |

### Tabela SQL das Relações

```sql
-- wp_jet_rel_default
-- parent_object_id | child_object_id | rel_id (hash da relação)

-- Ler todos os filhos de um pai
SELECT child_object_id
FROM wp_jet_rel_default
WHERE parent_object_id = 123
AND rel_id = 'relacao_empresa_colaboradores';

-- Ler o pai a partir de um filho
SELECT parent_object_id
FROM wp_jet_rel_default
WHERE child_object_id = 456
AND rel_id = 'relacao_empresa_colaboradores';
```

**Importante:** Nunca editar esta tabela directamente via SQL para criar relações — usar a API PHP do JetEngine (ver `references/automation.md`).

## Query Builder

Substitui o `WP_Query` com interface visual. Ligar ao Listing Grid.

### Tipos de Query

| Tipo | Usa |
|------|-----|
| Posts | CPT, posts, páginas |
| Terms | Taxonomias |
| Users | Utilizadores WP |
| Custom Content Type | Tabelas CCT |
| REST API | Endpoint externo |

### Configurar Query Posts

```
JetEngine > Query Builder > Add New
├── Query Type: Posts
├── Post Type: [seleccionar CPT]
├── Order By: date / meta_value / rand / menu_order
├── Meta Query: adicionar condições de meta fields
├── Tax Query: filtrar por taxonomia
└── Author: específico ou current user
```

### Usar no Listing Grid

```
Elemento Elementor: Listing Grid
├── Listing Item: [seleccionar Listing Template]
├── Use Custom Query: YES → seleccionar Query criado acima
├── Items per page: N
└── Pagination: Activar se necessário
```

## Listing Grid e Listing Template

### Criar Listing Template

```
JetEngine > Listings > Add New
├── Template Type: Default / Popup
├── Content From: Posts / CCT / User / Term
└── Editar com Elementor → usar Dynamic Tags
```

### Dynamic Tags no Listing Template

```
Post Title         → {{ post_title }}
Field de Meta      → Meta Field → seleccionar nome do campo
Imagem             → Featured Image → meta field media
Link               → Post URL / Custom Field URL
Relação            → Relation Field
```

### Listing Map

```
JetEngine > Listings > Add New > Template Type: Map
├── Configurar campo de coordenadas (tipo: map no meta box)
├── Google Maps API Key: WP Admin > JetEngine > Settings
└── Ligar ao Query Builder
```

## Dynamic Content e Macros

### Macros Comuns

```
%current_user_id%          # ID do utilizador logado
%current_post_id%          # ID do post actual
%queried_object_id%        # ID do objecto em arquivo/single
%request_field|name%       # Parâmetro URL (?name=valor)
%current_meta|field_name%  # Meta field do post actual
%user_meta|field_name%     # Meta field do utilizador logado
```

### Usar Macros em Widgets Elementor

```
Textos: escrever macro directamente no campo de texto
Links: usar em URL field
Queries: usar em Meta Query → Valor = macro
```

### Profile Builder

```
JetEngine > Profile Builder > Add New
├── Criar páginas de conta (Dashboard, Submissões, etc.)
├── Cada página = Elementor Template
├── Acesso: utilizadores logados, por role, por condição
└── Menu de Profile: widget JetEngine Profile Menu
```

## Dify KB — Consultar Antes de Implementar

```javascript
// Dataset Crocoblock (JetEngine incluído)
mcp__dify-kb__dify_kb_retrieve_segments({
  dataset_id: "bdf85c26-1824-4021-92d1-be20501b35ac",
  query: "[funcionalidade JetEngine]"
})
```

## Troubleshooting

| Problema | Causa | Solução |
|----------|-------|---------|
| Listing não mostra resultados | Query sem posts ou condição errada | Debug Query: activar `WP_DEBUG` e verificar |
| Dynamic Tag retorna vazio | Campo meta não preenchido ou nome errado | Verificar key do meta field em JetEngine > Meta Boxes |
| Relações não aparecem | rel_id errado ou sem items relacionados | Verificar nome da relação em JetEngine > Relations |
| CCT não aparece no REST | REST API não activada | JetEngine > Content Types > Edit > Enable REST API |
| Filtros não funcionam | Listing ID errado no filtro | JetEngine Listing Grid > copiar ID do widget |

## Bridge Plugin — Deploy para Integração n8n

Para integração headless com n8n ou agentes IA, fazer deploy do MU plugin incluído:

```bash
PHP="/opt/alt/php-fpm83/usr/bin/php"
WP="$PHP /usr/local/bin/wp --allow-root --path=/home/USER/public_html"

# Copiar bridge plugin para mu-plugins (via SSH)
# O ficheiro está em: assets/descomplicar-jet-bridge.php (nesta skill)
scp descomplicar-jet-bridge.php server.descomplicar.pt:/home/USER/public_html/wp-content/mu-plugins/

# Verificar que está activo (MU plugins carregam automaticamente)
$WP plugin list --skip-plugins --skip-themes  # MU plugins não aparecem aqui — normal
```

**Endpoint exposto:** `POST /wp-json/descomplicar/v1/manage`

**Acções disponíveis:**
| Acção | Descrição |
|-------|-----------|
| `create_cct_item` | Criar item num CCT |
| `update_cct_item` | Actualizar item (`_ID` em item_data) |
| `get_cct_item` | Ler item por ID |
| `delete_cct_item` | Eliminar item |
| `manage_relation` | Criar/remover relação (connect: true/false) |

```bash
# Testar endpoint (exemplo: criar fatura)
curl -X POST https://site.pt/wp-json/descomplicar/v1/manage \
  -H "Authorization: Basic $(echo -n 'user:app-password' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create_cct_item",
    "cct_slug": "faturas",
    "item_data": { "titulo": "Fatura #001", "valor": 500 }
  }'
```

## JetEngine MCP Server (v3.8.0+)

A partir da versão 3.8.0, o JetEngine tem **MCP Server nativo**:

```
WP Admin > JetEngine > AI Command Center > Enable MCP Server
→ Agentes IA podem inspecionar e criar CPTs/CCTs/Relations via linguagem natural
→ Claude consegue ler o schema completo e instanciar estruturas directamente
```

## Referências Adicionais

- **`assets/descomplicar-jet-bridge.php`** — MU Plugin pronto a deployar: CRUD CCT + Relations via REST API
- **`references/automation.md`** — BD completa (CCT, Relations meta, Custom Meta Storage), WP-CLI batch, PHP hooks, REST API avançada (store_items_type, filtros CCT), cache e guardrails
- **`references/query-listings.md`** — Query Builder avançado, Listing Map, paginação, ordenação dinâmica
- **`references/dynamic-content.md`** — Dynamic Tags, Profile Builder, Macros, Conditional Fields

---

**Versão**: 1.1.0 | **Autor**: Descomplicar® | **Data**: 18-02-2026