Core - Projeto GraphQL Principal

Projeto independente que faz parte do workspace graphql-microservice. Expõe a API GraphQL e gerencia o MongoDB para o sistema de geração de relatórios.

📁 Contexto: Este projeto trabalha em conjunto com o projeto report-generator via Google Cloud Pub/Sub para formar um sistema completo de microserviços.

🎯 Responsabilidades

• API GraphQL: Endpoint principal para clientes externos
• Pub/Sub Publisher: Publica eventos de solicitação de relatórios para o report-generator
• Pub/Sub Subscriber: Consome eventos de conclusão de relatórios do report-generator
• Banco de Dados: Gerencia dados no MongoDB via Mongoose
• Orquestração: Coordena o fluxo entre os dois projetos do workspace

🚀 Como Executar

Desenvolvimento

# A partir do workspace root
cd core
pnpm install
cp .env.example .env
# Configurar variáveis no .env

# Executar em desenvolvimento
pnpm dev

# Para testar integração completa, execute também:
# cd ../report-generator && pnpm dev

Produção

pnpm build
pnpm start

📝 Variáveis de Ambiente

Crie um arquivo .env com base no .env.example:

# Servidor
PORT=4000
NODE_ENV=development

# MongoDB
MONGODB_URL=mongodb://localhost:27017/graphql-microservice

# Google Cloud Pub/Sub
GOOGLE_CLOUD_PROJECT_ID=seu-project-id
GOOGLE_APPLICATION_CREDENTIALS=./gcp-service-account.json

# Tópicos Pub/Sub
TOPIC_REPORT_REQUESTS=report-requests
TOPIC_REPORT_COMPLETED=report-completed
TOPIC_PROCESSING_STATUS=processing-status

🗂️ Estrutura Prevista

core/src/
├── graphql/
│   ├── schema/              # Schemas GraphQL
│   ├── resolvers/           # Resolvers GraphQL
│   └── types/               # Definições de tipos
├── pubsub/
│   ├── publishers/          # Publishers de eventos
│   └── subscribers/         # Subscribers de eventos
├── database/
│   ├── models/              # Models Mongoose
│   └── connection.ts        # Configuração MongoDB
├── services/                # Lógica de negócio
├── utils/                   # Utilitários
└── index.ts                 # Entry point

🔗 API GraphQL

Queries

# Listar relatórios
query {
  reports {
    id
    type
    status
    createdAt
    data
  }
}

# Buscar relatório específico
query {
  report(id: "report-id") {
    id
    type
    status
    data
    error
  }
}

Mutations

# Solicitar geração de relatório
mutation {
  requestReport(input: {
    type: "movie-analysis"
    movieId: "tt1234567"
    parameters: "{\"includeReviews\": true}"
  }) {
    id
    status
    message
  }
}

Subscriptions

# Acompanhar status de relatórios
subscription {
  reportStatusUpdated {
    id
    status
    progress
    message
  }
}

📊 Eventos Pub/Sub

Eventos Publicados

• report-requests: Solicitações de geração de relatórios
• processing-status-requests: Solicitações de status de processamento

Eventos Consumidos

• report-completed: Relatórios concluídos pelo report-generator
• processing-status: Status de processamento em tempo real

🗄️ Modelos de Dados

Report

interface Report {
  id: string;
  type: 'movie-analysis' | 'trend-report' | 'user-stats';
  status: 'pending' | 'processing' | 'completed' | 'failed';
  movieId?: string;
  userId?: string;
  parameters: Record<string, any>;
  data?: any;
  error?: string;
  requestedBy: string;
  createdAt: Date;
  updatedAt: Date;
}

MovieData

interface MovieData {
  imdbId: string;
  title: string;
  year: string;
  rating: number;
  genre: string[];
  director: string;
  plot: string;
  lastUpdated: Date;
}

🧪 Comandos Disponíveis

# Desenvolvimento
pnpm dev                    # Executar com nodemon
pnpm dev:debug              # Executar com debug
pnpm dev:watch              # Executar com watch mode

# Build e Produção
pnpm build                  # Compilar TypeScript
pnpm start                  # Executar versão compilada
pnpm start:prod             # Executar em modo produção

# Qualidade de Código
pnpm lint                   # Executar ESLint
pnpm lint:fix               # Corrigir erros do ESLint
pnpm format                 # Formatar com Prettier
pnpm type-check             # Verificar tipos TypeScript

# Testes com AVA
pnpm test                   # Executar todos os testes
pnpm test:watch             # Executar em modo watch
pnpm test:coverage          # Executar com coverage (c8)
pnpm test:verbose           # Executar em modo verbose
pnpm test:serial            # Executar testes em série

# Banco de Dados
pnpm db:migrate             # Executar migrações
pnpm db:seed                # Popular banco com dados teste
pnpm db:reset               # Resetar banco de dados

🐛 Debug e Logs

# Ver logs em tempo real
pnpm logs

# Debug com breakpoints
pnpm dev:debug

# Logs estruturados em produção
pnpm start:prod | pnpm dlx pino-pretty

🔧 Configuração de Desenvolvimento

MongoDB Local

# Docker
docker run -d -p 27017:27017 --name mongodb mongo:6

# Verificar conexão
pnpm db:ping

Google Cloud Pub/Sub (Emulador)

# Instalar e iniciar emulador
gcloud components install pubsub-emulator
gcloud beta emulators pubsub start --project=local-project

# Em outro terminal
export PUBSUB_EMULATOR_HOST=localhost:8085
pnpm dev

📚 Dependências Principais

• @apollo/server: Servidor GraphQL
• graphql: GraphQL core
• mongoose: ODM para MongoDB
• @google-cloud/pubsub: Cliente Google Cloud Pub/Sub
• express: Framework web
• dotenv: Gerenciamento de variáveis de ambiente

Dependências de Teste

• ava: Test runner moderno e rápido
• @ava/typescript: Suporte TypeScript para AVA
• c8: Coverage de código com V8

🚨 Troubleshooting

Erro de Conexão MongoDB

# Verificar se MongoDB está rodando
mongosh --eval "db.adminCommand('ismaster')"

# Verificar logs
docker logs mongodb

Erro Pub/Sub

# Verificar autenticação
gcloud auth application-default login

# Verificar tópicos
gcloud pubsub topics list

Porta em Uso

# Verificar processos na porta 4000
lsof -i :4000

# Mudar porta
export PORT=4001
pnpm dev

Problemas com Testes AVA

# Limpar cache e reinstalar
rm -rf node_modules dist
pnpm install

# Executar testes com debug
pnpm test:verbose

# Verificar configuração TypeScript
pnpm type-check

🧪 Estrutura de Testes

tests/
├── unit/               # Testes unitários
│   └── *.test.ts
├── integration/        # Testes de integração
│   └── *.test.ts
└── helpers/           # Utilitários de teste
    └── test-utils.ts

Convenções de Teste

• Arquivos de teste terminam com .test.ts
• Testes unitários para funções isoladas
• Testes de integração para fluxos completos
• Uso de mocks para dependências externas