296 lines
6.6 KiB
Markdown
296 lines
6.6 KiB
Markdown
# Backoffice API - NestJS
|
|
|
|
[](https://nestjs.com/)
|
|
[](https://typescriptlang.org/)
|
|
[](https://fastify.io/)
|
|
|
|
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)
|
|
|
|
```typescript
|
|
// 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
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```typescript
|
|
// 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Instalar dependências
|
|
pnpm install
|
|
|
|
# Desenvolvimento
|
|
pnpm start:dev
|
|
|
|
# Produção
|
|
pnpm build
|
|
pnpm start:prod
|
|
```
|
|
|
|
### Testes
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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 |
|