API REST — do Zero ao CRUD Completo

<!-- ════ PARENT ════════════════════════════════════════════════════ -->
<!-- Define o Spring Boot como "pai" — ele gerencia todas as versões
     das dependências filhas e configura o plugin de build -->
<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>4.0.5</version>   <!-- versão do Spring Boot -->
  <relativePath/>              <!-- busca no repositório Maven Central -->
</parent>

<!-- ════ IDENTIFICAÇÃO DO PROJETO ══════════════════════════════════ -->
<groupId>com.github</groupId>        <!-- pacote base da organização/desenvolvedor -->
<artifactId>app</artifactId>           <!-- nome do projeto (gera app.jar) -->
<version>0.0.1-SNAPSHOT</version>    <!-- versão em desenvolvimento -->

<!-- ════ PROPRIEDADES ══════════════════════════════════════════════ -->
<properties>
  <java.version>17</java.version>  <!-- versão do Java usada na compilação -->
</properties>

<!-- ════ DEPENDÊNCIAS ══════════════════════════════════════════════ -->
<dependencies>

  <!-- WEB MVC ──────────────────────────────────────────────────────
       Inclui: Tomcat embutido, Spring MVC, Jackson (JSON).
       Sem isso: não há servidor HTTP, @RestController não funciona -->
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webmvc</artifactId>
  </dependency>

  <!-- DATA JPA ─────────────────────────────────────────────────────
       Inclui: Hibernate, Spring Data JPA, JDBC.
       Sem isso: @Entity, @Repository, JpaRepository não funcionam -->
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
  </dependency>

  <!-- H2 DATABASE ──────────────────────────────────────────────────
       Banco de dados em memória. Perfeito para testes: não precisa
       instalar nada. scope=runtime: só existe ao executar, não compila.
       Sem isso: não há driver de banco → aplicação não inicia -->
  <dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <scope>runtime</scope>  <!-- disponível somente em tempo de execução -->
  </dependency>

  <!-- LOMBOK ───────────────────────────────────────────────────────
       Gera em tempo de compilação: getters, setters, construtores,
       equals/hashCode, toString. Elimina ~70% do código boilerplate.
       optional=true: não é transitivo (outros projetos não herdam).
       Sem isso: precisa escrever todos os métodos manualmente -->
  <dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <optional>true</optional>
  </dependency>

  <!-- VALIDATION ───────────────────────────────────────────────────
       Habilita Bean Validation: @NotBlank, @Email, @NotNull, @Valid.
       Sem isso: as anotações de validação são ignoradas silenciosamente
       e dados inválidos chegam até o banco -->
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
  </dependency>

  <!-- ACTUATOR ─────────────────────────────────────────────────────
       Expõe endpoints de monitoramento da aplicação:
       /actuator/health → status da app
       /actuator/info   → informações do projeto
       Útil para produção e integração com ferramentas de monitoramento -->
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
  </dependency>

  <!-- DEVTOOLS ─────────────────────────────────────────────────────
       Hot reload: detecta mudanças no código e reinicia a aplicação
       automaticamente. runtime+optional: não vai para produção.
       Sem isso: precisa parar e reiniciar manualmente a cada mudança -->
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-devtools</artifactId>
    <scope>runtime</scope>
    <optional>true</optional>
  </dependency>

  <!-- TEST ─────────────────────────────────────────────────────────
       Inclui JUnit 5, Mockito, Spring Test. scope=test: só em testes.
       Não vai para o jar de produção -->
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
  </dependency>

</dependencies>

<!-- ════ BUILD ══════════════════════════════════════════════════════ -->
<build>
  <plugins>
    <!-- Plugin que empacota a aplicação como JAR executável (fat jar) -->
    <plugin>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-maven-plugin</artifactId>
    </plugin>
  </plugins>
</build>

package com.github.app;
// O pacote raiz deve ser o mais alto da hierarquia — todos os
// subpacotes (controller, model...) serão varridos automaticamente

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
// Dois imports: a classe que faz o boot e a anotação mágica

@SpringBootApplication
// A anotação mais importante: combina @Configuration + @EnableAutoConfiguration
// + @ComponentScan. Detalhe abaixo.
public class AppApplication {

    public static void main(String[] args) {
        // Ponto de entrada do programa Java (método main padrão)
        // O JVM chama este método ao executar o .jar

        SpringApplication.run(AppApplication.class, args);
        // SpringApplication.run() é quem dispara tudo:
        // 1. Cria o ApplicationContext (container de IoC)
        // 2. Inicia o servidor Tomcat embutido na porta 8080
        // 3. Registra todos os Controllers, Repositories e Beans
        // 4. Executa os CommandLineRunners (se houver)
        // AppApplication.class → diz ao Spring onde começar o scan
        // args → passa argumentos da linha de comando (ex: --server.port=9090)
    }
}

package com.github.app.controller;
// Fica no subpacote "controller" — o @ComponentScan vai encontrá-lo

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
// Três anotações do Spring MVC: definem o comportamento HTTP da classe

@RestController
// Combina @Controller + @ResponseBody.
// @Controller: registra a classe como um bean que trata requisições HTTP.
// @ResponseBody: serializa automaticamente o retorno do método para JSON/texto
// no corpo da resposta HTTP (sem isso, o Spring tentaria encontrar uma view HTML)

@RequestMapping("ola")
// Define o caminho base para TODOS os métodos desta classe.
// A URL completa será: http://localhost:8080/ola
// Pode conter múltiplos níveis: "api/v1/medicos"

public class OlaController {

    @GetMapping
    // Mapeia este método para requisições HTTP GET no caminho base (/ola).
    // Se fosse @GetMapping("teste") seria GET /ola/teste

    public String olaMundo() {
        // O método retorna uma String. Com @RestController, ela é
        // enviada diretamente no corpo da resposta HTTP como texto puro.
        // Se retornasse um objeto Java, o Jackson o converteria para JSON.

        return "Olá Mundo!";
        // Resposta: HTTP 200 OK, body: Olá Mundo!
    }
}

// Regra: URL final = caminho do @RequestMapping + caminho do @GetMapping/@PostMapping etc.

@RequestMapping("medicos")      // → base: /medicos
public class MedicoController {

    @GetMapping                 // → GET  /medicos       (sem caminho adicional)
    public ... listar() { }

    @GetMapping("todos")        // → GET  /medicos/todos
    public ... listarTodos() { }

    @PostMapping                // → POST /medicos
    public void cadastrar() { }

    @PutMapping                 // → PUT  /medicos
    public void atualizar() { }

    @DeleteMapping("/{id}")    // → DELETE /medicos/5  (id é variável na URL)
    public void excluir() { }
}

package com.github.app.model.medico;

