claude-plugins/wordpress/skills/crocoblock/references/patterns.md

# Crocoblock — Padrões de Integração Avançados

## Padrão 1: Directório com Filtros + Mapa

**Plugins:** JetEngine + JetSmartFilters + JetElements (Maps)

```
Arquitectura:
CPT "Negócio" (com meta: morada, coordenadas, categoria, horário)
    ↓
Query Builder (posts, post_type=negocio)
    ↓
┌────────────────┬──────────────────┐
│  Listing Grid  │   Listing Map    │
│  (cards)       │   (pins)         │
└────────────────┴──────────────────┘
         ↑ sincronizados ↑
    JetSmartFilters:
    - Categoria (checkbox, taxonomy)
    - Localização (select, meta)
    - Pesquisa (search text)
    - Raio de distância (range, meta GPS)
```

**Configuração de sincronização:**
```
Listing Map > Settings:
├── Synchronize with Listing Grid: YES
└── Listing Grid Selector: ID do widget Listing Grid

JetSmartFilters > Apply For:
└── Seleccionar ID do Listing Grid
    (o mapa segue automaticamente via sincronização)
```

---

## Padrão 2: Marketplace / Multi-vendor Simples

**Plugins:** JetEngine + JetFormBuilder + JetSmartFilters + Profile Builder

```
Fluxo do vendedor:
1. Registo (JetFormBuilder → Register User)
2. Login
3. Dashboard vendedor (Profile Builder)
4. Criar produto (JetFormBuilder → Create Post no CPT)
5. Produto aparece no catálogo (Listing Grid filtrado por author)

Fluxo do comprador:
1. Catálogo com filtros (JetSmartFilters)
2. Contactar vendedor (JetFormBuilder → Email ao author)
3. Ver perfil vendedor (Profile Builder page pública)
```

**Relations necessárias:**
```
User → N Produtos (one-to-many)
User → N Favoritos (many-to-many)
Produto → N Reviews (one-to-many, via JetReviews)
```

---

## Padrão 3: Portal de Imobiliário

**Plugins:** JetEngine + JetSmartFilters + JetWooBuilder (opcional) + JetBooking

```
CPT: Imóvel
Meta Boxes:
├── Preço (number)
├── Área m² (number)
├── Tipologia (select: T0/T1/T2/T3/T4+)
├── Tipo (select: venda/arrendamento)
├── Localização (taxonomy: Distrito → Concelho → Freguesia)
├── Coordenadas (map)
├── Galeria (gallery)
├── Características (checkbox-list: piscina, garagem, jardim...)
└── Agente responsável (posts: CPT Agente)

Query Builder:
├── Ordenação: data / preço / área
└── Meta Query: tipo = "arrendamento" (para página específica)

JetSmartFilters:
├── Range: Preço min-max
├── Range: Área min-max
├── Checkboxes: Tipologia
├── Select Hierarchical: Localização
├── Checkboxes: Características
└── Sorting: Preço ASC/DESC, Mais recentes
```

---

## Padrão 4: E-learning / Cursos

**Plugins:** JetEngine + JetFormBuilder + Profile Builder

```
CPTs:
├── Curso (conteúdo, preço, dutor)
├── Lição (sub-item do curso)
└── Avaliação (questionário)

Relations:
├── Curso → N Lições (one-to-many)
├── Utilizador → N Cursos Inscritos (many-to-many)
└── Utilizador → N Avaliações (one-to-many)

Profile Builder Pages:
├── Meus Cursos (Query: cursos onde utilizador está inscrito)
├── Continuar Lição (última lição acedida)
└── Certificados (download PDF após conclusão)

Automatização:
JetFormBuilder → compra → Inscrever no curso → Criar relação User↔Curso
```

---

## Padrão 5: Multi-Relation (Relações Aninhadas)

```
Exemplo: Agência → Clientes → Projectos → Tarefas

Relations JetEngine:
├── agencia_clientes: Agência (1) → Clientes (N)
├── cliente_projectos: Cliente (1) → Projectos (N)
└── projecto_tarefas: Projecto (1) → Tarefas (N)

No Listing Template de Agência:
├── Lista de Clientes (Relation Field Widget)
│   └── Dentro de cada Cliente: Lista de Projectos (nested listing)
│       └── Dentro de cada Projecto: Contador de Tarefas

Nota: Listings aninhados afectam performance.
      Limitar a 2 níveis de profundidade.
      Para listas longas, usar AJAX/JetSmartFilters paginado.
```

---

## Padrão 6: User-Generated Content (UGC)

**Plugins:** JetEngine + JetFormBuilder + Profile Builder + JetSmartFilters

```
Fluxo:
1. Utilizador logado → Dashboard (Profile Builder)
2. Formulário "Submeter Conteúdo" (JetFormBuilder)
   → Action: Create Post no CPT "Aviso" com status "pending"
   → Action: Email de notificação ao admin
3. Admin aprova → post_status = publish
4. Conteúdo aparece no listing público

Queries do Dashboard:
├── "Os meus avisos" → Query: author = %current_user_id% + status = any
└── "Aprovados" → Query: author = %current_user_id% + status = publish

Moderação rápida:
├── Admin lista pendentes com Listing Grid
└── JetFormBuilder inline para aprovar/rejeitar (Update Post Status)
```

---

## Padrão 7: JetBooking + WooCommerce + JetEngine

```
Fluxo de Reserva:
1. Página de serviço (CPT Serviço com meta JetEngine)
2. Calendário JetBooking (disponibilidade em tempo real)
3. Seleccionar datas → Form de reserva (JetFormBuilder ou JetBooking nativo)
4. Checkout WooCommerce (JetBooking cria produto temporário)
5. Pagamento → Reserva confirmada
6. Email de confirmação (JetBooking + SMTP)
7. Dashboard cliente (Profile Builder → Minhas Reservas)

Automatização n8n:
JetBooking webhook → n8n → Google Calendar → SMS (via Twilio)
```

---

## Anti-Padrões (Evitar)

### Demasiados JetPlugins Activos

```
Problema: Cada JetPlugin adiciona JS/CSS extra
Solução: Desactivar plugins não usados em cada site específico
Ferramenta: JetPlugins > Settings > Disable components não usados
```

### Listings Sem Paginação em Catálogos Grandes

```
Problema: Listing Grid sem paginação carrega todos os posts → PHP timeout
Solução: Sempre activar paginação ou Load More em listas >20 items
```

### JetSmartFilters Sem AJAX

```
Problema: URL-based filters recarregam a página inteira
Uso correcto: AJAX filters para UX fluida; URL-based apenas para SEO
```

### Meta Boxes em CCT Desnecessariamente

```
CCT não suporta taxonomies nativas, comentários, revisões.
Usar CPT quando precisar dessas funcionalidades WordPress.
```

---

*Crocoblock Patterns | Descomplicar® | 18-02-2026*