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

---
name: jetengine
description: >
  JetEngine development: Custom Post Types (CPT), Custom Content Types (CCT), Meta Boxes, Taxonomies,
  Relations, Query Builder, Listing Grid, Listing Map, Dynamic Content, Dynamic Tags, Macros, Profile Builder,
  REST API, and headless/programmatic automation for AI agents and n8n integration.
  This skill should be used when the user asks about "jetengine", "jet engine", "custom post type jetengine",
  "meta box jetengine", "relations jetengine", "query builder jetengine", "listing grid", "listing map",
  "jetengine dynamic content", "jetengine macros", "profile builder jetengine", "cct jetengine",
  "custom content type", "jetengine cct", "jetengine rest api", "jetengine n8n", "jetengine sql",
  "jetengine automação", "jetengine headless", "wp_jet_rel_default", "wp_jet_cct", "jetengine relations",
  "conteúdo dinâmico elementor jetengine", "jetengine filtros", "jetengine repeater".
author: Descomplicar® Crescimento Digital
version: 1.0.0
user_invocable: true
tags: [wordpress, elementor, crocoblock, jetengine, cpt, cct, listings, dynamic-content]
allowed-tools: Read, Write, Edit, Bash, mcp__ssh-unified__ssh_execute, mcp__notebooklm__notebook_query, mcp__dify-kb__dify_kb_retrieve_segments
category: dev
quality_score: 85
updated: "2026-02-18T00:00:00Z"
---

# /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