gohorsejobs/backend/README.md

Backend - GoHorse Jobs API

API REST desenvolvida em Go seguindo princípios de Clean Architecture e DDD.

---

🏗️ Arquitetura

internal/
├── api/                    # Clean Architecture Layer
│   ├── handlers/           # HTTP Handlers (Controllers)
│   └── middleware/         # Auth, CORS, Rate Limiting
│
├── core/                   # Domain Layer (DDD)
│   ├── domain/entity/      # Entidades puras (sem deps externas)
│   ├── ports/              # Interfaces (Repository, Service)
│   └── usecases/           # Casos de uso (Business Logic)
│
├── infrastructure/         # Infrastructure Layer
│   ├── auth/               # JWT Service implementation
│   └── persistence/        # Repository implementations
│
├── handlers/               # Legacy controllers
├── middleware/             # Security middlewares
├── models/                 # GORM models
├── services/               # Business logic (legacy)
└── utils/                  # Helpers (JWT, Sanitizer)

---

🔒 Segurança

Middlewares Implementados

Middleware	Arquivo	Descrição
Auth	middleware/auth.go	Validação JWT + RBAC
CORS	middleware/cors.go	Whitelist de origens via CORS_ORIGINS
Rate Limiting	middleware/rate_limit.go	100 req/min por IP
Security Headers	middleware/security_headers.go	OWASP headers (XSS, CSP, etc.)

Validação de JWT

O servidor valida no boot que JWT_SECRET tenha pelo menos 32 caracteres. Em produção (ENV=production), o servidor não inicia com secrets fracos.

---

📡 Endpoints

Públicos

Método	Endpoint	Descrição
GET	/health	Health check
GET	/swagger/*	Documentação Swagger
POST	/api/v1/auth/login	Autenticação
POST	/api/v1/companies	Registro de empresa
GET	/jobs	Listar vagas (Busca, Filtros, Paginação)

🔍 Busca e Filtros (GET /jobs)

O endpoint /jobs suporta filtros avançados via query params:

• q: Busca textual (Título, Descrição, Empresa)
• location: Filtro por localização (Partial Match)
• type: Tipo de contrato (full-time, part-time, etc.)
• workMode: Modelo de trabalho (remote, hybrid, onsite)
• page & limit: Paginação server-side

Protegidos (JWT Required)

Método	Endpoint	Roles	Descrição
GET	/api/v1/users	superadmin, companyAdmin	Listar usuários
POST	/api/v1/users	superadmin, companyAdmin	Criar usuário
DELETE	/api/v1/users/{id}	superadmin	Deletar usuário
POST	/jobs	companyAdmin, recruiter	Criar vaga

---

Exemplo: atualizar candidatura para "Contratado"

Use este fluxo para marcar uma candidatura como aprovada (status hired).

1. Endpoint: PUT /applications/{id}/status
   • Substitua {id} pelo identificador numérico da candidatura. Exemplo: /applications/1234/status.
2. Payload (application/json):

{
  "status": "hired",
  "notes": "Candidato APROVADO após a entrevista final. Salário de R$ 5.500,00 acordado. Início em 01/02/2026."
}

• O campo status é obrigatório e deve ser "hired" para confirmar a contratação.
• O campo notes é opcional e pode registrar observações do recrutador.

3. Próximo passo recomendado: Após o 200 OK, crie a conta de usuário interno do contratado com POST /api/v1/users.

---

🚀 Desenvolvimento

Executar

# Copie o .env
cp .env.example .env

# Execute
go run ./cmd/api

Testes

# Todos os testes
go test ./...

# Com verbose
go test -v ./internal/middleware/... ./internal/utils/...

Regenerar Swagger

swag init -g cmd/api/main.go --parseDependency --parseInternal

---

🐳 Docker

# Build
docker build -t gohorse-backend .

# Run
docker run -p 8080:8080 --env-file .env gohorse-backend

Imagem otimizada: ~73MB (Alpine + non-root user)

---

📁 Arquivos Importantes

Arquivo	Descrição
cmd/api/main.go	Entrypoint da aplicação
internal/router/router.go	Configuração de todas as rotas
internal/database/database.go	Conexão GORM com PostgreSQL
migrations/*.sql	Migrations do banco de dados
docs/swagger.json	Documentação OpenAPI gerada