🌊 OpenSea API

Uma API REST completa para gerenciamento de estoque e vendas, construída com Clean Architecture, TypeScript e Fastify.

📋 Índice

Características
Arquitetura
Pré-requisitos
Instalação
Configuração
Executando o Projeto
Testes
Documentação da API
Estrutura do Projeto
Módulos
Scripts Disponíveis
Tecnologias
Licença

✨ Características

🏗️ Clean Architecture - Separação clara de responsabilidades
🔐 Autenticação JWT - Sistema completo com refresh tokens
🏢 Multi-Tenant - Isolamento por tenant com planos, módulos e feature flags
👑 Central de Gerenciamento - Painel administrativo para super admins
📊 Gestão de Estoque - Controle de produtos, variantes, itens e movimentações
💰 Gestão de Vendas - Pedidos, clientes, promoções e reservas
🧪 Testes Abrangentes - 569 testes unitários + 285 testes E2E
📝 Documentação Swagger - OpenAPI 3.0 interativa
🔒 Segurança - Rate limiting, CORS, validação Zod
🐳 Docker Ready - Desenvolvimento com Docker Compose
🎯 TypeScript - Type-safe em todo o código
🚀 Alta Performance - Fastify + Prisma otimizado

🆕 Sprint 2 - Melhorias de Qualidade

Schemas Centralizados ✅

Sistema unificado de validação Zod
5 arquivos de schemas (common, user, product, auth, index)
Eliminação de duplicação de código inline
350+ linhas de schemas reutilizáveis

Paginação Padronizada ✅

21 endpoints de listagem com paginação
Parâmetros padrão: page (default: 1) e limit (default: 20)

Resposta estruturada com metadados:

{
  "data": [...],
  "meta": {
    "total": 100,
    "page": 1,
    "limit": 20,
    "pages": 5
  }
}

Logger Estruturado ✅

Migração de console.log para Pino logger
5 contextos especializados: httpLogger, dbLogger, authLogger, errorLogger, performanceLogger
Logs estruturados em JSON para produção
Pretty-print no desenvolvimento

Senhas Fortes ✅

Validação rigorosa em todos os endpoints de autenticação
Requisitos: 8+ caracteres, maiúscula, minúscula, número, caractere especial
Aplicado em: criação de usuário, mudança de senha, reset de senha

Health Check Avançado ✅

Monitoramento de banco de dados (latência, conectividade)
Métricas de memória (heap, RSS)
Uptime e ambiente
Endpoint: GET /health

🏛️ Arquitetura

O projeto segue os princípios da Clean Architecture:

┌─────────────────────────────────────────────────┐
│            HTTP Layer (Controllers)             │
│         Fastify + Zod Validation                │
└────────────────┬────────────────────────────────┘
                 │
┌────────────────▼────────────────────────────────┐
│         Application Layer (Use Cases)           │
│              Business Logic                     │
└────────────────┬────────────────────────────────┘
                 │
┌────────────────▼────────────────────────────────┐
│           Domain Layer (Entities)               │
│         Value Objects + Domain Logic            │
└────────────────┬────────────────────────────────┘
                 │
┌────────────────▼────────────────────────────────┐
│      Infrastructure Layer (Repositories)        │
│            Prisma + PostgreSQL                  │
└─────────────────────────────────────────────────┘

Padrões Implementados

Repository Pattern - Abstração de acesso a dados
DTO Pattern - Data Transfer Objects para comunicação entre camadas
Factory Pattern - Criação de use cases e entidades
Value Objects - Encapsulamento de lógica de domínio
Dependency Injection - Inversão de dependências

📦 Pré-requisitos

Node.js 20.x ou superior
Docker & Docker Compose (para banco de dados)
npm ou yarn

🚀 Instalação

Clone o repositório

git clone https://github.com/Ganim/OpenSea-API.git
cd OpenSea-API

Instale as dependências

npm install

Configure as variáveis de ambiente

cp .env.example .env

Edite o arquivo .env com suas configurações (veja Configuração).

Inicie o banco de dados (a partir do monorepo root)

cd .. && docker compose up -d

Execute as migrations

npx prisma migrate dev

Inicie o servidor

npm run dev

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

⚙️ Configuração

Variáveis de Ambiente

Crie um arquivo .env na raiz do projeto:

# Ambiente
NODE_ENV=dev

# Servidor
PORT=3333

