# 🤝 Guia de Contribuição - UtilizaAI

Obrigado por considerar contribuir para o UtilizaAI! 🎉

Este documento fornece diretrizes e instruções para contribuir com o projeto.

---

## 📋 Código de Conduta

Este projeto adota um Código de Conduta para garantir um ambiente acolhedor para todos.

### Nossa Missão
- Ser inclusivo e acolhedor
- Respeitar todos os participantes
- Focar na construtividade
- Resolver conflitos pacificamente

---

## 🚀 Como Começar

### 1. Fork o Repositório

```bash
# Clonar seu fork
git clone https://github.com/seu-usuario/utilizaai.git
cd utilizaai

# Adicionar upstream
git remote add upstream https://github.com/utilizaai/utilizaai.git
```

### 2. Criar Branch

```bash
# Atualizar main
git checkout main
git pull upstream main

# Criar nova branch
git checkout -b feature/sua-feature
# ou
git checkout -b fix/seu-fix
# ou
git checkout -b docs/sua-documentacao
```

### 3. Fazer Mudanças

Editar arquivos e testar localmente

```bash
# Testar mudanças
cd public
php -S localhost:8000
```

### 4. Commit

```bash
# Commit com mensagem clara
git commit -m "feat: adicionar novo conversor"
git commit -m "fix: corrigir bug no upload"
git commit -m "docs: atualizar README"
```

### 5. Push e Pull Request

```bash
# Push para seu fork
git push origin feature/sua-feature

# Ir para GitHub e criar Pull Request
```

---

## 📝 Convenções

### Mensagens de Commit

