StackSpot AI: Hands-on de Onboarding

hands-on-stackspot-ai.md

Hands-on StackSpot AI

A ideia é implementar um Quick Command que converte um schema DDL para entidades e em seguida para uma API REST em Java com Spring Boot. Este Quick Command terá 3 passos:

1. Ler um script DDL e converter para entidades da JPA e Hibernate;
2. A partir das entidades, gerar os repositories e controllers (somente com o endpoint de cadastro);
   • o mesmo terá anexado um Knowleged Source de boas práticas de arquitetura de código;
3. A partir dos controllers, gerar os testes de integração do Spring Boot;
   • o mesmo terá anexado um Knowleged Source de boas práticas de testes automatizados;

Diagrama MER e schema DDL

Abaixo temos o diagrama MER em Mermaid para o modelo simplificado de uma loja virtual ou e-commerce:

erDiagram
    CLIENTE {
        int id PK
        varchar nome
        varchar email
        varchar telefone
        text endereco
    }
    
    PEDIDO {
        int id PK
        int cliente_id FK
        timestamp data_pedido
        varchar status
        decimal valor_total
    }
    
    ITEM_PEDIDO {
        int id PK
        int pedido_id FK
        int produto_id
        int quantidade
        decimal preco_unitario
    }
    
    CLIENTE ||--o{ PEDIDO: "possui"
    PEDIDO ||--o{ ITEM_PEDIDO: "contém"

Loading

Abaixo temos o schema DDL para PostgreSQL utilizado para gerar o diagrama acima:

-- Criação da tabela Cliente
CREATE TABLE Cliente (
    id       SERIAL       PRIMARY KEY,
    nome     VARCHAR(100) NOT NULL,
    email    VARCHAR(100) UNIQUE NOT NULL,
    telefone VARCHAR(15),
    endereco TEXT
);

-- Criação da tabela Pedido
CREATE TABLE Pedido (
    id          SERIAL        PRIMARY KEY,
    cliente_id  INT           NOT NULL,
    data_pedido TIMESTAMP     NOT NULL DEFAULT CURRENT_TIMESTAMP,
    status      VARCHAR(20)   NOT NULL,
    valor_total DECIMAL(10,2) NOT NULL,
    CONSTRAINT fk_cliente
        FOREIGN KEY(cliente_id) 
        REFERENCES Cliente(id)
);

-- Criação da tabela Item_Pedido
CREATE TABLE Item_Pedido (
    id             SERIAL        PRIMARY KEY,
    pedido_id      INT           NOT NULL,
    produto_id     INT           NOT NULL,
    quantidade     INT           NOT NULL,
    preco_unitario DECIMAL(10,2) NOT NULL,
    CONSTRAINT fk_pedido
        FOREIGN KEY(pedido_id) 
        REFERENCES Pedido(id)
);

Knowledge Source

Criaremos um único documento Markdown com as regras e boas práticas de código e arquitetura para classes de Controller e testes de integração com o seguinte conteúdo:

Boas práticas de código para controllers:

1. Crie DTO's de entrada e saída na controller, utilize os sufixos `Request` e `Response` para isso; 
2. Adicione anotações de validação da Bean Validation nos atributos do DTO de request;
3. Crie ou utilize classe Service. O controller não deve ter acesso direto ao Repository da entidade;
3. Para endpoint de cadastro, retorne um status HTTP 201 com DTO de response no body da requisição;

Boas práticas de código para testes de integração:

1. Crie um teste de integração do Spring Boot via anotação `@SpringBootTest`;
2. Crie um cenário de teste para o happy-path;
3. Crie um cenário de teste para erros de validação existentes no DTO de request;
4. Use o Repository da entidade para limpar e/ou popular a tabela do banco de dados antes de cada cenário de teste via anotação `@BeforeEach` do jUnit;
5. Verifique os status HTTP de retorno e payloads de resposta;

Exemplo de Knowledge Source

Abaixo tem o conteudo do Knowledge Source em formato Markdown:

# Boas práticas de código e arquitetura

Este documento descreve as boas práticas de design de código, testes, e de arquitetura.

## Boas práticas de código para controllers:

Todo controller deve seguir o padrão de código abaixo:

1. Crie DTO's de entrada e saída na controller, utilize os sufixos `Request` e `Response` para isso; 
2. Adicione anotações de validação da Bean Validation nos atributos do DTO de request;
3. Crie ou utilize classe Service. O controller não deve ter acesso direto ao Repository da entidade;
3. Para endpoint de cadastro, retorne um status HTTP 201 com DTO de response no body da requisição;

## Boas práticas de código para testes de integração:

Todo teste automatizado deve ser feito como teste de integração do Spring Boot e deve seguir o padrão de código abaixo:

1. Crie um teste de integração do Spring Boot via anotação `@SpringBootTest`;
2. Crie um cenário de teste para o happy-path;
3. Crie um cenário de teste para erros de validação existentes no DTO de request;
4. Use o Repository da entidade para limpar e/ou popular a tabela do banco de dados antes de cada cenário de teste via anotação `@BeforeEach` do jUnit;
5. Verifique os status HTTP de retorno e payloads de resposta;

Exemplo de Quick Command

Aqui temos o conteudo utilizado na criação do nosso Quick Command:

start

Name: handson-from-ddl-to-rest-api
Description: Gerar APIs REST a partir de um schema DDL de PostgreSQL.

step-01-gerar-entidades

A partir do schema DDL selecionado, gere código Java com as entidades da JPA e Hibernate.

 {{selected_code}} 

step-02-gerar-controllers

Agora, me gere as classes de Repository e Controller do Spring Boot para as entidades da JPA e Hibernate, mas somente para o endpoint de cadastro. **Também siga os padrões de código e arquitetura de classes**.

step-03-gerar-testes

Por fim, a partir dos Controllers gerados, gere testes de integração com Spring Boot para cada um dos controllers.

End

## Step 01: Gerar entidades
 {{step-01-gerar-entidades.answer}} 

## Step 02: Gerar controllers
 {{step-02-gerar-controllers.answer}} 

# Step 03: Gerar testes de integração
 {{step-03-gerar-testes.answer}}