From 6700d367f0b9e2d1490cf7d4243125a43a3ea6fa Mon Sep 17 00:00:00 2001 From: Yamamoto Date: Fri, 2 Jan 2026 18:58:08 -0300 Subject: [PATCH] docs: update BACKEND.md with comprehensive API routes and removal of docker-compose --- backend/BACKEND.md | 132 +++++++++++++++++++++++++++++++++------------ 1 file changed, 99 insertions(+), 33 deletions(-) diff --git a/backend/BACKEND.md b/backend/BACKEND.md index 845dd4d..4c390bd 100755 --- a/backend/BACKEND.md +++ b/backend/BACKEND.md @@ -141,61 +141,123 @@ Este workflow é disparado automaticamente ao realizar um push para o branch `de ## 📡 Endpoints (API Reference) -### 🔐 Auth & Core +### 🔐 Auth & Identity | Método | Endpoint | Descrição | Roles | |--------|----------|-----------|-------| -| `POST` | `/api/v1/auth/login` | Autenticação de usuário | Public | +| `POST` | `/api/v1/auth/login` | Autenticação (Retorna JWT + User) | Public | +| `POST` | `/api/v1/auth/logout` | Logout (Limpa Cookie HttpOnly) | Public | | `POST` | `/api/v1/auth/register` | Registro de Candidato | Public | -| `POST` | `/api/v1/auth/register/company` | Registro de Empresa | Public | +| `POST` | `/api/v1/auth/register/company` | Registro de Empresa (Cria Admin) | Public | +| `POST` | `/api/v1/tokens` | Salvar token FCM para Push | Auth | + +### 👤 Users & Profiles +| Método | Endpoint | Descrição | Roles | +|--------|----------|-----------|-------| | `GET` | `/api/v1/users/me` | Dados do usuário logado | Auth | -| `PATCH` | `/api/v1/users/me/profile` | Atualizar perfil | Auth | -| `GET` | `/api/v1/notifications` | Listar notificações | Auth | -| `POST` | `/api/v1/tokens` | Salvar token FCM | Auth | +| `PATCH` | `/api/v1/users/me/profile` | Atualizar meu perfil | Auth | +| `GET` | `/api/v1/users` | Listar usuários (Admin: da empresa. Superadmin: todos) | Admin/Super | +| `POST` | `/api/v1/users` | Criar usuário (Admin: user normal. Superadmin: pode criar outros Supers) | Admin/Super | +| `GET` | `/api/v1/users/roles` | Listar roles disponíveis no sistema | Admin/Super | +| `PATCH` | `/api/v1/users/{id}` | Atualizar usuário | Admin/Super | +| `DELETE` | `/api/v1/users/{id}` | Remover usuário | Admin/Super | + +### 🏢 Companies (Tenants) +| Método | Endpoint | Descrição | Roles | +|--------|----------|-----------|-------| +| `GET` | `/api/v1/companies` | Listar empresas (Public: simples. Admin: detalhado) | Public/Admin | +| `POST` | `/api/v1/companies` | Criar nova empresa (via auto-cadastro ou Admin) | Public | +| `GET` | `/api/v1/companies/{id}` | Detalhes da empresa | Public | +| `PATCH` | `/api/v1/companies/{id}` | Editar dados da empresa | Admin/Super | +| `PATCH` | `/api/v1/companies/{id}/status` | Alterar status (Ativo/Inativo) | Admin/Super | +| `DELETE` | `/api/v1/companies/{id}` | Remover empresa (Soft delete) | Admin/Super | ### 💼 Jobs (Vagas) | Método | Endpoint | Descrição | Roles | |--------|----------|-----------|-------| -| `GET` | `/api/v1/jobs` | Listar vagas (filtros) | Public | +| `GET` | `/api/v1/jobs` | Listar vagas (filtros: local, keywords) | Public | | `GET` | `/api/v1/jobs/{id}` | Detalhes da vaga | Public | | `POST` | `/api/v1/jobs` | Criar nova vaga | Recruiter | | `PUT` | `/api/v1/jobs/{id}` | Editar vaga | Recruiter | | `DELETE` | `/api/v1/jobs/{id}` | Remover vaga | Recruiter | +| `POST` | `/api/v1/jobs/{id}/duplicate` | Duplicar uma vaga existente | Admin/Recruiter | +| `GET` | `/api/v1/jobs/moderation` | Listar vagas para moderação | Admin/Super | +| `PATCH` | `/api/v1/jobs/{id}/status` | Aprovar/Rejeitar vaga | Admin/Super | ### 📝 Applications (Candidaturas) | Método | Endpoint | Descrição | Roles | |--------|----------|-----------|-------| | `POST` | `/api/v1/applications` | Candidatar-se a uma vaga | Candidate | -| `GET` | `/api/v1/applications` | Minhas candidaturas | Auth | +| `GET` | `/api/v1/applications` | Minhas candidaturas (ou recebidas, se Recruiter) | Auth | | `GET` | `/api/v1/applications/{id}` | Detalhes da candidatura | Auth | -| `PUT` | `/api/v1/applications/{id}/status` | Atualizar status | Recruiter | +| `PUT` | `/api/v1/applications/{id}/status` | Atualizar fase/status | Recruiter | | `DELETE` | `/api/v1/applications/{id}` | Desistir/Remover | Auth | +| `GET` | `/api/v1/candidates` | Listar base de candidatos (Global) | Admin/Super | ### 🎫 Support (Tickets) | Método | Endpoint | Descrição | Roles | |--------|----------|-----------|-------| | `GET` | `/api/v1/support/tickets` | Meus tickets de suporte | Auth | +| `GET` | `/api/v1/support/tickets/all` | Todos os tickets (Visão Admin) | SuperAdmin | | `POST` | `/api/v1/support/tickets` | Abrir novo ticket | Auth | | `GET` | `/api/v1/support/tickets/{id}` | Ver conversa do ticket | Auth | -| `POST` | `/api/v1/support/tickets/{id}/messages` | Enviar mensagem | Auth | +| `POST` | `/api/v1/support/tickets/{id}/messages` | Enviar mensagem no ticket | Auth | | `PATCH` | `/api/v1/support/tickets/{id}/close` | Fechar ticket | Auth | +| `DELETE` | `/api/v1/support/tickets/{id}` | Remover ticket | Admin/Super | -### 💬 Chat & Locais +### 💬 Chat & Messaging | Método | Endpoint | Descrição | Roles | |--------|----------|-----------|-------| -| `GET` | `/api/v1/conversations` | Listar conversas | Auth | -| `GET` | `/api/v1/conversations/{id}/messages` | Ver mensagens | Auth | -| `POST` | `/api/v1/conversations/{id}/messages` | Enviar mensagem | Auth | -| `GET` | `/api/v1/locations/search` | Buscar cidade/estado | Public | +| `GET` | `/api/v1/conversations` | Listar conversas ativas | Auth | +| `GET` | `/api/v1/conversations/{id}/messages` | Ver histórico de mensagens | Auth | +| `POST` | `/api/v1/conversations/{id}/messages` | Enviar mensagem direta | Auth | -### 🛡️ Admin & System +### 🔔 Notifications | Método | Endpoint | Descrição | Roles | |--------|----------|-----------|-------| -| `GET` | `/api/v1/users` | Listar todos usuários | Admin | -| `GET` | `/api/v1/jobs/moderation` | Moderação de vagas | Admin | -| `GET` | `/api/v1/system/credentials` | Ver credenciais (mascaradas) | Admin | -| `POST` | `/api/v1/system/credentials` | Salvar credencial | Admin | -| `POST` | `/api/v1/system/cloudflare/purge` | Limpar cache CDN | Admin | -| `GET` | `/api/v1/admin/email-templates` | Gerenciar emails | Admin | +| `GET` | `/api/v1/notifications` | Listar notificações | Auth | +| `PATCH` | `/api/v1/notifications/{id}/read` | Marcar como lida | Auth | +| `PATCH` | `/api/v1/notifications/read-all` | Marcar todas como lidas | Auth | + +### 🌍 Locations +| Método | Endpoint | Descrição | Roles | +|--------|----------|-----------|-------| +| `GET` | `/api/v1/locations/countries` | Listar países | Public | +| `GET` | `/api/v1/locations/countries/{id}/states` | Listar estados de um país | Public | +| `GET` | `/api/v1/locations/states/{id}/cities` | Listar cidades de um estado | Public | +| `GET` | `/api/v1/locations/search` | Busca textual (Cidade/Estado) | Public | + +### 🏷️ Tags & Metadata +| Método | Endpoint | Descrição | Roles | +|--------|----------|-----------|-------| +| `GET` | `/api/v1/tags` | Listar tags (skills, benefícios) | Public | +| `POST` | `/api/v1/tags` | Criar nova tag | Admin/Super | +| `PATCH` | `/api/v1/tags/{id}` | Editar tag | Admin/Super | + +### ⚙️ System & Settings +| Método | Endpoint | Descrição | Roles | +|--------|----------|-----------|-------| +| `GET` | `/api/v1/system/settings/{key}` | Ler configuração de sistema | Auth | +| `POST` | `/api/v1/system/settings/{key}` | Salvar configuração | SuperAdmin | +| `GET` | `/api/v1/system/credentials` | Ver credenciais (mascaradas) | SuperAdmin | +| `POST` | `/api/v1/system/credentials` | Salvar/Rotacionar credencial | SuperAdmin | +| `GET` | `/api/v1/storage/upload-url` | Gerar URL pré-assinada (S3/R2) | Auth | +| `POST` | `/api/v1/system/cloudflare/purge` | Limpar cache CDN | SuperAdmin | +| `GET` | `/api/v1/audit/logins` | Ver logs de acesso | SuperAdmin | + +### 📧 Email Management +| Método | Endpoint | Descrição | Roles | +|--------|----------|-----------|-------| +| `GET` | `/api/v1/admin/email-templates` | Listar templates | SuperAdmin | +| `POST` | `/api/v1/admin/email-templates` | Criar template | SuperAdmin | +| `GET` | `/api/v1/admin/email-settings` | Configurações SMTP/Provider | SuperAdmin | +| `PUT` | `/api/v1/admin/email-settings` | Atualizar configs de email | SuperAdmin | + +### 💳 Payments +| Método | Endpoint | Descrição | Roles | +|--------|----------|-----------|-------| +| `POST` | `/api/v1/payments/create-checkout` | Criar sessão de checkout | Auth | +| `GET` | `/api/v1/payments/status/{id}` | Verificar status pagto | Auth | +| `POST` | `/api/v1/payments/webhook` | Webhook (Stripe/Gateway) | Public | --- @@ -213,31 +275,35 @@ go run ./cmd/manual_migrate ## 💻 Desenvolvimento Local ### Pré-requisitos -- Go 1.22+ -- Docker & Docker Compose **OU** Podman -- PostgreSQL +- **Go 1.22+** +- **Podman** (ou Docker, mas o projeto é otimizado para Podman/Quadlet) +- **PostgreSQL** (Rodando local ou via container) -### Executar com Go +### Executar com Go (Método Padrão) ```bash -# Copiar .env +# 1. Configurar Ambiente cp .env.example .env +# Edite o .env com suas credentials (DB, JWT_SECRET, etc) -# Executar migrations +# 2. Executar Migrations go run ./cmd/manual_migrate -# Iniciar servidor +# 3. Iniciar API Server go run ./cmd/api ``` -### Executar com Podman +### Executar com Podman (Container) ```bash -# Build +# Construir a imagem podman build -t gohorse-backend ./backend -# Run -podman run -p 8080:8080 --env-file ./backend/.env gohorse-backend +# Rodar o container +# Nota: --network host é útil em dev para acessar o DB local facilmente +podman run --name api -p 8080:8080 --env-file ./backend/.env gohorse-backend ``` +> **Nota:** Não utilizamos `docker-compose` neste projeto. A infraestrutura de produção utiliza **Quadlet (Systemd + Podman)**. Para dev, recomenda-se rodar o binário Go nativo ou usar `podman run` individualmente. + ### Testes ```bash # Todos os testes