# Autenticação JWT
JWT_SECRET=sua_chave_secreta_super_segura_aqui

# Banco de Dados PostgreSQL
DATABASE_URL=postgresql://docker:docker@localhost:5432/opensea-db?schema=public

# SMTP (para recuperação de senha)
SMTP_HOST=smtp.ethereal.email
SMTP_PORT=587
SMTP_USER=seu_usuario_smtp
SMTP_PASS=sua_senha_smtp

# Frontend (CORS)
FRONTEND_URL=http://localhost:3000

Configurações Importantes

JWT_SECRET: Use uma chave forte e única para produção
DATABASE_URL: Ajuste as credenciais do PostgreSQL
SMTP: Configure com um serviço real (Gmail, SendGrid, etc.)

🏃 Executando o Projeto

Desenvolvimento

npm run dev

Servidor com hot-reload em http://localhost:3333

Produção

npm run build
npm start

Docker

# Iniciar banco de dados (do monorepo root)
cd .. && docker compose up -d

# Ver logs (do monorepo root)
cd .. && docker compose logs -f

# Parar serviços (do monorepo root)
cd .. && docker compose down

🧪 Testes

Testes Unitários

npm run test

569 testes cobrindo todas as camadas da aplicação.

Testes E2E

npm run test:e2e

285 testes testando os endpoints HTTP completos.

Watch Mode

npm run test:watch        # Unitários
npm run test:e2e:watch    # E2E

Cobertura

npm run test:coverage

📚 Documentação da API

Swagger UI

Acesse a documentação interativa em:

http://localhost:3333/docs

Autenticação

A maioria dos endpoints requer autenticação JWT:

# 1. Registrar usuário
POST /v1/auth/register/password
{
  "email": "user@example.com",
  "password": "SenhaForte@123"
}

# 2. Fazer login
POST /v1/auth/login/password
{
  "email": "user@example.com",
  "password": "SenhaForte@123"
}

# 3. Usar o token retornado
Authorization: Bearer <seu_token_jwt>

🎯 Paginação (Sprint 2)

Todos os endpoints de listagem suportam paginação:

# Listar produtos com paginação
GET /v1/products?page=1&limit=20

# Resposta:
{
  "data": [...],  # Array de produtos
  "meta": {
    "total": 150,    # Total de registros
    "page": 1,       # Página atual
    "limit": 20,     # Itens por página
    "pages": 8       # Total de páginas
  }
}

Parâmetros:

page: Número da página (padrão: 1)
limit: Itens por página (padrão: 20, máximo: 100)

Endpoints com paginação:

GET /v1/users - Listar usuários
GET /v1/products - Listar produtos
GET /v1/variants - Listar variantes
GET /v1/items - Listar itens de estoque
GET /v1/sessions/me - Minhas sessões
E mais 16 endpoints!

🔐 Senhas Fortes (Sprint 2)

Todos os endpoints de autenticação agora exigem senhas fortes:

Requisitos:

Mínimo 8 caracteres
Pelo menos 1 letra maiúscula
Pelo menos 1 letra minúscula
Pelo menos 1 número
Pelo menos 1 caractere especial

# ✅ Válido
"SenhaForte@123"
"MyP@ssw0rd!"

# ❌ Inválido
"senha123"     # Sem maiúscula e caractere especial
"SENHA@123"    # Sem minúscula
"SenhaForte"   # Sem número e caractere especial

📊 Health Check (Sprint 2)

Monitore a saúde da aplicação:

GET /health

# Resposta:
{
  "status": "ok",
  "timestamp": "2025-01-10T12:00:00.000Z",
  "uptime": 3600,
  "environment": "production",
  "database": {
    "status": "connected",
    "latency": 15
  },
  "memory": {
    "heapUsed": 45.2,
    "heapTotal": 128.5,
    "rss": 156.8
  }
}

📁 Estrutura do Projeto

