Ramen Go API

API RESTful para a aplicação "Ramen Go", uma plataforma onde usuários podem criar contas, autenticar-se, montar e pedir seu próprio ramen. Esta API gerencia usuários, ingredientes (caldos, proteínas) e o processamento de pedidos.

Contexto da Aplicação

Para ajudar a imaginar como esses dados vão estar sendo utilizados pelo cliente web e/ou mobile, abaixo está o link para o layout da aplicação que consumiria esta API.

Layout no Figma

Tecnologias Utilizadas

• NestJS — Framework Node.js para construção de APIs escaláveis e modulares.
• TypeScript — Superset do JavaScript com tipagem estática, melhorando manutenção e DX.
• Prisma — ORM com geração de client e suporte a migrations para PostgreSQL.
• PostgreSQL — Banco de dados relacional usado em desenvolvimento e produção.
• Zod — Validação de schemas e parsing seguro de variáveis de ambiente.
• Swagger / OpenAPI — Documentação interativa da API gerada via @nestjs/swagger.
• JWT & Bcrypt — Autenticação segura via JSON Web Tokens e hash de senhas.
• Nodemailer & Handlebars — Envio de e-mails transacionais (como recuperação de senha) utilizando templates HTML dinâmicos.
• Armazenamento: Cloudflare R2 / S3 — Integração de arquivos usando @aws-sdk/client-s3.
• Testes: Vitest + Supertest — Testes unitários e E2E com mocks, banco de dados isolados em memória e fake providers.
• Docker & Docker Compose — Facilita rodar serviços dependentes (PostgreSQL) localmente com bancos separados para dev e testes.
• CI/CD: GitHub Actions — Pipeline de integração contínua configurada para rodar a suíte de testes isolada e realizar o deploy automático no Render.

Como Começar

Siga os passos abaixo para configurar e executar o projeto localmente.

1. Clone o repositório

   git clone https://github.com/Robson16/ramen-go-api.git
   cd ramen-go-api

2. Instale as dependências

   npm install

3. Suba o Banco de Dados (Docker)

   docker-compose up -d

4. Configure as variáveis de ambiente Crie um arquivo .env na raiz do projeto com base no .env.example:

   # Application Front-End
   APP_URL="http://localhost:3000"
   
   # Application Back-End
   APP_PORT="3333"
   
   DATABASE_URL="postgresql://postgres:docker@localhost:5432/ramengo?schema=public"
   JWT_SECRET="sua-chave-secreta-jwt"
   
   # Cloudflare R2 / S3
   CLOUDFLARE_ACCOUNT_ID=your-cloudflare-account-id
   AWS_BUCKET_NAME=your-r2-bucket-name
   AWS_ACCESS_KEY_ID=your-r2-access-key-id
   AWS_SECRET_ACCESS_KEY=your-r2-secret-access-key
   
   # SMTP / E-mail
   SMTP_HOST="sandbox.smtp.mailtrap.io"
   SMTP_PORT=2525
   SMTP_USER="seu_usuario_aqui"
   SMTP_PASS="sua_senha_aqui"
   MAIL_FROM="Equipe Ramen Go <noreply@ramengo.com>"

   • APP_URL: URL do frontend, usada nos links de redefinição de senha enviados por e-mail.
   • APP_PORT: porta em que a API backend será iniciada.
   • SMTP_*: configurações do provedor de e-mail usado para envio real das mensagens.

5. Execute as Migrations Para criar as tabelas no banco de dados:

   npx prisma migrate dev

6. Inicie a aplicação

   npm run start:dev

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

Documentação da API

A API possui duas interfaces interativas geradas a partir da especificação OpenAPI. O Swagger UI permite visualizar todos os endpoints, os formatos de envio e resposta e testar as requisições.

• Swagger: https://ramen-go-api-xyjm.onrender.com/api

Documentação com Scalar

O Scalar oferece uma interface alternativa e moderna para explorar a documentação OpenAPI da API. Ele utiliza a mesma especificação gerada pelo NestJS e está disponível em:

• Scalar: https://ramen-go-api-xyjm.onrender.com/docs

Use o botão de autorização da interface para informar um token no formato Bearer <seu-jwt-token> e testar as rotas protegidas.

Testando rotas protegidas:

1. Crie uma conta na rota POST /accounts.
2. Faça login na rota POST /sessions para receber o seu access_token.
3. Copie o token, clique no botão verde "Authorize" (no topo do Swagger) e cole o token.
4. Agora você pode testar rotas protegidas, como gerenciar o perfil, criar pedidos e consultar o histórico de pedidos.

Rotas administrativas:

As rotas administrativas exigem um JWT válido de um usuário com a role ADMIN. Usuários comuns recebem 403 Forbidden. A role padrão de novas contas é USER.

Testes e CI/CD

O projeto possui uma suíte robusta de testes para garantir a integridade da aplicação:

• Testes Unitários: Testam os Casos de Uso (Domain) utilizando Repositórios em Memória (In-Memory), sem tocar no banco de dados ou em APIs externas.

  npm run test

