README

SierraTecnologia Fabrica fabrica is all of freelancer developer need. Validator functionality, and basic controller included out-of-the-box.

📚 Índice

• Introdução
• Instalação
• Arquitetura e Estrutura Interna
• Principais Funcionalidades
• Uso Prático
• Integração com o Ecossistema SierraTecnologia
• Extensão e Customização
• Exemplos Reais
• Ferramentas de Qualidade
• Guia de Contribuição

🎯 Introdução

O Fábrica é o núcleo de automação e scaffolding da SierraTecnologia / Rica Soluções, projetado para acelerar e padronizar a criação de módulos, serviços, entidades e recursos Laravel dentro do ecossistema da empresa.

O que é o Fábrica?

Fábrica é uma CLI inteligente e framework interno que atua como uma fábrica de código, automatizando tarefas repetitivas de desenvolvimento e garantindo consistência arquitetural entre todos os projetos da organização.

Objetivo e Motivação

• Acelerar o desenvolvimento: Reduzir drasticamente o tempo gasto em scaffolding manual
• Padronizar arquitetura: Garantir que todos os projetos sigam os mesmos padrões e melhores práticas
• Reduzir erros: Eliminar inconsistências causadas por criação manual de código
• Facilitar manutenção: Código gerado seguindo padrões facilita a manutenção por diferentes desenvolvedores

Importância no Ecossistema

O Fábrica é fundamental para o ecossistema SierraTecnologia pois:

• Serve como base para geração de recursos em todos os projetos internos
• Integra-se nativamente com outros pacotes do ecossistema (Facilitador, Finder, Market, CMS)
• Mantém a coesão arquitetural entre diferentes times e projetos
• Acelera a entrega de novos módulos e funcionalidades

📦 Instalação

Requisitos Mínimos

• PHP: ^8.1 ou superior
• Laravel: ^8.0, ^9.0, ^10.0 ou ^11.0
• Composer: ^2.0

Instalação via Composer

composer require sierratecnologia/fabrica

Publicação de Arquivos de Configuração

Após a instalação, publique os arquivos de configuração:

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

# Publicar views (opcional)
php artisan vendor:publish --provider="Fabrica\FabricaProvider" --tag="views"

# Publicar traduções (opcional)
php artisan vendor:publish --provider="Fabrica\FabricaProvider" --tag="translations"

# Publicar todos os recursos
php artisan vendor:publish --provider="Fabrica\FabricaProvider"

Registro Automático de Service Providers

O Fábrica utiliza auto-discovery do Laravel. O FabricaProvider é registrado automaticamente.

Caso necessário, registre manualmente em config/app.php:

'providers' => [
    // ...
    Fabrica\FabricaProvider::class,
],

Configuração

O arquivo de configuração é publicado em config/sitec/fabrica.php. Customize conforme necessário:

<?php

return [
    // Configurações personalizadas do Fábrica
    // (expandir conforme necessidades do projeto)
];

🏗️ Arquitetura e Estrutura Interna

Estrutura de Diretórios

fabrica/
├── src/
│   ├── Acl/                    # Sistema de ACL (Access Control List)
│   ├── ActiveDirectory/        # Integração com LDAP/Active Directory
│   ├── Bundle/                 # Bundles do sistema
│   │   ├── CoreBundle/        # Bundle principal
│   │   ├── DistributionBundle/# Bundle de distribuição
│   │   ├── JobBundle/         # Sistema de jobs
│   │   └── WebsiteBundle/     # Bundle web
│   ├── Component/             # Componentes reutilizáveis
│   │   ├── Config/           # Gerenciamento de configuração
│   │   ├── Pagination/       # Sistema de paginação
│   │   └── Requirements/     # Verificação de requisitos
│   ├── Console/              # Comandos Artisan
│   │   └── Commands/        # Comandos customizados
│   ├── Contracts/            # Interfaces e contratos
│   ├── Events/               # Eventos do sistema
│   ├── Exceptions/           # Exceções customizadas
│   ├── Facades/              # Facades do Laravel
│   ├── Http/                 # Camada HTTP
│   │   ├── Api/             # Controllers API
│   │   └── Controllers/     # Controllers web
│   ├── Listeners/            # Event Listeners
│   ├── Models/               # Modelos Eloquent
│   │   ├── Planning/        # Modelos de planejamento (Sprint, etc)
│   │   └── Workflow/        # Modelos de workflow
│   ├── Observers/            # Model Observers
│   ├── Project/              # Gerenciamento de projetos
│   ├── QA/                   # Quality Assurance
│   ├── Services/             # Camada de serviços
│   ├── Traits/               # Traits reutilizáveis
│   ├── Utils/                # Utilitários
│   ├── Workflow/             # Sistema de workflow
│   └── FabricaProvider.php   # Service Provider principal
├── database/
│   └── migrations/           # Migrations do banco de dados
├── publishes/
│   ├── assets/              # Assets publicáveis
│   └── config/              # Configurações publicáveis
├── resources/
│   ├── lang/                # Traduções
│   └── views/               # Views Blade
├── routes/                  # Arquivos de rotas
├── tests/                   # Testes automatizados
│   ├── Feature/            # Testes de features
│   └── Unit/               # Testes unitários
└── composer.json

