Challenge 2 - E-commerce (CompassUOL)

O projeto consiste no desenvolvimento de uma API REST para um e-commerce, utilizando as tecnologias e conhecimentos aprendidos até o momento durante essa jornada do programa de bolsas de estágio da Compass UOL | Back-end Journey (Spring Boot) - AWS Cloud Context.

O projeto foi desenvolvimento utilizando o Java JDK na versão 17 e separado em dois domínios: Produto (Product) e Pedido (Order). Cada domínio possui 5 (cinco) endpoints, e foram todos documentados utilizando o Swagger.

Para testes das implementações, foi utilizado inicialmente o aplicativo Postman, cobrindo assim os testes de requisições. Ademais, posteriormente para testes de únidades e integração, foi utilizado o JUnit 5 em conjunto com o Mockito.

Autores

A equipe CoffeeWithSpring, responsável pelo desenvolvimento do projeto desse desáfio é composta por:

E-mail	Usuário Github
bruno.ronning.pb@compasso.com.br	quasemago
franciele.dalaros.pb@compasso.com.br	francieledalarosa
luisa.kroth.pb@compasso.com.br	luisafkroth
mayke.lellis.pb@compasso.com.br	maykeanselmo
pedro.koberstain.pb@compasso.com.br	pedrokoberstain

Sumário

• Challenge 2 - E-commerce (CompassUOL)
  • Autores
  • Tecnologias utilizadas
    • Dependências
  • Domínios
    • Regras de negócio gerais
    • Estrutura do banco de dados
    • Product (Produto)
      • Regras de negócio
      • Endpoints
      • Payloads
        • Exemplos de requisições
    • Pedido (Order)
      • Regras de negócio
      • Endpoints
      • Payloads
        • Exemplos de requisições
  • Fluxo de erros
  • Como executar o projeto
    • Utilizando uma IDE (IntelliJ IDEA)
    • Utilizando o terminal
    • Projeto em execução
      • Coleção do Postman
  • Conclusão

Tecnologias utilizadas

• Java JDK 17

Dependências

• Spring Boot 3
• Spring Boot Test (inclui o JUnit 5 e Mockito)
• Spring Web
• Spring Data JPA
• Spring Validation
• Spring DevTools
• Spring Doc OpenAPI (Swagger)
• Spring Cloud OpenFeign
• ModelMapper
• Lombok
• Banco de dados H2 (utilizando apenas na camada de testes)
• Banco de dados MySQL

---

Domínios

Regras de negócio gerais

Apesar do projeto ter sido separado em dois domínios, ambos possuem regras de negócio em comum, sendo elas:

• Todos os campos data, devem seguir o padrão ISO 8601 (exemplo: 2023-07-20T12:00:00Z ).
• Todos os campos data, devem ser definidas automaticamente.
• As funcionalidades pedido e produto podem conter: data de cadastro ( created_date ), data de atualização ( update_date ) e data de cancelamento ( cancel_date ).
• A documentação da API ViaCEP pode ser encontrada no endereço https://viacep.com.br/

Estrutura do banco de dados

O domínio possui a seguinte estrutura de banco de dados:

Observações importantes sobre alterações nos requisitos do domínio Produto:

• Os requisitos do desáfio especificavam que a coluna que armazenaria o valor do produto na tabela products deveria ser nomeada de value, porém, devido a conflitos com o banco de dados H2 pois value é uma palavra-chave reservada do mesmo, a coluna foi renomeada para price.

Observações importantes sobre alterações nos requisitos do domínio Pedido:

• Os requisitos do desáfio especificavam que a coluna que armazenaria o endereço de entrega do pedido na tabela orders deveria ser nomeada de address, porem visando um melhor desenvolvimento seguindo um padrão de normalização, a coluna foi renomeada para address_id e foi criada uma nova tabela chamada addresses para armazenar os endereços de entrega dos pedidos por relacionamento do banco de dados.
• Os requisitos do desáfio também especificavam que haveria uma coluna chamada products na tabela orders que armazenaria a lista de produtos do pedido, mas a nossa abordagem de desenvolvimento foi criar uma tabela intermediaria chamada order_products para armazenar essa lista de produtos, contendo o id do pedido e o id do produto, para que possamos ter um relacionamento entre as tabelas orders e products.

Com essas alterações, foi possível concluir o desenvolvimento do projeto de forma mais eficiente e simples.

Produto (Product)

O domínio Produto consiste em uma API REST que permite que os usuários criem, leiam, atualizem e excluam produtos.

Regras de negócio

O domínio Produto possui as seguintes regras de negócio:

• O nome do produto deve ser único;
• A descrição do produto deve ter no mínimo 10 caracteres;
• O valor do produto deve ser um número positivo.

Endpoints

A API disponibiliza endpoints REST para interação. Sendo:

• POST /products: Cria um novo produto.
• GET /products: Recupera uma lista de todos os produtos cadastrados.
• GET /products/:id: Recupera as informações de um produto específico.
• PUT /products/:id: Atualiza as informações de um produto existente.
• DELETE /products/:id: Deleta um produto existente.

Payloads

Ademais, a API possui os seguintes payloads para interação:

• ProductCreate: Payload utilizado para criação e atualização de um produto. Exemplo:

  {
    "name": "Product name",
    "description": "Product description",
    "value": 10.5
  }
  

• ProductResponse: Payload utilizado para retorno de informações de um produto. Exemplo:

  {
    "id": 1,
    "name": "Product name",
    "description": "Product description",
    "value": 10.5
  }
  

Exemplos de requisições

Para criar um novo produto:

