📚 Pré-requisitos Teóricos: este projeto aplica conceitos ensinados na Especialização em Android Nativo. Recomendado revisar antes de iniciar.

☁️ P07: Master Pokédex (Conectando à Nuvem com Retrofit 2)

v1.0 — Android Nativo, Kotlin, Retrofit 2, Moshi, OkHttp Interceptors, Consumo de APIs REST e Carregamento Assíncrono com Glide

Série Prática Android Clássico — Projeto 7 de 21

• P06: Catálogo Offline com Room Database & Coroutines
• ➡️ P07 (este): Master Pokédex com Retrofit 2 & REST API
• P08: Batalha Scanner com CameraX & QR Code
• P09: PokeMap com Google Maps & GPS
• P10: Arena Social com Firebase Suite

🏛️ Visão Geral & Arquitetura Visual

O projeto Master Pokédex implementa o consumo corporativo de APIs RESTful na plataforma Android utilizando o padrão de ouro da indústria: Retrofit 2 integrado ao cliente HTTP OkHttp. A aplicação realiza requisições assíncronas para a PokéAPI pública, desserializa payloads JSON complexos com segurança de tipos via Moshi, intercepta requisições para telemetria de rede com HttpLoggingInterceptor e renderiza sprites em alta resolução com a biblioteca de imagem Glide.

📁 Estrutura de Pastas Anti-Colisão

Todos os clientes HTTP, contratos de serviço, DTOs e telas residem na subpasta canônica mobile-android-kotlin/:

catalogo_projetos/android_p07_pokedex_retrofit/
├── assets/
│   └── arquitetura_pokedex_retrofit.svg
├── mobile-android-kotlin/
│   ├── app/
│   │   ├── src/
│   │   │   └── main/
│   │   │       ├── java/br/com/curso/pokedex/
│   │   │       │   ├── api/
│   │   │       │   │   ├── PokeApiService.kt
│   │   │       │   │   └── RetrofitClient.kt
│   │   │       │   ├── model/
│   │   │       │   │   └── PokemonResponse.kt
│   │   │       │   └── MainActivity.kt
│   │   │       └── res/
│   │   └── build.gradle
│   ├── gradle/
│   ├── build.gradle
│   ├── gradlew
│   ├── settings.gradle
│   └── README.md
└── index.md

🧑‍💼 Engenharia de Software & Especificação Formal

1. Histórias de Usuário (User Stories)

2. Requisitos do Sistema

Requisitos Funcionais (RF)

• RF-01: Definir interface declarativa PokeApiService com método anotado @GET("pokemon/{id}").
• RF-02: Desserializar respostas JSON aninhadas através do converter MoshiConverterFactory.
• RF-03: Configurar pool de conexões HTTP, timeout de 15 segundos e interceptor de log no OkHttpClient.
• RF-04: Carregar imagens de sprites de forma eficiente utilizando Glide.with(context).load(url).
• RF-05: Implementar controle de concorrência com Coroutines para cancelamento automático de requisições pendentes ao sair da tela.

Requisitos Não-Funcionais (RNF)

• RNF-01 (Segurança de Rede): Comunicação obrigatória via protocolo seguro HTTPS / TLS 1.3.
• RNF-02 (Cache de Imagens): Otimização de banda e cache em disco gerenciado pelo Glide.
• RNF-03 (Resiliência): Tratamento de falhas HTTP (404 Not Found, 500 Internal Server Error) com mensagens amigáveis.
• RNF-04 (Assincronismo): Requisições executadas no despachante Dispatchers.IO sem congelar a tela.
• RNF-05 (Consumo de Memória): Descarte ordenado de bitmaps em memória ao navegar pela lista de monstros.

3. Diagrama de Casos de Uso

flowchart TD
    User([fa:fa-user Treinador])
    API[(fa:fa-cloud PokéAPI REST)]

    subgraph AppPokedex ["☁️ Master Pokédex (mobile-android-kotlin)"]
        UC01["Pesquisar Pokémon por Nome/ID"]
        UC02["Disparar Requisição REST Retrofit"]
        UC03["Desserializar Payload com Moshi"]
        UC04["Baixar e Exibir Sprite via Glide"]
        UC05["Tratar Falhas de Conectividade"]
    end

    User --> UC01
    UC01 --> UC02
    UC02 --> API
    API -.->|JSON| UC03
    UC03 --> UC04
    UC02 -.->|Falha/Timeout| UC05

4. Matriz de Rastreabilidade (RTM)

🛠️ Implementação Guiada (PokeApi.kt)

📄 mobile-android-kotlin/app/src/main/java/br/com/curso/masterpokedex/data/network/PokeApi.kt (arquivo real do projeto)

package br.com.curso.masterpokedex.data.network

import com.google.gson.annotations.SerializedName
import retrofit2.http.GET
import retrofit2.http.Path

// 1. MODELOS DE DADOS (Dicionário da API)
data class PokemonListResponse(
    val results: List<PokemonBrief>
)

data class PokemonBrief(
    val name: String,
    val url: String
)

data class PokemonDetailResponse(
    val id: Int,
    val name: String,
    @SerializedName("sprites") val sprites: SpriteResponse
)

data class SpriteResponse(
    @SerializedName("front_default") val frontDefault: String
)

// 2. O GARÇOM (Retrofit Interface)
interface PokeApiService {
    @GET("pokemon?limit=20")
    suspend fun getList(): PokemonListResponse

    @GET("pokemon/{name}")
    suspend fun getDetail(@Path("name") name: String): PokemonDetailResponse
}

🚀 Como Executar no Laboratório

1. Navegue até a subpasta do projeto

cd catalogo_projetos/android_p07_pokedex_retrofit/mobile-android-kotlin

2. Compile e execute

./gradlew assembleDebug
./gradlew test

🏁 Matriz de Checkpoints de Conclusão