Ambiente de Desenvolvimento

Guia para um desenvolvedor configurar e subir o ShopB2B na própria máquina.

A aplicação vive em src/ (projeto Laravel + docker-compose + configs). Rode composer/artisan/npm dentro de src/. Os serviços de apoio (Postgres, Redis, Mailpit, MinIO) sobem via Docker.

Pré-requisitos

Ferramenta	Versão	Observação
PHP	8.3+	com extensões pdo_pgsql / pgsql (e bcmath, mbstring)
Composer	2.x	gerenciador de dependências PHP
Node.js + npm	Node 20+	front (Vite + React)
Docker Desktop	atual	Postgres 16, Redis, Mailpit, MinIO
Git	atual	no Windows, use o Git Bash

Primeira configuração (uma vez)

# 1. clonar o repositório e entrar na aplicação
git clone <url-do-repo> && cd <repo>/src

# 2. variáveis de ambiente (o .env já aponta para o Postgres do Docker: porta 5434, user shopb2b_app)
cp .env.example .env        # se ainda não existir

# 3. dependências
composer install
npm install

# 4. chave da aplicação
php artisan key:generate

# 5. subir os serviços de apoio (cria a role NÃO-superuser `shopb2b_app` e o banco `shopb2b_test`
#    no primeiro start, via docker/postgres/init/01-app-role.sql)
docker compose up -d
#    aguarde o container `shopb2b-postgres` ficar healthy:
docker inspect --format '{{.State.Health.Status}}' shopb2b-postgres   # -> healthy

# 6. schema + dados de demonstração
php artisan migrate --seed

Billing/Stripe (opcional). O módulo de assinatura usa o Stripe em test mode. Coloque as chaves de teste em src/.env (STRIPE_KEY, STRIPE_SECRET, STRIPE_WEBHOOK_SECRET, BILLING_PRICE_ID). Sem elas, apenas o checkout de assinatura fica indisponível — o resto do sistema funciona normalmente. Segredos não vão para o git (docs/keys/ é ignorado). Detalhes em docs/tech/go-live-billing.md.

Iniciar no dia a dia

# 1. Docker Desktop aberto, então suba os serviços (idempotente)
cd src && docker compose up -d

# 2. suba a aplicação completa (server + fila + logs + Vite) num único comando
composer run dev

• App: http://localhost:8000 · Mailpit (e-mails de teste): http://localhost:8026

Alternativa sem o composer run dev (dois terminais): php artisan serve e npm run dev.

Serviços e portas

Serviço	URL / porta
Aplicação (artisan serve)	http://localhost:8000
PostgreSQL 16	localhost:5434 (db shopb2b, user shopb2b_app)
Redis 7	localhost:6380
Mailpit — SMTP / UI	localhost:1026 / http://localhost:8026
MinIO (S3) — API / console	http://localhost:9002 / http://localhost:9003

Banco e multi-tenant (importante)

A aplicação conecta como a role não-superuser shopb2b_app de propósito: o isolamento entre empresas usa Row-Level Security (RLS), que um superusuário ignoraria. Não troque o usuário do banco para superusuário no .env.

Testes e qualidade

cd src
php artisan test           # suíte (usa o banco shopb2b_test, criado pelo init do Postgres)
./vendor/bin/pint          # corrige estilo (pint --test apenas verifica)
npm run build              # build de produção do front

Parar / recriar

docker compose down        # para os serviços (mantém os dados nos volumes)
docker compose down -v     # apaga os volumes (zera o banco; no próximo `up` o init recria a role)

Troubleshooting

• http://localhost:8000 não responde: confirme composer run dev (ou php artisan serve) rodando e o Docker de pé.
• shopb2b-postgres não fica healthy: veja docker logs shopb2b-postgres; portas 5434/6380/1026/ 8026/9002/9003 podem estar ocupadas por outro stack.
• migrate falha por permissão/role: o init só roda no primeiro start (volume vazio). Se o volume já existia sem a role, recrie: docker compose down -v && docker compose up -d.
• Front (Vite) não atualiza: confirme npm run dev ativo; rode npm install se trocou de branch.

Atalho com o assistente (Claude Code)

Este repositório está configurado para que, ao dizer "inicie o ambiente de desenvolvimento", o assistente execute o runbook de início (subir Docker, aguardar o Postgres, rodar migrations pendentes, subir server + Vite e confirmar :8000). O passo a passo canônico que ele segue está no CLAUDE.md do repositório da aplicação, espelhando esta página.