EloShop

E-commerce e Marketplace dedicado ao público que fabrica artesanato e produtos feitos à mão.

Stack

• Ruby 3.3.11 / Rails 8.1
• PostgreSQL 16
• Hotwire (Turbo + Stimulus)
• Tailwind CSS
• Active Storage
• Solid Queue, Solid Cache, Solid Cable
• RSpec + rswag (suíte principal de testes e documentação de API)
• Capybara + Selenium para testes de sistema

Requisitos

• Ruby 3.3.11 (veja .ruby-version)
• Docker (para subir o PostgreSQL local)

Configuração inicial

bin/setup

Instala as dependências, prepara o banco de dados, limpa logs/tmp, instala o git hook de pre-commit (RuboCop + testes, ver .githooks/README.md) e sobe bin/dev. Para pular a subida do servidor: bin/setup --skip-server.

Alternativa manual, passo a passo:

bundle install
docker compose up -d      # sobe o Postgres em localhost:5432
cp .env.example .env      # opcional, defaults já batem com o docker-compose
bin/rails db:setup        # cria os bancos e carrega o schema

O docker-compose.yml cria o banco eloshop_development com usuário/senha eloshop/eloshop. As credenciais podem ser sobrescritas via variáveis de ambiente (DATABASE_HOST, DATABASE_PORT, DATABASE_USERNAME, DATABASE_PASSWORD) — veja config/database.yml.

Rodando o servidor

bin/dev

Sobe o servidor Rails e o watcher do Tailwind (via Procfile.dev) em http://localhost:3000. A área administrativa fica em /admin (autenticação própria, ver app/controllers/admin/).

Testes

bundle exec rspec                     # suíte principal de testes
bundle exec rspec spec/requests       # request specs e OpenAPI
bin/rails rswag:specs:swaggerize     # gera swagger/v1/swagger.yaml
bin/rails test:system                 # testes de sistema (Capybara + Selenium)

Documentação de API

Com o servidor rodando, a UI do Swagger fica em /api-docs. O arquivo swagger/v1/swagger.yaml é gerado a partir dos specs em spec/requests/:

bin/rails rswag:specs:swaggerize

Lint e segurança

bin/rubocop         # lint
bin/brakeman        # análise estática de segurança
bin/bundler-audit   # vulnerabilidades conhecidas em gems

CI (GitHub Actions, .github/workflows/) roda lint, testes, testes de sistema, Brakeman/bundler-audit e CodeQL a cada push/PR em main.

Error tracking (Sentry)

Em produção, exceções e performance do backend são reportadas para o Sentry (organização eloshop, projeto eloshop) via sentry-ruby/sentry-rails (config/initializers/sentry.rb).

Ativa apenas quando SENTRY_DSN está definida e RAILS_ENV=production; sem a variável, o SDK não é inicializado e development/test seguem inertes. Não há SDK JS nem Session Replay — decisão deliberada para não expor dados de checkout (nome, endereço) capturados em gravação de tela.

Configurar

1. Acesse o projeto eloshop em eloshop.sentry.io e copie o DSN em Settings → Client Keys (DSN).
2. Configure SENTRY_DSN com esse valor nas variáveis de ambiente do serviço em produção (painel da Railway).

Testar a integração

O SDK só ativa com RAILS_ENV=production. Ao usar railway run, o comando é executado localmente, injetando as variáveis do serviço remoto mas mantendo o RAILS_ENV do seu shell — sem sobrescrever explicitamente, o initializer nunca ativa e nada é enviado. Prefixe o comando:

RAILS_ENV=production railway run --service eloshop-web bin/rails runner '
  Sentry.capture_message("Teste de integração Sentry", level: :info)
  Sentry.get_current_client&.flush
'

O flush explícito garante que o evento seja enviado antes do processo runner (de vida curta) encerrar. Depois, confira no painel do Sentry se o evento apareceu.

Detalhes em docs/architecture.md, seção "Deploy".

Documentação do domínio

O contexto de negócio e as decisões arquiteturais estão em docs/. Consulte ROADMAP.md para o estado atual do projeto e a próxima fase planejada.