b09bd023ed
- impl(frontend): server-side pagination for jobs listing - impl(frontend): standardized api error handling and sonner integration - test(frontend): added unit tests for JobCard - impl(backend): added SanitizeMiddleware for XSS protection - test(backend): added table-driven tests for JobService - docs: updated READMES, created ROADMAP.md and DATABASE.md - fix(routing): redirected landing page buttons to /jobs
159 lines
4.7 KiB
Markdown
Executable file
159 lines
4.7 KiB
Markdown
Executable file
# Backend - GoHorse Jobs API
|
|
|
|
[](https://golang.org/)
|
|
[](https://postgresql.org/)
|
|
|
|
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`)**:
|
|
|
|
```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
|
|
|
|
```bash
|
|
# Copie o .env
|
|
cp .env.example .env
|
|
|
|
# Execute
|
|
go run ./cmd/api
|
|
```
|
|
|
|
### Testes
|
|
|
|
```bash
|
|
# Todos os testes
|
|
go test ./...
|
|
|
|
# Com verbose
|
|
go test -v ./internal/middleware/... ./internal/utils/...
|
|
```
|
|
|
|
### Regenerar Swagger
|
|
|
|
```bash
|
|
swag init -g cmd/api/main.go --parseDependency --parseInternal
|
|
```
|
|
|
|
---
|
|
|
|
## 🐳 Docker
|
|
|
|
```bash
|
|
# 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 |
|