OpenSea-API/
├── prisma/
│   ├── schema.prisma              # Schema do banco (inclui multi-tenant)
│   ├── seed.ts                    # Seed (superadmin, planos, tenant demo)
│   ├── migrations/                # Histórico de migrations
│   └── vitest-environment-prisma/ # Ambiente de testes
│
├── src/
│   ├── @env/                      # Validação de variáveis de ambiente
│   ├── @errors/                   # Classes de erro customizadas
│   ├── @types/                    # Definições de tipos TypeScript
│   │
│   ├── config/                    # Configurações da aplicação
│   │   ├── auth.ts                # Constantes de autenticação
│   │   └── swagger-tags.ts        # Tags do Swagger
│   │
│   ├── entities/                  # 🎯 DOMAIN LAYER
│   │   ├── core/                  # Entidades de auth + tenant + plan
│   │   ├── sales/                 # Entidades de vendas
│   │   ├── stock/                 # Entidades de estoque
│   │   └── domain/                # Base classes (Entity, ValueObject)
│   │
│   ├── use-cases/                 # 🎯 APPLICATION LAYER
│   │   ├── core/                  # Casos de uso de auth + tenants
│   │   ├── admin/                 # Casos de uso de admin (plans, dashboard)
│   │   ├── sales/                 # Casos de uso de vendas
│   │   └── stock/                 # Casos de uso de estoque
│   │
│   ├── repositories/              # 🎯 INFRASTRUCTURE LAYER
│   │   ├── core/
│   │   │   ├── prisma/            # Implementação Prisma
│   │   │   └── in-memory/         # Implementação para testes
│   │   ├── sales/
│   │   └── stock/
│   │
│   ├── http/                      # 🎯 HTTP LAYER
│   │   ├── controllers/
│   │   │   ├── admin/             # Controllers admin (super admin)
│   │   │   ├── core/              # Controllers auth, me, sessions, tenants
│   │   │   └── ...                # Demais módulos
│   │   ├── middlewares/           # Middlewares (auth, tenant, superadmin)
│   │   └── routes.ts              # Registro de rotas
│   │
│   ├── mappers/                   # Conversores (Entity ↔ DTO ↔ Prisma)
│   ├── services/                  # Serviços (email, tenant-context)
│   ├── utils/                     # Utilitários e helpers
│   ├── lib/                       # Bibliotecas configuradas
│   │
│   ├── app.ts                     # Configuração do Fastify
│   └── server.ts                  # Entry point da aplicação
│
├── docker-compose.yml             # Stub — see ../docker-compose.yml at monorepo root
├── package.json
├── tsconfig.json
└── vitest.config.ts

🧩 Módulos

Core (Autenticação & Multi-Tenant)

✅ Registro de usuários
✅ Login com senha
✅ JWT + Refresh Tokens (com isSuperAdmin e tenantId)
✅ Recuperação de senha
✅ Gestão de sessões
✅ Perfis de usuário
✅ Controle de acesso (ADMIN, MANAGER, USER)
✅ Multi-Tenant - Tenants, planos, módulos, feature flags
✅ Seleção de Tenant - JWT tenant-scoped após seleção
✅ Super Admin - Usuários com isSuperAdmin acessam Central

Admin (Super Admin)

✅ Dashboard - Estatísticas do sistema
✅ Gestão de Tenants - Listar, detalhes, status, plano, feature flags, usuários
✅ Gestão de Planos - CRUD completo + módulos do sistema
✅ Seed - Super admin, 4 planos padrão, tenant demo

Stock (Estoque)

✅ Products - Catálogo de produtos
✅ Variants - Variações de produtos (tamanho, cor, etc)
✅ Categories - Categorias hierárquicas
✅ Manufacturers - Fabricantes
✅ Suppliers - Fornecedores
✅ Locations - Locais de armazenamento
✅ Tags - Tags para organização
✅ Templates - Templates de atributos
✅ Items - Itens individuais em estoque
✅ Item Movements - Movimentações de estoque
✅ Purchase Orders - Ordens de compra

Sales (Vendas)

✅ Customers - Gestão de clientes
✅ Sales Orders - Pedidos de venda
✅ Comments - Comentários em entidades
✅ Variant Promotions - Promoções de produtos
✅ Item Reservations - Reservas de estoque
✅ Notification Preferences - Preferências de notificação

📜 Scripts Disponíveis

# Desenvolvimento
npm run dev              # Inicia servidor em modo watch

# Build
npm run build            # Compila TypeScript para JavaScript
npm start                # Inicia servidor em produção

# Testes
npm run test             # Testes unitários
npm run test:e2e         # Testes end-to-end
npm run test:watch       # Testes unitários em watch mode
npm run test:e2e:watch   # Testes E2E em watch mode
npm run test:coverage    # Relatório de cobertura

# Linting
npm run lint             # Verifica problemas no código
npm run lint:fix         # Corrige problemas automaticamente

