sierratecnologia/gamer

Game

0.4.4 2024-01-16 03:12 UTC

Requires

• jordanbrauer/unit-converter: ^0.8.4
• lorisleiva/laravel-actions: ^1.1
• markrogoyski/math-php: *
• php-ai/php-ml: >=0.8
• sierratecnologia/audit: ^0.4.0
• sierratecnologia/muleta: ^0.4.0
• sierratecnologia/pedreiro: ^0.4.0
• spatie/laravel-event-sourcing: ^4.3

Requires (Dev)

• codedungeon/phpunit-result-printer: >=0.27.0
• doctrine/dbal: ^2.10
• fakerphp/faker: ^1.5
• friendsofphp/php-cs-fixer: ^2.16
• illuminate/database: ^6.0|^7.0|^8.0
• mockery/mockery: ^1.0
• orchestra/testbench: ^4.0|^5.0|^6.0
• phpro/grumphp: ^1.3
• phpunit/phpunit: ^9.0
• squizlabs/php_codesniffer: ^3.4
• vimeo/psalm: ^4.0

MIT

• Ricardo Sierra
• Ricardo Rebello Sierra
• SierraTecnologia

• laravel
• reward
• loyalty
• gamer
• points
• pointable
• SierraTecnologia

README

SierraTecnologia Gamer Various functionality, and basic controller included out-of-the-box.

[x] Point Transaction system for laravel X

📚 Índice

1. Introdução
2. Instalação
3. Arquitetura e Estrutura Interna
4. Principais Funcionalidades
5. Uso Prático
6. Integração com o Ecossistema SierraTecnologia
7. Extensão e Customização
8. Exemplos Reais
9. Configuração de Ferramentas de Qualidade
10. Guia de Contribuição

🎮 Introdução

O que é o Gamer?

Gamer é um módulo de gamificação completo e extensível para aplicações Laravel, desenvolvido pela SierraTecnologia / Rica Soluções. O pacote oferece um sistema robusto de pontuação, conquistas, competições, badges e progressão de usuários, permitindo aumentar o engajamento e a retenção de usuários em plataformas web e APIs.

Objetivo e Motivação

O projeto nasceu da necessidade de criar experiências interativas e engajadoras em plataformas corporativas, educacionais e de e-commerce. Com o Gamer, é possível:

• Incentivar comportamentos desejados através de sistemas de recompensa
• Aumentar a retenção e engajamento de usuários
• Criar competições saudáveis entre usuários ou equipes
• Medir e rastrear progressão através de métricas de gamificação
• Personalizar experiências baseadas em conquistas e níveis

Contexto no Ecossistema SierraTecnologia

O Gamer faz parte do ecossistema modular da SierraTecnologia / Rica Soluções, integrando-se nativamente com outros módulos como:

• Informate - Sistema de notificações e comunicação
• Market - Plataforma de e-commerce
• CMS - Sistema de gerenciamento de conteúdo
• Tracking - Rastreamento e analytics
• Finder - Sistema de busca e descoberta

Benefícios para Plataformas de Engajamento

• ✅ Sistema de pontuação flexível com suporte a múltiplos tipos de pontos
• ✅ Histórico completo de transações com rastreabilidade total
• ✅ Event-driven architecture utilizando Spatie Event Sourcing
• ✅ Observers automáticos para eventos de Eloquent e autenticação
• ✅ Dashboard administrativo completo com interface AdminLTE
• ✅ APIs RESTful para integração com aplicações frontend
• ✅ Sistema de competições com times e jogadores
• ✅ Extensível e customizável através de traits, contratos e eventos

📦 Instalação

Requisitos Mínimos

• PHP: >= 7.4 (recomendado >= 8.2)
• Laravel: ^6.0 | ^7.0 | ^8.0 | ^9.0 | ^10.0 | ^11.0
• Composer: ^2.0
• Banco de Dados: MySQL >= 5.7, PostgreSQL >= 9.6 ou SQLite >= 3.8

Dependências Principais

• sierratecnologia/audit - Sistema de auditoria
• sierratecnologia/pedreiro - Componentes base
• sierratecnologia/muleta - Utilitários e helpers
• spatie/laravel-event-sourcing - Event Sourcing
• lorisleiva/laravel-actions - Actions pattern

