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

📍 P09: PokeMap (Ginásios na Cidade com Google Maps & GPS)

v1.0 — Android Nativo, Kotlin, Google Maps SDK, FusedLocationProviderClient, Sensores de GPS e Cálculo de Proximidade Geográfica

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

🏛️ Visão Geral & Arquitetura Visual

O projeto PokeMap demonstra a integração completa do ecossistema de mapas e serviços de localização do Google no Android. Utilizando o Google Maps Android SDK em combinação com a API de localização do Google Play Services (FusedLocationProviderClient), a aplicação renderiza um mapa vetorial estilizado em tempo real, obtém as coordenadas geográficas precisas do usuário (latitude e longitude), demarca ginásios virtuais com marcadores customizados e calcula a distância euclidiana/geodésica para liberar desafios apenas quando o jogador estiver no raio de ação físico (geofencing local).

Fluxo Visual do PokeMap com Google Maps e GPS

📁 Estrutura de Pastas Anti-Colisão

Todos os serviços de mapa, provedores de geolocalização e interfaces residem na subpasta canônica mobile-android-kotlin/:

catalogo_projetos/android_p09_pokemap_gps/
├── assets/
│   ├── mockup_pokemap_fluxo.svg
│   ├── screenshot_01_permissao_gps.svg
│   ├── screenshot_02_mapa_ativo.svg
│   └── screenshot_03_desafio_ginasio.svg
├── mobile-android-kotlin/
│   ├── app/
│   │   ├── src/
│   │   │   └── main/
│   │   │       ├── java/br/com/curso/pokemap/
│   │   │       │   ├── location/
│   │   │       │   │   └── LocationService.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)

ID Persona Narrativa da Funcionalidade Critério de Aceitação Principal Prioridade
US-01 Jogador Explorador Quero autorizar o acesso à minha localização precisa (GPS) para visualizar meu avatar no mapa. Solicitação nativa de permissões ACCESS_FINE_LOCATION e ACCESS_COARSE_LOCATION. Alta
US-02 Jogador Explorador Quero visualizar um mapa estilizado da minha cidade com zoom automático na minha posição atual. Câmera do Google Maps centralizada nas coordenadas do usuário com animação suave. Alta
US-03 Jogador Explorador Quero ver marcadores de ginásios espalhados pelo mapa com ícones temáticos. Inclusão de MarkerOptions com ícones customizados e títulos descritivos. Alta
US-04 Jogador Explorador Quero que o botão de desafio seja habilitado somente se eu estiver a menos de 50 metros do ginásio. Cálculo contínuo de distância com Location.distanceBetween(). Média
US-05 Desenvolvedor Mobile Quero suspender as atualizações periódicas de localização quando o app for para segundo plano. Cancelamento do LocationCallback no ciclo de vida onPause para preservar a bateria. Baixa

2. Requisitos do Sistema

Requisitos Funcionais (RF)

Requisitos Não-Funcionais (RNF)

3. Diagrama de Casos de Uso

flowchart TD
    Player([fa:fa-user Jogador Explorador])
    GPS[(fa:fa-satellite Google Location GPS)]
    GMaps[(fa:fa-map Google Maps SDK)]

    subgraph AppPokeMap ["📍 PokeMap (mobile-android-kotlin)"]
        UC01["Solicitar Permissão de GPS"]
        UC02["Obter Coordenadas Atuais"]
        UC03["Carregar Mapa Vetorial"]
        UC04["Renderizar Marcadores de Ginásio"]
        UC05["Calcular Raio de Desafio (< 50m)"]
    end

    Player --> UC01
    UC01 -->|Concedida| UC02
    UC02 --> GPS
    Player --> UC03
    UC03 --> GMaps
    GMaps --> UC04
    UC02 --> UC05
    UC04 --> UC05

4. Matriz de Rastreabilidade (RTM)

ID Requisito História de Usuário Artefato de Código Teste de Aceitação
RF-01 US-01 mobile-android-kotlin/app/.../MainActivity.kt testLocationPermissionFlow()
RF-02 US-02 mobile-android-kotlin/app/src/main/res/layout/activity_main.xml testSupportMapFragmentNotNull()
RF-03 US-02, US-05 mobile-android-kotlin/app/.../LocationService.kt testLocationRequestAccuracy()
RF-04 US-03 mobile-android-kotlin/app/.../MainActivity.kt testGymMarkersPlotted()
RF-05 US-04 mobile-android-kotlin/app/.../MainActivity.kt testProximityRadiusCalculation()

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

ℹ️ O trecho de código que ficava aqui não correspondia ao código do projeto e foi retirado. Consulte os arquivos em mobile-android-kotlin.

🚀 Como Executar no Laboratório

1. Configure a chave do Google Maps

Defina a variável MAPS_API_KEY no seu arquivo local.properties:

MAPS_API_KEY=sua_chave_aqui

2. Navegue até a subpasta do projeto e instale

cd catalogo_projetos/android_p09_pokemap_gps/mobile-android-kotlin
./gradlew installDebug

🏁 Matriz de Checkpoints de Conclusão

Checkpoint Meta Técnica Critério de Aceite Status
CP-01 Permissão de Localização Solicitação e concessão de GPS em tempo de execução PASS ✅
CP-02 Inicialização do Mapa Google Maps carregado sem erros de autenticação de chave PASS ✅
CP-03 Marcadores Customizados Ginásios exibidos no mapa com coordenadas geográficas válidas PASS ✅
CP-04 Cálculo de Proximidade Validação precisa do raio de 50 metros para liberação de combate PASS ✅
CP-05 Suíte de Testes Automatizados Testes de unidade de cálculo geodésico aprovados com 100% de sucesso PASS ✅