# DaazMarkets — Visão PRO & Futuro

> Documento único e focado no futuro do plugin.
> Data: Julho 2026 | Versão actual: FREE 1.1.5 / PRO 1.1

---

## Diagnóstico Actual (FREE) — Problemas Resolvidos ✅

> **Julho 2026:** Os problemas abaixo estão todos resolvidos nas versões actuais.
> A arquitectura PRO implementada (cron SWR a dois níveis, LKG, cascata multi-provider)
> é acima da média dos plugins comerciais do CodeCanyon.

### Por que a página carregava lentamente? ✅ Resolvido

| Causa | Impacto | Estado |
|-------|---------|--------|
| **Todas as chamadas API eram síncronas** | ⛔ Crítico | ✅ Cron PRO pré-aquece em background |
| **1 HTTP request por símbolo** (sem batching) | ⛔ Crítico | ✅ Batching + cURL multi |
| **Sem cron/background update** | ⛔ Crítico | ✅ `daaz_gmp_bg_refresh` a cada 5-30 min |
| **Fallback em cascata síncrono** | 🔴 Alto | ✅ Cascata só corre no cron |
| Cache OK mas só ajudava após a 1ª carga | 🟡 Médio | ✅ SWR a dois níveis (dados + HTML) |

### Por que os preços apareciam a zero? ✅ Resolvido

| Causa | Frequência | Estado |
|-------|------------|--------|
| **Rate limiting (429)** | ~40% | ✅ Backoff com `Retry-After` + cron pré-aquece |
| **Sem last-known-good** | ~30% | ✅ LKG corrigido (§1.1 `setted_transient`) |
| **Símbolos spot vs futures** | ~20% | ✅ Mapa dual-format implementado |
| **Parsing incompleto** | ~10% | ✅ Normalização por provider |

---

## 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 ✅ Concluída

- [x] Remover probe loop (eliminamos ~6-8 chamadas parasitas)
- [x] Corrigir campo Custom Provider (save via form funciona)
- [x] Fallback cross-category (chave Finnhub em ETFs é encontrada para Markets)
- [x] Validar estrutura HTML da documentação
- [x] Rate-limit backoff simples (429 respeita `Retry-After`, cap 1h)
- [x] Normalizar order de símbolos no cache key (sort antes de md5)

### FASE 1 — PRO Standard Core ✅ Concluída

- [x] Background Cron Engine (`cron-engine.php`) com intervalo 5/10/15/30 min configurável
- [x] Last-Known-Good Cache (`last-good-cache.php`) — bug `set_transient` corrigido em Julho 2026
- [x] Centralização de APIs (`api-keys-page.php`)
- [x] Licenciamento HMAC v2 (`license.php`) — formato `DAAZ2-{payload}-{sig}`

### FASE 2 — PRO Standard Extras ✅ Concluída

- [x] Charts avançados (candlestick + multi-asset)
- [x] Dark mode + toggle shortcode
- [x] Alertas email (5 max no TRIAL, ilimitados no STANDARD) — bug de lookup de preço corrigido em Julho 2026

### FASE 3 — PRO Premium ✅ Concluída

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

### FASE 4 — Polish & Lançamento (em curso)

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

### FASE 4.1 — Correcções Críticas ✅ Concluída (Julho 2026)

> Correcções aplicadas a partir da revisão de código completa (`_REVIEW-CLAUDE-MELHORIAS.md`).

| Secção | Ficheiro(s) | Correcção |
|--------|-------------|-----------|
| §1.1 | `last-good-cache.php` | `set_transient` → `setted_transient` — LKG nunca guardava nada |
| §1.7 | `alerts.php`, `cron-engine.php` | Alertas nunca disparavam — chaves de transient não batiam; substituído por índice `daaz_gmp_last_prices` |
| B.3 | `daazmarkets.php` | SWR bg refresh apagava dados stale antes de saber se a API respondia |
| B.2 | `api-crypto.php`, `api-markets.php`, `api-miners.php`, `cron-engine.php` | `$force` param + fresh_ttl alinhado com intervalo do cron; Run Now mostra contagens reais |
| B.5 | `cron-engine.php` | `daaz_pro_schedule_cron()` corria em todos os pageviews |
| §1.6 | `realtime-ajax.php` | Micro-cache 20s no endpoint `rt-refresh`; get-before-set no `rt_wrap_output` |
| B.4 | `daazmarkets.php`, `daazmarkets-pro.php` | Deactivation hooks limpam eventos cron pendentes |
| §1.3 | `cron-engine.php` | GC diário de options LKG e HTML-cb órfãs |
| §1.4 | `uninstall.php` (ambos) | Criados — base de dados limpa ao desinstalar |
| §2.1 | `daazmarkets.php`, `daazmarkets-pro.php` | Assets só carregam em páginas com shortcodes DaazMarkets |
| Anexo A | `license.php`, `tools/generate-license.php` | Licença HMAC v2 (`DAAZ2-…`) — chaves antigas já não são válidas |

### FASE 5 — Próximas Prioridades (Semanas 2-4)

- [ ] Licenças via Freemius (checkout + updates automáticos do PRO)
- [ ] Registo passivo de símbolos para o cron (Elementor, widgets, templates)
- [ ] Mascarar API keys no admin (`••••1a2b`)
- [ ] PHPCS + PHPStan + primeiros testes unitários (parsers com fixtures)
- [ ] Ficheiro `.pot` de traduções (`wp i18n make-pot`)
- [ ] Bloco Gutenberg genérico (server-side render do shortcode)

### FASE 6 — Crescimento (Mês 2)

- [ ] Provider registry/interface (`Daaz_Provider`) — adicionar APIs pagas = 1 ficheiro
- [ ] Tabela de histórico local de preços (`daaz_price_history`)
- [ ] Health dashboard de providers no admin
- [ ] Blocos Gutenberg dedicados por shortcode + Elementor widgets nativos
- 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.