# Database (Prisma)
npx prisma studio        # Interface visual do banco
npx prisma migrate dev   # Cria e aplica migrations
npx prisma generate      # Gera Prisma Client

🛠️ Tecnologias

Backend

Fastify - Framework web de alta performance
TypeScript - Superset JavaScript com tipagem estática
Prisma - ORM moderno para TypeScript
PostgreSQL - Banco de dados relacional
Zod - Validação de schemas TypeScript-first

Autenticação & Segurança

@fastify/jwt - JSON Web Tokens
@fastify/cors - Cross-Origin Resource Sharing
@fastify/rate-limit - Rate limiting
@fastify/cookie - Cookie parsing
bcryptjs - Hashing de senhas

Documentação

@fastify/swagger - Geração OpenAPI
@fastify/swagger-ui - Interface Swagger
swagger-themes - Temas customizados

Testes

Vitest - Framework de testes rápido
Supertest - Testes HTTP
@faker-js/faker - Geração de dados fake

Desenvolvimento

tsx - Executar TypeScript diretamente
tsup - Bundler TypeScript
ESLint - Linter
Prettier - Formatador de código

🤝 Contribuindo

Contribuições são bem-vindas! Para contribuir:

Fork o projeto
Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
Commit suas mudanças (git commit -m 'Add some AmazingFeature')
Push para a branch (git push origin feature/AmazingFeature)
Abra um Pull Request

Padrões de Código

✅ Siga os princípios da Clean Architecture
✅ Escreva testes para novas features
✅ Use TypeScript estrito
✅ Valide inputs com Zod
✅ Documente endpoints no Swagger

📄 Licença

Este projeto está sob a licença ISC.

👨‍💻 Autor

Guilherme Ganim

GitHub: @Ganim

🙏 Agradecimentos

Desenvolvido com base em princípios modernos de arquitetura de software e boas práticas de desenvolvimento.

📞 Suporte

Para dúvidas ou problemas:

Abra uma issue
Consulte a documentação Swagger
Verifique os testes para exemplos de uso

⭐ Se este projeto foi útil, considere dar uma estrela!

Name		Name	Last commit message	Last commit date
Latest commit History 1,422 Commits
.github/workflows		.github/workflows
assets/care		assets/care
docs		docs
prisma		prisma
scripts		scripts
src		src
test/e2e		test/e2e
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.env.production.example		.env.production.example
.gitignore		.gitignore
.mcp.json		.mcp.json
.npmrc		.npmrc
.versionrc.json		.versionrc.json
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
Dockerfile.worker		Dockerfile.worker
README.md		README.md
biome.json		biome.json
commitlint.config.js		commitlint.config.js
docker-compose.prod.yml		docker-compose.prod.yml
docker-compose.yml		docker-compose.yml
fly.staging.toml		fly.staging.toml
fly.toml		fly.toml
package-lock.json		package-lock.json
package.json		package.json
prisma.config.ts		prisma.config.ts
run-calendar-e2e.sh		run-calendar-e2e.sh
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vite.config.mjs		vite.config.mjs
vitest.e2e.config.ts		vitest.e2e.config.ts

Folders and files

Latest commit

History

Repository files navigation

🌊 OpenSea API

📋 Índice

✨ Características

🆕 Sprint 2 - Melhorias de Qualidade

🏛️ Arquitetura

Padrões Implementados

📦 Pré-requisitos

🚀 Instalação

⚙️ Configuração

Variáveis de Ambiente

Configurações Importantes

🏃 Executando o Projeto

Desenvolvimento

Produção

Docker

🧪 Testes

Testes Unitários

Testes E2E

Watch Mode

Cobertura

📚 Documentação da API

Swagger UI

Autenticação

🎯 Paginação (Sprint 2)

🔐 Senhas Fortes (Sprint 2)

📊 Health Check (Sprint 2)

📁 Estrutura do Projeto

🧩 Módulos

Core (Autenticação & Multi-Tenant)

Admin (Super Admin)

Stock (Estoque)

Sales (Vendas)

📜 Scripts Disponíveis

🛠️ Tecnologias

Backend

Autenticação & Segurança

Documentação

Testes

Desenvolvimento

🤝 Contribuindo

Padrões de Código

📄 Licença

👨‍💻 Autor

🙏 Agradecimentos

📞 Suporte

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages