gohorsejobs/backoffice/BACKOFFICE.md

Backoffice API - NestJS

GoHorse Jobs SaaS Administration, Subscription Management, and Email Worker API.

---

🏗️ Arquitetura

backoffice/
├── src/
│   ├── admin/              # Dashboard e estatísticas
│   │   ├── admin.controller.ts
│   │   ├── admin.service.ts
│   │   └── admin.module.ts
│   │
│   ├── auth/               # Autenticação JWT
│   │   ├── jwt-auth.guard.ts
│   │   ├── jwt-strategy.ts
│   │   └── auth.module.ts
│   │
│   ├── email/              # Email Worker (LavinMQ Consumer)
│   │   ├── email.service.ts
│   │   ├── email.module.ts
│   │   └── entities/
│   │       ├── email-setting.entity.ts
│   │       └── email-template.entity.ts
│   │
│   ├── external-services/  # Gestão de credenciais
│   │   ├── external-services.controller.ts
│   │   ├── external-services.service.ts
│   │   └── external-services.module.ts
│   │
│   ├── fcm-tokens/         # Firebase Cloud Messaging
│   │   ├── fcm-tokens.controller.ts
│   │   ├── fcm-tokens.service.ts
│   │   └── fcm-tokens.module.ts
│   │
│   ├── plans/              # Planos de assinatura
│   │   ├── plans.controller.ts
│   │   ├── plans.service.ts
│   │   └── plans.module.ts
│   │
│   ├── stripe/             # Integração Stripe
│   │   ├── stripe.controller.ts
│   │   ├── stripe.service.ts
│   │   └── stripe.module.ts
│   │
│   ├── app.module.ts       # Módulo raiz
│   └── main.ts             # Bootstrap

---

🔧 Módulos

Módulo	Descrição
AdminModule	Dashboard stats, revenue analytics, subscription metrics
AuthModule	JWT validation (Bearer + Cookie), guards
EmailModule	LavinMQ consumer, Nodemailer sender, template rendering (Handlebars)
ExternalServicesModule	RSA encryption, credentials storage
FcmTokensModule	Firebase Admin SDK, push notifications
PlansModule	Subscription plans CRUD
StripeModule	Checkout sessions, webhooks, billing portal

---

📧 Email Worker

O módulo EmailModule atua como consumer do LavinMQ:

Fluxo

1. Go Backend → Publica job em `mail_queue`
2. NestJS → Consome job da fila
3. NestJS → Busca template do banco (email_templates)
4. NestJS → Renderiza com Handlebars
5. NestJS → Envia via SMTP (Nodemailer)

Entidades (TypeORM)

// email_settings
{
  id: UUID,
  provider: string,
  smtp_host: string,
  smtp_port: number,
  smtp_user: string,
  smtp_pass: string,
  smtp_secure: boolean,
  sender_name: string,
  sender_email: string,
  amqp_url: string,
  is_active: boolean
}

// email_templates
{
  id: UUID,
  slug: string,
  subject: string,
  body_html: string,
  variables: string[]
}

---

💳 Stripe Integration

Endpoints

Método	Endpoint	Descrição
POST	/stripe/checkout	Criar Checkout Session
POST	/stripe/portal	Criar Billing Portal
POST	/stripe/webhook	Webhook handler

Webhooks Suportados

• checkout.session.completed - Pagamento concluído
• customer.subscription.created - Nova assinatura
• customer.subscription.updated - Assinatura atualizada
• customer.subscription.deleted - Assinatura cancelada
• invoice.payment_failed - Pagamento falhou

---

📊 Admin Dashboard

Endpoints

Método	Endpoint	Descrição
GET	/admin/stats	Dashboard stats
GET	/admin/revenue	Revenue by month
GET	/admin/subscriptions-by-plan	Subscriptions breakdown

Stats Response

{
  "totalCompanies": 150,
  "activeSubscriptions": 120,
  "monthlyRevenue": 25000,
  "newCompaniesThisMonth": 15
}

---

🔒 Autenticação

O backoffice suporta dois métodos:

1. Bearer Token - Authorization: Bearer <token>
2. JWT Cookie - jwt=<token> (fallback)

Implementado em src/auth/jwt-auth.guard.ts.

---

🔐 External Services Credentials

Gerenciamento seguro de credenciais com criptografia RSA:

// Fluxo de criptografia
1. Frontend envia credencial
2. Backoffice criptografa com RSA public key
3. Armazena criptografada no banco (external_services_credentials)
4. Go Backend descriptografa com private key quando necessário

Services Suportados

• Stripe
• Firebase (FCM)
• Cloudflare
• SMTP (Email)
• S3/R2 (Storage)

---

🔧 Environment Variables

# Server
PORT=3001

# Database (compartilhado com Go)
DATABASE_URL=postgres://user:pass@host:5432/dbname

# Stripe
STRIPE_SECRET_KEY=sk_test_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx

# Firebase
FIREBASE_ADMIN_SDK_PATH=/path/to/service-account.json
# OU
FIREBASE_SERVICE_ACCOUNT={"type":"service_account",...}

# JWT (mesmo do Go backend)
JWT_SECRET=your-secret-key

---

🚀 Desenvolvimento

Requisitos

• Node.js 20+
• pnpm 9+

Executar

# Instalar dependências
pnpm install

# Desenvolvimento
pnpm start:dev

# Produção
pnpm build
pnpm start:prod

Testes

# Unit tests
pnpm test

# E2E tests
pnpm test:e2e

# Coverage
pnpm test:cov

---

📡 API Documentation

Swagger UI disponível em:

Development: http://localhost:3001/api/docs

---

🐳 Docker

# Build
docker build -t gohorse-backoffice .

# Run
docker run -p 3001:3001 --env-file .env gohorse-backoffice

---

📦 Tech Stack

Tecnologia	Versão	Uso
NestJS	11+	Framework
Fastify	4+	HTTP Server
TypeORM	0.3+	ORM (Email entities)
Stripe	20+	Pagamentos
Firebase Admin	13+	Push Notifications
amqplib	0.10+	LavinMQ Consumer
Nodemailer	6+	SMTP Client
Handlebars	4+	Template Engine
Pino	9+	Logging

---

🔗 Integrações

Serviço	Módulo	Uso
Stripe	StripeModule	Pagamentos, assinaturas
LavinMQ	EmailModule	Fila de emails
Firebase	FcmTokensModule	Push notifications
PostgreSQL	TypeORM	Email settings/templates