// ── Anotações Lombok (geração de código em tempo de compilação) ─────
@Getter
// Gera automaticamente: getNome(), getEmail(), getCrm(), getId()...
// para todos os atributos private da classe. Sem isso, o Spring
// não consegue serializar o objeto para JSON (o Jackson usa getters)

@Setter
// Gera automaticamente: setNome(), setEmail()...
// O JPA precisa dos setters para popular os campos ao ler do banco

@AllArgsConstructor
// Gera um construtor com TODOS os atributos como parâmetro:
// new Medico(id, nome, email, telefone, crm, ativo, especialidade, endereco)
// Usado internamente pelo Lombok e pode ser útil em testes

@NoArgsConstructor
// Gera um construtor SEM argumentos: new Medico()
// OBRIGATÓRIO para o JPA: o Hibernate precisa instanciar a entidade
// sem parâmetros ao ler registros do banco via reflexão Java

@EqualsAndHashCode(of = "id")
// Gera equals() e hashCode() baseados APENAS no campo "id".
// Isso garante que dois objetos Medico com mesmo id são considerados iguais,
// independente dos outros campos. Essencial para coleções (Set, HashMap)

// ── Anotações JPA (mapeamento objeto-relacional) ────────────────────
@Entity
// Marca a classe como uma entidade JPA.
// O Hibernate irá criar/usar uma tabela para esta classe no banco.
// Sem @Entity: o Spring ignora a classe e não cria nenhuma tabela

@Table(name = "medicos")
// Define explicitamente o nome da tabela no banco: "medicos".
// Sem @Table: o Hibernate usa o nome da classe ("Medico") como nome da tabela.
// Convenção: tabelas em minúsculas e plural

public class Medico {

    @Id
    // JPA: indica que este campo é a Chave Primária (PRIMARY KEY) da tabela.
    // Toda entidade JPA DEVE ter exatamente um campo @Id

    @GeneratedValue(strategy = GenerationType.IDENTITY)
    // JPA: o banco gera o valor automaticamente usando AUTO_INCREMENT (MySQL)
    // ou SERIAL (PostgreSQL). O H2 também suporta.
    // strategy=IDENTITY: delega a geração ao banco (não ao Hibernate).
    // Sem @GeneratedValue: você precisaria definir o id manualmente

    private Integer id;
    // Tipo Integer (objeto) em vez de int (primitivo) porque pode ser null
    // antes da entidade ser salva — o banco ainda não gerou o id

    private String nome;      // coluna "nome" VARCHAR na tabela
    private String email;     // coluna "email" VARCHAR na tabela
    private String telefone;  // coluna "telefone" VARCHAR na tabela
    private String crm;       // coluna "crm" VARCHAR — identificação profissional

    private Boolean ativo = true;
    // Flag para exclusão lógica: true=ativo, false=desativado.
    // Valor padrão true: novos médicos já são cadastrados como ativos.
    // Permite "excluir" sem apagar do banco (ver Seção 13)

    @Enumerated(EnumType.STRING)
    // JPA: instrui o Hibernate a salvar o TEXTO do enum no banco.
    // Sem isso, o padrão seria EnumType.ORDINAL (salva 0, 1, 2...).
    // EnumType.STRING é muito melhor: salva "CARDIOLOGIA", "ORTOPEDIA".
    // Se você reordenar o enum, os dados não ficam corrompidos

    private Especialidade especialidade;
    // Coluna "especialidade" VARCHAR(255) no banco, ex: "CARDIOLOGIA"

    @Embedded
    // JPA: os campos da classe Endereco são "embutidos" diretamente
    // nesta tabela "medicos". Não cria uma tabela separada de endereços.
    // A classe Endereco deve estar anotada com @Embeddable (ver Seção 12)

    private Endereco endereco;
    // Resultado: as colunas logradouro, bairro, cep, cidade, uf
    // aparecem diretamente na tabela "medicos"

    // ── Construtor de conversão: DTO → Entidade ──────────────────────
    public Medico(DadosCadastroMedico dados) {
        // Este construtor recebe o DTO (que veio do JSON da requisição)
        // e popula os campos da entidade. Separa a camada de entrada
        // da camada de persistência — a entidade nunca é exposta ao cliente

        this.nome = dados.nome();
        // dados.nome() — método acessor de record (sem "get")

        this.email = dados.email();
        this.telefone = dados.telefone();
        this.crm = dados.crm();
        this.especialidade = dados.especialidade();

        this.endereco = new Endereco(dados.endereco());
        // dados.endereco() retorna um DadosCadastroEndereco (outro DTO).
        // O construtor de Endereco converte esse DTO em um objeto Endereco.
    }

    // ── Método de atualização parcial ────────────────────────────────
    public void atualizarInformacoes(DadosAtualizacaoMedico dados) {
        if (dados.nome() != null)     this.nome = dados.nome();
        if (dados.email() != null)    this.email = dados.email();
        if (dados.endereco() != null) this.endereco.atualizarInformacoes(dados.endereco());
        // Verifica null antes de atualizar: se o campo não veio no JSON,
        // ele chegará null no DTO e não sobrescreve o valor existente no banco
    }

    // ── Exclusão lógica ──────────────────────────────────────────────
    public void exclusaoLogica() {
        this.ativo = false;
        // Não deleta do banco — apenas marca como inativo.
        // O @Transactional no Controller detectará a mudança (dirty checking)
        // e gerará UPDATE medicos SET ativo=false WHERE id=?
    }
}

package com.github.app.model.medico;

public enum Especialidade {
    ORTOPEDIA,    // tratamento de ossos, articulações e músculos
    CARDIOLOGIA,  // doenças do coração e sistema circulatório
    GINECOLOGIA,  // saúde da mulher
    DERMATOLOGIA; // doenças da pele
}
// Um enum é um tipo especial que define um conjunto fixo de valores possíveis.
// No banco (com @Enumerated(STRING)), será salvo como texto: "CARDIOLOGIA".
// No JSON de entrada, o cliente deve enviar exatamente a string: "CARDIOLOGIA"

// ── Com RECORD (forma moderna — usada no projeto) ───────────────────
public record DadosCadastroMedico(
    String nome,
    String email,
    String telefone,
    String crm,
    Especialidade especialidade,
    DadosCadastroEndereco endereco
) { }
// Para acessar: dados.nome(), dados.email(), dados.crm()
//              SEM "get" na frente — essa é a sintaxe do record!

// ── Com CLASSE NORMAL (equivalente, mais verboso) ───────────────────
public class DadosCadastroMedicoClasseNormal {
    private String nome;
    private String email;
    private String telefone;
    private String crm;
    private Especialidade especialidade;
    private DadosCadastroEndereco endereco;

