gohorsejobs/README.md

# 🐴 GoHorse Jobs

[![Go](https://img.shields.io/badge/Go-1.24-00ADD8?style=flat-square&logo=go)](https://golang.org/)
[![Next.js](https://img.shields.io/badge/Next.js-15-black?style=flat-square&logo=next.js)](https://nextjs.org/)
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16-336791?style=flat-square&logo=postgresql)](https://postgresql.org/)
[![Docker](https://img.shields.io/badge/Docker-Ready-2496ED?style=flat-square&logo=docker)](https://docker.com/)
[![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE)

> 🇧🇷 Plataforma de recrutamento conectando profissionais de tecnologia a oportunidades de emprego.

---

## 📋 Índice

- [Visão Geral](#-visão-geral)
- [Arquitetura](#-arquitetura)
- [Tech Stack](#-tech-stack)
- [Pré-requisitos](#-pré-requisitos)
- [Instalação](#-instalação)
- [Variáveis de Ambiente](#-variáveis-de-ambiente)
- [Scripts Disponíveis](#-scripts-disponíveis)
- [Credenciais de Teste](#-credenciais-de-teste)
- [Documentação da API](#-documentação-da-api)
- [Estrutura de Pastas](#-estrutura-de-pastas)

---

## 🎯 Visão Geral

**GoHorse Jobs** é uma plataforma completa de recrutamento que permite:

- 🏢 **Empresas**: Publicar vagas, gerenciar candidaturas e comunicar-se com candidatos
- 👤 **Candidatos**: Buscar vagas, candidatar-se e acompanhar status
- 👑 **Administradores**: Gerenciar todo o sistema com painel administrativo

---

## 🏗️ Arquitetura

O projeto segue uma arquitetura de **microserviços** com três componentes principais:

```mermaid
graph TB
    subgraph Frontend
        A[Next.js 15<br/>App Router]
    end
    
    subgraph Backend
        B[Go API<br/>Clean Architecture]
    end
    
    subgraph Database
        C[(PostgreSQL 16)]
    end
    
    subgraph Seeder
        D[Node.js<br/>Seeder API]
    end
    
    A -->|REST API| B
    B -->|GORM| C
    D -->|pg client| C
```

### Padrões Arquiteturais

| Componente | Padrão | Descrição |
|------------|--------|-----------|
| **Backend** | Clean Architecture | Separação em `handlers`, `services`, `models`, `usecases` |
| **Frontend** | App Router | Next.js 15 com Server Components e Client Components |
| **Multi-tenancy** | JWT + Company Context | Isolamento de dados por empresa via middleware |

---

## 🛠️ Tech Stack

### Backend
| Tecnologia | Versão | Uso |
|------------|--------|-----|
| Go | 1.24 | Linguagem principal |
| PostgreSQL | 16 | Banco de dados |
| JWT | v5 | Autenticação |
| Swagger | 2.0 | Documentação API |

### Frontend
| Tecnologia | Versão | Uso |
|------------|--------|-----|
| Next.js | 15 | Framework React |
| Tailwind CSS | 4 | Estilização |
| shadcn/ui | - | Componentes UI |
| Zod | 3.x | Validação de schemas |
| React Hook Form | 7.x | Gerenciamento de forms |

### DevOps
| Tecnologia | Uso |
|------------|-----|
| Docker | Containerização |
| Alpine Linux | Imagem base (mínima) |

---

## 📦 Pré-requisitos

Antes de começar, certifique-se de ter instalado:

- **Docker** (v24+) e **Docker Compose** (v2+)
- **Go** (v1.24+) - para desenvolvimento local
- **Node.js** (v20+) e **npm** - para frontend e seeder
- **PostgreSQL** (v16+) - se rodar sem Docker

---

## 🚀 Instalação

### Opção 1: Script de Desenvolvimento (Recomendado)

```bash
# Clone o repositório
git clone https://github.com/rede5/gohorsejobs.git
cd gohorsejobs

# Execute o script de desenvolvimento
./run_dev.sh
```

### Opção 2: Manual (Passo a Passo)

```bash
# 1. Clone o repositório
git clone https://github.com/rede5/gohorsejobs.git
cd gohorsejobs

# 2. Configure as variáveis de ambiente
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env
cp seeder-api/.env.example seeder-api/.env

# 3. Inicie o banco de dados (PostgreSQL)
# Certifique-se de ter um PostgreSQL rodando na porta 5432

# 4. Inicie o Backend
cd backend
go run ./cmd/api

# 5. Em outro terminal, inicie o Frontend
cd frontend
npm install
npm run dev

# 6. (Opcional) Popule o banco com dados de teste
cd seeder-api
npm install
npm run seed
```

---

## 🔐 Variáveis de Ambiente

### Backend (`backend/.env`)

| Variável | Descrição | Exemplo |
|----------|-----------|---------|
| `DB_HOST` | Host do PostgreSQL | `localhost` |
| `DB_PORT` | Porta do PostgreSQL | `5432` |
| `DB_USER` | Usuário do banco | `postgres` |
| `DB_PASSWORD` | Senha do banco | `yourpassword` |
| `DB_NAME` | Nome do banco | `gohorsejobs` |
| `JWT_SECRET` | Secret para JWT (min 32 chars) | `your-secret-key-at-least-32-chars` |
| `PORT` | Porta da API | `8080` |
| `ENV` | Ambiente | `development` ou `production` |
| `CORS_ORIGINS` | Origens permitidas | `http://localhost:3000` |

### Frontend (`frontend/.env`)

| Variável | Descrição | Exemplo |
|----------|-----------|---------|
| `NEXT_PUBLIC_API_URL` | URL da API Backend | `http://localhost:8080` |

---

## 📜 Scripts Disponíveis

### Raiz do Projeto

| Comando | Descrição |
|---------|-----------|
| `./run_dev.sh` | Inicia backend + frontend em modo desenvolvimento |
| `./run_dev_seed.sh` | Inicia tudo + popula banco com dados de teste |

### Backend (`cd backend`)

| Comando | Descrição |
|---------|-----------|
| `go run ./cmd/api` | Inicia o servidor de desenvolvimento |
| `go build ./cmd/api` | Compila o binário |
| `go test ./...` | Executa todos os testes |
| `swag init -g cmd/api/main.go` | Regenera documentação Swagger |

### Frontend (`cd frontend`)

| Comando | Descrição |
|---------|-----------|
| `npm run dev` | Inicia servidor de desenvolvimento |
| `npm run build` | Compila para produção |
| `npm run start` | Inicia servidor de produção |
| `npm run lint` | Executa linter |

### Seeder API (`cd seeder-api`)

| Comando | Descrição |
|---------|-----------|
| `npm run seed` | Popula banco com todos os dados |
| `npm run seed:reset` | Limpa banco e repopula |
| `npm run seed:users` | Popula apenas usuários |

---

## 🔑 Credenciais de Teste

| Tipo | Usuário | Senha | Dashboard |
|------|---------|-------|-----------|
| **SuperAdmin** | `superadmin` | `Admin@2025!` | `/dashboard/admin` |
| **Admin Empresa** | `takeshi_yamamoto` | `Takeshi@2025` | `/dashboard/empresa` |
| **Recrutador** | `maria_santos` | `Maria@2025` | `/dashboard/empresa` |
| **Candidato** | `paulo_santos` | `User@2025` | `/dashboard/candidato` |

---

## 📖 Documentação da API

### Swagger UI
Acesse a documentação interativa em: **http://localhost:8080/swagger/index.html**

### Endpoints Principais

| Método | Endpoint | Descrição | Autenticação |
|--------|----------|-----------|--------------|
| `GET` | `/health` | Health check | ❌ |
| `POST` | `/api/v1/auth/login` | Login | ❌ |
| `POST` | `/api/v1/companies` | Criar empresa | ❌ |
| `GET` | `/api/v1/users` | Listar usuários | ✅ JWT |
| `POST` | `/api/v1/users` | Criar usuário | ✅ JWT |
| `GET` | `/jobs` | Listar vagas | ❌ |
| `POST` | `/jobs` | Criar vaga | ✅ JWT |

---

## 📂 Estrutura de Pastas

```
gohorsejobs/
├── backend/                 # API Go
│   ├── cmd/api/             # Entrypoint da aplicação
│   ├── internal/            # Código interno
│   │   ├── api/             # Handlers e middlewares (Clean Arch)
│   │   ├── core/            # Domain e UseCases (DDD)
│   │   ├── database/        # Conexão com banco
│   │   ├── dto/             # Data Transfer Objects
│   │   ├── handlers/        # Controllers (legacy)
│   │   ├── middleware/      # Middlewares de segurança
│   │   ├── models/          # Entidades do banco
│   │   ├── router/          # Configuração de rotas
│   │   ├── services/        # Lógica de negócios
│   │   └── utils/           # Utilitários (JWT, sanitizer)
│   ├── migrations/          # Migrations SQL
│   └── docs/                # Swagger gerado
│
├── frontend/                # Next.js App
│   └── src/
│       ├── app/             # App Router (páginas)
│       ├── components/      # Componentes React
│       ├── contexts/        # React Contexts
│       ├── hooks/           # Custom Hooks
│       └── lib/             # Utilitários
│
├── seeder-api/              # Seeder Node.js
│   └── src/
│       ├── seeders/         # Scripts de seed por entidade
│       └── index.js         # Entrypoint
│
├── run_dev.sh               # Script de desenvolvimento
└── README.md                # Este arquivo
```

---

## 🤝 Contribuindo

1. Fork o projeto
2. Crie sua branch (`git checkout -b feature/AmazingFeature`)
3. Commit suas mudanças (`git commit -m 'feat: add amazing feature'`)
4. Push para a branch (`git push origin feature/AmazingFeature`)
5. Abra um Pull Request

---

## 📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo [LICENSE](LICENSE) para mais detalhes.

---

<p align="center">
  <sub>Desenvolvido com ❤️ pela equipe GoHorse</sub>
</p>