• Requisição:

  POST /products
  {
    "name": "Nome do Produto",
    "description": "Descrição do Produto",
    "value": 29.99
  }
  

• Resposta (Status 201 - Created):

  {
    "id": 1,
    "name": "Nome do Produto",
    "description": "Descrição do Produto",
    "value": 29.99
  }
  

Para recuperar uma lista de todos os produtos cadastrados:

• Requisição:

  GET /products
  

• Resposta (Status 200 - OK):

  [
    {
      "id": 1,
      "name": "Nome do Produto 1",
      "description": "Descrição do Produto 1",
      "value": 29.99
    },
    // Outros produtos...
  ]
  

Para recuperar informações de um produto específico:

• Requisição:

  GET /products/5
  

• Resposta (Status 200 - OK):

  {
    "id": 5,
    "name": "Nome do Produto",
    "description": "Descrição do Produto",
    "value": 29.99
  }
  

Para atualizar um produto existente:

• Requisição:

  PUT /products/15
  {
    "name": "Novo Nome",
    "description": "Nova Descrição",
    "value": 39.99
  }
  

• Resposta (Status 200 - OK):

  {
    "id": 15,
    "name": "Novo Nome",
    "description": "Nova Descrição",
    "value": 39.99
  }
  

Para deletar um produto existente:

• Requisição:

  DELETE /products/15
  

• Resposta (Status 204 - No Content):
  • Nesse caso, não há corpo de resposta, pois a resposta é sem conteúdo.

Pedido (Order)

O domínio Pedido consiste em uma API REST que permite que os usuários façam pedidos de produtos de um catálogo.

Regras de negócio

O domínio Pedido possui as seguintes regras de negócio:

• Para completar as informações relativas ao endereço, deve ser consultado os dados na API ViaCEP.
• A operação GET /orders deve estar ordenada por data de criação, dos pedidos mais recentes para os mais antigos. Além disso, deve ser possível filtrar por status do pedido.
• Status dos pedidos: CONFIRMED, SENT, CANCELED
• Tipos permitidos de pagamento: CREDIT_CARD, BANK_TRANSFER, CRYPTOCURRENCY, GIFT_CARD, PIX, OTHER.
• O valor total do pedido é calculado pela aplicação de acordo com a seguinte fórmula: total_value = subtotal_value - discount
• O desconto de 5% é aplicado apenas para pedidos com método de pagamento PIX.
• Para o endereço, deve ser informado apenas number, complement e postal_code.
• Para complementar as informações relativas ao endereço, deve ser consultar os dados na API ViaCEP.

Além disso, a opção de cancelamento de pedidos possui as seguintes regras de negócio:

• Um pedido só pode ser cancelado se o status for diferente de SENT.
• Um pedido não pode ser cancelado se tiver mais de 90 dias de criação.
• Após o cancelamento, o status do pedido deverá ser alterado para CANCELED.

Endpoints

A API disponibiliza endpoints REST para interação. Sendo:

• POST /orders: Cria um novo pedido.
• GET /orders: Recupera uma lista ordenada por data de criação, do mais recente para o mais antigo, de todos os pedidos cadastrados. Além disso, é possível filtrar por status do pedido.
  • Exemplo do endpoint com filtro por status: GET /orders?status=CONFIRMED.
• GET /orders/:id: Recupera as informações de um pedido específico.
• PUT /orders/:id: Atualiza as informações do status de um pedido existente.
• POST /orders/:id/cancel: Cancela um pedido existente.

Payloads

Ademais, a API possui os seguintes payloads para interação:

• OrderCreate: Payload utilizado para criação de um pedido. Exemplo:

  {
    "products": [
      {
        "productId": 1,
        "quantity": 2
      },
      {
        "productId": 2,
        "quantity": 5
      }
    ],
    "address": {
      "number": 10,
      "complement": "Próximo a av. Pitanga",
      "postalCode": "01001000"
    },
    "paymentMethod": "PIX"
  }
  

• OrderUpdate: Payload utilizado para atualização do status de um pedido. Exemplo:

  {
    "status": "SENT"
  }
  

• OrderCancel: Payload utilizado para cancelamento de um pedido. Exemplo:

  {
    "cancelReason": "Motivo do cancelamento do cliente"
  }
  

• OrderResponse: Payload utilizado para retorno de informações de um pedido. Exemplo:

  {
    "id": 1,
    "products": [
      {
        "productId": 1,
        "quantity": 2
      },
      {
        "productId": 2,
        "quantity": 5
      }
    ],
    "address": {
      "street": "Praça da Sé",
      "number": 10,
      "complement": "Próximo a av. Pitanga",
      "city": "São Paulo",
      "state": "SP",
      "postalCode": "01001-000"
    },
    "paymentMethod": "PIX",
    "subtotalValue": 100.00,
    "discount": 0.5,
    "totalValue": 95.00,
    "createdDate": "2023-07-20T12:00:00Z",
    "status": "CONFIRMED"
  }
  

Exemplos de requisições

Para criar um novo pedido:

• Requisição:

  POST /orders
  {
    "products": [
      {
        "productId": 1,
        "quantity": 2
      },
      {
        "productId": 2,
        "quantity": 5
      }
    ],
    "address": {
      "number": 10,
      "complement": "Próximo a av. Pitanga",
      "postalCode": "01001000"
    },
    "paymentMethod": "PIX"
  }
  

• Resposta (Status 201 - Created):

  {
    "id": 1,
    "products": [
      {
        "productId": 1,
        "quantity": 2
      },
      {
        "productId": 2,
        "quantity": 5
      }
    ],
    "address": {
      "street": "Praça da Sé",
      "number": 10,
      "complement": "Próximo a av. Pitanga",