Padrões de Design

O Fábrica implementa diversos padrões de design para garantir código limpo e manutenível:

1. Service Provider Pattern

Utiliza o sistema de Service Providers do Laravel para registro de serviços, rotas e recursos.

class FabricaProvider extends ServiceProvider
{
    public function register()
    {
        // Registro de serviços
        $this->app->singleton(FabricaService::class, function ($app) {
            return new FabricaService(config('sitec.fabrica'));
        });
    }

    public function boot()
    {
        // Bootstrap de recursos
        $this->registerDirectories();
        $this->routes();
        $this->loadLogger();
    }
}

2. Repository Pattern

Abstração da camada de dados para facilitar testes e manutenção.

3. Service Layer Pattern

Lógica de negócio encapsulada em classes de serviço.

4. Observer Pattern

Utilização de Observers para reação a eventos de modelos.

5. Facade Pattern

Facades para acesso simplificado a serviços complexos.

Relação entre Componentes

┌─────────────────────────────────────────────────────┐
│                   Laravel App                        │
└─────────────────────┬───────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────┐
│              FabricaProvider                         │
│  ┌──────────────────────────────────────────────┐   │
│  │  - Registro de Serviços                      │   │
│  │  - Carregamento de Rotas                     │   │
│  │  - Publicação de Assets                      │   │
│  │  - Registro de Comandos Artisan              │   │
│  └──────────────────────────────────────────────┘   │
└─────────┬────────────────────────────────┬──────────┘
          │                                │
┌─────────▼─────────┐           ┌──────────▼──────────┐
│   Services        │           │   Commands          │
│  ┌──────────────┐ │           │  ┌───────────────┐  │
│  │FabricaService│ │           │  │ Sync Commands │  │
│  └──────────────┘ │           │  └───────────────┘  │
└───────────────────┘           └─────────────────────┘
          │                                │
┌─────────▼─────────────────────────────────▼─────────┐
│              Models & Repositories                   │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐          │
│  │ Sprint   │  │ Workflow │  │ Project  │  ...     │
│  └──────────┘  └──────────┘  └──────────┘          │
└──────────────────────────────────────────────────────┘

Boas Práticas de Modularização

• Separação de responsabilidades: Cada namespace tem uma responsabilidade clara
• Injeção de dependências: Utilização extensiva de DI para facilitar testes
• Contratos (Interfaces): Definição de contratos para componentes críticos
• Eventos: Comunicação entre componentes via eventos
• Traits: Reutilização de código através de traits

🚀 Principais Funcionalidades

1. Geração Automática de Código

O Fábrica fornece comandos para geração automática de:

• Models: Modelos Eloquent com configurações pré-definidas
• Controllers: Controllers RESTful ou personalizados
• Requests: Form Requests com validação
• Services: Classes de serviço para lógica de negócio
• Repositories: Implementação do padrão Repository
• Tests: Testes unitários e de integração

2. Sistema de Workflow

Gerenciamento completo de workflows:

use Fabrica\Models\Workflow\Workflow;
use Fabrica\Models\Workflow\WorkflowItemType;
use Fabrica\Models\Workflow\Transaction;

// Criar um novo workflow
$workflow = Workflow::create([
    'name' => 'Desenvolvimento de Features',
    'description' => 'Workflow padrão para desenvolvimento'
]);