    public DadosCadastroMedicoClasseNormal(String nome, String email,
            String telefone, String crm, Especialidade especialidade,
            DadosCadastroEndereco endereco) {
        this.nome = nome; this.email = email; ...
    }
    public String getNome() { return nome; }
    public String getEmail() { return email; }
    // ... mais 8 getters, equals(), hashCode(), toString() ...
}

package com.github.app.model.medico;

public record DadosCadastroMedico(
    // Campos que o cliente DEVE enviar no JSON ao fazer POST /medicos

    String nome,
    // "nome": "Dr. Joao Silva" — nome completo do médico

    String email,
    // "email": "joao@clinic.com" — e-mail de contato

    String telefone,
    // "telefone": "11999998888" — campo opcional (sem validação)

    String crm,
    // "crm": "123456" — registro profissional do médico

    Especialidade especialidade,
    // "especialidade": "CARDIOLOGIA" — deve ser um dos valores do enum Especialidade
    // O Jackson converte automaticamente a String para o enum correspondente

    DadosCadastroEndereco endereco
    // "endereco": { ... } — outro DTO aninhado com os campos de endereço
    // O Jackson converte o objeto JSON para um DadosCadastroEndereco automaticamente
) { }
// O corpo vazio {} significa: sem métodos customizados (apenas o que o record gera)

public record DadosCadastroEndereco(
    String logradouro,  // nome da rua: "Rua das Flores"
    String bairro,      // bairro: "Centro"
    String cep,         // CEP: "01001000" (sem traço)
    String complemento, // complemento: "Ap 42" — opcional
    String cidade,      // cidade: "Sao Paulo"
    String uf           // estado: "SP" — sigla de 2 letras
) { }

// POST http://localhost:8080/medicos
// Content-Type: application/json
{
  "nome":          "Dr. Joao Silva",
  "email":         "joao@clinic.com",
  "telefone":      "11999998888",
  "crm":           "123456",
  "especialidade": "CARDIOLOGIA",
  "endereco": {
    "logradouro":  "Rua das Flores",
    "bairro":      "Centro",
    "cep":         "01001000",
    "complemento": "Sala 202",
    "cidade":      "Sao Paulo",
    "uf":          "SP"
  }
}
// O Spring/Jackson desserializa esse JSON para um DadosCadastroMedico automaticamente.
// O campo "endereco" vira um DadosCadastroEndereco aninhado.

package com.github.app.model.medico;

import jakarta.validation.Valid;
import jakarta.validation.constraints.*;

public record DadosCadastroMedico(

    @NotBlank
    // Valida: não nulo E não vazio E não apenas espaços em branco.
    // Exemplos que FALHAM: null, "", "   "
    // Exemplos que PASSAM: "Dr. João", "a"
    String nome,

    @Email
    // Valida o formato do e-mail: deve ter @ e domínio.
    // Exemplos que FALHAM: "joao", "joao@", "@clinic.com"
    // Exemplos que PASSAM: "joao@clinic.com"
    @NotBlank
    // Combinando duas anotações: deve ser não-vazio E formato de e-mail
    String email,

    String telefone,
    // Sem anotação = campo opcional. null é aceito. Pode ser vazio.

    String crm,
    // Também opcional neste projeto (poderia ter @NotBlank em produção)

    @NotNull
    // Valida: não pode ser null. Diferente de @NotBlank: aceita string vazia.
    // Usado para tipos que não são String: enums, objetos, números.
    // Exemplos que FALHAM: null, campo ausente no JSON
    // Exemplos que PASSAM: "CARDIOLOGIA", qualquer valor do enum
    Especialidade especialidade,

    @NotNull
    @Valid
    // @Valid é ESSENCIAL: propaga a validação para DENTRO do objeto DadosCadastroEndereco.
    // Sem @Valid, as anotações @NotBlank dentro do DadosCadastroEndereco são IGNORADAS.
    // Pense assim: @Valid diz "valide também o objeto aninhado, não só se é null"
    DadosCadastroEndereco endereco

) { }

public record DadosCadastroEndereco(

    @NotBlank
    String logradouro,  // obrigatório: nome da rua

    @NotBlank
    String bairro,      // obrigatório: bairro

    @NotBlank
    String cep,         // obrigatório: CEP (poderia ter @Pattern para validar formato)

    String complemento, // opcional: apartamento, sala, etc.

    @NotBlank
    String cidade,      // obrigatório: cidade

    @NotBlank
    String uf           // obrigatório: estado (sigla)

) { }

// ── SEM @Valid no Controller (ERRADO — validações ignoradas) ────────
@PostMapping
public void cadastrar(@RequestBody DadosCadastroMedico dados) {
    repository.save(new Medico(dados));
    // ⚠️ Sem @Valid: dados com nome="" ou email="invalido" seriam aceitos!
}

// ── COM @Valid no Controller (CORRETO — validações ativadas) ────────
@PostMapping
public void cadastrar(@RequestBody @Valid DadosCadastroMedico dados) {
    // ✅ @Valid ANTES do parâmetro: o Spring valida o DTO antes de executar o método.
    // Se qualquer campo falhar a validação → 400 Bad Request automático.
    // O método não executa — nenhum dado inválido chega ao banco.
    repository.save(new Medico(dados));
}

// Requisição enviada com nome vazio:
{
  "nome": "",
  "email": "invalido-sem-arroba",
  "especialidade": "CARDIOLOGIA",
  "endereco": { ... }
}

// Resposta automática do Spring: 400 Bad Request
{
  "status": 400,
  "errors": [
    { "field": "nome",  "message": "must not be blank" },
    { "field": "email", "message": "must be a well-formed email address" }
  ]
}
// O método cadastrar() NÃO é executado. Nada é salvo no banco.

package com.github.app.model.medico;

import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;

@Repository
// Marca a interface como um componente de acesso a dados.
// Tecnicamente opcional — o Spring já detecta interfaces que herdam JpaRepository.
// Mas é boa prática manter: documenta a intenção e habilita tradução de exceções
// (ex: DataAccessException em vez de HibernateException)

public interface MedicoRepository extends JpaRepository<Medico, Integer> {
// ↑ Interface, não classe — o Spring cria a implementação em tempo de execução!
//
// JpaRepository recebe dois tipos genéricos:
//   Medico   → o tipo da entidade que este repository gerencia
//   Integer  → o tipo da chave primária (@Id) da entidade Medico
//
// Ao herdar JpaRepository, você ganha GRATUITAMENTE:
//   save(), findAll(), findById(), deleteById(), getReferenceById(),
//   existsById(), count(), findAll(Pageable), saveAll()...
//
// O Spring Data JPA usa um Proxy dinâmico para implementar esta interface.
// Você nunca escreve "new MedicoRepositoryImpl()" — o Spring faz isso.

