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

💾 P06: Meus Jogos Favoritos (Catálogo Offline com Room)

v1.0 — Android Jetpack, Kotlin, Room Database (SQLite), Padrão DAO, Coroutines e StateFlow Reativo

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

• P05: Quiz Game com Cronômetro Decrescente
• ➡️ P06 (este): Catálogo Offline com Room Database & Coroutines
• P07: Master Pokédex com Retrofit 2 & REST API
• P08: Batalha Scanner com CameraX & QR Code
• P09: PokeMap com Google Maps & GPS

🏛️ Visão Geral & Arquitetura Visual

O projeto Meus Jogos Favoritos aborda a camada de persistência estruturada recomendada pelo Google no ecossistema Android moderno: o Room Persistence Library. A aplicação implementa uma camada de abstração elegante sobre o SQLite relacional, com validação de consultas SQL em tempo de compilação, operações assíncronas em segundo plano com Kotlin Coroutines (Dispatchers.IO) e fluxo de dados reativo contínuo via Flow / StateFlow.

📁 Estrutura de Pastas Anti-Colisão

Os modelos, DAOs, base de dados e componentes de interface estão organizados na subpasta canônica mobile-android-kotlin/:

catalogo_projetos/android_p06_jogos_room/
├── assets/
│   └── arquitetura_jogos_room.svg
├── mobile-android-kotlin/
│   ├── app/
│   │   ├── src/
│   │   │   └── main/
│   │   │       ├── java/br/com/curso/jogosroom/
│   │   │       │   ├── data/
│   │   │       │   │   ├── JogoEntity.kt
│   │   │       │   │   ├── JogoDao.kt
│   │   │       │   │   └── AppDatabase.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: Mapear entidade relacional @Entity(tableName = "jogos") com chave primária auto-incremental.
• RF-02: Definir interface @Dao com métodos anotados @Insert, @Delete e consultas @Query.
• RF-03: Emitir atualizações de lista através de Flow<List<JogoEntity>> observado pela ViewModel.
• RF-04: Configurar classe abstrata @Database com padrão Singleton thread-safe para acesso ao Room.
• RF-05: Disponibilizar formulário modal para inclusão de novos títulos com validação de campos.

Requisitos Não-Funcionais (RNF)

• RNF-01 (Prevenção de ANR): Proibição estrita de chamadas síncronas de banco na Main Thread do Android.
• RNF-02 (Integridade Transacional): Suporte a transações ACID automáticas fornecidas pelo SQLite.
• RNF-03 (Performance de Leitura): Tempo de resposta para consultas de até 1.000 itens inferior a 25 milissegundos.
• RNF-04 (Migrações Seguras): Definição de estratégia de migração (fallbackToDestructiveMigration para dev).
• RNF-05 (Compatibilidade): Suporte operacional desde Android 5.0 (API 21) até Android 14 (API 34).

3. Diagrama de Casos de Uso

flowchart TD
    User([fa:fa-user Usuário / Colecionador])
    Room[(fa:fa-database Room SQLite)]

    subgraph AppRoom ["💾 Catálogo de Jogos (mobile-android-kotlin)"]
        UC01["Cadastrar Novo Jogo"]
        UC02["Listar Jogos em Tempo Real"]
        UC03["Filtrar por Plataforma"]
        UC04["Excluir Registro de Jogo"]
        UC05["Consultar Estatísticas Locais"]
    end

    User --> UC01
    User --> UC02
    User --> UC03
    User --> UC04
    UC01 --> Room
    Room -.->|Flow| UC02
    UC04 --> Room

4. Matriz de Rastreabilidade (RTM)

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

📄 mobile-android-kotlin/app/src/main/java/br/com/curso/colecaojogos/data/local/JogoDatabase.kt (arquivo real do projeto)

package br.com.curso.colecaojogos.data.local

import android.content.Context
import androidx.room.*
import kotlinx.coroutines.flow.Flow

// 1. A TABELA (Entity)
@Entity(tableName = "jogos")
data class Jogo(
    @PrimaryKey(autoGenerate = true) val id: Int = 0,
    val nome: String,
    val plataforma: String
)

// 2. O CONTROLE REMOTO (DAO)
@Dao
interface JogoDao {
    @Insert
    suspend fun inserir(jogo: Jogo)

    @Query("SELECT * FROM jogos ORDER BY id DESC")
    fun listarTodos(): Flow<List<Jogo>>

    @Delete
    suspend fun deletar(jogo: Jogo)
}

// 3. A CENTRAL (Database)
@Database(entities = [Jogo::class], version = 1)
abstract class JogoDatabase : RoomDatabase() {
    abstract fun jogoDao(): JogoDao

    companion object {
        @Volatile
        private var INSTANCE: JogoDatabase? = null

        fun getDatabase(context: Context): JogoDatabase {
            return INSTANCE ?: synchronized(this) {
                val instance = Room.databaseBuilder(
                    context.applicationContext,
                    JogoDatabase::class.java,
                    "jogo_database"
                ).build()
                INSTANCE = instance
                instance
            }
        }
    }
}

🚀 Como Executar no Laboratório

1. Navegue até a subpasta do projeto

cd catalogo_projetos/android_p06_jogos_room/mobile-android-kotlin

2. Compile e execute os testes unitários do Room

./gradlew test
./gradlew connectedAndroidTest

🏁 Matriz de Checkpoints de Conclusão