// Adicionar estágios
$workflow->stages()->create([
    'name' => 'Backlog',
    'order' => 1
]);

3. Sistema de Planejamento

Gerenciamento de sprints e planejamento ágil:

use Fabrica\Models\Planning\Sprint;

$sprint = Sprint::create([
    'name' => 'Sprint 23',
    'init' => now(),
    'end' => now()->addWeeks(2),
    'order' => 23
]);

4. Sistema de ACL

Controle de acesso baseado em papéis e permissões:

use Fabrica\Acl\Acl;
use Fabrica\Acl\Eloquent\Role;

// Verificar permissões
if (Acl::check($user, 'fabrica.projects.create')) {
    // Usuário tem permissão
}

5. Integração com Active Directory

Suporte para autenticação e sincronização com LDAP/AD.

6. Sistema de Jobs

Gerenciamento de tarefas assíncronas e background jobs.

7. API RESTful

Controllers e rotas pré-configuradas para APIs RESTful.

💻 Uso Prático

Exemplo 1: Gerando um Novo Módulo "Pedidos"

# Sincronizar pacotes (se disponível)
php artisan fabrica:sync:packages

# Estrutura manual (exemplo de organização)
# 1. Criar Model
# app/Models/Pedido.php

# 2. Criar Migration
php artisan make:migration create_pedidos_table

# 3. Criar Controller
# app/Http/Controllers/PedidoController.php

# 4. Criar Service
# app/Services/PedidoService.php

# 5. Criar Requests
# app/Http/Requests/PedidoStoreRequest.php
# app/Http/Requests/PedidoUpdateRequest.php

Exemplo 2: Usando o Sistema de Workflow

use Fabrica\Models\Workflow\Workflow;
use Fabrica\Models\Workflow\WorkflowItemType;

// 1. Criar tipo de item de workflow
$itemType = WorkflowItemType::create([
    'name' => 'Feature',
    'description' => 'Nova funcionalidade'
]);

// 2. Criar workflow
$workflow = Workflow::create([
    'name' => 'Desenvolvimento Ágil',
    'item_type_id' => $itemType->id
]);

// 3. Adicionar estágios
$stages = [
    ['name' => 'Backlog', 'order' => 1],
    ['name' => 'Em Desenvolvimento', 'order' => 2],
    ['name' => 'Em Revisão', 'order' => 3],
    ['name' => 'Concluído', 'order' => 4],
];

foreach ($stages as $stageData) {
    $workflow->stages()->create($stageData);
}

Exemplo 3: Personalização de Templates

// publishes/config/sitec/fabrica.php
return [
    'templates' => [
        'model' => base_path('stubs/fabrica/model.stub'),
        'controller' => base_path('stubs/fabrica/controller.stub'),
    ],
    'namespace' => [
        'models' => 'App\\Models',
        'controllers' => 'App\\Http\\Controllers',
    ],
];

Exemplo 4: Integração com CI/CD

# .github/workflows/ci.yml
name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: 8.2
      - run: composer install
      - run: vendor/bin/phpunit
      - run: vendor/bin/phpstan analyse
      - run: vendor/bin/phpcs

🔗 Integração com o Ecossistema SierraTecnologia

O Fábrica integra-se nativamente com outros pacotes do ecossistema:

Integração com Facilitador

// O Fábrica utiliza traits do Facilitador
use Muleta\Traits\Providers\ConsoleTools;

class FabricaProvider extends ServiceProvider
{
    use ConsoleTools;

    // Métodos fornecidos pelo ConsoleTools
}

Integração com Operador

// Dependência no composer.json
"sierratecnologia/operador": "^0.4"

Integração com Integrations

// Sistema de integrações externas
"sierratecnologia/integrations": "^0.4"

Integração com Muleta

// Biblioteca de utilitários compartilhados
"sierratecnologia/muleta": "^0.4.0"

Práticas Compartilhadas

1. Padronização de Namespaces: Todos os pacotes seguem SierraTecnologia\{Package}
2. Service Providers: Padrão consistente de registro de serviços
3. Configurações: Estrutura config/sitec/{package}.php
4. Views: Namespace de views {package}::{view}
5. Rotas: Prefixo e nomenclatura padronizados

Pipelines de Build