Instalação via Composer

composer require sierratecnologia/gamer

Publicação de Configurações e Migrations

Após a instalação, publique os arquivos de configuração e execute as migrations:

# Publicar configurações
php artisan vendor:publish --provider="Gamer\GamerProvider" --tag=config

# Publicar migrations
php artisan vendor:publish --provider="Gamer\GamerProvider" --tag=migrations

# Executar migrations
php artisan migrate

Publicação de Assets e Views (Opcional)

# Publicar views
php artisan vendor:publish --provider="Gamer\GamerProvider" --tag=views

# Publicar traduções
php artisan vendor:publish --provider="Gamer\GamerProvider" --tag=lang

Registro de Service Provider

O Service Provider é registrado automaticamente através do Laravel Auto-Discovery. Caso necessário, adicione manualmente em config/app.php:

'providers' => [
    // ...
    Gamer\GamerProvider::class,
];

Configuração do Arquivo .env

Para integração com serviços externos, adicione ao .env:

# Integração com Pointagram (opcional)
SERVICES_POINTAGRAM_KEY=seu_token_aqui

🏗️ Arquitetura e Estrutura Interna

Estrutura de Diretórios

src/
├── Aggregates/          # Event Sourcing Aggregates
├── Builders/            # Query Builders customizados
├── Console/             # Comandos Artisan
│   └── Commands/
├── Connectors/          # Conectores com serviços externos
├── Contracts/           # Interfaces e Contratos
│   └── Pointable.php    # Contrato para entidades pontuáveis
├── Entities/            # Value Objects e Entidades de Domínio
│   └── Points/
├── Events/              # Eventos de Domínio
├── Facades/             # Facades do Laravel
├── Http/                # Camada HTTP
│   ├── Controllers/     # Controllers (User, Painel, RiCa)
│   ├── Middleware/      # Middlewares
│   └── Requests/        # Form Requests
├── Models/              # Eloquent Models
├── Notifications/       # Notificações
├── Observers/           # Eloquent Observers
├── Policies/            # Authorization Policies
├── Pointable/           # Sistema de pontuação
│   └── Mapeamento/
├── Processing/          # Processadores de lógica de negócio
├── Reactors/            # Event Sourcing Reactors
├── Repositories/        # Repositories Pattern
├── Services/            # Camada de Serviços
├── Traits/              # Traits reutilizáveis
│   ├── Pointable.php    # Trait principal de gamificação
│   └── AsPointable.php  # Trait auxiliar
├── Gamer.php            # Classe principal
└── GamerProvider.php    # Service Provider

Componentes Centrais

1. Sistema de Pontos e Transações

• Transaction (Model): Representa uma transação de pontos, armazenando quantidade, mensagem, saldo atual e relacionamento polimórfico com a entidade pontuável.
• Point (Model): Representa tipos de pontos (ex: XP, moedas, estrelas).
• PointType (Model): Define categorias de pontos com regras específicas.

2. Trait Pointable

// src/Traits/Pointable.php
trait Pointable
{
    public function transactions($amount = null);      // Relacionamento com transações
    public function points();                           // Relacionamento com tipos de pontos
    public function countTransactions();                // Contagem de transações
    public function currentPoints();                    // Saldo atual de pontos
    public function addPoints($amount, $message, $data = null); // Adicionar pontos
}

Funcionalidades:

• Relacionamento polimórfico com Transaction e Point
• Cálculo automático de saldo atual
• Histórico completo de transações
• Suporte a metadados customizados

3. Sistema de Competições

• Competition (Model): Gerencia competições/desafios
• Team (Model): Gerencia equipes
• Player (Model): Gerencia jogadores
• CompetitionPlayer (Model): Relacionamento entre competições e jogadores

4. Sistema de Scores e Séries

• ScoreSerie (Model): Gerencia séries de pontuação
• ScoreSeriePointType (Model): Relacionamento entre séries e tipos de pontos

5. Sistema de Eventos

• GamerEvent (Model): Gerencia eventos de gamificação
• EventPointable (Processing): Processa eventos e atribui pontos

6. Observers

• ModelCallbacks: Observa todos os eventos Eloquent (created, updated, deleted)
• LoginObserver: Observa eventos de login para atribuir pontos automaticamente

