242 lines
8.3 KiB
Markdown
Executable file
242 lines
8.3 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
|
|
|
|
```
|
|
backend/
|
|
├── cmd/
|
|
│ ├── api/ # Entrypoint principal
|
|
│ └── manual_migrate/ # Migration runner
|
|
│
|
|
├── internal/
|
|
│ ├── api/ # Clean Architecture Layer
|
|
│ │ ├── handlers/ # HTTP Handlers (Admin, Auth, Settings, Storage, Tickets)
|
|
│ │ └── middleware/ # Auth, CORS, Rate Limiting, Sanitize
|
|
│ │
|
|
│ ├── core/ # Domain Layer (DDD)
|
|
│ │ ├── domain/entity/ # Entidades (User, Company, Email)
|
|
│ │ ├── ports/ # Interfaces (Repositories)
|
|
│ │ └── usecases/ # Casos de uso (Auth, Register)
|
|
│ │
|
|
│ ├── infrastructure/ # Infrastructure Layer
|
|
│ │ ├── auth/ # JWT Service implementation
|
|
│ │ └── persistence/ # Repository implementations (Postgres)
|
|
│ │
|
|
│ ├── services/ # Business logic services (Email, Notification, Tickets)
|
|
│ │
|
|
│ ├── dto/ # Data Transfer Objects
|
|
│ ├── models/ # GORM models (Legacy/Transition)
|
|
│ ├── router/ # Route configuration
|
|
│ └── utils/ # Helpers (JWT, Sanitizer)
|
|
│
|
|
├── migrations/ # SQL Migrations (30+)
|
|
├── tests/ # E2E and Integration tests
|
|
└── docs/ # Swagger documentation
|
|
```
|
|
|
|
### 📊 Diagrama de Fluxo (C4 Simplificado)
|
|
|
|
```mermaid
|
|
graph TD
|
|
Client[📱 Clients (Frontend/App)] -->|JSON/HTTP| Router[🚦 Router (Mux)]
|
|
|
|
subgraph "Core Backend"
|
|
Router --> Middleware[🛡️ Middleware (Auth, CORS)]
|
|
Middleware --> Handlers[🎮 HTTP Handlers]
|
|
|
|
Handlers --> UseCases[🧠 Services & UseCases]
|
|
|
|
UseCases --> Repos[💾 Repositories]
|
|
UseCases --> Adapters[🔌 External Adapters]
|
|
end
|
|
|
|
Repos --> DB[(🐘 PostgreSQL)]
|
|
|
|
Adapters --> Firebase[🔥 Firebase (FCM)]
|
|
Adapters --> LavinMQ[📨 LavinMQ]
|
|
Adapters --> Storage[☁️ S3/R2 Storage]
|
|
Adapters --> Stripe[💳 Stripe]
|
|
```
|
|
|
|
---
|
|
|
|
## 🚀 Deployment & CI/CD (Forgejo)
|
|
|
|
O deployment é automatizado via **Forgejo Actions**.
|
|
|
|
### Workflow: `Deploy Backend (Dev)`
|
|
Arquivo: `.forgejo/workflows/deploy.yaml`
|
|
|
|
Este workflow é disparado automaticamente ao realizar um push para o branch `dev` com alterações na pasta `backend/`.
|
|
|
|
**Etapas do CI/CD:**
|
|
1. **Trigger:** Push no branch `dev` (apenas alterações em `backend/**`).
|
|
2. **Runner:** Executa no ambiente `docker` (verifique as labels do seu runner).
|
|
3. **SSH Action:** Conecta no servidor de desenvolvimento (Apolo) via SSH.
|
|
4. **Atualização de Código:**
|
|
* Navega até `/mnt/data/gohorsejobs` (ou caminho configurado).
|
|
* Faz `git fetch` e `git checkout dev`.
|
|
* `git pull origin dev`.
|
|
5. **Build & Restart (Podman):**
|
|
* Constrói a imagem: `podman build -t localhost/gohorsejobs-backend-dev ./backend`
|
|
* Reinicia o serviço: `sudo systemctl restart gohorsejobs-backend-dev`
|
|
* Limpeza: `podman image prune -f`
|
|
|
|
**Secrets Necessários (Forgejo):**
|
|
* `HOST`: IP do servidor.
|
|
* `USERNAME`: Usuário SSH.
|
|
* `SSH_KEY`: Chave privada SSH.
|
|
* `PORT`: Porta SSH (ex: 22).
|
|
|
|
---
|
|
|
|
## 🔧 Services
|
|
|
|
| Service | Arquivo | Descrição |
|
|
|---------|---------|-----------|
|
|
| **AdminService** | `admin_service.go` | CRUD de empresas, usuários, candidatos, tags, email templates |
|
|
| **JobService** | `job_service.go` | CRUD de vagas com filtros avançados |
|
|
| **ApplicationService** | `application_service.go` | Gestão de candidaturas |
|
|
| **TicketService** | `ticket_service.go` | **(Novo)** Sistema de tickets de suporte |
|
|
| **ChatService** | `chat_service.go` | Mensagens e conversas (Appwrite) |
|
|
| **NotificationService** | `notification_service.go` | Notificações push |
|
|
| **EmailService** | `email_service.go` | Produtor de emails via LavinMQ |
|
|
| **FCMService** | `fcm_service.go` | Firebase Cloud Messaging |
|
|
| **StorageService** | `storage_service.go` | Pre-signed URLs (S3/R2) |
|
|
| **CredentialsService** | `credentials_service.go` | **(Novo)** Gestão de credenciais criptografadas |
|
|
| **CloudflareService** | `cloudflare_service.go` | Cache purge via API |
|
|
| **SettingsService** | `settings_service.go` | System settings |
|
|
| **AppwriteService** | `appwrite_service.go` | Integração Appwrite Realtime |
|
|
| **AuditService** | `audit_service.go` | Logs de auditoria |
|
|
|
|
---
|
|
|
|
## 🔒 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.) |
|
|
| **Sanitize** | `middleware/sanitize.go` | XSS sanitization em JSON bodies |
|
|
|
|
### Autenticação
|
|
|
|
- **JWT** com expiração configurável
|
|
- **Password Pepper** via `PASSWORD_PEPPER` env var
|
|
- **HttpOnly Cookies** para refresh tokens
|
|
- **RSA Encryption** para credenciais sensíveis
|
|
|
|
---
|
|
|
|
## 📡 Endpoints Principais
|
|
|
|
### Helper & System
|
|
| Recurso | Método | Endpoint | Descrição |
|
|
|---------|--------|----------|-----------|
|
|
| Health | `GET` | `/health` | Health Check |
|
|
| Docs | `GET` | `/docs/*` | Swagger UI |
|
|
| Settings| `GET` | `/api/v1/system/settings/{key}` | Obter configurações públicas |
|
|
|
|
### Auth & Usuários
|
|
| Recurso | Método | Endpoint | Roles |
|
|
|---------|--------|----------|-------|
|
|
| Login | `POST` | `/api/v1/auth/login` | Public |
|
|
| Me | `GET` | `/api/v1/users/me` | Auth |
|
|
| Profile | `PATCH`| `/api/v1/users/me/profile` | Auth |
|
|
|
|
### Tickets & Suporte (Novo)
|
|
| Recurso | Método | Endpoint | Roles |
|
|
|---------|--------|----------|-------|
|
|
| Listar | `GET` | `/api/v1/support/tickets` | Auth |
|
|
| Criar | `POST` | `/api/v1/support/tickets` | Auth |
|
|
| Mensagem| `POST` | `/api/v1/support/tickets/{id}/messages`| Auth |
|
|
|
|
### Admin & Credenciais (Novo)
|
|
| Recurso | Método | Endpoint | Roles |
|
|
|---------|--------|----------|-------|
|
|
| Credentials | `GET` | `/api/v1/system/credentials` | Admin |
|
|
| Credentials | `POST` | `/api/v1/system/credentials` | Admin |
|
|
| Purge Cache | `POST` | `/api/v1/system/cloudflare/purge`| Admin |
|
|
|
|
---
|
|
|
|
## 🗄️ Migrations
|
|
|
|
O projeto usa um sistema de migrations manuais via `cmd/manual_migrate`.
|
|
|
|
### Executar Migrations
|
|
```bash
|
|
go run ./cmd/manual_migrate
|
|
```
|
|
|
|
---
|
|
|
|
## 💻 Desenvolvimento Local
|
|
|
|
### Pré-requisitos
|
|
- Go 1.22+
|
|
- Docker & Docker Compose **OU** Podman
|
|
- PostgreSQL
|
|
|
|
### Executar com Go
|
|
```bash
|
|
# Copiar .env
|
|
cp .env.example .env
|
|
|
|
# Executar migrations
|
|
go run ./cmd/manual_migrate
|
|
|
|
# Iniciar servidor
|
|
go run ./cmd/api
|
|
```
|
|
|
|
### Executar com Podman
|
|
```bash
|
|
# Build
|
|
podman build -t gohorse-backend ./backend
|
|
|
|
# Run
|
|
podman run -p 8080:8080 --env-file ./backend/.env gohorse-backend
|
|
```
|
|
|
|
### Testes
|
|
```bash
|
|
# Todos os testes
|
|
go test ./...
|
|
|
|
# Com cobertura
|
|
go test -cover ./...
|
|
```
|
|
|
|
---
|
|
|
|
## ❓ Troubleshooting (CI/CD & Runner)
|
|
|
|
### O Workflow não inicia (`Waiting for runner...`)
|
|
* **Causa:** Nenhuma maquina registrada com o label correto.
|
|
* **Solução:**
|
|
1. Verifique, no arquivo `.forgejo/workflows/deploy.yaml`, o campo `runs-on`.
|
|
2. Se estiver como `docker`, seu `act_runner` deve ter suporte a este label (ex: `labels: "docker:docker://node:16-bullseye,ubuntu-latest:docker://node:16-bullseye"` no `config.yaml`).
|
|
3. Se o runner for genérico, use `ubuntu-latest`.
|
|
|
|
### Falha de SSH (`ssh: handshake failed`)
|
|
* **Solução:**
|
|
1. Verifique se a chave pública (`id_rsa.pub`) correspondente à `SSH_KEY` do secret está no arquivo `~/.ssh/authorized_keys` da máquina de destino.
|
|
2. Confira se o IP (`HOST`) está acessível da rede onde o runner está.
|
|
|
|
### Falha de Build no Podman
|
|
* **Causa:** Falta de permissão ou serviço parado.
|
|
* **Solução:**
|
|
1. Rode `podman logs -f <conteiner>` na máquina de destino.
|
|
2. Verifique se o usuário tem permissão de usar podman (rootless ou sudo).
|