# G) PLANO DE ONDAS + I) ARQUIVOS QUE SERÃO CRIADOS

> Regra de trabalho de cada onda: auditar → explicar → implementar → testar → corrigir →
> documentar → commit lógico. **Nunca alterar produção sem backup.**
> Achou coisa quebrada que não é da onda? Vai para `docs/TECH-DEBT.md`, não para o commit.

---

## Estado das ondas

| Onda | Entrega | Status |
|---|---|---|
| **0** | Auditoria, arquitetura, escolha da plataforma, plano | ✅ **CONCLUÍDA** (15/08/2026) |
| **1** | Infra + Medusa + Commerce API de pé | ⛔ **bloqueada pela VPS** (R1) |
| 2 | Catálogo: import da Nuvemshop, categorias, marcas, variantes | — |
| 3 | Storefront: home, categoria, produto, busca | — |
| 4 | Carrinho + checkout | — |
| 5 | Pagamento (gateway a definir) | — |
| 6 | Pedido → ERP (`pedidos_cache`) e teste de idempotência | — |
| 7 | Atribuição de afiliado ponta a ponta | — |
| 8 | Cliente + integração com `cliente.ofertadistribuidora.com.br` | — |
| 9 | Cashback (consumindo o ledger que já existe) | — |
| 10 | Carrinho abandonado (substitui `GET /checkouts`) | — |
| 11 | Marketing: Pixel, CAPI, GA4, GTM, UTM | — |
| 12 | SEO + PWA + performance | — |
| 13 | Migrador Nuvemshop completo (clientes, pedidos, cupons) | — |
| 14 | Testes de produção com pedidos reais controlados | — |
| 15 | Cutover: DNS, 301, desligar a Nuvemshop | — |

---

## Detalhe das primeiras ondas

### ONDA 1 — Fundação (bloqueada pela decisão de infra)
**Entrega:** `docker compose up` sobe Medusa + Postgres + Redis + Commerce API + storefront vazio,
com `lojavirtual.ofertadistribuidora.com.br` respondendo HTTPS e `/health` verde.
**Prova:** admin do Medusa abre, `/health` lista Postgres/Redis/ERP/Nuvemshop com latência.

### ONDA 2 — Catálogo
Importador **idempotente** por `external_provider='nuvemshop' + external_id`.
Rodar 5× não duplica nada. Traz produto, variante, categoria, imagem, preço, custo, estoque, SEO.
⚠️ `stock NULL` = estoque infinito. ⚠️ imagem baixada e reservida por nós (a NS some no cutover).
**Prova:** contagem NS = contagem Medusa; rodada 2 não cria nada; relatório do que não casou.

### ONDA 3 — Storefront
Mobile-first, cores da marca, SSR/ISR. Home com banner, vitrines, ofertas, benefícios,
entrega, montagem, cashback, CTA WhatsApp. Categoria com filtro/ordenação/paginação.
Produto com galeria, zoom, Pix, parcelamento, medidas, frete, montagem, relacionados.

### ONDA 4 — Carrinho + checkout
Checkout próprio: identificação (CPF/CNPJ + telefone), endereço, entrega, montagem,
pagamento, cupom, cashback, revisão. Carrinho carrega a atribuição desde o primeiro clique.

### ONDA 5 — Pagamento
**Decisão pendente do dono** (não existe gateway no sistema atual — ver AUDITORIA §A.3).
Camada `PaymentProvider` com Pix + cartão + parcelamento + webhook idempotente.
Nunca guardar dado de cartão. Pedido só é "pago" com confirmação assinada do provedor.

### ONDA 6 — Pedido → ERP  ← *a onda mais delicada de todas*
`vo/api/loja-pedido.php` (arquivo **novo**, nada reescrito) grava em `pedidos_cache` com
`nuvemshop_id = 'LP-000123'`. Notifica afiliado e admin igual hoje.
**Testes obrigatórios:** mesmo pedido 5× = 1 linha · baixa dupla = 1 jogo de comissões ·
pedido da loja nova não é tocado pelo `sincronizar.php` · estorno cancela comissão e cashback.

### ONDA 7 — Atribuição
`?ref=GO_123`, `utm_*`, `cupom=` → resolvido e **validado no servidor** → gravado no carrinho →
no pedido → no `afiliado_id`. Cliente não consegue alterar. Sem `GO` válido = **sem atribuição**
(nunca cair num afiliado padrão — lição de 25/07, quando `GO_1` recebeu a comissão de todos os motoristas).
Janela de atribuição, último toque, e registro de quem levou e por quê.

---

## I) ARQUIVOS QUE SERÃO CRIADOS

### No projeto novo — `C:\Users\mac\Documents\LOJA VIRTUAL\`

```
/docker/               docker-compose.yml, Dockerfiles, nginx/traefik
/commerce/             Medusa v2 (backend + admin)
  src/modules/oferta-attribution/
  src/modules/oferta-cashback/
  src/modules/oferta-erp-sync/
  src/modules/oferta-cms/          banners, vitrines, campanhas
  src/workflows/                   criar-pedido, sincronizar-catalogo, abandono
  src/api/                         rotas custom (inclui a fachada NS-compatível)
/storefront/           Next.js 15 + TypeScript + Tailwind
  app/(loja)/  app/(conta)/  middleware.ts  lib/  components/  public/manifest.json
/integrations/         clientes de ERP, Meta, WhatsApp, Nuvemshop (import)
/scripts/              importadores, seeds, verificadores
/tests/                unit + e2e (Playwright) + testes de idempotência
/docs/                 esta pasta
CLAUDE.md  ESTADO.md  .env.example  .gitignore
```

### No sistema existente — **só arquivos NOVOS, aditivos**

| Arquivo | Onda | Função |
|---|---|---|
| `vo/api/loja-pedido.php` | 6 | Recebe pedido da loja nova → `pedidos_cache` |
| `vo/api/loja-cliente.php` | 8 | Resolve identidade (chama `config/clientes.php`) |
| `vo/api/loja-afiliado.php` | 7 | Valida `GO_n`/cupom → `afiliado_id` |
| `vo/api/loja-cashback.php` | 9 | Saldo e aplicação (chama `config/cashback.php`) |
| `vo/api/loja-eventos.php` | 10–11 | Repassa eventos para CRM/Marketing |
| `vo/config/loja.php` | 6 | Segredo HMAC + base da Commerce API (fonte única) |
| `vo/loja-status.php` | 6 | Painel de saúde da integração (admin) |

Todos com: assinatura HMAC, `try/catch` que nunca derruba o ERP, log em `sistema_eventos`,
e resposta no padrão `jsonRes()` da casa.

### Alterações mínimas em arquivos existentes (uma linha cada, só no cutover)

| Arquivo | Mudança | Quando |
|---|---|---|
| `afiliado/config.php:23` | `LOJA_URL` → domínio novo | Onda 15 |
| `vo/config/db.php:16` | `NS_API_BASE` → fachada da Commerce API | Onda 15 |
| `cliente./config.php:59`, `afiliado/api/venda-manual.php:17`, `afiliado/diag-busca.php:7` | mesma constante duplicada | Onda 15 |

**Nenhuma dessas alterações acontece antes da Onda 14 estar aprovada.**