# CLAUDE.md — Loja Virtual Própria (Oferta Distribuidora)

> ⚠️ Antes de qualquer tarefa: leia `ESTADO.md` e `docs/NAO-TOCAR.md`.

Plataforma de e-commerce própria que vai **substituir a Nuvemshop**, sem quebrar nada do
que já existe. O ERP, o MMN, o CRM, o Marketing OS, o agente de WhatsApp, o cashback,
o painel do cliente e a montagem **continuam onde estão** — a loja nova se integra a eles.

## O sistema irmão (somente leitura)

`C:\Users\mac\Documents\Sistema MMN Oferta Distribuidora\` — PHP puro + MySQL `ofertadi_os`,
hospedado em cPanel. É o ERP/MMN/CRM em produção. **Ler sim, alterar não** (exceto os
arquivos novos `vo/api/loja-*.php` a partir da Onda 6).
Documentos-fonte dele: `CLAUDE.md`, `ESTADO.md`, `CRM-PLANO.md`.

## Stack desta loja

| Camada | Escolha |
|---|---|
| Commerce engine | **Medusa v2** (Node + TypeScript) — justificativa em `docs/ARCHITECTURE.md` |
| Banco | PostgreSQL (novo) — o MySQL antigo **não é tocado** |
| Cache/fila | Redis |
| Storefront | Next.js 15 + TypeScript + Tailwind, mobile-first, PWA |
| API de integração | **Oferta Commerce API** — a única ponte entre a loja e os sistemas antigos |
| Infra | Docker Compose em VPS |
| Domínio provisório | `lojavirtual.ofertadistribuidora.com.br` |

## As 6 regras que não se negociam

1. **Comissão não se calcula aqui.** A loja entrega o pedido com `afiliado_id`;
   quem gera comissão é `vo/api/dar-baixa.php`, como sempre foi. Nível 1 = 3 %, 2 = 2 %, 3 = 1 %.
2. **Cashback não ganha tabela nova.** `cashback_mov` é o ledger; saldo é sempre soma de
   movimentações. O percentual **nunca** aparece para o cliente.
3. **Atribuição de afiliado é resolvida no servidor.** O navegador nunca decide quem recebe.
   Sem `GO` válido = sem atribuição (nunca cair num afiliado padrão).
4. **Idempotência em tudo que é dinheiro.** Mesmo evento 5×, efeito comercial 1×.
5. **Nada é apagado da Nuvemshop.** A migração só lê.
6. **Segredo não entra no git.** `.env` fora do repositório, credenciais próprias
   (não copiar nenhuma do sistema antigo).

## Identidade visual

Azul `#07166F` · Vermelho `#9A0808` · Branco.
Design premium, limpo, alta conversão, mobile impecável. Sem cara de template.
**UI só com ícone SVG, nunca emoji** (regra do dono) — WhatsApp continua com emoji.

## Idioma e convenções

Código, comentários, commits e documentação em **português (pt-BR)**, como no sistema irmão.
Fuso `America/Cuiaba` em toda data que conversa com o ERP.

## Documentação obrigatória (manter atualizada)

`docs/AUDITORIA-ONDA0.md` · `ARCHITECTURE.md` · `DATA-OWNERSHIP.md` · `PLANO-ONDAS.md` ·
`NAO-TOCAR.md` · `MIGRATION-NUVEMSHOP.md` · `TECH-DEBT.md` · (a criar) `API.md`,
`INTEGRATIONS.md`, `DEPLOY.md`, `TESTS.md`.