# Fullstack Vivilo3d

> Full-stack development for Vivilo 3D (Next.js 16, Prisma, custom order flow, Mercado Pago sinal/saldo, Melhor Envio, referral). Use when building or maintaining vivilo3d, custom 3D gift orders from drawings, admin pedidos, or the valentierro/vivilo3d repository.

- Skill: `valentierro/fullstack-vivilo3d` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add valentierro/fullstack-vivilo3d`
- Raw SKILL.md: https://api.skillmd.com/api/skills/valentierro/fullstack-vivilo3d/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: valentierro (https://skillmd.com/u/valentierro)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/valentierro/fullstack-vivilo3d

---


# Full-Stack — Vivilo 3D

Estúdio criativo sob encomenda: desenhos → estatuetas/chaveiros 3D. Repo: `valentierro/vivilo3d`.

## Stack

| Camada | Tecnologia |
|--------|------------|
| Framework | Next.js **16**, React **19**, TypeScript 5 |
| DB | PostgreSQL + Prisma 6 (`src/generated/prisma`) |
| Migrations | `prisma migrate dev` / `db:migrate:deploy` (≠ Cometa que usa só `db push`) |
| Auth | Auth.js v5 — Credentials + **Google OAuth**, roles `USER` / `ADMIN` |
| Pagamentos | Mercado Pago — fluxo **sinal + saldo** (`MERCADOPAGO_PERCENTUAL_SINAL`) |
| Frete | Melhor Envio OAuth (tokens no banco via `site-settings`) |
| Storage | Vercel Blob (`blob-storage.ts`) |
| Email | SMTP (templates em `email-template.ts`, paleta Vivilo) |
| Styling | **Tailwind CSS 4** (`@import "tailwindcss"`), CSS vars em `globals.css` |
| Motion | Framer Motion |
| Deploy | Vercel + crons |

**Sem preview 3D no site** — fluxo é pedido → prévia → aprovação → produção.

## Domínio de negócio

- Produtos: estatuetas, chaveiros, objetos a partir de **desenhos infantis**
- Não faz: impressão técnica, STL pronto, peças de reposição
- Tagline: "A sua imaginação ganha forma"
- Instagram: `@vivilo3d`

## Fluxo de pedido (`Pedido`)

```
RASCUNHO → RECEBIDO → AGUARDANDO_CONFIRMACAO_VALOR → AGUARDANDO_PAGAMENTO_SINAL
→ EM_PRODUCAO → AGUARDANDO_APROVACAO → APROVADO | AJUSTE_SOLICITADO
→ AGUARDANDO_PAGAMENTO_SALDO → CONCLUIDO | RECUSADO
```

- **Rascunho:** `pedido-rascunho.ts` + upload fotos via API
- **Precificação:** `precificacao.ts` — tamanho, multicolor, quantidade personagens
- **Pagamento:** `pagamento.ts` / `mercadopago.ts` — sinal % configurável
- **Aprovação prévia 3D:** admin envia → cliente aprova/recusa no painel

## Estrutura

```
src/app/
├── page.tsx, sob-encomenda/, catalogo/, galeria/, projetos/
├── painel/          # Cliente: pedidos, endereços, indicações
├── admin/           # Pedidos, preços, galeria, cupons, funil, ME OAuth
└── api/
    ├── pedidos/     # Criação, rascunho, pagamento
    ├── painel/      # Confirmar valor, aprovar, ajuste
    ├── admin/       # Backoffice completo
    └── webhooks/    # mercadopago, melhor-envio
```

Lógica em `src/lib/` — 55+ módulos (`pedido.ts`, `precificacao.ts`, `referral.ts`, etc.).

## Brand / UI

```css
--accent-red: #e8543a    --accent-olive: #8a8b4e    --accent-yellow: #f5a623
--bg-secondary: #faf8f4  --text-primary: #5c3a28
```

Fontes: **Baloo 2** (display), **Poppins** (body). Componentes orgânicos: `OrganicBlob`, `FloatingShape`, bordas arredondadas 2xl–3xl.

## Regras obrigatórias

1. **Lógica em `src/lib/`** — rotas API finas; precificação centralizada em `precificacao.ts`.
2. **Prisma client** import de `@/generated/prisma` (output customizado).
3. **Migrations** — preferir `db:migrate` para schema; `db:push` só quando alinhado ao time.
4. **Fluxo sinal/saldo** — nunca cobrar valor total de uma vez sem revisar `pagamento-calc.ts`.
5. **Tamanho máximo peça:** 22 cm (`MAX_PIECE_SIZE_CM` em `precificacao.ts`).
6. **Copy pt-BR** — tom emocional, familiar; constantes em `constants.ts`.
7. **Auth** — `requireAdmin()` no layout admin; Google OAuth via env `GOOGLE_CLIENT_*`.
8. **Referral** — respeitar `referral.ts`, créditos e cookie de atribuição.
9. **Uploads** — usar `upload.ts` / `blob-storage.ts`; fotos de rascunho via API dedicada.
10. **Instagram/reels** — artes em `public/instagram/`; scripts em `scripts/`. Para design social, usar skill **`design-social-vivilo`**.

## Scripts úteis

```bash
npm run dev
npm run db:migrate && npm run criar-admin
npm run test:e2e:fluxo          # fluxo pedido E2E
npx tsx scripts/gerar-reel-*.ts # reels Instagram
```

## Diferenças vs Cometa Geek 3D

| | Vivilo | Cometa Geek |
|---|--------|-------------|
| Next | 16 / React 19 | 14 / React 18 |
| Tailwind | v4 | v3 |
| DB sync | migrations | db push |
| Modelo | Pedido sob encomenda | E-commerce catálogo |
| 3D site | Sem model-viewer | `<model-viewer>` GLB |
| Pagamento | Sinal + saldo | Checkout único |
| Paleta | coral/olive/yellow | orange/gold/teal |

Para env completo, ver [reference.md](reference.md).