# DaazMarkets — Visão PRO & Futuro

> Documento único e focado no futuro do plugin.
> Data: Março 2026 | Versão actual: FREE 1.x

---

## Diagnóstico Actual (FREE) — O Que Corrigir Antes de Tudo

### Por que a página carrega lentamente?

| Causa | Impacto |
|-------|---------|
| **Todas as chamadas API são síncronas** — feitas durante o render da página, bloqueiam até resposta | ⛔ Crítico |
| **1 HTTP request por símbolo** — sem batching (excepto CoinGecko) | ⛔ Crítico |
| **Sem cron/background update** — zero `wp_schedule_event()` no código inteiro | ⛔ Crítico |
| **Fallback em cascata** — se Finnhub falha, tenta EODHD, TwelveData, AlphaVantage... tudo síncrono | 🔴 Alto |
| Cache OK (transients 5-30 min) mas só ajuda após a 1ª carga | 🟡 Médio |

**Resultado:** Uma página com 3-4 shortcodes pode fazer **30-57 HTTP requests** na primeira carga → **30-90 segundos** de espera.

### Por que os preços aparecem a zero?

| Causa | Frequência |
|-------|------------|
| **Rate limiting (429)** — todos os shortcodes batem no mesmo provider ao mesmo tempo | ~40% |
| **Sem "last known good"** — quando API falha, mostra erro em vez de último preço bom | ~30% |
| **Símbolos spot vs futures** — Gold/Silver/Oil têm dual-format, provider certo rejeitado | ~20% |
| **Parsing incompleto** — cada provider devolve JSON diferente | ~10% |

---

## A Solução: Duas Versões PRO Simples

### Arquitectura em Camadas

```
┌─────────────────────────────────────────────────────┐
│                   FRONTEND (igual)                  │
│         Shortcodes + Widgets + Dark Mode            │
├─────────────────────────────────────────────────────┤
│              PRO STANDARD (€29)                     │
│   Background Cron + Last-Good Cache + Charts        │
│   Centralização APIs + Dark Mode + Alertas Email    │
├─────────────────────────────────────────────────────┤
│              PRO PREMIUM (€59)                      │
│   Tudo do Standard + Real-time AJAX polling         │
│   Portfolio Tracker + CSV Export + White Label       │
├─────────────────────────────────────────────────────┤
│                 FREE (base)                         │
│   Shortcodes básicos + Cache 5-30 min               │
│   Providers manuais por categoria                   │
└─────────────────────────────────────────────────────┘
```

---

## PRO STANDARD — "Low Cost" (€29 one-time)

> **Objectivo:** Resolver os 2 problemas reais (lentidão + zeros) sem custos de infraestrutura.
> **Custo de operação:** €0/mês (tudo gratuito).

### O que inclui (6 funcionalidades concretas):

#### 1. Background Cron Update (~2 dias de trabalho)
Em vez de buscar dados ao carregar a página, um WP-Cron corre a cada X minutos e pré-carrega todos os transients.

```
ANTES (FREE):                          DEPOIS (PRO):
Visitante abre página                  WP-Cron corre a cada 5 min
  → 30-57 HTTP calls síncronos           → Faz os HTTP calls em background
  → Página bloqueia 30-90 seg            → Guarda em transients
  → Visitante espera                    Visitante abre página
                                          → Lê transients (0 HTTP calls)
                                          → Página carrega em <1 segundo
```

**Impacto:** Elimina 100% da lentidão. É a funcionalidade mais importante.

#### 2. Last-Known-Good Cache (~0.5 dias)
Quando uma API falha (429, timeout, erro), em vez de mostrar zero/erro, mostra o último preço válido com indicador `(stale)`.

```php
// Lógica simples:
$fresh = fetch_from_api( $symbol );
if ( ! is_wp_error( $fresh ) ) {
    set_transient( 'lastgood_' . $symbol, $fresh, 0 ); // sem expiração
    return $fresh;
}
// API falhou → retorna último bom
$stale = get_transient( 'lastgood_' . $symbol );
if ( $stale ) {
    $stale['_stale'] = true;
    return $stale;
}
```