• Testes E2E (End-to-End): Testam a aplicação de ponta a ponta (Controllers, Casos de Uso, Prisma e Banco de Dados real). Para proteger os dados de desenvolvimento, o Docker Compose inicializa um banco isolado chamado ramen-go-test, que é recriado e limpo automaticamente a cada execução.

  npm run test:e2e

Integração Contínua (CI/CD):

O repositório está integrado com o GitHub Actions. A cada push na branch main, a pipeline:

1. Sobe um banco PostgreSQL temporário isolado.
2. Executa toda a suíte de testes unitários e E2E.
3. Se todos os testes passarem, dispara o gatilho (Deploy Hook) para a nuvem (Render).

Estrutura do Código

O projeto segue os princípios de Arquitetura Limpa (Clean Architecture) e Domain-Driven Design (DDD), separando as responsabilidades:

.
├── .github/workflows/      # Pipeline de CI/CD (GitHub Actions)
├── prisma/                 # Schema do Prisma, Migrations e Seeds
├── scripts/                # Scripts utilitários (Limpeza do R2, Init DB de Testes)
├── src/
│   ├── core/               # Lógica compartilhada, base de Entidades e erros globais
│   ├── domain/             # Núcleo da aplicação (Casos de Uso e Regras de Negócio)
│   │   ├── account/        # Domínio de Usuários e Autenticação
│   │   └── restaurant/     # Domínio de Catálogo e Pedidos (Broths, Proteins, Orders)
│   └── infra/              # Camada externa e framework (NestJS)
│       ├── auth/           # JwtStrategy, Guards e Decorators
│       ├── cryptography/   # Implementações de Hash (Bcrypt) e Encriptação (JWT)
│       ├── database/       # Integração com Prisma, Repositórios e Mappers
│       ├── env/            # Validação Zod para variáveis de ambiente
│       ├── http/           # Controladores (REST) e Presenters (DTOs)
│       ├── mailing/        # Provedores de envio de e-mails
│       └── storage/        # Integração R2 / S3 para imagens
└── test/                   # Testes automatizados (E2E, Unitários, Setup e Factories)

Funcionalidades e Endpoints

👤 Contas e Autenticação (Accounts)

• POST /accounts: Cria uma nova conta de usuário.
• POST /sessions: Realiza login e retorna um JWT.
• GET /profile: Retorna o perfil do usuário logado (protegido).
• PUT /profile: Edita os dados do próprio perfil (protegido).
• DELETE /profile: Exclui a própria conta permanentemente (protegido).
• POST /password/forgot: Solicita a recuperação de senha e envia um e-mail com o token.
• PATCH /password/reset: Redefine a senha do usuário utilizando o token de recuperação.

Administração de Usuários (Accounts - Admin)

• GET /admin/users: Lista todos os usuários (restrito a administradores).

🍜 Catálogo (Catalog - Public)

Caldos (Broths)

• GET /broths: Lista todos os caldos disponíveis.
• GET /broths/:brothId: Recupera os detalhes de um caldo específico (com URLs de imagens em alta resolução).

Proteínas (Proteins)

• GET /proteins: Lista todas as proteínas disponíveis.
• GET /proteins/:proteinId: Recupera os detalhes de uma proteína específica (com URLs de imagens em alta resolução).

---

🛠️ Administração do Catálogo (Catalog - Admin)

Caldos (Broths)

• POST /admin/broths: Cria um novo caldo (restrito a administradores).
• PUT /admin/broths/:brothId: Edita um caldo (restrito a administradores).
• DELETE /admin/broths/:brothId: Exclui um caldo (restrito a administradores).

Proteínas (Proteins)

• POST /admin/proteins: Cria uma nova proteína (restrito a administradores).
• PUT /admin/proteins/:proteinId: Edita uma proteína (restrito a administradores).
• DELETE /admin/proteins/:proteinId: Exclui uma proteína (restrito a administradores).

Mídia / Imagens (Uploads)

• POST /admin/images: Faz upload de uma nova imagem para o Cloudflare R2.
• GET /admin/images: Lista a galeria de imagens cadastradas.
• GET /admin/images/:id: Recupera os detalhes de uma imagem.
• PUT /admin/images/:id: Edita os metadados de uma imagem.
• DELETE /admin/images/:id: Exclui permanentemente uma imagem do banco e do Cloudflare R2 (bloqueado caso a imagem esteja em uso por um caldo/proteína).

Pedidos (Orders - Public)

• POST /orders: Realiza um novo pedido enviando ID do caldo e proteína (protegido).
• GET /orders: Lista os pedidos do usuário autenticado (protegido).
• GET /orders/:orderId: Recupera os detalhes de um pedido específico (protegido; o proprietário ou um administrador pode acessar).

Administração de Pedidos (Orders - Admin)

• GET /admin/orders: Lista todos os pedidos (restrito a administradores).
• PATCH /admin/orders/:orderId/status: Atualiza o status de um pedido (restrito a administradores). Os status possíveis são PENDING, PREPARING, READY e DELIVERED.

Autenticação

A aplicação utiliza JWT (JSON Web Token). Após fazer login na rota de sessões, você deve incluir o token gerado no cabeçalho Authorization das requisições protegidas:

Authorization: Bearer <seu-jwt-token>