gohorsejobs/backend/BACKEND.md

Backend - GoHorse Jobs API

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)

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 ubuntu-latest.
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 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

go run ./cmd/manual_migrate

---

💻 Desenvolvimento Local

Pré-requisitos

• Go 1.22+
• Docker & Docker Compose OU Podman
• PostgreSQL

Executar com Go

# Copiar .env
cp .env.example .env

# Executar migrations
go run ./cmd/manual_migrate

# Iniciar servidor
go run ./cmd/api

Executar com Docker

docker compose up -d

Executar com Podman

# Build
podman build -t gohorse-backend ./backend

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

Testes

# Todos os testes
go test ./...

# Com cobertura
go test -cover ./...