Padrões Arquiteturais

Event-Driven Architecture

O Gamer utiliza Spatie Event Sourcing para rastreamento completo de eventos:

// Eventos registrados no GamerProvider
$this->app['events']->listen(
    'eloquent.*',
    'Gamer\Observers\ModelCallbacks'
);

$this->app['events']->listen(
    'Illuminate\Auth\Events\Login',
    'Gamer\Observers\LoginObserver'
);

Repository Pattern

Exemplo de Repository:

// src/Repositories/PromotionRepository.php
class PromotionRepository
{
    // Lógica de acesso a dados isolada
}

Service Layer

// src/Services/GamerService.php
class GamerService
{
    // Lógica de negócio centralizada
}

Comunicação entre Camadas

┌─────────────┐
│  Controller │ → HTTP Request
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   Service   │ → Lógica de Negócio
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Repository  │ → Acesso a Dados
└──────┬──────┘
       │
       ▼
┌─────────────┐
│    Model    │ → Eloquent ORM
└─────────────┘

Integração com Eloquent

O sistema utiliza relacionamentos polimórficos para máxima flexibilidade:

// Qualquer modelo pode ser "Pointable"
class User extends Model implements Pointable
{
    use PointableTrait;
}

// Relacionamento polimórfico
$user->transactions()->save($transaction);

🚀 Principais Funcionalidades

1. Sistema de Pontuação e Níveis

Adicionar Pontos

$user = User::first();
$user->addPoints(100, 'Completou tutorial');

// Com metadados personalizados
$user->addPoints(50, 'Primeira compra', [
    'ref_id' => 'ORDER-123',
    'category' => 'sales'
]);

Consultar Saldo Atual

$currentPoints = $user->currentPoints(); // 150.0

Histórico de Transações

// Todas as transações
$transactions = $user->transactions;

// Últimas 5 transações
$lastTransactions = $user->transactions(5)->get();

// Contagem total
$total = $user->countTransactions();

2. Sistema de Conquistas e Badges

(Em desenvolvimento - estrutura preparada em migrations)

// Estrutura planejada
$user->badges()->attach($badgeId);
$user->achievements()->where('unlocked', true)->get();

3. Eventos Automáticos de Gamificação

O sistema observa automaticamente eventos do Laravel:

Eventos de Autenticação

// LoginObserver.php - Pontos automáticos ao fazer login
Event::listen('Illuminate\Auth\Events\Login', function($event) {
    $event->user->addPoints(10, 'Login diário');
});

Eventos de Eloquent

// ModelCallbacks.php - Pontos por ações em modelos
Event::listen('eloquent.created', function($model) {
    if ($model instanceof Post) {
        $model->user->addPoints(50, 'Criou um novo post');
    }
});

4. Sistema de Competições

// Criar competição
$competition = Competition::create([
    'name' => 'Desafio de Vendas Q1',
    'start_date' => now(),
    'end_date' => now()->addMonths(3),
]);

// Adicionar jogadores
$competition->players()->attach($userId);

// Criar time
$team = Team::create(['name' => 'Time Alpha']);
$team->players()->attach($playerIds);

5. Dashboard e APIs de Ranking

Controllers Disponíveis

• User Controllers (src/Http/Controllers/User/):

  • HomeController - Dashboard do usuário

• Painel Controllers (src/Http/Controllers/Painel/):

  • ObjectiveController - Gerenciar objetivos
  • MetaController - Gerenciar metas

• RiCa Controllers (src/Http/Controllers/RiCa/):

  • PointController - CRUD de pontos
  • PointTypeController - CRUD de tipos de pontos
  • TransactionController - Histórico de transações
  • CompetitionController - Gerenciar competições
  • PlayerController - Gerenciar jogadores
  • TeamController - Gerenciar times
  • ScoreSerieController - Gerenciar séries de score
  • GamerEventController - Gerenciar eventos

Rotas Disponíveis

// Rotas de usuário
Route::get('profile/gamer/home', 'User\HomeController@index')
    ->name('profile.gamer.home');

// Rotas administrativas (RiCa)
Route::resource('rica/gamer/points', 'RiCa\PointController');
Route::resource('rica/gamer/transactions', 'RiCa\TransactionController');
Route::resource('rica/gamer/competitions', 'RiCa\CompetitionController');

