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:

```bash
# 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

```bash
# 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

```bash
# Build
pnpm build

# Executar em produção
pnpm start

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

## 🐳 Docker

```bash
# 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

```bash
# 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

```bash
# Abrir interface visual do banco de dados
pnpm prisma studio
```

## 🧪 Testes

```bash
# 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](../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