CONTRIBUTING.md

🤝 Guia de Contribuição - DigiVerse

Obrigado por considerar contribuir com o DigiVerse! Este documento fornece diretrizes para contribuir com o projeto.

📋 Índice

• Código de Conduta
• Como Posso Contribuir?
• Configuração do Ambiente
• Padrões de Código
• Processo de Pull Request
• Convenções de Commit
• Estrutura do Projeto

📜 Código de Conduta

Este projeto adere ao Código de Conduta. Ao participar, espera-se que você mantenha este código. Por favor, reporte comportamentos inaceitáveis para caiofernandes.dev@gmail.com.

🚀 Como Posso Contribuir?

Reportando Bugs

Antes de criar um issue de bug, verifique se já não existe um issue similar. Quando criar um bug report, inclua o máximo de detalhes possível:

• Título claro e descritivo
• Passos para reproduzir o problema
• Comportamento esperado vs comportamento atual
• Screenshots se aplicável
• Ambiente: SO, versão do Node.js, navegador, etc.

Exemplo de Bug Report:

**Descrição**: Dropdown de filtros é cortado pela imagem do card

**Passos para Reproduzir**:
1. Acesse a home page
2. Clique no filtro "Nível"
3. Observe que o dropdown é sobreposto pelas imagens

**Esperado**: Dropdown deve aparecer acima de todos os elementos
**Atual**: Dropdown é cortado pelas imagens dos cards

**Ambiente**:
- SO: Windows 11
- Navegador: Chrome 120
- Resolução: 1920x1080

Sugerindo Melhorias

Issues de melhoria são bem-vindos! Ao criar uma sugestão:

• Use um título claro e descritivo
• Descreva o comportamento atual e o comportamento desejado
• Explique por que esta melhoria seria útil
• Inclua mockups ou exemplos se possível

Pull Requests

1. Fork o repositório
2. Clone seu fork: git clone https://github.com/seu-usuario/API-REST-Digimon.git
3. Crie uma branch para sua feature: git checkout -b feature/MinhaFeature
4. Faça suas alterações seguindo os padrões de código
5. Teste suas alterações
6. Commit suas mudanças seguindo as convenções de commit
7. Push para sua branch: git push origin feature/MinhaFeature
8. Abra um Pull Request

🛠️ Configuração do Ambiente

Pré-requisitos

• Node.js >= 18.0.0
• pnpm >= 8.0.0
• Docker e Docker Compose (recomendado)

Setup Inicial

# Clone o repositório
git clone https://github.com/CAFernandes/API-REST-Digimon.git
cd API-REST-Digimon

# Instale as dependências
pnpm install

# Configure variáveis de ambiente
cp packages/backend/.env.example packages/backend/.env
# Edite packages/backend/.env conforme necessário

# Inicie os serviços Docker
pnpm docker:backend:up

# Execute migrations e seed
cd packages/backend
pnpm prisma:migrate
pnpm db:seed
cd ../..

# Inicie o desenvolvimento
pnpm backend:dev  # Terminal 1
pnpm web:dev      # Terminal 2

Rodando Testes

# Backend
pnpm backend:test
pnpm backend:test -- --coverage

# Todos os pacotes
pnpm test:all

📝 Padrões de Código

Backend (packages/backend/)

• TypeScript estrito com tipos explícitos
• Fastify com padrão FastifyPluginAsync
• Prisma para todas as operações de banco de dados
• Zod para validação de schemas
• ESLint + Prettier para formatação

Padrão de Controller:

export class DigimonController {
  async getAllDigimon(request: FastifyRequest, reply: FastifyReply) {
    try {
      // Business logic
      return reply.status(200).send({ data, message: 'Success' });
    } catch (error) {
      throw new AppError('Error message', 500, 'ERROR_CODE');
    }
  }
}

Padrão de Rota:

const routes: FastifyPluginAsync = async (fastify) => {
  const controller = new DigimonController();

  fastify.get('/digimon', {
    preHandler: verifyToken,
    schema: {
      tags: ['Digimon'],
      response: { 200: DigimonResponseSchema }
    },
    handler: controller.getAllDigimon.bind(controller)
  });
};

Frontend (packages/web/)

• React 19 com Hooks
• TypeScript com tipos explícitos
• TailwindCSS para estilização (sem CSS inline ou styled-components)
• React Query para gerenciamento de estado do servidor
• React Hook Form + Zod para formulários

Padrão de Componente:

interface MyComponentProps {
  title: string;
  onAction: () => void;
}

export function MyComponent({ title, onAction }: MyComponentProps) {
  const [state, setState] = useState<string>('');

  return (
    <div className="glass-card rounded-xl p-4">
      <h2 className="text-xl font-bold text-white">{title}</h2>
      <button onClick={onAction} className="btn-primary">
        Action
      </button>
    </div>
  );
}

Classes TailwindCSS Customizadas:

• .glass-card - Card com efeito glassmorphism
• .glass-dropdown - Dropdown opaco para melhor visibilidade
• .btn-primary - Botão com gradiente primário
• .text-glow - Texto com efeito de brilho

Estilo de Código

• Indentação: 2 espaços
• Quotes: Single quotes para strings
• Semicolons: Sempre usar
• Naming:
  • Componentes: PascalCase (DigimonCard)
  • Funções: camelCase (getAllDigimon)
  • Constantes: UPPER_SNAKE_CASE (JWT_SECRET)
  • Arquivos: kebab-case para utilitários, PascalCase para componentes