**Impacto:** Elimina 70% dos zeros. Preço antigo > preço zero.

#### 3. Centralização de API Keys (~1 dia)
Uma página única no admin: **Settings → API Keys**.
O utilizador mete cada chave uma vez e o plugin usa-a em todas as categorias automaticamente.

```
ANTES (FREE):                          DEPOIS (PRO):
Settings → Markets → EODHD key         Settings → API Keys
Settings → Markets → Finnhub key         EODHD: [__________]
Settings → ETFs → EODHD key              Finnhub: [__________]
Settings → ETFs → Finnhub key            TwelveData: [__________]
Settings → Miners → Finnhub key          AlphaVantage: [__________]
Settings → Forex → TwelveData key        CoinGecko: [__________]
  (6 sítios para a mesma chave!)          GoldAPI: [__________]
                                          (1 sítio, usa em tudo)
```

**Como funciona:** A tabela centralizada guarda em `daaz_gmp_settings['api_keys']`. A função `daaz_gmp_get_category_api_key()` já existente passa a verificar primeiro este campo centralizado, mantendo retrocompatibilidade com as chaves individuais.

#### 4. Charts Avançados (~1.5 dias)
- Chart.js já incluído no plugin (MIT, custo zero)
- Adicionar: candlestick (via plugin financeiro do Chart.js), linhas com 2+ assets, zoom
- Chart Builder visual no admin (gera shortcode pronto a copiar)

#### 5. Dark Mode (~0.5 dias)
CSS toggle claro/escuro. Shortcode `[daaz_gmp_theme_toggle]` que o utilizador coloca onde quiser.

#### 6. Alertas por Email (~1 dia)
- Regra simples: "Bitcoin > $100.000 → envia email"
- Usa `wp_mail()` nativo do WordPress (custo zero)
- Verificação via WP-Cron (mesmo cron do ponto 1)
- Limite: 5 alertas na versão Standard

**Timeline total PRO Standard: ~6-7 dias de trabalho**

---

## PRO PREMIUM — "Full" (€59 one-time)

> **Objectivo:** Funcionalidades avançadas para traders e sites profissionais.
> **Custo de operação:** €0/mês.

### Tudo do Standard + 5 funcionalidades extra:

#### 7. Real-Time AJAX Polling (~1.5 dias)
Preços actualizam-se na página **sem refresh** (AJAX a cada 30-60 seg). Indicador LED verde "LIVE" nos widgets.

```javascript
// Frontend: intervalo configurável
setInterval(function() {
    fetch('/wp-json/daaz-gmp/v1/prices?symbols=BTC,ETH,AAPL')
    .then(r => r.json())
    .then(data => updatePricesInDOM(data));
}, 30000); // 30 segundos
```

#### 8. Portfolio Tracker (~2 dias)
- Adicionar holdings: "Comprei 0.5 BTC a $42.000"
- Dashboard com P&L em tempo real
- Suporte multi-portfólio (crypto, stocks, commodities separados)
- Dados guardados no `wp_usermeta` (sem tabelas custom)

#### 9. CSV/JSON Export (~0.5 dias)
- Exportar dados de qualquer shortcode
- Endpoint REST: `GET /wp-json/daaz-gmp/v1/export?category=markets&format=csv`
- Botão "Download CSV" nos widgets PRO

#### 10. White Label (~0.5 dias)
- Remover "Powered by DaazMarkets" de todos os widgets
- Opção para texto/logo customizado
- Campo nas Settings: "Brand Name" + "Brand URL"

#### 11. Alertas Ilimitados + Webhook (~1 dia)
- Sem limite de alertas (vs 5 no Standard)
- Webhook: quando alerta dispara, POST para URL configurável
- Permite integração com Zapier, Make, Telegram bots, Discord