6. Exemplo Prático de Fluxo Completo

// 1. Usuário realiza uma ação (ex: compra um produto)
$order = Order::create([...]);

// 2. Evento é disparado
event(new OrderCreated($order));

// 3. Observer captura e atribui pontos
// EventPointable.php ou Listener customizado
$order->user->addPoints(
    $order->total * 0.1, // 10% do valor em pontos
    'Compra no valor de R$ ' . $order->total,
    ['order_id' => $order->id]
);

// 4. Sistema verifica conquistas
if ($order->user->countTransactions() >= 10) {
    $order->user->badges()->attach($badge10Compras);
    // 5. Notificação é enviada
    $order->user->notify(new BadgeUnlocked($badge10Compras));
}

// 6. Pontos são exibidos no dashboard
return view('gamer::profile.home', [
    'currentPoints' => $order->user->currentPoints(),
    'recentTransactions' => $order->user->transactions(5)->get(),
]);

💻 Uso Prático

Como Implementar o Sistema de Pontos em um Projeto Laravel

Passo 1: Implementar o Contrato e Trait

<?php

namespace App\Models;

use Gamer\Contracts\Pointable;
use Gamer\Traits\Pointable as PointableTrait;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable implements Pointable
{
    use PointableTrait;

    // ... resto do modelo
}

Passo 2: Criar Eventos de Gamificação

<?php

namespace App\Listeners;

use App\Events\PostPublished;

class AwardPostPoints
{
    public function handle(PostPublished $event)
    {
        $post = $event->post;

        // Pontos base
        $post->user->addPoints(100, 'Publicou um artigo');

        // Bônus por qualidade
        if ($post->word_count >= 1000) {
            $post->user->addPoints(50, 'Artigo com mais de 1000 palavras');
        }

        // Bônus por categoria
        if ($post->category === 'tutorial') {
            $post->user->addPoints(25, 'Tutorial técnico');
        }
    }
}

Passo 3: Registrar Listeners

// EventServiceProvider.php
protected $listen = [
    'App\Events\PostPublished' => [
        'App\Listeners\AwardPostPoints',
    ],
];

Como Criar Badges e Conquistas Personalizadas

Estrutura de Badge (em desenvolvimento)

// Migration já preparada: 2020_09_18_231619_create_gamer_badges_tables.php

// Model customizado
class Badge extends Model
{
    protected $fillable = ['name', 'description', 'icon', 'points_required'];

    public function users()
    {
        return $this->belongsToMany(User::class, 'user_badges')
            ->withTimestamps();
    }
}

// Lógica de desbloqueio
class BadgeService
{
    public function checkAndUnlock($user, $badgeSlug)
    {
        $badge = Badge::where('slug', $badgeSlug)->first();

        if ($user->currentPoints() >= $badge->points_required) {
            $user->badges()->attach($badge);
            event(new BadgeUnlocked($user, $badge));
        }
    }
}

Como Conectar o Gamer a Eventos e Listeners Existentes

Usando Observers

<?php

namespace App\Observers;

use App\Models\Comment;

class CommentObserver
{
    public function created(Comment $comment)
    {
        // Pontos para quem comentou
        $comment->user->addPoints(5, 'Comentou em um post');

        // Pontos para o autor do post
        $comment->post->author->addPoints(2, 'Recebeu um comentário');
    }
}

// AppServiceProvider.php
public function boot()
{
    Comment::observe(CommentObserver::class);
}

Usando Event Subscribers

<?php

namespace App\Listeners;

use Illuminate\Events\Dispatcher;

class GamificationSubscriber
{
    public function onUserLogin($event)
    {
        $event->user->addPoints(10, 'Login diário');
    }

    public function onProfileUpdate($event)
    {
        if ($event->user->profile->isComplete()) {
            $event->user->addPoints(50, 'Completou o perfil');
        }
    }

    public function subscribe(Dispatcher $events)
    {
        $events->listen(
            'Illuminate\Auth\Events\Login',
            'App\Listeners\GamificationSubscriber@onUserLogin'
        );

        $events->listen(
            'App\Events\ProfileUpdated',
            'App\Listeners\GamificationSubscriber@onProfileUpdate'
        );
    }
}

Boas Práticas de Integração

1. Separe a lógica de pontuação

   • Use Listeners/Subscribers para manter controllers limpos
   • Centralize regras de negócio em Services

2. Documente regras de pontuação

   /**
    * Pontuação de Artigos:
    * - Publicação: 100 pontos
    * - +1000 palavras: +50 pontos
    * - Categoria Tutorial: +25 pontos
    * - Primeiro artigo: +100 pontos (badge)
    */

3. Use transações de banco de dados

   DB::transaction(function () use ($user, $order) {
       $order->save();
       $user->addPoints(100, 'Nova compra');
   });

4. Valide dados antes de atribuir pontos

   if ($user->hasVerifiedEmail() && !$user->isBanned()) {
       $user->addPoints(50, 'Ação válida');
   }

🔗 Integração com o Ecossistema SierraTecnologia

Módulos do Ecossistema

O Gamer integra-se nativamente com:

1. Tracking (sierratecnologia/tracking)

• Rastreamento de ações do usuário
• Analytics de progressão
• Métricas de engajamento

// Provider já registra Tracking automaticamente
public static $providers = [
    \Tracking\TrackingProvider::class,
    // ...
];

2. Finder (sierratecnologia/finder)

• Busca avançada de pontos e transações
• Indexação Elasticsearch para rankings
• Pesquisa full-text de conquistas

3. Informate (Notificações)

• Notificações de novas conquistas
• Alertas de mudança de nível
• Resumos de progresso

use Gamer\Notifications\BadgeUnlocked;

$user->notify(new BadgeUnlocked($badge));

4. Market (E-commerce)

• Pontos por compras
• Sistema de cashback em pontos
• Loja de recompensas

// Exemplo de integração
Event::listen('Market\Events\OrderCompleted', function($event) {
    $order = $event->order;
    $points = $order->total * 0.05; // 5% cashback

    $order->customer->addPoints(
        $points,
        'Cashback da compra #' . $order->id,
        ['order_id' => $order->id]
    );
});

5. Audit (Auditoria)

• Rastreamento completo de mudanças em pontos
• Logs de transações suspeitas
• Histórico de correções

Padrões Compartilhados

Event Sourcing com Spatie

// config/event-sourcing.php (publicado pelo Gamer)
return [
    'stored_event_model' => \Spatie\EventSourcing\StoredEvents\Models\EloquentStoredEvent::class,
    'stored_event_repository' => \Spatie\EventSourcing\StoredEvents\Repositories\EloquentStoredEventRepository::class,
    // ...
];

Base Models (Pedreiro)

use Pedreiro\Models\Base;

class Point extends Base
{
    // Herda funcionalidades comuns: slugs, UUIDs, soft deletes, etc.
}

Padrões de CI/CD

Todos os módulos SierraTecnologia seguem:

• PSR-12 para estilo de código
• PHPUnit para testes
• PHPStan nível 8 para análise estática
• Psalm para verificação de tipos
• GitHub Actions para CI/CD

Versionamento Semântico

O Gamer segue Semantic Versioning 2.0.0:

• MAJOR (0.x.0): Breaking changes
• MINOR (0.4.x): Novas funcionalidades (compatível)
• PATCH (0.4.4): Correções de bugs

Versão atual: 0.4.4 (stable)

🛠️ Extensão e Customização

Como Criar Novos Tipos de Conquistas

Passo 1: Criar Model de Conquista

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Achievement extends Model
{
    protected $fillable = [
        'name',
        'description',
        'type', // 'points', 'actions', 'streak', 'level'
        'requirement',
        'reward_points',
        'icon',
    ];

    protected $casts = [
        'requirement' => 'array',
    ];

    public function users()
    {
        return $this->belongsToMany(User::class, 'user_achievements')
            ->withPivot('unlocked_at', 'progress')
            ->withTimestamps();
    }
}

Passo 2: Criar Service de Verificação

<?php

namespace App\Services;

use App\Models\Achievement;

class AchievementService
{
    public function checkAchievements($user)
    {
        $achievements = Achievement::all();

        foreach ($achievements as $achievement) {
            if ($this->meetsRequirement($user, $achievement)) {
                $this->unlock($user, $achievement);
            }
        }
    }

    protected function meetsRequirement($user, $achievement)
    {
        switch ($achievement->type) {
            case 'points':
                return $user->currentPoints() >= $achievement->requirement['min_points'];

            case 'actions':
                $count = $user->transactions()
                    ->where('message', 'like', '%' . $achievement->requirement['action'] . '%')
                    ->count();
                return $count >= $achievement->requirement['count'];

            case 'streak':
                return $this->checkLoginStreak($user, $achievement->requirement['days']);

            default:
                return false;
        }
    }

    protected function unlock($user, $achievement)
    {
        if ($user->achievements()->where('achievement_id', $achievement->id)->exists()) {
            return; // Já desbloqueada
        }

        $user->achievements()->attach($achievement, [
            'unlocked_at' => now(),
        ]);

        // Recompensa
        if ($achievement->reward_points > 0) {
            $user->addPoints(
                $achievement->reward_points,
                'Conquista desbloqueada: ' . $achievement->name
            );
        }

        // Notificar
        $user->notify(new \App\Notifications\AchievementUnlocked($achievement));
    }
}

Como Personalizar a Lógica de Progressão

Sistema de Níveis

<?php

namespace App\Services;

class LevelService
{
    protected $levels = [
        1 => ['min' => 0, 'max' => 100, 'title' => 'Novato'],
        2 => ['min' => 100, 'max' => 300, 'title' => 'Iniciante'],
        3 => ['min' => 300, 'max' => 700, 'title' => 'Intermediário'],
        4 => ['min' => 700, 'max' => 1500, 'title' => 'Avançado'],
        5 => ['min' => 1500, 'max' => 3000, 'title' => 'Expert'],
        6 => ['min' => 3000, 'max' => PHP_INT_MAX, 'title' => 'Master'],
    ];

    public function getCurrentLevel($user)
    {
        $points = $user->currentPoints();

        foreach ($this->levels as $level => $config) {
            if ($points >= $config['min'] && $points < $config['max']) {
                return [
                    'level' => $level,
                    'title' => $config['title'],
                    'current_points' => $points,
                    'next_level_at' => $config['max'],
                    'progress' => $this->calculateProgress($points, $config),
                ];
            }
        }
    }

    protected function calculateProgress($points, $config)
    {
        $range = $config['max'] - $config['min'];
        $current = $points - $config['min'];

        return min(100, ($current / $range) * 100);
    }
}

Recomendações para Manter Compatibilidade

1. Não modifique tabelas core do Gamer

   • Use migrations separadas para extensões
   • Prefira relacionamentos polimórficos

2. Estenda em vez de modificar

   // ❌ Evite modificar Transaction.php
   
   // ✅ Crie seu próprio modelo
   class CustomTransaction extends \Gamer\Models\Transaction
   {
       public function customMethod() { ... }
   }

3. Use eventos para customizações

   Event::listen('gamer.points.added', function($transaction) {
       // Sua lógica customizada
   });

4. Namespace suas extensões

   namespace App\Gamer\Extensions;
   
   class CustomPointType extends PointType { ... }

📊 Exemplos Reais

Caso de Uso 1: Plataforma Educacional

Contexto: Plataforma de cursos online da SierraTecnologia

Implementação:

// Pontos por assistir aulas
Event::listen('Course\Events\LessonCompleted', function($event) {
    $event->user->addPoints(10, 'Completou aula: ' . $event->lesson->title);
});

// Pontos por concluir curso
Event::listen('Course\Events\CourseCompleted', function($event) {
    $points = 100 + ($event->course->lessons_count * 5);
    $event->user->addPoints($points, 'Concluiu curso: ' . $event->course->title);
});

Resultados:

• ⬆️ +45% de conclusão de cursos após implementação
• ⬆️ +60% de tempo médio na plataforma
• ⬆️ +30% de cursos iniciados por usuário

Caso de Uso 2: Marketplace Gamificado

Contexto: E-commerce B2C integrado com Market

Resultados:

• ⬆️ +25% de repeat purchase rate
• ⬆️ +40% de valor médio do carrinho
• ⬆️ +80% de engajamento de vendedores

🧪 Configuração de Ferramentas de Qualidade

PHPUnit - Testes Automatizados

Executar testes:

# Todos os testes
vendor/bin/phpunit

# Com coverage HTML
vendor/bin/phpunit --coverage-html coverage