Formatação

Antes de commitar, rode:

pnpm lint:all      # Verifica linting
pnpm format:all    # Formata código

🔄 Processo de Pull Request

Checklist do PR

Antes de submeter, certifique-se que:

• O código segue os padrões do projeto
• Testes foram adicionados/atualizados
• Todos os testes passam (pnpm test:all)
• Lint passa sem erros (pnpm lint:all)
• Documentação foi atualizada se necessário
• Commits seguem as convenções
• Branch está atualizada com main

Template de PR

## Descrição

[Descreva as mudanças feitas]

## Tipo de Mudança

- [ ] Bug fix
- [ ] Nova feature
- [ ] Breaking change
- [ ] Documentação

## Como Testar

1. [Passo 1]
2. [Passo 2]
3. [Passo 3]

## Screenshots (se aplicável)

[Adicione screenshots]

## Checklist

- [ ] Código segue os padrões do projeto
- [ ] Testes passam
- [ ] Documentação atualizada

Revisão de Código

• Todos os PRs precisam de aprovação antes do merge
• Responda aos comentários de forma construtiva
• Faça commits adicionais para correções (não force-push após review)

📋 Convenções de Commit

Usamos Conventional Commits para mensagens de commit claras:

Formato

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

<corpo opcional>

<footer opcional>

Tipos

• feat: Nova feature
• fix: Correção de bug
• docs: Mudanças na documentação
• style: Formatação, missing semicolons, etc (sem mudança de código)
• refactor: Refatoração de código
• perf: Melhoria de performance
• test: Adição ou correção de testes
• chore: Tarefas de build, configs, etc

Exemplos

feat(filters): add compact inline filter system

Implemented CompactFilter component with expand/collapse functionality
and Portal API rendering for proper z-index stacking.

Closes #123

fix(dropdown): resolve z-index conflicts with cards

Changed dropdown rendering to use createPortal with z-9999
to ensure proper stacking above all page elements.

docs(readme): update with DigiVerse branding

- Changed project name to DigiVerse
- Added screenshots section
- Updated feature list

🏗️ Estrutura do Projeto

digiverse/
├── packages/
│   ├── backend/
│   │   ├── src/
│   │   │   ├── controllers/     # Lógica de negócio
│   │   │   ├── models/          # Modelos Prisma
│   │   │   ├── Routes/          # Definição de rotas (Fastify plugins)
│   │   │   ├── services/        # Serviços auxiliares
│   │   │   ├── validations/     # Schemas Zod
│   │   │   ├── errors/          # Error handling
│   │   │   └── server.ts        # Entry point
│   │   ├── prisma/
│   │   │   ├── schema.prisma    # Schema do banco
│   │   │   └── seed.ts          # Dados iniciais
│   │   └── tests/               # Testes
│   │
│   └── web/
│       ├── src/
│       │   ├── components/      # Componentes React
│       │   │   ├── auth/        # Login, Register
│       │   │   ├── common/      # SearchBar, Filters, SEO
│       │   │   ├── digimon/     # DigimonCard, DigimonDetail
│       │   │   └── layout/      # Header, Footer
│       │   ├── pages/           # Páginas de rota
│       │   ├── contexts/        # React Contexts (Auth)
│       │   ├── services/        # API client
│       │   ├── hooks/           # Custom hooks
│       │   └── types/           # TypeScript types
│       └── public/              # Assets estáticos
│
├── docs/                        # Documentação adicional
├── CONTRIBUTING.md              # Este arquivo
├── CODE_OF_CONDUCT.md           # Código de conduta
└── README.md                    # Documentação principal

🎨 Design System

Cores

Definidas em packages/web/tailwind.config.ts:

• Primary: Blue (cyan-500)
• Secondary: Purple (purple-500)
• Background: Slate-900 to Slate-950 gradient
• Glass Effects: White with opacity

Componentes Reutilizáveis

• Glass Card: .glass-card - 5% opacity, backdrop-blur
• Glass Dropdown: .glass-dropdown - 95% opacity para dropdowns
• Buttons: .btn-primary, .btn-secondary, .btn-ghost
• Inputs: .input-glass
• Badges: .badge-primary, .badge-secondary, etc.

Z-Index Hierarchy

Documentado em packages/web/Z_INDEX_GUIDE.md:

• Base content: z-0
• Header/Footer: z-10
• Modals/Overlays: z-50
• Dropdowns (Portal): z-[9999]
• Backdrop: z-[9998]

🧪 Testes

Backend

• Unit Tests: tests/unit/ - Testes de modelos e serviços
• Integration Tests: tests/integration/ - Testes de endpoints

pnpm backend:test                         # Todos os testes
pnpm backend:test -- tests/unit/          # Apenas unit
pnpm backend:test -- -t "DigimonModel"    # Teste específico

Frontend

(Em desenvolvimento - contribuições bem-vindas!)

📚 Recursos Úteis

• Fastify Documentation
• Prisma Documentation
• React Documentation
• TailwindCSS Documentation
• TanStack Query

❓ Dúvidas?

Se tiver dúvidas sobre como contribuir:

• Abra uma Discussion
• Entre em contato: caiofernandes.dev@gmail.com

🙏 Agradecimentos

Obrigado por dedicar seu tempo para contribuir com o DigiVerse! Cada contribuição, grande ou pequena, faz diferença.

---

Feito com ❤️ pela comunidade DigiVerse