**Timeline total PRO Premium: +5-6 dias sobre o Standard**

---

## Tabela Comparativa Final

| Funcionalidade | FREE | PRO Standard (€29) | PRO Premium (€59) |
|---|:---:|:---:|:---:|
| Shortcodes (todos) | ✅ | ✅ | ✅ |
| Widgets | ✅ | ✅ | ✅ |
| Cache (transients) | ✅ | ✅ | ✅ |
| Multi-provider fallback | ✅ | ✅ | ✅ |
| API keys por categoria | ✅ | ✅ | ✅ |
| **Background Cron** (página rápida) | ❌ | ✅ | ✅ |
| **Last-Known-Good** (sem zeros) | ❌ | ✅ | ✅ |
| **API Keys Centralizadas** | ❌ | ✅ | ✅ |
| **Charts Avançados** | Básico | Candlestick + Multi-asset | Candlestick + Multi-asset |
| **Dark Mode** | ❌ | ✅ | ✅ |
| **Alertas Email** | ❌ | 5 alertas | Ilimitados |
| **Real-Time AJAX** | ❌ | ❌ | ✅ (30-60s polling) |
| **Portfolio Tracker** | ❌ | ❌ | ✅ |
| **CSV Export** | ❌ | ❌ | ✅ |
| **White Label** | ❌ | ❌ | ✅ |
| **Webhooks** | ❌ | ❌ | ✅ |
| Suporte | Fórum WP.org | Email prioritário | Email prioritário |

---

## APIs Gratuitas vs Pagas — Estratégia Realista

### APIs Gratuitas (suficientes para 90% dos utilizadores):

| API | Limite Free | Melhor Para | Qualidade |
|-----|-------------|-------------|-----------|
| **CoinGecko** | 10-30 req/min | Crypto + Treasuries | ⭐⭐⭐⭐⭐ |
| **Finnhub** | 60 req/min | Stocks, ETFs | ⭐⭐⭐⭐ |
| **TwelveData** | 800 req/dia | Forex, Stocks, Commodities | ⭐⭐⭐⭐ |
| **AlphaVantage** | 25 req/dia | Stocks (backup) | ⭐⭐⭐ |
| **EODHD** | 20 req/dia (demo) | Stocks, ETFs, Histórico | ⭐⭐⭐ |
| **ExchangeRate.host** | 1500 req/mês | Forex | ⭐⭐⭐ |
| **GoldAPI** | 3-6 req/dia | Gold/Silver spot | ⭐⭐⭐⭐ |
| **Metals.dev** | 100 req/mês | Metais preciosos | ⭐⭐⭐ |

### APIs Pagas (para sites de alto tráfego):

| API | Preço | Vantagem |
|-----|-------|----------|
| **EODHD Starter** | $20/mês | 100.000 req/dia, dados completos |
| **Polygon.io** | $29/mês | Real-time stocks USA, WebSocket |
| **CoinGecko Pro** | $129/mês | Sem limites, candlestick data |
| **Finnhub Premium** | $50/mês | Real-time, WebSocket |
| **TwelveData Growth** | $29/mês | 3000 req/dia, todos os mercados |

### Recomendação por perfil:

**Blogger/Site pessoal (€0/mês):** CoinGecko free + Finnhub free + TwelveData free
→ PRO Standard (€29) + Background Cron = site rápido e funcional

**Site financeiro (€20-50/mês):** EODHD Starter + Finnhub free
→ PRO Premium (€59) + real-time polling = site profissional

**Empresa/Agência (€100+/mês):** Polygon.io + CoinGecko Pro
→ PRO Premium + White Label = solução à medida do cliente

---

## Plano de Implementação — Faseado

### FASE 0 — Correcções Imediatas na FREE (2-3 dias)

Antes de qualquer PRO, corrigir os problemas actuais da FREE:

- [ ] **Remover probe loop** já feito (eliminamos ~6-8 chamadas parasitas)
- [ ] **Corrigir campo Custom Provider** já feito (save via form funciona)
- [ ] **Fallback cross-category** já feito (chave Finnhub em ETFs é encontrada para Markets)
- [ ] **Validar estrutura HTML** da documentação — já feito
- [ ] Adicionar rate-limit backoff simples (se 429, espera e não tenta novamente durante 60s)
- [ ] Normalizar order de símbolos no cache key (sort antes de md5) para evitar cache miss

### FASE 1 — PRO Standard Core (3-4 dias)

> **Objectivo:** Background Cron + Last-Good + API Centralizada
> Estas 3 funcionalidades sozinhas resolvem 90% das queixas.

**Dia 1-2: Background Cron Engine**
```
Novo ficheiro: includes/pro/cron-engine.php
- Registar wp_schedule_event( 'daaz_gmp_bg_refresh', 'every_5_min' )
- Colectar todos os símbolos usados (transient registry)
- Fazer fetch em background para cada categoria
- Guardar resultados em transients (stale-while-revalidate)
```

**Dia 2: Last-Known-Good Cache**
```
Modificar: includes/api/api-helpers.php
- Após cada fetch bem sucedido: set_transient( 'lastgood_' + hash, data, 0 )
- Em caso de erro: retornar lastgood + flag _stale=true
```

**Dia 3: Centralização de APIs**
```
Novo ficheiro: includes/pro/api-keys-page.php
- Página admin: Settings → API Keys
- Inputs para cada provider conhecido
- daaz_gmp_get_category_api_key() primeiro verifica api_keys[] centralizado
```

**Dia 4: Licenciamento + Activação**
```
Novo ficheiro: includes/pro/license.php
- Chave de licença simples (verificação local, sem servidor)
- Constante DAAZ_GMP_PRO_TIER = 'standard' | 'premium'
- Filtros para mostrar/esconder funcionalidades PRO no admin
```

### FASE 2 — PRO Standard Extras (2-3 dias)

- Charts avançados (candlestick + multi-asset)
- Dark mode + toggle shortcode
- Alertas email (5 max, WP-Cron + wp_mail)

### FASE 3 — PRO Premium (4-5 dias)

- Real-time AJAX polling + badge LIVE
- Portfolio tracker (wp_usermeta based)
- CSV export endpoint
- White label settings
- Webhooks + alertas ilimitados

### FASE 4 — Polish & Lançamento (2-3 dias)

- Testes em WP limpo (WP 6.9+)
- Screenshots + banners para WP.org / CodeCanyon
- Landing page actualizada
- Email marketing para utilizadores FREE

---

## Arquitectura Técnica PRO

### Estrutura de Ficheiros (Plugin Separado)

```
daazmarkets-pro/
├── daazmarkets-pro.php          ← Bootstrap + license check
├── includes/
│   ├── license.php              ← Validação de licença
│   ├── cron-engine.php          ← Background refresh (Standard+)
│   ├── last-good-cache.php      ← Stale-while-revalidate (Standard+)
│   ├── api-keys-page.php        ← Centralização APIs (Standard+)
│   ├── charts-advanced.php      ← Candlestick+multi (Standard+)
│   ├── dark-mode.php            ← CSS toggle (Standard+)
│   ├── alerts.php               ← Email alerts engine (Standard+)
│   ├── realtime-ajax.php        ← AJAX polling (Premium)
│   ├── portfolio.php            ← Portfolio tracker (Premium)
│   ├── export.php               ← CSV/JSON export (Premium)
│   ├── whitelabel.php           ← Brand settings (Premium)
│   └── webhooks.php             ← Webhook dispatcher (Premium)
├── assets/
│   ├── css/pro-admin.css
│   ├── css/dark-mode.css
│   └── js/realtime.js
└── readme.txt
```

### Dependência do Plugin FREE