# Teste específico
vendor/bin/phpunit --filter PointableTest

PHPCS - Padrão PSR-12

Executar verificação:

# Verificar código
vendor/bin/phpcs

# Corrigir automaticamente
vendor/bin/phpcbf

# Verificar arquivo específico
vendor/bin/phpcs src/Models/Transaction.php

PHPStan - Análise Estática (Nível 8)

Executar análise:

# Análise completa
vendor/bin/phpstan analyse

# Nível específico
vendor/bin/phpstan analyse --level=6

# Com baseline
vendor/bin/phpstan analyse --generate-baseline

PHPMD - Boas Práticas

Executar PHPMD:

# Análise completa
vendor/bin/phpmd src text phpmd.xml

# Formato HTML
vendor/bin/phpmd src html phpmd.xml --reportfile phpmd-report.html

Psalm - Verificação de Tipos

# Executar Psalm
vendor/bin/psalm

# Corrigir automaticamente
vendor/bin/psalm --alter --issues=MissingReturnType,MissingParamType

👥 Guia de Contribuição

Como Contribuir

Contribuições são muito bem-vindas! Para contribuir com o Gamer:

1. Fork o repositório
2. Crie uma branch para sua feature (git checkout -b feature/nova-funcionalidade)
3. Commit suas mudanças seguindo os padrões
4. Push para a branch (git push origin feature/nova-funcionalidade)
5. Abra um Pull Request

Padrões de Commits

Seguimos Conventional Commits:

<tipo>[escopo opcional]: <descrição>

Tipos:

• feat: Nova funcionalidade
• fix: Correção de bug
• docs: Documentação
• style: Formatação (não afeta código)
• refactor: Refatoração
• test: Testes
• chore: Manutenção

Exemplos:

git commit -m "feat(points): adicionar multiplicador de pontos por nível"
git commit -m "fix(transaction): corrigir cálculo de saldo negativo"
git commit -m "docs(readme): atualizar exemplos de uso"

Padrões de Branches

• main - Branch principal (protegida)
• develop - Branch de desenvolvimento
• feature/<nome> - Novas funcionalidades
• fix/<nome> - Correções de bugs
• hotfix/<nome> - Correções urgentes
• release/<versão> - Preparação de releases

Versionamento Semântico

Seguimos SemVer 2.0.0:

• MAJOR (1.0.0): Breaking changes
• MINOR (0.1.0): Novas funcionalidades (compatível)
• PATCH (0.0.1): Correções de bugs

Execução Local das Ferramentas

# Instalar dependências
composer install

# Executar testes
composer test

# Verificar código
vendor/bin/phpcs
vendor/bin/phpstan analyse
vendor/bin/psalm
vendor/bin/phpmd src text phpmd.xml

# Corrigir código automaticamente
composer format
vendor/bin/phpcbf

Checklist de Pull Request

Antes de submeter um PR, verifique:

• Código segue PSR-12
• Testes passam (composer test)
• PHPStan nível 8 sem erros
• PHPCS sem violações
• Documentação atualizada
• CHANGELOG.md atualizado
• Commits seguem padrão Conventional Commits
• Branch atualizada com develop

Changelog

Refer to the Changelog for a full history of the project.

Support

The following support channels are available at your fingertips:

• Chat on Slack
• Help on Email
• Follow on Twitter

Contributing & Protocols

Thank you for considering contributing to this project! The contribution guide can be found in CONTRIBUTING.md.

Bug reports, feature requests, and pull requests are very welcome.

• Versioning
• Pull Requests
• Coding Standards
• Feature Requests
• Git Flow

Security Vulnerabilities

If you discover a security vulnerability within this project, please send an e-mail to [e-mail]. All security vulnerabilities will be promptly addressed.

About SierraTecnologia

SierraTecnologia is a software solutions startup, specialized in integrated enterprise solutions for SMEs established in Rio de Janeiro, Brazil since June 2008. We believe that our drive The Value, The Reach, and The Impact is what differentiates us and unleash the endless possibilities of our philosophy through the power of software. We like to call it Innovation At The Speed Of Life. That's how we do our share of advancing humanity.

License

This software is released under The MIT License (MIT).

(c) 2008-2020 SierraTecnologia, Some rights reserved.