🚀 DigiVerse API - Backend

API REST completa para o universo Digimon construída com Fastify, Prisma e TypeScript

📖 Índice

Sobre
Características
Stack Tecnológica
Começando
Estrutura do Projeto
API Endpoints
Autenticação
Desenvolvimento
Testes
Deploy
Documentação da API

🎯 Sobre

Esta API REST fornece acesso completo ao universo Digimon, incluindo:

325+ Digimons com informações detalhadas
122+ Relacionamentos de evolução
8 Níveis de evolução (Fresh, In-Training, Rookie, Champion, Ultimate, Mega, Armor, Hybrid)
4 Tipos principais (Vaccine, Virus, Data, Free)
Múltiplos atributos e tipos de evolução

✨ Características

Performance

⚡ Cache Redis em todos os endpoints
🔄 Otimizações de query com Prisma
📦 Compressão automática de respostas
🎯 Paginação e filtros avançados

Segurança

🔐 Autenticação JWT com refresh tokens
🛡️ Rate limiting (100 req/min por IP)
✅ Validação de dados com Zod
🔒 Helmet.js para headers de segurança
🚫 CORS configurável

Observabilidade

📊 Logs estruturados com Pino
🏥 Health checks
📈 Métricas de performance
🐛 Error tracking centralizado

Qualidade

🧪 Testes unitários e de integração (Jest)
📝 Documentação Swagger/OpenAPI 3.0
🎨 ESLint + Prettier
🔄 CI/CD pronto (GitHub Actions)

🛠️ Stack Tecnológica

Runtime: Node.js 18+
Framework: Fastify 5.6.1
Language: TypeScript 5.3
ORM: Prisma 6.17.1
Database: PostgreSQL 15
Cache: Redis 7
Validation: Zod 4.1.12
Testing: Jest 29.7
Logging: Pino 10.0
Documentation: Swagger/OpenAPI 3.0

🚀 Começando

Pré-requisitos

Node.js >= 18.0.0
pnpm >= 8.0.0
PostgreSQL 15 (ou Docker)
Redis 7 (ou Docker)

Instalação

Instale as dependências:

pnpm install

Configure as variáveis de ambiente:

cp .env.example .env
# Edite .env com suas configurações

Inicie os serviços via Docker (recomendado):

pnpm docker:up

Ou configure PostgreSQL e Redis manualmente.

Execute as migrações:

pnpm prisma:migrate

Popule o banco de dados:

pnpm db:seed

Inicie o servidor:

# Desenvolvimento
pnpm dev

# Produção
pnpm build
pnpm start

A API estará disponível em http://localhost:3000

📁 Estrutura do Projeto

packages/backend/
├── src/
│   ├── controllers/      # Lógica de negócio
│   ├── models/           # Modelos Prisma
│   ├── Routes/           # Definição de rotas
│   ├── services/         # Serviços auxiliares
│   ├── plugins/          # Plugins Fastify
│   ├── errors/           # Error handling
│   ├── validations/      # Schemas Zod
│   ├── database/         # Configuração do Prisma
│   └── server.ts         # Entry point
├── prisma/
│   ├── schema.prisma     # Database schema
│   ├── migrations/       # Database migrations
│   └── seed.ts           # Seed data
├── tests/
│   ├── unit/             # Testes unitários
│   └── integration/      # Testes de integração
├── images/               # Imagens dos Digimons
├── Dockerfile            # Docker image
├── docker-compose.yml    # Docker services
├── .eslintrc.json        # ESLint config
├── .prettierrc.json      # Prettier config
├── tsconfig.json         # TypeScript config
└── package.json          # Dependencies

🔌 API Endpoints

Autenticação

POST   /token                    # Gerar JWT token
POST   /auth/login               # Login com refresh token
POST   /auth/refresh             # Renovar access token
POST   /auth/logout              # Logout (revoga refresh token)
POST   /auth/logout-all          # Logout de todos os dispositivos

Digimons

GET    /digimon                  # Listar todos os Digimons
GET    /digimon/:id              # Buscar Digimon por ID
GET    /digimon/search/:name     # Buscar por nome
GET    /digimon/filter           # Busca avançada com filtros
GET    /digimon/:id/evolution-tree  # Árvore evolutiva completa
POST   /digimon                  # Criar novo Digimon
PUT    /digimon                  # Atualizar Digimon
DELETE /digimon                  # Deletar Digimon

Metadados

GET    /types                    # Listar tipos (Vaccine, Virus, etc)
GET    /types/:id                # Buscar tipo por ID
GET    /attributes               # Listar atributos
GET    /attributes/:id           # Buscar atributo por ID
GET    /levels                   # Listar níveis de evolução
GET    /levels/:id               # Buscar nível por ID
GET    /levels/:id/digimons      # Digimons de um nível específico
GET    /evolution-types          # Tipos de evolução (Normal, DNA, etc)
GET    /evolution-types/:id      # Buscar tipo de evolução por ID

Documentação

GET    /docs                     # Swagger UI
GET    /docs/json                # OpenAPI JSON spec

🔐 Autenticação

A API usa um sistema de dual-token JWT:

1. Obter Token

# Método simples (desenvolvimento)
curl http://localhost:3000/token

# Método com refresh token (recomendado)
curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"userId": "user123"}'

Resposta:

{
  "accessToken": "eyJhbGciOiJIUz...",
  "refreshToken": "eyJhbGciOiJIUz...",
  "expiresIn": 900
}

2. Usar Token

Incluir o accessToken no header Authorization:

curl http://localhost:3000/digimon \
  -H "Authorization: Bearer eyJhbGciOiJIUz..."

