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

# 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:

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

# 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

# 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

# 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

# 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

📊 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