# MIGRAÇÃO NUVEMSHOP → LOJA PRÓPRIA

> Princípio: **nunca cortar de uma vez.** A Nuvemshop continua vendendo até o dia em que
> a loja nova já provou que vende melhor. Nada é apagado lá — a migração só **lê**.

---

## Chave externa (idempotência)

Todo registro importado guarda:

```
external_provider = 'nuvemshop'
external_id       = '<id da NS>'
```

O importador casa por essa dupla. **Rodar de novo atualiza, nunca duplica.**
Regra de teste: rodar 5×, contar 1×.

---

## Ordem de importação

| # | O que | Fonte | Cuidados |
|---|---|---|---|
| 1 | Categorias | `GET /categories` | Recriar a árvore antes dos produtos |
| 2 | Produtos + variantes | `GET /products` | `stock: null` = **estoque infinito** (não é zero). Preço promocional vem em `promotional_price` |
| 3 | Imagens | `product.images[].src` | **Baixar e reservir do nosso servidor** — o CDN da NS morre no cutover. Converter para WebP/AVIF |
| 4 | Custo | `variant.cost` | Alimenta `painel_lucro_sku`. Pedido pago tem custo **congelado** |
| 5 | Clientes | `GET /customers` | ⚠️ **Não criar cliente novo.** Casar com `clientes` do MySQL pela cascata CPF → telefone(DDD+8) → `ns_customer_id` → e-mail, respeitando as 2 travas de privacidade |
| 6 | Pedidos históricos | `GET /orders` | Só para histórico/analytics do storefront. **`pedidos_cache` já é a verdade** — não reimportar em cima |
| 7 | Cupons ativos | `GET /coupons` | Ignorar os `CB*` (cashback) — são efêmeros, de 24h |
| 8 | URLs | tema/sitemap | Base do mapa de 301 (ver abaixo) |

## As duas travas de privacidade que o importador de clientes precisa respeitar

Vêm do relatório de 09/08/2026 e não são detalhe:

1. **Telefone/e-mail de afiliado nunca vira identidade de cliente.** Sem isso, a Ludmila
   (afiliada) veria os pedidos das clientes dela ao entrar no painel.
2. **E-mail só identifica se o primeiro nome bater.**

O motor já existe: `vo/config/clientes.php` (`clienteDoPedido`, `telefoneEhDaCasa`,
`emailEhDaCasa`). O importador **chama esse motor**, não escreve outro.

---

## Modo de transição (Onda 13 → 15)

```
Fase 1  NS vende  ·  loja nova em construção            ← estamos aqui
Fase 2  NS vende  ·  loja nova espelha catálogo (1 via, leitura)
Fase 3  NS vende  ·  loja nova aberta em lojavirtual.  ·  pedido de TESTE
Fase 4  NS vende  ·  loja nova recebe pedidos REAIS controlados (equipe/afiliados)
Fase 5  loja nova é a principal  ·  NS fica no ar, sem tráfego
Fase 6  301 completo  ·  NS desligada
```

**Critérios para avançar de fase** (não é "achou que está bom"):
- Fase 3→4: checkout completo, pedido chega ao `pedidos_cache`, baixa gera comissão certa,
  cashback bate com o ledger, e-mail/WhatsApp saem.
- Fase 4→5: 20 pedidos reais sem intervenção manual · zero comissão duplicada ·
  zero pedido órfão · Pixel/CAPI sem `Purchase` duplicado.
- Fase 5→6: 301 conferido URL a URL, Search Console sem pico de 404, 7 dias estáveis.

**Coexistência:** enquanto as duas lojas estiverem no ar, o pedido tem origem marcada
(`nuvemshop_id` numérico = NS · `LP-*` = loja nova). O `sincronizar.php` continua rodando
e **não enxerga** os pedidos da loja nova.

---

## Redirects (o que protege o SEO)

Antes do cutover, exportar **todas** as URLs indexadas (sitemap da NS + Search Console) e
gerar um mapa 1:1:

```
/produtos/guarda-roupa-abc      → /produto/guarda-roupa-abc      301
/categoria/moveis               → /moveis                        301
```

Sem correspondência → 301 para a categoria mais próxima, **nunca para a home**
(301 em massa para a home a Google trata como 404 soft).

---

## Desligar a Nuvemshop — checklist final

- [ ] 301 no ar e conferido
- [ ] Pixel + CAPI apontando só para a loja nova
- [ ] `LOJA_URL` e `NS_API_BASE` trocados nos 5 arquivos PHP
- [ ] `cron-carrinho-abandonado` lendo os eventos novos
- [ ] Cupom de cashback sendo criado na loja nova
- [ ] Catálogo PDF e agente IA lendo a fachada nova
- [ ] Backup do Postgres na rotina do Drive
- [ ] **Exportação completa da Nuvemshop guardada** (produtos, pedidos, clientes) antes de cancelar o plano
- [ ] 30 dias de convivência antes de cancelar a assinatura