# Script comum para todos os pacotes
composer install
composer test          # PHPUnit
composer psalm         # Psalm
vendor/bin/phpstan analyse
vendor/bin/phpcs --standard=PSR12

🔧 Extensão e Customização

Como Criar Novos Templates (Stubs)

1. Criar diretório de stubs:

mkdir -p stubs/fabrica

1. Criar template de modelo:

// stubs/fabrica/model.stub
<?php

namespace {{ namespace }};

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\SoftDeletes;

class {{ class }} extends Model
{
    use SoftDeletes;

    protected $fillable = [
        {{ fillable }}
    ];

    protected $casts = [
        {{ casts }}
    ];
}

1. Configurar no arquivo de config:

// config/sitec/fabrica.php
return [
    'stubs' => [
        'model' => base_path('stubs/fabrica/model.stub'),
    ],
];

Como Adicionar Comandos Artisan Personalizados

1. Criar comando:

// app/Console/Commands/FabricaCustomCommand.php
namespace App\Console\Commands;

use Illuminate\Console\Command;

class FabricaCustomCommand extends Command
{
    protected $signature = 'fabrica:custom {name}';
    protected $description = 'Comando customizado do Fábrica';

    public function handle()
    {
        $name = $this->argument('name');
        $this->info("Processando: {$name}");

        // Sua lógica aqui
    }
}

1. Registrar no Provider:

// app/Providers/AppServiceProvider.php
public function boot()
{
    if ($this->app->runningInConsole()) {
        $this->commands([
            \App\Console\Commands\FabricaCustomCommand::class,
        ]);
    }
}

Como Sobrescrever Classes Base

// app/Services/CustomFabricaService.php
namespace App\Services;

use Fabrica\Services\FabricaService;

class CustomFabricaService extends FabricaService
{
    public function customMethod()
    {
        // Nova funcionalidade
    }

    public function generate($type, $name)
    {
        // Sobrescrever método base
        parent::generate($type, $name);

        // Adicionar lógica customizada
        $this->customMethod();
    }
}

// app/Providers/AppServiceProvider.php
public function register()
{
    $this->app->singleton(FabricaService::class, function ($app) {
        return new CustomFabricaService(config('sitec.fabrica'));
    });
}

📊 Exemplos Reais

Caso de Uso 1: Criação de Sistema de Tickets

Antes do Fábrica (tempo estimado: 2-3 horas):

• Criar manualmente Model, Migration, Controller
• Configurar validações
• Criar testes
• Implementar Repository
• Configurar rotas

Depois do Fábrica (tempo estimado: 15 minutos):

# Comandos automáticos gerariam toda estrutura
# (exemplo conceitual - adaptar conforme comandos disponíveis)
php artisan fabrica:module Ticket --with-tests --with-api

Caso de Uso 2: Padronização de Projetos

Benefício: Todos os 15 projetos internos da SierraTecnologia seguem a mesma estrutura:

project/
├── app/
│   ├── Models/          # Gerados pelo Fábrica
│   ├── Services/        # Gerados pelo Fábrica
│   └── Http/
│       └── Controllers/ # Gerados pelo Fábrica
├── tests/               # Gerados pelo Fábrica
└── config/
    └── sitec/           # Padrão SierraTecnologia

Caso de Uso 3: Onboarding de Novos Desenvolvedores

Antes: 2-3 semanas para entender padrões de código

Depois: 3-5 dias com código gerado padronizado e documentação integrada

Métricas de Impacto

• Redução de tempo: 70% menos tempo em scaffolding
• Consistência: 100% dos projetos seguem os mesmos padrões
• Qualidade: Redução de 60% em bugs relacionados a estrutura
• Produtividade: Desenvolvedores focam em lógica de negócio, não em boilerplate

🛠️ Ferramentas de Qualidade

PHPUnit - Testes Automatizados

# Executar todos os testes
vendor/bin/phpunit

# Executar testes com cobertura
vendor/bin/phpunit --coverage-html coverage

# Executar apenas testes unitários
vendor/bin/phpunit --testsuite "Fabrica Unit Tests"

# Executar apenas testes de feature
vendor/bin/phpunit --testsuite "Fabrica Feature Tests"

Configuração: phpunit.xml

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

# Analisar código
vendor/bin/phpstan analyse

