saveinmed/backoffice/BACKOFFICE.md

SaveInMed Backoffice

Sistema de gestão administrativa (backoffice) do SaveInMed, desenvolvido com NestJS e Fastify.

🎯 Propósito

O Backoffice é a interface de administração e gestão do SaveInMed, fornecendo ferramentas para:

• Gerenciamento de usuários e autenticação
• Controle de inventário e estoque
• Administração de empresas cadastradas
• Processamento de webhooks de pagamento
• Relatórios e analytics

🚀 Tecnologias

• NestJS 10 - Framework backend progressivo para Node.js
• Fastify 4 - Web framework de alta performance
• Prisma 5 - ORM moderno para TypeScript
• PostgreSQL - Banco de dados relacional
• JWT - Autenticação via JSON Web Tokens
• Bcrypt - Hash seguro de senhas
• Swagger - Documentação automática da API

📋 Funcionalidades

Autenticação e Autorização

• Login com JWT (access + refresh tokens)
• Proteção de rotas com guards
• Estratégias de autenticação Passport
• Refresh token rotation

Gestão de Usuários

• CRUD completo de usuários
• Perfis e permissões
• Validação de dados com class-validator

Inventário

• Controle de produtos e estoque
• Registro de compras
• Movimentação de produtos
• Relatórios de inventário

Webhooks

• Processamento de notificações do Mercado Pago
• Atualização automática de status de pedidos
• Logs de eventos

🏗️ Arquitetura

backoffice/
├── prisma/
│   └── schema.prisma         # Schema do banco de dados
├── src/
│   ├── auth/                 # Módulo de autenticação
│   │   ├── guards/           # Guards JWT e Refresh Token
│   │   ├── strategies/       # Estratégias Passport
│   │   └── dto/              # DTOs de login
│   ├── users/                # Módulo de usuários
│   │   ├── users.controller.ts
│   │   ├── users.service.ts
│   │   └── dto/
│   ├── inventory/            # Módulo de inventário
│   │   ├── inventory.controller.ts
│   │   ├── inventory.service.ts
│   │   └── dto/
│   ├── webhooks/             # Módulo de webhooks
│   │   ├── webhooks.controller.ts
│   │   └── webhooks.module.ts
│   ├── common/               # Recursos compartilhados
│   │   └── guards/
│   ├── prisma/               # Módulo Prisma
│   │   ├── prisma.module.ts
│   │   └── prisma.service.ts
│   ├── app.module.ts         # Módulo raiz
│   └── main.ts               # Entry point
├── Dockerfile
├── nest-cli.json
├── package.json
└── README.md

🔧 Configuração

Variáveis de Ambiente

Crie um arquivo .env na raiz do projeto:

# Database
DATABASE_URL="postgresql://user:password@localhost:5432/saveinmed?schema=public"

# JWT
JWT_SECRET="your-secret-key-here"
JWT_REFRESH_SECRET="your-refresh-secret-key-here"
JWT_EXPIRES_IN="15m"
JWT_REFRESH_EXPIRES_IN="7d"

# Server
PORT=3000
NODE_ENV=development

Pré-requisitos

• Node.js 20+
• pnpm 8+ (gerenciador de pacotes)
• PostgreSQL 14+

🏃 Execução Local

# Instalar dependências
pnpm install

# Gerar Prisma Client
pnpm prisma:generate

# Executar migrations
pnpm prisma migrate dev

# Modo desenvolvimento
pnpm start:dev

# Modo debug
pnpm start:debug

# API estará disponível em http://localhost:3000
# Swagger UI em http://localhost:3000/api

🏗️ Build e Produção

# Build
pnpm build

# Executar em produção
pnpm start

# Ou com PM2
pm2 start dist/main.js --name saveinmed-backoffice

🐳 Docker

# Build da imagem
docker build -t saveinmed-backoffice:latest .

# Executar container
docker run -p 3000:3000 \
  -e DATABASE_URL="postgresql://..." \
  -e JWT_SECRET="..." \
  saveinmed-backoffice:latest

📚 Documentação da API

A documentação completa da API está disponível via Swagger UI:

http://localhost:3000/api

Principais Endpoints

Autenticação

• POST /auth/login - Login de usuário
• POST /auth/refresh - Renovar access token
• GET /auth/me - Obter usuário autenticado

Usuários

• GET /users - Listar usuários
• POST /users - Criar usuário
• GET /users/:id - Obter usuário por ID
• PATCH /users/:id - Atualizar usuário
• DELETE /users/:id - Deletar usuário

Inventário

• GET /inventory - Listar itens do inventário
• POST /inventory/purchase - Registrar compra
• GET /inventory/:id - Obter item por ID

Webhooks

• POST /webhooks/mercadopago - Webhook do Mercado Pago

🗄️ Prisma

Migrations

# Criar nova migration
pnpm prisma migrate dev --name nome_da_migration

# Aplicar migrations em produção
pnpm prisma migrate deploy

# Resetar banco de dados (desenvolvimento)
pnpm prisma migrate reset

Prisma Studio

# Abrir interface visual do banco de dados
pnpm prisma studio

🧪 Testes

# Testes unitários
pnpm test

# Testes e2e
pnpm test:e2e

# Coverage
pnpm test:cov

Para matriz completa (com/sem banco e Playwright), veja: docs/TESTES.md

🔒 Segurança

• Senhas hasheadas com bcrypt (salt rounds: 10)
• JWT com expiração curta (15 minutos)
• Refresh tokens com rotação automática
• Validação de entrada com class-validator
• Guards para proteção de rotas
• CORS configurado adequadamente

🔗 Integração com Outros Componentes

• Backend (Go API): Compartilha o mesmo banco de dados PostgreSQL
• SaveInMed Frontend: Consome esta API para operações administrativas
• Mercado Pago: Recebe webhooks de notificação de pagamento

📝 Licença

MIT