    // Corpo vazio — tudo que precisamos já está em JpaRepository!
    // Poderia adicionar métodos customizados aqui. Ex:
    // List<Medico> findByEspecialidade(Especialidade especialidade);
    // O Spring gera automaticamente o SQL: SELECT * FROM medicos WHERE especialidade = ?
}

@RestController
public class MedicoController {

    @Autowired
    // Injeção de Dependência: em vez de você criar o objeto:
    //     MedicoRepository repo = new MedicoRepository(); // ERRADO — é interface!
    // O Spring cria a implementação e "injeta" aqui automaticamente.
    //
    // Como funciona:
    // 1. @ComponentScan encontra MedicoRepository (marcado com @Repository)
    // 2. Spring cria a implementação via proxy dinâmico
    // 3. Spring detecta @Autowired no Controller
    // 4. Spring injeta a instância criada automaticamente
    //
    // Benefício: baixo acoplamento. Se trocar MedicoRepository por outro,
    // o Controller não precisa mudar nada.
    private MedicoRepository repository;
}

@RestController          // registra como controller que retorna dados JSON
@RequestMapping("medicos") // todos os endpoints começam com /medicos
public class MedicoController {

    @Autowired
    private MedicoRepository repository;
    // Spring injeta automaticamente a implementação do repository
}

@PostMapping
// Responde a: POST http://localhost:8080/medicos
// Usado para CRIAR um novo recurso

@Transactional
// Abre uma transação de banco de dados antes de executar o método.
// Se o método terminar sem exceção → COMMIT (confirmação no banco).
// Se ocorrer uma exceção → ROLLBACK (desfaz tudo).
// Obrigatório no cadastrar: garante que o INSERT seja confirmado.

public void cadastrar(@RequestBody @Valid DadosCadastroMedico dados) {
    // @RequestBody: diz ao Spring para ler o JSON do corpo da requisição
    //              e desserializar para DadosCadastroMedico
    // @Valid:      ativa a Bean Validation — campos @NotBlank etc. são verificados

    repository.save(new Medico(dados));
    // new Medico(dados): chama o construtor especial que converte DTO → Entidade
    // repository.save(): gera INSERT INTO medicos (nome, email...) VALUES (?, ?...)
}
// JSON para teste no Insomnia:
// POST /medicos
// { "nome": "Dr. Ana", "email": "ana@clinic.com", "crm": "654321",
//   "especialidade": "GINECOLOGIA",
//   "endereco": { "logradouro": "Av. Brasil", "bairro": "Centro",
//                 "cep": "01001000", "cidade": "SP", "uf": "SP" } }

@GetMapping("todos")
// Responde a: GET http://localhost:8080/medicos/todos

public List<Medico> listarTodos() {
    return repository.findAll();
    // ⚠️ Retorna a entidade Medico diretamente — má prática!
    // Problemas:
    // 1. Expõe campos internos (ativo) ao cliente
    // 2. Se houver @ManyToOne, pode causar LazyInitializationException
    // 3. Serialização recursiva infinita em relacionamentos bidirecionais
    // Use apenas para depuração. Em produção, use sempre um DTO de listagem.
}

@GetMapping("listar")
// Responde a: GET http://localhost:8080/medicos/listar
// Sem paginação — retorna todos de uma vez (ruim para grandes volumes)

public List<DadosListagemMedico> listar() {
    return repository.findAll()
                      .stream()
                      // .stream() → transforma List<Medico> em um fluxo de dados
                      .map(DadosListagemMedico::new)
                      // .map() → para cada Medico no fluxo, cria um DadosListagemMedico
                      // DadosListagemMedico::new é uma referência ao construtor do record
                      .toList();
                      // .toList() → coleta todos os elementos em uma List imutável
}
// Resultado: List<DadosListagemMedico> — só id, nome, email, crm, especialidade.
// Sem endereço completo, sem campo ativo — apenas o que o cliente precisa ver.

@GetMapping
// Responde a: GET http://localhost:8080/medicos
// Aceita parâmetros: ?page=0&size=10&sort=nome,asc

public Page<DadosListagemMedico> listarPorPagina(Pageable paginacao) {
    // Pageable: o Spring preenche automaticamente com os parâmetros da URL.
    //   GET /medicos?page=1&size=5 → paginacao = {page:1, size:5}
    //   GET /medicos?sort=nome,desc → ordena por nome decrescente
    // Se não passar parâmetros: page=0, size=20 (padrões do Spring)

    return repository.findAll(paginacao)
                      // findAll(Pageable) gera: SELECT * FROM medicos LIMIT ? OFFSET ?
                      .map(DadosListagemMedico::new);
                      // Page tem .map() nativo — não precisa de .stream()
                      // Converte cada Medico da página em DadosListagemMedico
}
// Resposta JSON inclui: content[], totalElements, totalPages, size, number...

@PutMapping
// Responde a: PUT http://localhost:8080/medicos
// Usado para ATUALIZAR um recurso existente

@Transactional
// ESSENCIAL aqui: sem @Transactional, o dirty checking não funciona.
// O Hibernate precisa de uma transação ativa para detectar mudanças
// e gerar o UPDATE automaticamente

public void atualizar(@RequestBody DadosAtualizacaoMedico dados) {

    var medico = repository.getReferenceById(dados.id());
    // var: palavra-chave do Java 10+ para inferência de tipo.
    //      var medico = ... equivale a Medico medico = ...
    //      O compilador Java infere o tipo pelo lado direito.
    //
    // getReferenceById(dados.id()): retorna um proxy do Medico com o id informado.
    //   Não faz SELECT ainda — o SELECT ocorre ao acessar os campos.
    //   Se o id não existir, lança EntityNotFoundException ao acessar.

    medico.atualizarInformacoes(dados);
    // Chama o método da entidade que atualiza os campos com null-check.
    // O Hibernate monitora o objeto medico dentro da transação (@Transactional).
    // Ao detectar que os campos mudaram (dirty checking), gera automaticamente:
    // UPDATE medicos SET nome=?, email=? WHERE id=?
    // NÃO precisa chamar repository.save() aqui!
}
// JSON para teste: PUT /medicos
// { "id": 1, "nome": "Dr. Joao Atualizado" }
// Só envie os campos que quer alterar — null não sobrescreve

@DeleteMapping("/{id}")
// Responde a: DELETE http://localhost:8080/medicos/5
// {id} é uma variável na URL — capturada pelo @PathVariable

@Transactional
public void excluir(@PathVariable Integer id) {
    // @PathVariable: extrai o {id} da URL e injeta no parâmetro.
    // DELETE /medicos/5 → id = 5
    // O nome {id} na URL DEVE ser igual ao nome do parâmetro (id)

    repository.deleteById(id);
    // Gera: DELETE FROM medicos WHERE id = ?
    // Exclusão física — o registro é removido permanentemente do banco.
    // Ver Seção 13 para exclusão lógica (alternativa recomendada)
}
// Teste no Insomnia: DELETE http://localhost:8080/medicos/5