# Analisar com relatório detalhado
vendor/bin/phpstan analyse --error-format=table

# Gerar baseline (para projetos legados)
vendor/bin/phpstan analyse --generate-baseline

Configuração: phpstan.neon

PHP_CodeSniffer - Padrão PSR-12

# Verificar código
vendor/bin/phpcs

# Verificar arquivos específicos
vendor/bin/phpcs src/

# Corrigir automaticamente
vendor/bin/phpcbf

# Relatório detalhado
vendor/bin/phpcs --report=summary

Configuração: phpcs.xml

Psalm - Análise de Tipos

# Executar Psalm
vendor/bin/psalm

# Com relatório de progresso
vendor/bin/psalm --show-info=true

# Modo rigoroso
vendor/bin/psalm --show-info=true --no-cache

Configuração: psalm.xml

PHPMD - PHP Mess Detector

# Analisar código
vendor/bin/phpmd src/ text phpmd.xml

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

# Apenas regras específicas
vendor/bin/phpmd src/ text cleancode,codesize

Configuração: phpmd.xml

GrumPHP - Git Hooks

GrumPHP executa automaticamente verificações antes de commits:

# Instalado via composer
# Hooks configurados automaticamente

# Executar manualmente
vendor/bin/grumphp run

# Pular verificações (não recomendado)
git commit --no-verify

Configuração: grumphp.yml

GitHub Actions - CI/CD

Workflows configurados em .github/workflows/:

• ci.yml: Pipeline completo (testes, qualidade, segurança)
• run-tests.yml: Testes em múltiplas versões PHP/Laravel
• php-cs-fixer.yml: Verificação e correção de estilo
• psalm.yml: Análise estática

🤝 Guia de Contribuição

Como Contribuir

1. Fork o repositório

2. Clone seu fork:

   git clone https://github.com/seu-usuario/fabrica.git
   cd fabrica

3. Crie uma branch:

   git checkout -b feature/nova-funcionalidade

4. Faça suas alterações

5. Execute as ferramentas de qualidade:

   composer test
   vendor/bin/phpstan analyse
   vendor/bin/phpcs
   vendor/bin/psalm

6. Commit suas mudanças:

   git add .
   git commit -m "feat: adiciona nova funcionalidade X"

7. Push para seu fork:

   git push origin feature/nova-funcionalidade

8. Abra um Pull Request

Padrões de Commits

Seguimos Conventional Commits:

<tipo>(<escopo>): <descrição>

[corpo opcional]

[rodapé opcional]

Tipos:

• feat: Nova funcionalidade
• fix: Correção de bug
• docs: Documentação
• style: Formatação (sem mudança de código)
• refactor: Refatoração
• test: Testes
• chore: Tarefas de build, configs, etc

Exemplos:

feat(workflow): adiciona sistema de aprovação em workflows
fix(models): corrige relacionamento em Sprint model
docs(readme): atualiza documentação de instalação
test(unit): adiciona testes para FabricaService

Padrões de Branches

• main / master: Produção
• develop: Desenvolvimento
• feature/*: Novas funcionalidades
• fix/*: Correções de bugs
• hotfix/*: Correções urgentes
• release/*: Preparação de releases

Execução Local das Ferramentas

# Instalar dependências
composer install

# Executar testes
composer test

# Verificar estilo de código
vendor/bin/phpcs

# Corrigir estilo
vendor/bin/phpcbf

# Análise estática PHPStan
vendor/bin/phpstan analyse

# Análise estática Psalm
vendor/bin/psalm

# PHP Mess Detector
vendor/bin/phpmd src/ text phpmd.xml

# Executar todas as verificações (via GrumPHP)
vendor/bin/grumphp run

Processo de Code Review

1. Automated checks: GitHub Actions executa automaticamente
2. Code review: Pelo menos 1 aprovação necessária
3. Tests: Todos os testes devem passar
4. Quality gates: PHPStan nível 8, PHPCS PSR-12, cobertura mínima

Reportando Issues

Ao reportar um bug, inclua:

• Versão do PHP
• Versão do Laravel
• Versão do Fábrica
• Passos para reproduzir
• Comportamento esperado vs atual
• Stacktrace (se aplicável)

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 help@sierratecnologia.com.br. 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.