```php
// daazmarkets-pro.php
add_action( 'plugins_loaded', function() {
    if ( ! defined( 'DAAZ_GMP_VERSION' ) ) {
        add_action( 'admin_notices', function() {
            echo '<div class="notice notice-error"><p>';
            echo esc_html__( 'DaazMarkets PRO requires the free DaazMarkets plugin.', 'daazmarkets-pro' );
            echo '</p></div>';
        });
        return;
    }
    // Activar funcionalidades PRO via hooks
    define( 'DAAZ_GMP_PRO_ACTIVE', true );
    define( 'DAAZ_GMP_PRO_TIER', get_option( 'daaz_gmp_pro_tier', 'standard' ) );

    require_once __DIR__ . '/includes/license.php';
    require_once __DIR__ . '/includes/cron-engine.php';
    require_once __DIR__ . '/includes/last-good-cache.php';
    // ... etc
});
```

### Hooks no Plugin FREE (preparação)

O FREE precisa de poucos hooks para o PRO funcionar:

```php
// Em cada shortcode, antes de retornar HTML:
$html = apply_filters( 'daaz_gmp_shortcode_output', $html, $atts, $category );

// Em cada fetch, antes de retornar dados:
$data = apply_filters( 'daaz_gmp_before_cache_store', $data, $symbol, $provider );

// Ao registar menus admin:
do_action( 'daaz_gmp_admin_menu_items' );

// No settings page:
do_action( 'daaz_gmp_settings_tabs', $current_tab );
```

---

## Modelo de Receita

| Cenário | Standard (€29) | Premium (€59) | Total Anual |
|---------|:-:|:-:|:-:|
| **Conservador** (Ano 1) | 50 vendas | 15 vendas | €2.335 |
| **Moderado** (Ano 2) | 150 vendas | 40 vendas | €6.710 |
| **Optimista** (Ano 3) | 300 vendas | 80 vendas | €13.420 |

**Custos operacionais: €0/mês** (sem servidores, sem APIs pagas, sem suporte pago)

**Canais de venda:**
1. WordPress.org (link para site próprio) — gratuito
2. CodeCanyon — comissão ~35%
3. Site próprio (daazlabs.com) — Stripe/PayPal, zero comissão

---

## Inovação — O Que Torna Este Plugin Único

1. **Multi-provider inteligente** — Nenhum outro plugin WordPress faz fallback automático entre 6+ providers
2. **Zero infrastructure** — PRO funciona sem servidor, sem base de dados extra, sem subscrição mensal
3. **Background Cron** — A maioria dos concorrentes faz chamadas síncronas (0.5-3s delay)
4. **Last-Known-Good** — Preço antigo > preço zero. Nenhum plugin faz isto
5. **Centralização de API Keys** — Uma chave, todos os módulos. Simples e óbvio

### O Concorrente Mais Próximo

**CoinMarketCap Widgets (gratuito):** Só crypto, limitado a CMC, sem stocks/commodities
**Flavor Financial Widget ($49):** Só dados de mercados, sem crypto, sem fallback
**DaazMarkets PRO:** Crypto + Stocks + ETFs + Forex + Commodities + Miners + Treasuries → tudo num plugin

---

## Conclusão / Próximos Passos

**Prioridade absoluta:**
1. ✅ Corrigir FREE (probe loop, custom provider, cross-category keys) — FEITO
2. 🔲 Preparar hooks no FREE para o PRO (4-5 `apply_filters` + `do_action`)
3. 🔲 Construir PRO Standard core (Cron + Last-Good + API Central) — 3-4 dias
4. 🔲 Lançar PRO Standard (€29) — testar + publicar
5. 🔲 Construir PRO Premium add-ons — 4-5 dias
6. 🔲 Lançar PRO Premium (€59)

**A regra de ouro:** Cada fase dura no máximo 1 semana útil. Se demora mais, está demasiado complexo — simplificar.