public record DadosListagemMedico(
    Integer id,               // id do médico — necessário para operações futuras (PUT, DELETE)
    String nome,              // nome para exibição na lista
    String email,             // contato
    String crm,               // identificação profissional
    Especialidade especialidade // filtro/agrupamento por especialidade
    // ⚠️ Sem: telefone, ativo, endereço completo — não necessários na listagem
) {
    // Construtor de conversão: recebe uma Entidade Medico e popula o record
    public DadosListagemMedico(Medico medico) {
        this(
            medico.getId(),
            medico.getNome(),
            medico.getEmail(),
            medico.getCrm(),
            medico.getEspecialidade()
        );
        // this(...) chama o construtor canônico do record com todos os campos.
        // medico.getNome() usa o getter gerado pelo Lombok @Getter na entidade.
    }
}

// ── Versão COM Stream API (forma do projeto) ────────────────────────
return repository.findAll()          // 1. List<Medico> do banco
                  .stream()           // 2. transforma em Stream<Medico>
                  .map(DadosListagemMedico::new) // 3. converte cada Medico em DadosListagemMedico
                  .toList();           // 4. coleta em List<DadosListagemMedico>

// ── Versão SEM Stream (equivalente, mais verboso) ────────────────────
List<Medico> medicos = repository.findAll();
List<DadosListagemMedico> resultado = new ArrayList<>();
for (Medico medico : medicos) {
    DadosListagemMedico dto = new DadosListagemMedico(medico);
    resultado.add(dto);
}
return resultado;
// As duas versões fazem EXATAMENTE a mesma coisa.
// A versão Stream é mais legível e menos propensa a erros.

// Referência de método: uma forma concisa de referenciar um método/construtor existente

// DadosListagemMedico::new  →  referência ao CONSTRUTOR do record
// Equivale à lambda: medico -> new DadosListagemMedico(medico)

.map(DadosListagemMedico::new)
// O mesmo que:
.map(medico -> new DadosListagemMedico(medico))

// Outros exemplos de referências de método:
// String::toUpperCase    → s -> s.toUpperCase()
// System.out::println   → s -> System.out.println(s)
// Integer::parseInt     → s -> Integer.parseInt(s)

// filter() — filtra elementos que atendem a condição
repository.findAll().stream()
    .filter(m -> m.getAtivo())  // só médicos ativos
    .map(DadosListagemMedico::new)
    .toList();

// sorted() — ordena
.sorted((a, b) -> a.getNome().compareTo(b.getNome()))

// collect(Collectors.toList()) — alternativa mais antiga a .toList()
.collect(Collectors.toList())  // retorna List mutável
// .toList() retorna List imutável (Java 16+)

// GET http://localhost:8080/medicos/listar
[
  {
    "id": 1,
    "nome": "Dr. Joao Silva",
    "email": "joao@clinic.com",
    "crm": "123456",
    "especialidade": "CARDIOLOGIA"
  },
  {
    "id": 2,
    "nome": "Dra. Ana Costa",
    "email": "ana@clinic.com",
    "crm": "654321",
    "especialidade": "GINECOLOGIA"
  }
]
// Campos ausentes: telefone, ativo, endereço — protegidos pelo DTO

public record DadosAtualizacaoMedico(

    Integer id,
    // O id é OBRIGATÓRIO: o Controller precisa saber qual médico atualizar.
    // Diferente do cadastro (POST), o id vem no BODY do PUT, não na URL.
    // Alternativa: usar PUT /medicos/{id} com @PathVariable (igualmente válido)

    String nome,
    // Opcional: se null no JSON, o campo nome do médico não é alterado

    String email,
    // Opcional: pode atualizar só o email sem tocar no nome

    DadosCadastroEndereco endereco
    // Opcional: se null, o endereço não é tocado.
    // Se enviado, os campos não-null dentro do endereco são atualizados.
    // Usa o mesmo DTO de cadastro (DadosCadastroEndereco) para simplificar.
    // Nota: telefone e crm NÃO aparecem aqui — não são atualizáveis neste projeto

) { }

// Na entidade Medico.java:
public void atualizarInformacoes(DadosAtualizacaoMedico dados) {

    if (dados.nome() != null) {
        this.nome = dados.nome();
        // Só atualiza o nome se ele veio no JSON.
        // Se "nome" não está no JSON → dados.nome() retorna null → if falso → campo ignorado
        // Se "nome": "Dr. Novo" está no JSON → dados.nome() retorna "Dr. Novo" → atualiza
    }

    if (dados.email() != null) {
        this.email = dados.email();
        // Mesma lógica: só atualiza se o email vier no JSON
    }

    if (dados.endereco() != null) {
        this.endereco.atualizarInformacoes(dados.endereco());
        // Se o objeto endereco vier no JSON, delega a atualização para
        // o método atualizarInformacoes() da classe Endereco,
        // que fará null-check campo por campo dentro do endereço também
    }
    // Ao final: o @Transactional no Controller detecta quais campos mudaram
    // (dirty checking) e gera apenas: UPDATE medicos SET nome=? WHERE id=?
    // Campos não alterados NÃO aparecem no UPDATE
}

// ── Atualizar apenas o nome ─────────────────────────────────────────
// PUT /medicos
{ "id": 1, "nome": "Dr. Joao Atualizado" }
// SQL gerado: UPDATE medicos SET nome='Dr. Joao Atualizado' WHERE id=1
// email e endereco: null no DTO → não alterados

// ── Atualizar apenas o endereço ─────────────────────────────────────
// PUT /medicos
{
  "id": 1,
  "endereco": {
    "cidade": "Rio de Janeiro",
    "uf": "RJ"
  }
}
// SQL: UPDATE medicos SET cidade='Rio de Janeiro', uf='RJ' WHERE id=1
// Outros campos do endereço: null → não alterados

// ── Atualizar tudo ──────────────────────────────────────────────────
// PUT /medicos
{
  "id": 1,
  "nome": "Dr. Joao",
  "email": "novoemail@clinic.com",
  "endereco": {
    "logradouro": "Rua Nova", "bairro": "Jardins",
    "cep": "01400000", "cidade": "Sao Paulo", "uf": "SP"
  }
}
// SQL: UPDATE medicos SET nome=?, email=?, logradouro=?, bairro=?,
//      cep=?, cidade=?, uf=? WHERE id=1

package com.github.app.model.endereco;

@Getter
@Setter
@AllArgsConstructor
@NoArgsConstructor
// Mesmas anotacoes Lombok da entidade: getters, setters, construtores.
// @NoArgsConstructor é necessário porque @Embeddable também é instanciado
// pelo JPA via reflexão ao ler do banco

