saveinmed/backend/BACKEND.md

# SaveInMed API (Backend Go)

## Status (pronto x faltando)

**Pronto**
- Conteúdo descrito neste documento.

**Faltando**
- Confirmar no código o estado real das funcionalidades e atualizar esta seção conforme necessário.

---


API de alta performance em Go 1.24 para o marketplace farmacêutico B2B SaveInMed.

## 🎯 Propósito

Este é o núcleo de performance do SaveInMed, responsável por operações críticas que exigem alta velocidade e eficiência, incluindo:
- Gestão de empresas (farmácias, distribuidoras, administradores)
- Catálogo de produtos com controle de lote e validade
- Processamento de pedidos
- Integração com Mercado Pago para pagamentos

## 🚀 Tecnologias

- **Go 1.24.3** - Linguagem de programação
- **PostgreSQL** - Banco de dados (via pgx/v5)
- **json-iterator** - Serialização JSON de alta performance
- **Swagger** - Documentação automática da API
- **Gzip** - Compressão de respostas

## 📋 Funcionalidades

### Gestão de Empresas
- Separação de papéis: farmácia, distribuidora, administrador
- CRUD completo de empresas
- Validação de CNPJ

### Catálogo de Produtos
- Produtos com lote e validade obrigatórios
- Categorização e subcategorização
- Controle de estoque

### Pedidos
- Ciclo completo: Pendente → Pago → Faturado → Entregue
- Rastreamento de status
- Histórico de transações

### Pagamentos
- Geração de preferência de pagamento Mercado Pago
- Split de pagamento automático
- Retenção de comissão da plataforma

## 🏗️ Arquitetura

```
backend/
├── cmd/
│   └── api/
│       └── main.go               # Entry point da aplicação
├── internal/
│   ├── config/                   # Configurações (100% coverage)
│   ├── domain/                   # Modelos de domínio
│   ├── http/
│   │   ├── handler/              # Handlers HTTP (refatorado)
│   │   │   ├── handler.go        # Auth, Products, Orders, etc
│   │   │   ├── company_handler.go # CRUD de empresas
│   │   │   └── dto.go            # DTOs e funções utilitárias
│   │   └── middleware/           # Middlewares (95.9%-100% coverage)
│   ├── payments/                 # Integração MercadoPago (100% coverage)
│   ├── repository/
│   │   └── postgres/             # Repositório PostgreSQL
│   ├── server/                   # Configuração do servidor (74.7% coverage)
│   └── usecase/                  # Casos de uso (64.7%-88% coverage)
├── docs/                         # Documentação Swagger
├── Dockerfile
└── README.md
```

## 🧪 Cobertura de Testes

| Pacote | Cobertura |
|--------|-----------|
| `config` | **100%** ✅ |
| `middleware` | **95.9%-100%** ✅ |
| `payments` | **100%** ✅ |
| `usecase` | **64.7%-88%** |
| `server` | **74.7%** |
| `handler` | 6.6%-50% |


## 🔧 Configuração

### Variáveis de Ambiente

```bash
# Banco de Dados
DATABASE_URL=postgres://user:password@localhost:5432/saveinmed?sslmode=disable

# Servidor
BACKEND_PORT=8214

# Autenticação
JWT_SECRET=your-secret-key
JWT_EXPIRES_IN=24h
PASSWORD_PEPPER=your-pepper

# Superadmin Bootstrap
# O backend cria automaticamente um superadmin padrao ao subir.
# As credenciais iniciais sao geradas e registradas no log apenas na primeira criacao.

# CORS
CORS_ORIGINS=*

# Mercado Pago
MERCADOPAGO_BASE_URL=https://api.mercadopago.com
MARKETPLACE_COMMISSION=2.5
```

### Autenticação

A autenticação utiliza **username** (não email) para login:

```json
POST /api/v1/auth/login
{
  "username": "admin",
  "password": "admin123"
}
```

### Pré-requisitos

- Go 1.24 ou superior
- PostgreSQL 14+
- Swag CLI (para regenerar documentação)

## 🏃 Execução Local

```bash
# Configurar variável de ambiente
export DATABASE_URL=postgres://postgres:postgres@localhost:5432/saveinmed?sslmode=disable

# Instalar dependências
go mod download

# Executar API
go run ./cmd/api

# API estará disponível em http://localhost:8080
# Swagger UI em http://localhost:8080/docs/index.html
```

## 🐳 Docker

```bash
# Build da imagem
docker build -t saveinmed-api:latest .

# Executar container
docker run -p 8080:8080 \
  -e DATABASE_URL=postgres://user:password@host:5432/saveinmed \
  saveinmed-api:latest
```

## 📚 Documentação da API

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

```
http://localhost:8080/docs/index.html
```

### Regenerar Swagger

```bash
# Instalar swag
go install github.com/swaggo/swag/cmd/swag@latest

# Gerar documentação
swag init --dir ./cmd/api,./internal/http/handler,./internal/domain \
  --output ./docs \
  --parseDependency \
  --parseInternal
```

## 🧪 Testes

```bash
# Executar todos os testes
go test ./...

# Executar testes com coverage
go test -cover ./...

# Gerar relatório de coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out
```

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

## 📊 Performance

Esta API foi otimizada para alta performance:
- **json-iterator**: ~2-3x mais rápido que encoding/json padrão
- **Compressão gzip**: Reduz tamanho das respostas em ~70%
- **Connection pooling**: Gerenciamento eficiente de conexões com PostgreSQL
- **Prepared statements**: Queries otimizadas e protegidas contra SQL injection

## 🔗 Integração com Outros Componentes

- **Backoffice (NestJS)**: Compartilha o mesmo banco de dados PostgreSQL
- **Marketplace Frontend**: Consome esta API para operações críticas
- **SaveInMed BFF**: Pode fazer proxy para endpoints específicos desta API

## 📝 Licença

MIT