diff --git a/backend/BACKEND.md b/backend/BACKEND.md index 9ec0c5f..419dcea 100755 --- a/backend/BACKEND.md +++ b/backend/BACKEND.md @@ -17,7 +17,7 @@ backend/ │ ├── internal/ │ ├── api/ # Clean Architecture Layer -│ │ ├── handlers/ # HTTP Handlers (Admin, Auth, Settings, Storage) +│ │ ├── handlers/ # HTTP Handlers (Admin, Auth, Settings, Storage, Tickets) │ │ └── middleware/ # Auth, CORS, Rate Limiting, Sanitize │ │ │ ├── core/ # Domain Layer (DDD) @@ -29,12 +29,11 @@ backend/ │ │ ├── auth/ # JWT Service implementation │ │ └── persistence/ # Repository implementations (Postgres) │ │ +│ ├── services/ # Business logic services (Email, Notification, Tickets) +│ │ │ ├── dto/ # Data Transfer Objects -│ ├── handlers/ # Legacy controllers (Job, Application) -│ ├── middleware/ # Security middlewares -│ ├── models/ # GORM models +│ ├── models/ # GORM models (Legacy/Transition) │ ├── router/ # Route configuration -│ ├── services/ # Business logic services │ └── utils/ # Helpers (JWT, Sanitizer) │ ├── migrations/ # SQL Migrations (30+) @@ -44,6 +43,36 @@ backend/ --- +## 🚀 Deployment & CI/CD (Forgejo) + +O deployment é automatizado via **Forgejo Actions**. + +### Workflow: `Deploy Backend (Dev)` +Arquivo: `.github/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 | @@ -51,13 +80,13 @@ backend/ | **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` | Sistema de tickets de suporte | +| **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` | Gestão de credenciais criptografadas | +| **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 | @@ -86,64 +115,35 @@ backend/ --- -## 📡 Endpoints +## 📡 Endpoints Principais -### Públicos +### 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 | -| Método | Endpoint | Descrição | -|--------|----------|-----------| -| `GET` | `/` | Root check | -| `GET` | `/health` | Health check | -| `GET` | `/docs/*` | Swagger UI | -| `POST` | `/api/v1/auth/login` | Login | -| `POST` | `/api/v1/auth/register/candidate` | Registro de candidato | -| `POST` | `/api/v1/auth/register/company` | Registro de empresa | -| `GET` | `/api/v1/jobs` | Listar vagas (filtros, paginação) | -| `GET` | `/api/v1/jobs/{id}` | Detalhes da vaga | -| `GET` | `/api/v1/companies/{id}` | Detalhes da empresa | +### 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 | -### Protegidos (JWT Required) +### 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 | -| Método | Endpoint | Roles | Descrição | -|--------|----------|-------|-----------| -| `GET` | `/api/v1/users/me` | `any` | Perfil do usuário | -| `PATCH` | `/api/v1/users/me/profile` | `any` | Atualizar perfil | -| `GET` | `/api/v1/users` | `admin`, `superadmin` | Listar usuários | -| `POST` | `/api/v1/users` | `admin`, `superadmin` | Criar usuário | -| `DELETE` | `/api/v1/users/{id}` | `superadmin` | Deletar usuário | - -### Vagas (Autenticado) - -| Método | Endpoint | Roles | Descrição | -|--------|----------|-------|-----------| -| `POST` | `/api/v1/jobs` | `admin`, `recruiter` | Criar vaga | -| `PUT` | `/api/v1/jobs/{id}` | `admin`, `recruiter` | Atualizar vaga | -| `DELETE` | `/api/v1/jobs/{id}` | `admin` | Deletar vaga | - -### Admin - -| Método | Endpoint | Descrição | -|--------|----------|-----------| -| `GET` | `/api/v1/admin/companies` | Listar empresas | -| `PATCH` | `/api/v1/admin/companies/{id}/status` | Aprovar/Suspender empresa | -| `GET` | `/api/v1/admin/email-templates` | Listar templates de email | -| `POST` | `/api/v1/admin/email-templates` | Criar template | -| `PUT` | `/api/v1/admin/email-templates/{slug}` | Atualizar template | -| `DELETE` | `/api/v1/admin/email-templates/{slug}` | Deletar template | -| `GET` | `/api/v1/admin/email-settings` | Obter configurações SMTP | -| `PUT` | `/api/v1/admin/email-settings` | Atualizar configurações SMTP | - -### Outros - -| Método | Endpoint | Descrição | -|--------|----------|-----------| -| `GET` | `/api/v1/storage/upload-url` | Pre-signed URL para upload | -| `GET` | `/api/v1/notifications` | Listar notificações | -| `POST` | `/api/v1/tokens` | Salvar FCM token | -| `GET` | `/api/v1/support/tickets` | Listar tickets | -| `POST` | `/api/v1/support/tickets` | Criar ticket | -| `GET` | `/api/v1/conversations` | Listar conversas | -| `POST` | `/api/v1/conversations/{id}/messages` | Enviar mensagem | +### 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 | --- @@ -151,59 +151,21 @@ backend/ O projeto usa um sistema de migrations manuais via `cmd/manual_migrate`. -### Principais Migrations - -| # | Arquivo | Descrição | -|---|---------|-----------| -| 000 | `000_init_uuid_v7.sql` | Função UUID v7 | -| 001 | `001_create_users_table.sql` | Tabela de usuários | -| 002 | `002_create_companies_table.sql` | Tabela de empresas | -| 005 | `005_create_jobs_table.sql` | Tabela de vagas | -| 006 | `006_create_applications_table.sql` | Tabela de candidaturas | -| 016 | `016_create_notifications_table.sql` | Notificações | -| 017 | `017_create_tickets_table.sql` | Tickets de suporte | -| 021 | `021_location_hierarchy.sql` | Países, regiões, cidades | -| 024 | `024_create_external_services_credentials.sql` | Credenciais criptografadas | -| 025 | `025_create_chat_tables.sql` | Conversas e mensagens | -| 026 | `026_create_system_settings.sql` | Configurações do sistema | -| 027 | `027_create_email_system.sql` | Templates e configurações de email | -| 028 | `028_add_avatar_url_to_users.sql` | Avatar de usuário | - ### Executar Migrations - ```bash go run ./cmd/manual_migrate ``` --- -## 🔧 Environment Variables +## 💻 Desenvolvimento Local -```bash -# Database -DATABASE_URL=postgres://user:pass@host:5432/dbname - -# Auth -JWT_SECRET=your-secret-key-min-32-chars -PASSWORD_PEPPER=your-pepper-key - -# CORS -CORS_ORIGINS=https://frontend.com,https://admin.com - -# External Services -RSA_PRIVATE_KEY_BASE64=base64-encoded-private-key - -# Optional -PORT=8080 -ENV=production -``` - ---- - -## 🚀 Desenvolvimento - -### Executar +### Pré-requisitos +- Go 1.22+ +- Docker & Docker Compose **OU** Podman +- PostgreSQL +### Executar com Go ```bash # Copiar .env cp .env.example .env @@ -215,67 +177,25 @@ go run ./cmd/manual_migrate go run ./cmd/api ``` -### Testes +### Executar com Docker +```bash +docker compose up -d +``` +### 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 ./... - -# Verbose -go test -v ./internal/services/... ``` - -### Build - -```bash -go build -o api ./cmd/api -``` - -### 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 | -| `cmd/manual_migrate/main.go` | Migration runner | -| `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 | - ---- - -## 🔗 Integrações - -| Serviço | Uso | -|---------|-----| -| **LavinMQ** | Fila de emails assíncronos | -| **Appwrite** | Chat realtime | -| **Firebase** | Push notifications (FCM) | -| **Cloudflare** | CDN com cache purge | -| **S3/R2** | Storage com pre-signed URLs | -| **Stripe** | Pagamentos (via Backoffice) |