@Embeddable
// JPA: marca esta classe como "embutível".
// Isso significa que os campos desta classe podem ser incorporados
// diretamente na tabela de qualquer entidade que usar @Embedded.
// Endereco NÃO é uma entidade — não tem @Entity, não tem @Id,
// não tem tabela própria no banco de dados.

public class Endereco {

    private String logradouro; // → coluna "logradouro" na tabela pai (medicos ou pacientes)
    private String bairro;     // → coluna "bairro"
    private String cep;        // → coluna "cep"
    private String complemento;// → coluna "complemento" (pode ser null)
    private String cidade;     // → coluna "cidade"
    private String uf;         // → coluna "uf"

    // ── Construtor de conversão: DTO → Embeddable ────────────────────
    public Endereco(DadosCadastroEndereco dados) {
        this.logradouro = dados.logradouro();
        this.bairro = dados.bairro();
        this.cep = dados.cep();
        this.complemento = dados.complemento();
        this.cidade = dados.cidade();
        this.uf = dados.uf();
        // Converte DadosCadastroEndereco (DTO imutável) em Endereco (objeto mutável)
    }

    // ── Atualizacao parcial do endereco ─────────────────────────────
    public void atualizarInformacoes(DadosCadastroEndereco dados) {
        if (dados.logradouro() != null) this.logradouro = dados.logradouro();
        if (dados.bairro() != null)     this.bairro = dados.bairro();
        if (dados.cep() != null)       this.cep = dados.cep();
        if (dados.complemento() != null) this.complemento = dados.complemento();
        if (dados.cidade() != null)   this.cidade = dados.cidade();
        if (dados.uf() != null)       this.uf = dados.uf();
        // Null-check campo por campo: permite atualizar só cidade sem tocar CEP, bairro etc.
    }
}

@Entity
@Table(name = "medicos")
public class Medico {
    // ... outros campos (id, nome, email, crm, ativo, especialidade) ...

    @Embedded
    // JPA: inclui todos os campos da classe Endereco (@Embeddable)
    // diretamente nesta tabela "medicos".
    // Resultado: as colunas logradouro, bairro, cep, complemento, cidade, uf
    // aparecem DENTRO da tabela "medicos" — sem JOIN necessário.
    //
    // Equivalente a escrever cada campo de Endereco diretamente na entidade Medico,
    // mas com código reutilizável — Paciente também usa @Embedded Endereco
    private Endereco endereco;
}

// ── EXCLUSÃO FÍSICA — remove o registro para sempre ─────────────────
@DeleteMapping("/{id}")
// URL: DELETE http://localhost:8080/medicos/5
// O {id} na URL é capturado pelo @PathVariable

@Transactional
// Necessário para garantir que o DELETE seja commitado

public void excluir(@PathVariable Integer id) {
    // @PathVariable Integer id: extrai o valor {id} da URL.
    // DELETE /medicos/5 → id = 5

    repository.deleteById(id);
    // Gera: DELETE FROM medicos WHERE id = 5
    //
    // ⚠️ Problema: se existirem consultas com este médico,
    // o DELETE viola a FK e lança exceção.
    // O dado some para sempre — não pode ser recuperado.
    // Em sistemas médicos, isso é problemático: perde histórico de consultas.
}

// ── EXCLUSÃO LÓGICA — oculta o registro sem apagá-lo ────────────────
// (versão comentada no projeto — seria a alternativa recomendada)

// @DeleteMapping("/{id}")
// @Transactional
// public void alterarStatus(@PathVariable Integer id) {
//
//     var medico = repository.getReferenceById(id);
//     // Busca o médico — getReferenceById() não faz SELECT imediato (lazy proxy)
//
//     medico.exclusaoLogica();
//     // Chama o método da entidade que muda ativo = false
//     // @Transactional detecta a mudança (dirty checking) e gera:
//     // UPDATE medicos SET ativo = false WHERE id = 5
//     // O médico CONTINUA no banco — só o campo ativo mudou
// }

// ── Método exclusaoLogica() na entidade Medico ───────────────────────
public void exclusaoLogica() {
    this.ativo = false;
    // Muda apenas o campo booleano. O registro permanece intacto no banco.
    // Histórico de consultas, dados do médico: tudo preservado.
    // Para reativar: ativo = true (implementar um endpoint de reativação)
}

// Na entidade Medico.java:
private Boolean ativo = true;
// Boolean (objeto) em vez de boolean (primitivo) para aceitar null no banco.
// Valor padrão true: novos médicos começam ativos automaticamente.
// Sem precisar passar ativo no JSON de cadastro — o DTO não tem esse campo.

// Para listar só médicos ativos na listagem paginada, você adicionaria:
// No MedicoRepository: Page<Medico> findByAtivoTrue(Pageable pageable);
// No Controller: return repository.findByAtivoTrue(paginacao).map(DadosListagemMedico::new);
// Spring gera: SELECT * FROM medicos WHERE ativo = true LIMIT ? OFFSET ?

@Getter @Setter @AllArgsConstructor @NoArgsConstructor
@EqualsAndHashCode(of = "id")
@Entity
@Table(name = "pacientes")
// Mesmas anotações do Médico: JPA + Lombok. Tabela se chama "pacientes"
public class Paciente {

    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Integer id;

    private String nome;
    private String email;
    private String telefone;

    private String cpf;
    // Diferença em relação ao Médico: CPF em vez de CRM.
    // Paciente se identifica pelo CPF (cidadão), não por registro profissional.

    // Nota: Paciente NÃO tem campo "ativo" nem enum "Especialidade"
    // Poderia ter em produção — mas neste projeto é mais simples

    @Embedded
    private Endereco endereco;
    // Mesmo @Embeddable do Médico — reutilizável em qualquer entidade

    public Paciente(DadosCadastroPaciente dados) {
        this.nome = dados.nome();
        this.email = dados.email();
        this.telefone = dados.telefone();
        this.cpf = dados.cpf();
        this.endereco = new Endereco(dados.endereco());
        // Mesmo padrão: converte DTO em Entidade no construtor
    }

    public void atualizarInformacoes(DadosAtualizacaoPaciente dados) {
        if (dados.nome() != null)     this.nome = dados.nome();
        if (dados.telefone() != null) this.telefone = dados.telefone();
        if (dados.endereco() != null)  this.endereco.atualizarInformacoes(dados.endereco());
        // Diferença: paciente não pode atualizar email (email é documento de conta).
        // DadosAtualizacaoPaciente não tem campo email por decisão de design.
    }
}

// ── DadosCadastroPaciente ────────────────────────────────────────────
public record DadosCadastroPaciente(
    String nome,
    String email,
    String telefone,
    String cpf,              // CPF ao invés de CRM
    DadosCadastroEndereco endereco
    // Neste projeto sem validações @NotBlank — pode adicionar em produção
) { }

