@codigodoleo/wp-kit 1.0.0

package/modules/docs/templates/docs/Desenvolvimento.md

@@ -0,0 +1,1116 @@
+# 💻 Desenvolvimento
+
+Guia completo de desenvolvimento para o projeto Pipefy Website, com foco em qualidade, padrões e boas práticas profissionais.
+
+## 🌊 **Git Workflow (GitFlow Modificado)**
+
+### **Estratégia de Branching**
+
+Nossa estratégia é baseada no **GitFlow**, com uma modificação importante: **todas as branches são criadas a partir da `master`** para garantir que features em desenvolvimento não sejam levadas acidentalmente para produção.
+
+```mermaid
+graph LR
+    A[master] --> B[feature/new-feature]
+    A --> C[feature/another-feature]
+    A --> D[hotfix/critical-fix]
+    A --> E[release/v1.2.0]
+    
+    B --> F[MR to development]
+    C --> F
+    E --> G[MR to staging]
+    F --> H[development]
+    G --> I[staging]
+    H --> J[MR to staging]
+    J --> I
+    I --> K[MR to master]
+    K --> L[master]
+    
+    D --> M[MR to master]
+    M --> L
+    D --> N[MR to development]
+    N --> H
+    
+    style A fill:#ff6b6b
+    style H fill:#feca57
+    style I fill:#48dbfb
+    style L fill:#1dd1a1
+```
+
+### **Tipos de Branches**
+
+| Branch Type | Prefixo | Origem | Destino | Merge Via | Finalidade |
+|-------------|---------|--------|---------|-----------|------------|
+| **Feature** | `feature/` | `master` | `development` | **MR** | Novas funcionalidades |
+| **Bugfix** | `bugfix/` | `master` | `development` | **MR** | Correções não-críticas |
+| **Hotfix** | `hotfix/` | `master` | `master` + `development` | **MR** | Correções críticas |
+| **Release** | `release/` | `master` | `staging` → `master` | **MR** | Preparação de releases |
+| **Chore** | `chore/` | `master` | `development` | **MR** | Manutenção, docs, etc. |
+
+### **Nomenclatura de Branches**
+
+```bash
+# ✅ Correto (sempre em inglês)
+feature/user-authentication
+feature/payment-integration
+bugfix/header-responsive-issue
+hotfix/critical-security-patch
+release/v1.2.0
+chore/update-dependencies
+
+# ❌ Incorreto
+feature/autenticacao-usuario
+feature/NewFeature
+bugfix/bug_fix
+feature-payment
+```
+
+## 🔄 **Workflow de Desenvolvimento**
+
+### **1. Criando uma Nova Feature**
+
+```bash
+# 1. Sempre partir da master atualizada
+git checkout master
+git pull origin master
+
+# 2. Criar branch seguindo padrão
+git checkout -b feature/user-profile-enhancement
+
+# 3. Desenvolver com commits bem documentados
+git add .
+git commit -m "feat: add user profile avatar upload functionality"
+
+# 4. Push da branch
+git push origin feature/user-profile-enhancement
+
+# 5. Criar Merge Request para development (OBRIGATÓRIO)
+# Via GitLab interface - NUNCA merge direto
+```
+
+### **2. Fluxo de Merge Requests (Processo Obrigatório)**
+
+```mermaid
+graph TD
+    A[Feature Branch] --> B[Create MR to development]
+    B --> C[Code Review]
+    C --> D{Review Approved?}
+    D -->|No| E[Address Feedback]
+    E --> C
+    D -->|Yes| F[✅ Merge to development via MR]
+    F --> G[Auto Deploy to development-www.pipefy.com]
+    G --> H[QA Testing]
+    H --> I[✅ Create MR: development → staging]
+    I --> J[Code Review + Approval]
+    J --> K[✅ Merge to staging via MR]
+    K --> L[Deploy to staging-www.pipefy.com]
+    L --> M[Final Validation]
+    M --> N[✅ Create MR: staging → master]
+    N --> O[Final Code Review + Approval]
+    O --> P[✅ Merge to master via MR]
+    P --> Q[Deploy to www.pipefy.com]
+    
+    style F fill:#1dd1a1
+    style K fill:#1dd1a1
+    style P fill:#1dd1a1
+```
+
+### **3. Preparação de Release (Via Merge Requests)**
+
+```bash
+# 1. Criar branch de release a partir da master
+git checkout master
+git pull origin master
+git checkout -b release/v1.2.0
+
+# 2. Atualizar versões e changelog
+# - Atualizar version em style.css
+# - Atualizar CHANGELOG.md
+# - Commit de preparação
+
+git add .
+git commit -m "chore: prepare release v1.2.0"
+git push origin release/v1.2.0
+
+# 3. MERGE REQUEST para staging (OBRIGATÓRIO)
+# Via GitLab interface:
+# - Create MR: release/v1.2.0 → staging
+# - Assign reviewers
+# - Wait for approval
+# - Merge via MR
+
+# 4. Após validação em staging, MERGE REQUEST para master (OBRIGATÓRIO)
+# Via GitLab interface:
+# - Create MR: staging → master
+# - Assign senior reviewers
+# - Wait for approval
+# - Merge via MR
+
+# 5. Criar tag (APÓS merge para master)
+git checkout master
+git pull origin master
+git tag -a v1.2.0 -m "Release version 1.2.0"
+git push origin v1.2.0
+```
+
+### **4. Processo de Hotfix (Via Merge Requests)**
+
+```bash
+# 1. Criar hotfix a partir da master
+git checkout master
+git pull origin master
+git checkout -b hotfix/critical-security-patch
+
+# 2. Implementar correção crítica
+git add .
+git commit -m "fix: patch critical security vulnerability in user authentication"
+git push origin hotfix/critical-security-patch
+
+# 3. DUAS Merge Requests simultâneas (OBRIGATÓRIO)
+# 
+# MR 1: hotfix → master (para produção imediata)
+# - Create MR: hotfix/critical-security-patch → master
+# - Assign senior reviewers
+# - Mark as URGENT
+# - Merge after approval
+#
+# MR 2: hotfix → development (para sincronização)
+# - Create MR: hotfix/critical-security-patch → development
+# - Assign reviewers
+# - Merge after MR 1 is completed
+```
+
+## 📋 **Merge Request Guidelines**
+
+### **Template de Merge Request**
+
+```markdown
+## 🎯 Merge Request Title
+Brief description of changes
+
+## 📝 Description
+Detailed description of what this MR does and why.
+
+## 🔗 Related Issues
+- Closes #123
+- Relates to #456
+
+## 🧪 Testing
+- [ ] Unit tests pass
+- [ ] Integration tests pass
+- [ ] Manual testing completed
+- [ ] Tested in local environment
+
+## 📋 Checklist
+- [ ] Code follows project standards
+- [ ] All tests pass
+- [ ] Documentation updated
+- [ ] CHANGELOG.md updated (if user-facing)
+- [ ] No breaking changes (or properly documented)
+
+## 🖼️ Screenshots (if applicable)
+Before/After screenshots for UI changes
+
+## 🚀 Deployment Notes
+Any special deployment considerations
+
+## 👥 Reviewers
+@senior-dev @team-lead
+```
+
+### **Aprovações Obrigatórias por Branch**
+
+| Target Branch | Reviewers Required | Auto-merge | Finalidade |
+|---------------|-------------------|------------|------------|
+| **development** | 1 senior dev | ❌ | Features, bugfixes |
+| **staging** | 2 senior devs | ❌ | Release preparation |
+| **master** | 2 senior devs + 1 lead | ❌ | Production releases |
+
+### **Configuração GitLab (Merge Request Rules)**
+
+```yaml
+# .gitlab/merge_request_templates/default.md
+push_rules:
+  development:
+    required_approvals: 1
+    required_approval_groups: ["senior-developers"]
+    allow_force_push: false
+    
+  staging:
+    required_approvals: 2
+    required_approval_groups: ["senior-developers"]
+    allow_force_push: false
+    require_code_owner_reviews: true
+    
+  master:
+    required_approvals: 2
+    required_approval_groups: ["senior-developers", "tech-leads"]
+    allow_force_push: false
+    require_code_owner_reviews: true
+    dismiss_stale_reviews: true
+```
+
+## 🚫 **Práticas Proibidas**
+
+### **❌ Nunca Fazer**
+
+```bash
+# ❌ PROIBIDO: Merge direto sem MR
+git checkout staging
+git merge development  # NUNCA!
+
+# ❌ PROIBIDO: Push direto para branches protegidas
+git push origin master  # NUNCA!
+
+# ❌ PROIBIDO: Commits diretos em branches protegidas
+git checkout master
+git commit -m "quick fix"  # NUNCA!
+
+# ❌ PROIBIDO: Force push em branches compartilhadas
+git push --force origin development  # NUNCA!
+```
+
+### **✅ Sempre Fazer**
+
+```bash
+# ✅ CORRETO: Sempre via Merge Request
+# 1. Create branch
+git checkout -b feature/my-feature
+
+# 2. Develop and commit
+git commit -m "feat: add new functionality"
+
+# 3. Push branch
+git push origin feature/my-feature
+
+# 4. Create MR via GitLab interface
+# 5. Wait for review and approval
+# 6. Merge via GitLab interface
+```
+
+## 📦 **Gerenciamento de Dependências com Composer**
+
+### **Configuração do Composer**
+
+```json
+{
+    "name": "pipefy/wordpress-website",
+    "description": "Pipefy WordPress Website",
+    "type": "project",
+    "require": {
+        "php": ">=8.0",
+        "composer/installers": "^2.0",
+        "wpackagist-plugin/advanced-custom-fields-pro": "*",
+        "wpackagist-plugin/wp-rocket": "*"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^9.0",
+        "squizlabs/php_codesniffer": "*",
+        "dealerdirect/phpcodesniffer-composer-installer": "*",
+        "wp-coding-standards/wpcs": "*"
+    },
+    "repositories": [
+        {
+            "type": "composer",
+            "url": "https://wpackagist.org"
+        },
+        {
+            "type": "package",
+            "package": {
+                "name": "advanced-custom-fields/advanced-custom-fields-pro",
+                "version": "6.0.0",
+                "type": "wordpress-plugin",
+                "dist": {
+                    "type": "zip",
+                    "url": "https://connect.advancedcustomfields.com/..."
+                }
+            }
+        }
+    ],
+    "extra": {
+        "installer-paths": {
+            "dist/wp-content/plugins/{$name}/": ["type:wordpress-plugin"],
+            "dist/wp-content/themes/{$name}/": ["type:wordpress-theme"]
+        }
+    },
+    "autoload": {
+        "psr-4": {
+            "Pipefy\\": "dist/wp-content/themes/pipefy-2020/inc/"
+        }
+    },
+    "scripts": {
+        "install-plugins": "composer install --no-dev",
+        "test": "phpunit",
+        "lint": "phpcs --standard=WordPress dist/wp-content/themes/pipefy-2020/",
+        "format": "phpcbf --standard=WordPress dist/wp-content/themes/pipefy-2020/"
+    }
+}
+```
+
+### **Instalação de Plugins**
+
+```bash
+# Plugins do repositório WordPress.org
+composer require wpackagist-plugin/contact-form-7
+
+# Plugins premium (configurar repositório privado)
+composer require advanced-custom-fields/advanced-custom-fields-pro
+
+# Plugins de desenvolvimento
+composer require --dev phpunit/phpunit
+
+# Atualizar todas as dependências
+composer update
+
+# Instalar apenas dependências de produção
+composer install --no-dev --optimize-autoloader
+```
+
+### **Estrutura de Plugins Recomendada**
+
+```
+dist/wp-content/
+├── 📂 plugins/                    # Plugins via Composer
+│   ├── 📂 advanced-custom-fields-pro/
+│   ├── 📂 contact-form-7/
+│   └── 📂 wp-rocket/
+├── 📂 mu-plugins/                 # Must-use plugins (custom)
+│   ├── 📄 pipefy-core.php        # Core functionality
+│   ├── 📄 pipefy-security.php    # Security enhancements
+│   └── 📄 pipefy-performance.php # Performance optimizations
+└── 📂 themes/pipefy-2020/
+    └── 📂 vendor/                 # Autoloaded classes
+        └── 📂 composer/
+```
+
+## 🏷️ **Versionamento e Releases**
+
+### **Semantic Versioning (SemVer)**
+
+Seguimos o padrão **SemVer**: `MAJOR.MINOR.PATCH`
+
+```
+v1.2.3
+│ │ │
+│ │ └── PATCH: Bug fixes, hotfixes
+│ └──── MINOR: New features, backward compatible
+└────── MAJOR: Breaking changes, major updates
+```
+
+### **Versionamento do WordPress Core**
+
+```bash
+# Arquivo: dist/wp-content/themes/pipefy-2020/style.css
+/*
+Theme Name: Pipefy 2020
+Description: Custom WordPress theme for Pipefy website
+Version: 1.2.3
+Author: Pipefy Dev Team
+*/
+
+# Arquivo: dist/wp-content/themes/pipefy-2020/functions.php
+define('PIPEFY_THEME_VERSION', '1.2.3');
+
+# Uso no tema
+wp_enqueue_style('pipefy-main', get_theme_file_uri('assets/css/main.css'), [], PIPEFY_THEME_VERSION);
+```
+
+### **Automatização de Releases**
+
+```yaml
+# .gitlab-ci.yml - Job de Release
+create_release:
+  stage: release
+  script:
+    - echo "Creating release v${CI_COMMIT_TAG}"
+    - |
+      # Atualizar version no style.css
+      sed -i "s/Version: .*/Version: ${CI_COMMIT_TAG#v}/" dist/wp-content/themes/pipefy-2020/style.css
+      
+      # Atualizar version no functions.php
+      sed -i "s/PIPEFY_THEME_VERSION', '.*'/PIPEFY_THEME_VERSION', '${CI_COMMIT_TAG#v}'/" dist/wp-content/themes/pipefy-2020/functions.php
+      
+      # Commit das mudanças
+      git add .
+      git commit -m "chore: bump version to ${CI_COMMIT_TAG}"
+      git push origin HEAD:master
+      
+    - echo "Release ${CI_COMMIT_TAG} created successfully"
+  only:
+    - tags
+  when: manual
+```
+
+### **CHANGELOG.md Structure**
+
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- New feature in development
+
+### Changed
+- Improved existing functionality
+
+### Fixed
+- Bug fixes
+
+## [1.2.3] - 2025-06-05
+
+### Added
+- User profile avatar upload functionality
+- Enhanced security measures for file uploads
+- New Gutenberg block for testimonials
+
+### Changed
+- Improved performance of image loading
+- Updated WordPress core to latest version
+- Refactored authentication system
+
+### Fixed
+- Fixed responsive header issue on mobile devices
+- Resolved caching issue with dynamic content
+- Fixed accessibility issues in navigation
+
+### Security
+- Patched XSS vulnerability in contact form
+- Updated dependencies with security fixes
+
+## [1.2.2] - 2025-05-23
+...
+```
+
+## 📝 **Padrões de Código e Nomenclatura**
+
+### **Nomenclatura em Inglês (Obrigatório)**
+
+```php
+// ✅ Correto
+class UserProfileManager {
+    private $userRepository;
+    
+    public function updateUserAvatar($userId, $avatarData) {
+        // implementation
+    }
+    
+    private function validateImageFormat($imageData) {
+        // implementation
+    }
+}
+
+// ❌ Incorreto
+class GerenciadorPerfilUsuario {
+    private $repositorioUsuario;
+    
+    public function atualizarAvatarUsuario($idUsuario, $dadosAvatar) {
+        // implementation
+    }
+}
+```
+
+### **Padrões de Naming Convention**
+
+```php
+// Classes: PascalCase
+class PaymentProcessor {}
+class UserAuthenticationService {}
+
+// Methods/Functions: camelCase
+public function processPayment() {}
+private function validateCreditCard() {}
+
+// Variables: camelCase
+$userName = 'john_doe';
+$isUserLoggedIn = true;
+$paymentGatewayConfig = [];
+
+// Constants: UPPER_SNAKE_CASE
+define('MAX_UPLOAD_SIZE', 5242880);
+const API_BASE_URL = 'https://api.pipefy.com';
+
+// Files: kebab-case
+user-profile-manager.php
+payment-gateway-config.php
+
+// CSS Classes: BEM Methodology
+.user-profile {}
+.user-profile__avatar {}
+.user-profile__avatar--large {}
+.user-profile__info {}
+.user-profile__info--highlighted {}
+```
+
+### **BEM (Block Element Modifier) CSS**
+
+```scss
+// Block: componente independente
+.hero-section {
+    padding: 2rem;
+    background: #fff;
+    
+    // Element: parte do block
+    &__title {
+        font-size: 2.5rem;
+        font-weight: bold;
+        color: #333;
+    }
+    
+    &__subtitle {
+        font-size: 1.2rem;
+        color: #666;
+    }
+    
+    &__button {
+        padding: 1rem 2rem;
+        background: #007cba;
+        color: white;
+        border: none;
+        
+        // Modifier: variação do element
+        &--large {
+            padding: 1.5rem 3rem;
+            font-size: 1.2rem;
+        }
+        
+        &--secondary {
+            background: #666;
+            color: white;
+        }
+    }
+    
+    // Modifier: variação do block
+    &--dark-theme {
+        background: #333;
+        color: white;
+        
+        .hero-section__title {
+            color: white;
+        }
+    }
+}
+```
+
+### **DRY (Don't Repeat Yourself) Principles**
+
+```php
+// ❌ Código repetitivo
+class UserController {
+    public function updateProfile($userId, $data) {
+        $user = get_user_by('ID', $userId);
+        if (!$user) {
+            wp_send_json_error('User not found', 404);
+            return;
+        }
+        
+        if (!current_user_can('edit_user', $userId)) {
+            wp_send_json_error('Insufficient permissions', 403);
+            return;
+        }
+        
+        // Update logic
+    }
+    
+    public function deleteProfile($userId) {
+        $user = get_user_by('ID', $userId);
+        if (!$user) {
+            wp_send_json_error('User not found', 404);
+            return;
+        }
+        
+        if (!current_user_can('delete_user', $userId)) {
+            wp_send_json_error('Insufficient permissions', 403);
+            return;
+        }
+        
+        // Delete logic
+    }
+}
+
+// ✅ Aplicando DRY
+class UserController {
+    private function validateUserAccess($userId, $capability) {
+        $user = get_user_by('ID', $userId);
+        if (!$user) {
+            wp_send_json_error('User not found', 404);
+            return false;
+        }
+        
+        if (!current_user_can($capability, $userId)) {
+            wp_send_json_error('Insufficient permissions', 403);
+            return false;
+        }
+        
+        return $user;
+    }
+    
+    public function updateProfile($userId, $data) {
+        $user = $this->validateUserAccess($userId, 'edit_user');
+        if (!$user) return;
+        
+        // Update logic
+    }
+    
+    public function deleteProfile($userId) {
+        $user = $this->validateUserAccess($userId, 'delete_user');
+        if (!$user) return;
+        
+        // Delete logic
+    }
+}
+```
+
+## 🏗️ **Arquitetura de Código (Padrões Laravel)**
+
+### **Service Layer Pattern**
+
+```php
+// app/Services/UserService.php
+namespace Pipefy\Services;
+
+class UserService {
+    private $userRepository;
+    private $emailService;
+    
+    public function __construct(UserRepository $userRepository, EmailService $emailService) {
+        $this->userRepository = $userRepository;
+        $this->emailService = $emailService;
+    }
+    
+    public function createUser(array $userData): User {
+        $this->validateUserData($userData);
+        
+        $user = $this->userRepository->create($userData);
+        $this->emailService->sendWelcomeEmail($user);
+        
+        return $user;
+    }
+    
+    private function validateUserData(array $data): void {
+        if (empty($data['email'])) {
+            throw new InvalidArgumentException('Email is required');
+        }
+        
+        if (!filter_var($data['email'], FILTER_VALIDATE_EMAIL)) {
+            throw new InvalidArgumentException('Invalid email format');
+        }
+    }
+}
+```
+
+### **Repository Pattern**
+
+```php
+// app/Repositories/UserRepository.php
+namespace Pipefy\Repositories;
+
+interface UserRepositoryInterface {
+    public function find(int $id): ?User;
+    public function create(array $data): User;
+    public function update(int $id, array $data): User;
+    public function delete(int $id): bool;
+}
+
+class UserRepository implements UserRepositoryInterface {
+    public function find(int $id): ?User {
+        $userData = get_user_by('ID', $id);
+        return $userData ? new User($userData) : null;
+    }
+    
+    public function create(array $data): User {
+        $userId = wp_insert_user($data);
+        
+        if (is_wp_error($userId)) {
+            throw new Exception('Failed to create user: ' . $userId->get_error_message());
+        }
+        
+        return $this->find($userId);
+    }
+    
+    public function update(int $id, array $data): User {
+        $data['ID'] = $id;
+        $result = wp_update_user($data);
+        
+        if (is_wp_error($result)) {
+            throw new Exception('Failed to update user: ' . $result->get_error_message());
+        }
+        
+        return $this->find($id);
+    }
+    
+    public function delete(int $id): bool {
+        return wp_delete_user($id);
+    }
+}
+```
+
+### **Model Layer**
+
+```php
+// app/Models/User.php
+namespace Pipefy\Models;
+
+class User {
+    private $id;
+    private $email;
+    private $firstName;
+    private $lastName;
+    private $avatar;
+    
+    public function __construct($userData) {
+        $this->id = $userData->ID;
+        $this->email = $userData->user_email;
+        $this->firstName = $userData->first_name;
+        $this->lastName = $userData->last_name;
+        $this->avatar = get_user_meta($userData->ID, 'avatar', true);
+    }
+    
+    public function getId(): int {
+        return $this->id;
+    }
+    
+    public function getEmail(): string {
+        return $this->email;
+    }
+    
+    public function getFullName(): string {
+        return trim($this->firstName . ' ' . $this->lastName);
+    }
+    
+    public function getAvatar(): ?string {
+        return $this->avatar;
+    }
+    
+    public function toArray(): array {
+        return [
+            'id' => $this->id,
+            'email' => $this->email,
+            'first_name' => $this->firstName,
+            'last_name' => $this->lastName,
+            'full_name' => $this->getFullName(),
+            'avatar' => $this->avatar
+        ];
+    }
+}
+```
+
+## 🧪 **Qualidade e Testes**
+
+### **PHP CodeSniffer (PHPCS)**
+
+```bash
+# Instalar dependências de desenvolvimento
+composer require --dev squizlabs/php_codesniffer
+composer require --dev wp-coding-standards/wpcs
+
+# Configurar padrões WordPress
+./vendor/bin/phpcs --config-set installed_paths vendor/wp-coding-standards/wpcs
+
+# Verificar código
+./vendor/bin/phpcs --standard=WordPress dist/wp-content/themes/pipefy-2020/
+
+# Corrigir automaticamente (quando possível)
+./vendor/bin/phpcbf --standard=WordPress dist/wp-content/themes/pipefy-2020/
+```
+
+### **Configuração PHPCS**
+
+```xml
+<!-- phpcs.xml -->
+<?xml version="1.0"?>
+<ruleset name="Pipefy WordPress Coding Standards">
+    <description>Pipefy WordPress coding standards</description>
+    
+    <!-- Include WordPress-Core standards -->
+    <rule ref="WordPress-Core">
+        <!-- Exclude filename rules -->
+        <exclude name="WordPress.Files.FileName"/>
+    </rule>
+    
+    <!-- Include WordPress-Extra standards -->
+    <rule ref="WordPress-Extra">
+        <!-- Allow short array syntax -->
+        <exclude name="Generic.Arrays.DisallowShortArraySyntax"/>
+    </rule>
+    
+    <!-- Include WordPress-Docs standards -->
+    <rule ref="WordPress-Docs"/>
+    
+    <!-- Check only PHP files -->
+    <arg name="extensions" value="php"/>
+    
+    <!-- Show colors in output -->
+    <arg name="colors"/>
+    
+    <!-- Show progress -->
+    <arg value="p"/>
+    
+    <!-- Include paths -->
+    <file>dist/wp-content/themes/pipefy-2020/</file>
+    <file>dist/wp-content/mu-plugins/</file>
+    
+    <!-- Exclude paths -->
+    <exclude-pattern>*/vendor/*</exclude-pattern>
+    <exclude-pattern>*/node_modules/*</exclude-pattern>
+    <exclude-pattern>*/assets/build/*</exclude-pattern>
+</ruleset>
+```
+
+### **Unit Testing**
+
+```php
+// tests/Unit/UserServiceTest.php
+namespace Tests\Unit;
+
+use PHPUnit\Framework\TestCase;
+use Pipefy\Services\UserService;
+use Pipefy\Repositories\UserRepository;
+use Pipefy\Services\EmailService;
+
+class UserServiceTest extends TestCase {
+    private $userService;
+    private $userRepository;
+    private $emailService;
+    
+    protected function setUp(): void {
+        $this->userRepository = $this->createMock(UserRepository::class);
+        $this->emailService = $this->createMock(EmailService::class);
+        $this->userService = new UserService($this->userRepository, $this->emailService);
+    }
+    
+    public function testCreateUserWithValidData(): void {
+        $userData = [
+            'email' => 'test@example.com',
+            'first_name' => 'John',
+            'last_name' => 'Doe'
+        ];
+        
+        $expectedUser = new User((object) array_merge($userData, ['ID' => 1]));
+        
+        $this->userRepository
+            ->expects($this->once())
+            ->method('create')
+            ->with($userData)
+            ->willReturn($expectedUser);
+            
+        $this->emailService
+            ->expects($this->once())
+            ->method('sendWelcomeEmail')
+            ->with($expectedUser);
+        
+        $result = $this->userService->createUser($userData);
+        
+        $this->assertInstanceOf(User::class, $result);
+        $this->assertEquals('test@example.com', $result->getEmail());
+    }
+    
+    public function testCreateUserWithInvalidEmailThrowsException(): void {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Invalid email format');
+        
+        $userData = [
+            'email' => 'invalid-email',
+            'first_name' => 'John',
+            'last_name' => 'Doe'
+        ];
+        
+        $this->userService->createUser($userData);
+    }
+}
+```
+
+## 📋 **Code Review Guidelines**
+
+### **Checklist de Code Review**
+
+```markdown
+## Code Review Checklist
+
+### ✅ Functionality
+- [ ] Code implements requirements correctly
+- [ ] Edge cases are handled appropriately
+- [ ] Error handling is implemented
+- [ ] Performance considerations are addressed
+
+### ✅ Code Quality
+- [ ] Code follows DRY principles
+- [ ] Functions are single-responsibility
+- [ ] Variable and function names are descriptive (in English)
+- [ ] Code is readable and well-structured
+
+### ✅ Standards Compliance
+- [ ] Follows WordPress coding standards
+- [ ] BEM methodology for CSS
+- [ ] PSR-12 compliance for PHP
+- [ ] Semantic versioning for releases
+
+### ✅ Security
+- [ ] Input validation is implemented
+- [ ] SQL injection prevention
+- [ ] XSS prevention
+- [ ] CSRF protection where needed
+
+### ✅ Testing
+- [ ] Unit tests are included
+- [ ] Test coverage is adequate
+- [ ] Integration tests pass
+- [ ] Manual testing completed
+
+### ✅ Documentation
+- [ ] Code is properly documented
+- [ ] README updated if needed
+- [ ] CHANGELOG updated for user-facing changes
+- [ ] API documentation updated
+
+### ✅ Merge Request Process
+- [ ] MR template properly filled
+- [ ] Target branch is correct
+- [ ] Required approvals obtained
+- [ ] CI/CD pipeline passes
+```
+
+### **Commit Message Standards**
+
+```bash
+# Formato: type(scope): description
+# 
+# Types:
+# feat: nova funcionalidade
+# fix: correção de bug
+# docs: documentação
+# style: formatação, missing semi colons, etc
+# refactor: refatoração de código
+# test: adição de testes
+# chore: manutenção
+
+# ✅ Exemplos corretos
+feat(user): add avatar upload functionality
+fix(header): resolve responsive navigation issue
+docs(api): update authentication endpoints
+style(css): format according to BEM methodology
+refactor(auth): extract user validation logic
+test(user): add unit tests for user service
+chore(deps): update composer dependencies
+
+# ❌ Exemplos incorretos
+added new feature
+fix bug
+update code
+changes
+```
+
+## 🎯 **Performance e Otimização**
+
+### **WordPress Performance Best Practices**
+
+```php
+// ✅ Efficient database queries
+$posts = new WP_Query([
+    'post_type' => 'product',
+    'posts_per_page' => 10,
+    'meta_query' => [
+        [
+            'key' => 'featured',
+            'value' => 'yes',
+            'compare' => '='
+        ]
+    ],
+    'no_found_rows' => true, // Skip pagination count
+    'update_post_meta_cache' => false, // Skip meta cache if not needed
+    'update_post_term_cache' => false  // Skip term cache if not needed
+]);
+
+// ✅ Proper asset enqueuing with versioning
+wp_enqueue_script(
+    'pipefy-main',
+    get_theme_file_uri('assets/js/main.js'),
+    ['jquery'],
+    PIPEFY_THEME_VERSION,
+    true
+);
+
+// ✅ Conditional loading
+if (is_front_page()) {
+    wp_enqueue_script('hero-slider', get_theme_file_uri('assets/js/hero-slider.js'));
+}
+
+// ✅ Efficient image handling
+function pipefy_get_responsive_image($attachment_id, $sizes = 'full') {
+    return wp_get_attachment_image(
+        $attachment_id,
+        $sizes,
+        false,
+        [
+            'loading' => 'lazy',
+            'decoding' => 'async'
+        ]
+    );
+}
+```
+
+### **CSS/SCSS Organization**
+
+```scss
+// assets/scss/main.scss
+// Import order: Variables → Mixins → Base → Components → Pages
+
+// 1. Variables and configuration
+@import 'config/variables';
+@import 'config/breakpoints';
+@import 'config/colors';
+
+// 2. Mixins and utilities
+@import 'mixins/responsive';
+@import 'mixins/typography';
+@import 'utilities/helpers';
+
+// 3. Base styles
+@import 'base/reset';
+@import 'base/typography';
+@import 'base/layout';
+
+// 4. Components (BEM blocks)
+@import 'components/header';
+@import 'components/navigation';
+@import 'components/hero-section';
+@import 'components/card';
+@import 'components/button';
+
+// 5. Page-specific styles
+@import 'pages/home';
+@import 'pages/about';
+@import 'pages/contact';
+
+// 6. WordPress specific
+@import 'wordpress/gutenberg';
+@import 'wordpress/comments';
+@import 'wordpress/widgets';
+```
+
+## 🚀 **Próximos Passos**
+
+1. **[Deploy Pipeline](Deploy-Pipeline)** - Processo de CI/CD detalhado
+2. **[Plugins & Integrações](Plugins-Integracoes)** - Gestão de plugins
+3. **[Troubleshooting](Troubleshooting)** - Resolução de problemas comuns
+
+## 📞 **Suporte ao Desenvolvimento**
+
+- **Code Review**: Equipe senior (ver [CODEOWNERS](https://gitlab.com/pipefy/wordpress/pipefy-website/-/blob/master/CODEOWNERS))
+- **Standards Issues**: [GitLab Issues - Label: code-quality](https://gitlab.com/pipefy/wordpress/pipefy-website/-/issues?label_name=code-quality)
+- **Development Discussion**: Slack #dev-website
+- **Merge Request Help**: [GitLab MR Guidelines](https://docs.gitlab.com/ee/user/project/merge_requests/)
+
+---
+
+📝 **Última atualização**: Junho 2025  
+🌊 **Workflow**: GitFlow modificado (branches from master)  
+🏷️ **Versionamento**: Semantic Versioning (SemVer)  
+📦 **Dependencies**: Composer-based plugin management  
+🧪 **Quality**: PHPCS + Unit Tests + Code Review  
+🎨 **Standards**: BEM + DRY + Laravel-inspired architecture  
+✅ **Process**: **Merge Requests obrigatórios para staging/master**