# Backend - GoHorse Jobs API

[![Go](https://img.shields.io/badge/Go-1.24-00ADD8?style=flat-square&logo=go)](https://golang.org/)
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16-336791?style=flat-square&logo=postgresql)](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 CoreBackend [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).