// ── DadosListagemPaciente ────────────────────────────────────────────
public record DadosListagemPaciente(
    String nome,
    String email,
    String cpf               // só 3 campos — lista compacta para o frontend
) {
    public DadosListagemPaciente(Paciente paciente) {
        this(paciente.getNome(), paciente.getEmail(), paciente.getCpf());
        // Sem id, telefone, endereço — listagem simplificada
    }
}

// ── DadosAtualizacaoPaciente ─────────────────────────────────────────
public record DadosAtualizacaoPaciente(
    Integer id,
    String nome,
    String telefone,
    // ⚠️ email NÃO está aqui: paciente não pode alterar o próprio email
    //    (email geralmente é o login/identificador da conta)
    DadosCadastroEndereco endereco
) { }

package com.github.app.model.paciente;

import org.springframework.data.jpa.repository.JpaRepository;

// Sem @Repository explícito — o Spring detecta automaticamente
public interface PacienteRepository extends JpaRepository<Paciente, Integer> {
    // Mesmo padrão: JpaRepository<Paciente, Integer>
    // Ganha todos os métodos: save(), findAll(), findById(), deleteById()...
    // Corpo vazio: tudo que precisamos já está em JpaRepository
}

@RestController
@RequestMapping("/pacientes")
// Note a barra inicial "/pacientes" — funciona igual a "pacientes" sem barra
public class PacienteController {

    @Autowired
    private PacienteRepository repository;

    // ── POST /pacientes ──────────────────────────────────────────────
    @PostMapping
    @Transactional
    public void cadastrar(@RequestBody DadosCadastroPaciente dados) {
        repository.save(new Paciente(dados));
        // Mesmo padrão do Médico: converte DTO em Entidade e salva
    }

    // ── GET /pacientes/todos ─────────────────────────────────────────
    @GetMapping("todos")
    public List<Paciente> listarTodos() {
        return repository.findAll();
        // Retorna entidade bruta — útil para debug, ruim para produção
    }

    // ── GET /pacientes/listar ────────────────────────────────────────
    @GetMapping("listar")
    public List<DadosListagemPaciente> listar() {
        return repository.findAll().stream()
                          .map(DadosListagemPaciente::new).toList();
    }

    // ── GET /pacientes?page=0&size=10 ────────────────────────────────
    @GetMapping
    public Page<DadosListagemPaciente> listarPorPagina(Pageable paginacao) {
        return repository.findAll(paginacao).map(DadosListagemPaciente::new);
    }

    // ── PUT /pacientes ───────────────────────────────────────────────
    @PutMapping
    @Transactional
    public void atualizar(@RequestBody DadosAtualizacaoPaciente dados) {
        var paciente = repository.getReferenceById(dados.id());
        paciente.atualizarInformacoes(dados);
        // Dirty checking: sem save() explícito — mesmo padrão do Médico
    }

    // ── DELETE /pacientes/{id} ───────────────────────────────────────
    @DeleteMapping("/{id}")
    @Transactional
    public void excluir(@PathVariable Integer id) {
        repository.deleteById(id);
    }
}

// ── POST /pacientes — Cadastrar ─────────────────────────────────────
{
  "nome": "Maria Oliveira",
  "email": "maria@email.com",
  "telefone": "11988887777",
  "cpf": "12345678901",
  "endereco": {
    "logradouro": "Rua das Acácias", "bairro": "Vila Nova",
    "cep": "04500000", "cidade": "Sao Paulo", "uf": "SP"
  }
}

// ── PUT /pacientes — Atualizar (só telefone) ─────────────────────────
{ "id": 1, "telefone": "11999990000" }

// ── GET /pacientes/listar — Resposta ─────────────────────────────────
[
  { "nome": "Maria Oliveira", "email": "maria@email.com", "cpf": "12345678901" }
]

package com.github.app.model.consulta;

@Entity
@Getter @Setter @AllArgsConstructor @NoArgsConstructor
@EqualsAndHashCode(of = "id")
@Table(name = "consultas")
// Mesmo padrão de Medico e Paciente: JPA + Lombok
public class Consulta {

    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Integer id;

    @ManyToOne
    // Relacionamento: MUITAS consultas podem ter o MESMO médico.
    // (Um médico atende muitas consultas. Cada consulta tem um médico.)
    // No banco: cria uma coluna FK na tabela "consultas" apontando para "medicos"

    @JoinColumn(name = "medicoId")
    // Define o nome da coluna de chave estrangeira: "medicoId".
    // Sem @JoinColumn: o Hibernate geraria um nome automático como "medico_id".

    private Medico medico;
    // Objeto Medico completo — JPA carrega automaticamente ao consultar uma Consulta.
    // A serialização para JSON inclui os dados do médico no objeto de resposta.

    @ManyToOne
    // Mesmo padrão: MUITAS consultas → UM paciente

    @JoinColumn(name = "pacienteId")
    // Coluna FK: "pacienteId" → referencia "pacientes.id"

    private Paciente paciente;

    @Enumerated(EnumType.STRING)
    private Status status;
    // Salva o texto do enum: "AGENDADA", "CONFIRMADA", "CANCELADA", "REALIZADA"

    private String observacao;
    // Texto livre: "Retorno pós-cirurgia", "Primeiro atendimento" etc.

    private LocalDateTime data;
    // Data e hora da consulta: 2026-06-15T10:30:00
    // LocalDateTime: sem fuso horário — adequado para uso local

    // ── Construtor de conversão: DTO → Entidade ──────────────────────
    public Consulta(DadosAgendamentoConsulta dados) {
        this.status = dados.status();
        this.observacao = dados.observacao();
        this.data = dados.data();
        // ⚠️ Note: medico e paciente NÃO são populados aqui!
        // O DTO tem apenas medicoId e pacienteId (inteiros).
        // O Controller busca os objetos completos e usa setMedico() e setPaciente().
        // Ver ConsultaController na Seção 16.
    }
}

public enum Status {
    AGENDADA,    // consulta marcada mas aguardando confirmação
    CONFIRMADA,  // paciente confirmou presença
    CANCELADA,   // consulta desmarcada (por qualquer motivo)
    REALIZADA;   // consulta já aconteceu — histórico
}
// Fluxo típico: AGENDADA → CONFIRMADA → REALIZADA
//               AGENDADA → CANCELADA  (paciente cancelou)

public record DadosAgendamentoConsulta(

    Integer medicoId,
    // O cliente envia apenas o ID do médico, não o objeto completo.
    // Isso é o padrão REST: referenciar outros recursos pelo id.
    // O Controller busca o objeto Medico no banco a partir deste id.

    Integer pacienteId,
    // Mesmo raciocínio: só o id do paciente

    String observacao,
    // Texto livre — observação sobre a consulta

    Status status,
    // "AGENDADA" — valor do enum Status

    LocalDateTime data
    // "2026-06-15T10:30:00" — formato ISO 8601

) { }

