# Backoffice API - NestJS

[![NestJS](https://img.shields.io/badge/NestJS-11+-E0234E?style=flat-square&logo=nestjs)](https://nestjs.com/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5+-3178C6?style=flat-square&logo=typescript)](https://typescriptlang.org/)
[![Fastify](https://img.shields.io/badge/Fastify-4+-000000?style=flat-square&logo=fastify)](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 |