3. Renovar Token

Quando o accessToken expirar (15 minutos):

curl -X POST http://localhost:3000/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "eyJhbGciOiJIUz..."}'

💻 Desenvolvimento

Scripts Disponíveis

# Desenvolvimento
pnpm dev                 # Inicia com hot-reload
pnpm serve               # Inicia sem hot-reload

# Build
pnpm build               # Compila TypeScript

# Produção
pnpm start               # Inicia servidor de produção

# Testes
pnpm test                # Executa todos os testes
pnpm test:watch          # Testes em watch mode
pnpm test:coverage       # Cobertura de testes

# Qualidade de Código
pnpm lint                # Verifica com ESLint
pnpm lint:fix            # Corrige erros do ESLint
pnpm format              # Formata com Prettier
pnpm format:check        # Verifica formatação

# Prisma
pnpm prisma:generate     # Gera Prisma Client
pnpm prisma:studio       # Abre Prisma Studio
pnpm prisma:migrate      # Cria e aplica migrations
pnpm db:seed             # Popula banco de dados

# Docker
pnpm docker:build        # Build da imagem Docker
pnpm docker:run          # Executa container

Variáveis de Ambiente

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/digimon_db
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=password
DB_NAME=digimon_db

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# Application
NODE_ENV=development
PORT=3000
URL_APP=http://localhost

# Security
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
REFRESH_TOKEN_SECRET=your-refresh-token-secret

# Logging
LOG_LEVEL=info  # debug, info, warn, error

🧪 Testes

Executar Testes

# Todos os testes
pnpm test

# Apenas unitários
pnpm test tests/unit

# Apenas integração
pnpm test tests/integration

# Com cobertura
pnpm test:coverage

# Watch mode
pnpm test:watch

Cobertura Atual

Linhas: > 80%
Funções: > 75%
Branches: > 70%

Estrutura de Testes

tests/
├── unit/
│   ├── models/
│   │   └── DigimonPrisma.test.ts
│   └── services/
│       ├── CacheService.test.ts
│       └── RefreshTokenService.test.ts
└── integration/
    ├── api.test.ts
    ├── auth.test.ts
    └── advanced-endpoints.test.ts

🐳 Deploy

Docker

Build da Imagem

docker build -t digimon-backend .

Executar Container

docker run -p 3000:3000 \
  --env-file .env \
  digimon-backend

Docker Compose

# Apenas infra (PostgreSQL + Redis)
docker-compose up -d postgres redis

# Infra + Backend
docker-compose up -d

Deploy em Produção

Variáveis de Ambiente

Certifique-se de configurar:

NODE_ENV=production
DATABASE_URL apontando para seu banco de produção
JWT_SECRET e REFRESH_TOKEN_SECRET seguros
REDIS_HOST e REDIS_PORT do Redis de produção

Migrations

pnpm prisma:deploy

Health Check

O backend expõe um endpoint de health check:

curl http://localhost:3000/health

Resposta esperada:

{
  "status": "ok",
  "timestamp": "2025-10-15T14:30:00.000Z",
  "uptime": 123.45
}

📚 Documentação da API

Swagger UI

Acesse http://localhost:3000/docs para a documentação interativa completa.

OpenAPI Spec

A especificação OpenAPI 3.0 está disponível em:

JSON: http://localhost:3000/docs/json
YAML: http://localhost:3000/docs/yaml

Exemplos de Uso

Listar Digimons

curl http://localhost:3000/digimon \
  -H "Authorization: Bearer TOKEN"

Buscar com Filtros

curl "http://localhost:3000/digimon/filter?levelId=3&typeId=1&page=1&limit=10" \
  -H "Authorization: Bearer TOKEN"

Árvore Evolutiva

curl http://localhost:3000/digimon/2/evolution-tree \
  -H "Authorization: Bearer TOKEN"

🔧 Troubleshooting

Erros Comuns

Erro: "Cannot connect to database"

Verifique se o PostgreSQL está rodando
Confirme as credenciais no .env
Execute docker-compose up -d postgres

Erro: "Redis connection failed"

Verifique se o Redis está rodando
Execute docker-compose up -d redis

Erro: "Prisma Client not generated"

Execute pnpm prisma:generate

Erro: "Port 3000 already in use"

Altere a variável PORT no .env
Ou mate o processo: lsof -ti:3000 | xargs kill

📞 Suporte

Issues: GitHub Issues
Email: caiofernandes.dev@gmail.com

📄 Licença

⬆ Voltar ao topo

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

🚀 DigiVerse API - Backend

📖 Índice

🎯 Sobre

✨ Características

Performance

Segurança

Observabilidade

Qualidade

🛠️ Stack Tecnológica

🚀 Começando

Pré-requisitos

Instalação

📁 Estrutura do Projeto

🔌 API Endpoints

Autenticação

Digimons

Metadados

Documentação

🔐 Autenticação

1. Obter Token

2. Usar Token

3. Renovar Token

💻 Desenvolvimento

Scripts Disponíveis

Variáveis de Ambiente

🧪 Testes

Executar Testes

Cobertura Atual

Estrutura de Testes

🐳 Deploy

Docker

Build da Imagem

Executar Container

Docker Compose

Deploy em Produção

Variáveis de Ambiente

Migrations

Health Check

📚 Documentação da API

Swagger UI

OpenAPI Spec

Exemplos de Uso

Listar Digimons

Buscar com Filtros

Árvore Evolutiva

🔧 Troubleshooting

Erros Comuns

📞 Suporte

📄 Licença