package com.github.app.controller;

@RestController
@RequestMapping("consultas")
// Todos os endpoints deste controller começam com /consultas
public class ConsultaController {

    @Autowired
    private ConsultaRepository consultaRepository;
    // Repository da própria entidade Consulta: para salvar a consulta

    @Autowired
    private MedicoRepository medicoRepository;
    // Repository de Médico: para buscar o médico pelo id recebido no JSON
    // Por que precisamos? O DTO tem medicoId (Integer), mas a entidade
    // Consulta precisa de um objeto Medico completo (por causa do @ManyToOne)

    @Autowired
    private PacienteRepository pacienteRepository;
    // Mesma razão: DTO tem pacienteId, entidade precisa de objeto Paciente

    @PostMapping
    // Responde a: POST http://localhost:8080/consultas

    public Consulta agendar(@RequestBody DadosAgendamentoConsulta dados) {
        // Retorna Consulta (entidade) direto. Em produção, melhor retornar um DTO.
        // Aqui está ok para aprendizado — mas note que o JSON de resposta
        // incluirá o objeto Medico e Paciente completos aninhados.

        var medico = medicoRepository.getReferenceById(dados.medicoId());
        // Busca o médico pelo id: dados.medicoId() = o Integer do JSON.
        // getReferenceById() retorna um proxy lazy — não faz SELECT imediato.
        // Quando save() for chamado abaixo, o Hibernate resolve o proxy e
        // insere o medicoId correto na coluna FK da tabela consultas.

        var paciente = pacienteRepository.getReferenceById(dados.pacienteId());
        // Mesmo padrão: busca o paciente pelo id recebido no JSON

        var consulta = new Consulta(dados);
        // Cria o objeto Consulta a partir do DTO.
        // O construtor Consulta(dados) popula: status, observacao, data.
        // MAS NÃO popula medico e paciente (eles são objetos, não ids simples).

        consulta.setMedico(medico);
        // Setta o objeto Medico (proxy) na entidade Consulta.
        // Quando save() ocorrer, o Hibernate vai usar medico.getId() para
        // preencher a coluna medicoId na tabela consultas.

        consulta.setPaciente(paciente);
        // Mesmo raciocínio: setta o objeto Paciente

        return consultaRepository.save(consulta);
        // Gera: INSERT INTO consultas (medicoId, pacienteId, status, observacao, data)
        //       VALUES (1, 3, 'AGENDADA', 'Retorno...', '2026-06-15 10:30:00')
        // save() retorna a Consulta salva com o id gerado pelo banco.
        // Esse objeto com id é retornado como JSON na resposta.
    }
}

// POST http://localhost:8080/consultas
// Content-Type: application/json
{
  "medicoId":   1,
  "pacienteId": 2,
  "status":     "AGENDADA",
  "observacao": "Retorno de check-up cardíaco",
  "data":       "2026-06-15T10:30:00"
}
// Requisito: o médico com id=1 e o paciente com id=2 devem existir no banco.
// Se não existirem: EntityNotFoundException ao acessar o proxy.

// HTTP 200 OK — o objeto Consulta completo retornado
{
  "id": 1,
  "medico": {
    "id": 1,
    "nome": "Dr. Joao Silva",
    "email": "joao@clinic.com",
    "crm": "123456",
    "especialidade": "CARDIOLOGIA",
    "ativo": true,
    "endereco": { ... }
  },
  "paciente": {
    "id": 2,
    "nome": "Maria Oliveira",
    "email": "maria@email.com",
    "cpf": "12345678901",
    "endereco": { ... }
  },
  "status": "AGENDADA",
  "observacao": "Retorno de check-up cardíaco",
  "data": "2026-06-15T10:30:00"
}
// Note: retorna a entidade completa com médico e paciente aninhados.
// Em produção, crie um DadosDetalheConsulta (DTO) para controlar a resposta.

# ── application.properties ──────────────────────────────────────────
# Arquivo de configuração principal — sempre carregado.
# Define qual perfil específico também será carregado.

spring.profiles.active=test
# Define o perfil ativo: "test".
# Spring vai carregar TAMBÉM: application-test.properties.
# Os valores do perfil específico sobrescrevem os do principal.
# Para trocar o banco: mude para spring.profiles.active=dev

# ── application-test.properties ─────────────────────────────────────
# Carregado quando spring.profiles.active=test
# Usa H2: banco em memória, sem instalação, ideal para desenvolvimento

spring.datasource.url=jdbc:h2:mem:clinicadb
# jdbc:h2      → driver H2
# :mem:        → banco em MEMÓRIA (não cria arquivo no disco)
# clinicadb    → nome do banco (pode ser qualquer nome)
# mem = memória: o banco existe SOMENTE enquanto a aplicação está rodando.
# Ao parar e reiniciar a aplicação: banco apagado, tabelas recriadas, dados perdidos.

spring.datasource.username=sa
# Usuário padrão do H2: "sa" (System Administrator)

spring.datasource.password=
# Senha vazia: padrão do H2 em modo memória

spring.h2.console.enabled=true
# Habilita a interface web do H2 Console.
# Acesse: http://localhost:8080/h2-console
# Na tela de login, use:
#   Driver Class: org.h2.Driver
#   JDBC URL:     jdbc:h2:mem:clinicadb  (EXATAMENTE igual ao configurado)
#   User Name:    sa
#   Password:     (em branco)
# Depois de conectar: você verá as tabelas criadas pelo Hibernate!

# ── application-dev.properties ──────────────────────────────────────
# Carregado quando spring.profiles.active=dev
# Usa MySQL: dados persistidos entre restarts da aplicação

spring.datasource.url=jdbc:mysql://localhost:3306/vollmed?createDatabaseIfNotExist=true
# jdbc:mysql   → driver MySQL
# localhost    → servidor na máquina local
# :3306        → porta padrão do MySQL
# vollmed      → nome do banco de dados
# createDatabaseIfNotExist → cria o banco se não existir

spring.datasource.username=root
spring.datasource.password=sua_senha_aqui
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
# Driver JDBC do MySQL (necessário adicionar dependência mysql-connector no pom.xml)

spring.jpa.hibernate.ddl-auto=update
# Define o que o Hibernate faz com o schema do banco ao iniciar.
# update: cria tabelas se não existirem, adiciona colunas novas.
#         Nunca apaga dados existentes — seguro para desenvolvimento.

spring.jpa.show-sql=true
# Imprime no console todos os SQLs que o Hibernate gera.
# Ótimo para depuração: ver qual SQL foi gerado para cada operação.

spring.jpa.properties.hibernate.format_sql=true
# Formata o SQL com indentação — mais fácil de ler no console