Usar formato [Conventional Commits](https://www.conventionalcommits.org/):

```
<tipo>(<escopo>): <assunto>

<corpo>

<rodapé>
```

**Tipos:**
- `feat:` Nova funcionalidade
- `fix:` Correção de bug
- `docs:` Mudanças em documentação
- `style:` Formatação, indentação
- `refactor:` Refatoração sem mudança funcional
- `perf:` Melhoria de performance
- `test:` Adição de testes
- `chore:` Tarefas de build, dependências

**Exemplos:**
```bash
git commit -m "feat(conversor): adicionar PDF para Word"
git commit -m "fix(upload): validar MIME type corretamente"
git commit -m "docs(readme): atualizar instruções de instalação"
git commit -m "refactor(api): melhorar estrutura de endpoints"
```

### Branches

```
main                    # Produção
├── feature/*          # Novas funcionalidades
├── fix/*              # Correções
├── docs/*             # Documentação
├── refactor/*         # Refatoração
└── test/*             # Testes
```

**Exemplo:**
```
feature/pdf-to-word
fix/upload-validation
docs/api-endpoints
refactor/database-connection
```

---

## 🎯 Tipos de Contribuição

### 1. Novas Funcionalidades

- Discussão prévia em Issues
- Implementação clara e testada
- Documentação completa
- Exemplos de uso

### 2. Correção de Bugs

- Descrever o bug
- Fornecer exemplo de reprodução
- Corrigir com testes
- Adicionar test case

### 3. Documentação

- Melhorar README
- Adicionar exemplos
- Traduzir docs
- Criar tutoriais

### 4. Performance

- Benchmark antes/depois
- Explicar otimização
- Não quebrar funcionalidades
- Adicionar testes

### 5. Testes

- Testes unitários
- Testes de integração
- Cobertura > 80%
- Usar PHPUnit

---

## ✅ Checklist Antes de Submeter PR

- [ ] Fork do repositório criado
- [ ] Branch criado com nome descritivo
- [ ] Código segue o style guide
- [ ] Commits têm mensagens claras
- [ ] Testes foram adicionados/atualizados
- [ ] Documentação foi atualizada
- [ ] Sem conflitos com main
- [ ] PR descreve as mudanças claramente

---

## 👥 Processo de PR

### Etapas

1. **Submissão** → Você cria o PR
2. **Review** → Maintainer revisa
3. **Discussão** → Feedback e melhorias
4. **Aprovação** → Merge na main
5. **Publicação** → Release incluindo seu PR

### O que Esperar

- Resposta em 48-72 horas
- Feedback construtivo
- Colaboração na solução
- Crédito no CHANGELOG

---

## 📚 Estrutura do Projeto

```
utilizaai/
├── public/                # Frontend público
│   ├── css/              # Estilos
│   ├── js/               # JavaScript
│   ├── tools/            # Ferramentas
│   └── uploads/          # Arquivos temporários
├── src/
│   ├── api/              # Endpoints
│   ├── database/         # DB config
│   └── includes/         # Shared
├── docs/                 # Documentação
├── tests/                # Testes
└── [config files]
```

---

## 🧪 Testes

### Rodar Testes

```bash
# PHPUnit
./vendor/bin/phpunit

# Com coverage
./vendor/bin/phpunit --coverage-html coverage/
```

### Escrever Testes

```php
<?php

use PHPUnit\Framework\TestCase;

class ConverterTest extends TestCase
{
    public function testPdfToWord()
    {
        $converter = new PdfConverter();
        $result = $converter->convert('test.pdf', 'docx');
        
        $this->assertTrue($result['success']);
        $this->assertFileExists($result['file']);
    }
}
```

---

## 📖 Estilo de Código

### PHP

```php
<?php
// Namespace e imports no topo
namespace UtilizaAI\Api\Converters;

use UtilizaAI\Database\Database;
use Exception;

// PSR-12 style
class PdfConverter
{
    private $db;
    
    public function __construct()
    {
        $this->db = Database::getInstance();
    }
    
    public function convert(string $inputFile, string $format): array
    {
        // Implementação
        return [
            'success' => true,
            'file' => $outputFile
        ];
    }
}
```

### JavaScript

```javascript
// Usar ES6+
class FileUploader {
    constructor(options = {}) {
        this.options = options;
    }
    
    async upload(file) {
        const formData = new FormData();
        formData.append('file', file);
        
        const response = await fetch('/api/upload', {
            method: 'POST',
            body: formData
        });
        
        return response.json();
    }
}
```

### CSS

```css
/* BEM naming */
.card { }
.card__header { }
.card__body { }
.card--featured { }

/* Variáveis */
:root {
    --color-primary: #FFD700;
    --transition: all 0.3s ease;
}

/* Mobile-first */
@media (min-width: 768px) { }
```

---

## 🔍 Checklist de Review

Para revisor(a):

- [ ] Código segue padrões
- [ ] Testes inclusos e passam
- [ ] Sem erros de segurança
- [ ] Performance aceitável
- [ ] Documentação clara
- [ ] Compatibilidade mantida

---

## 🐛 Reportar Bugs

### Template

```markdown
## Descrição
[Descrever o bug claramente]

## Reprodução
1. ...
2. ...
3. ...

## Comportamento Esperado
[O que deveria acontecer]

## Comportamento Atual
[O que acontece realmente]

## Screenshots
[Se aplicável]

## Ambiente
- OS: [Windows/Linux/Mac]
- PHP: [versão]
- Navegador: [Chrome/Firefox/etc]

## Arquivos Relacionados
- [arquivo]
```

---

## 💡 Sugerir Melhorias

### Template

```markdown
## Resumo
[Breve descrição]

## Motivação
[Por que isso seria útil?]

## Solução Proposta
[Como poderia funcionar?]

## Alternativas
[Outras soluções possíveis]

## Contexto Adicional
[Screenshots, links, referências]
```

---

## 📞 Contato

- **Discord:** [Servidor](https://discord.gg/utilizaai)
- **Email:** dev@utilizaai.com
- **Twitter:** [@UtilizaAI](https://twitter.com/utilizaai)

---

## 📜 Licença

Ao contribuir, você concorda que suas contribuições serão licenciadas sob a MIT License.

---

## 🙏 Obrigado!

Obrigado por dedicar tempo para contribuir com o UtilizaAI! Você é incrível! ❤️

---

**Última atualização:** 25/04/2026