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

⚔️ P20: Alliance Battle (FSM & Testes JUnit 5)

v1.0 — Android Nativo, Kotlin, Máquina de Estados Finita (FSM), Sealed Interfaces, Arquitetura MVI e Testes Automatizados com JUnit 5 e MockK

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

• P19: Banco de Wakanda com MVVM & Room
• ➡️ P20 (este): Alliance Battle com FSM & Testes JUnit 5
• P21: Duelo Jedi com Física 2D & Colisão

🏛️ Visão Geral & Arquitetura Visual

O projeto Alliance Battle foca no controle rigoroso e determinístico de lógica de negócios em sistemas móveis complexos através do padrão de Máquina de Estados Finita (Finite State Machine - FSM) com arquitetura unidirecional inspirada em MVI. Utilizando sealed interfaces do Kotlin para modelar estados e intenções de combate de forma estritamente exaustiva pelo compilador (when sem ramo else), a aplicação implementa uma rodada tática de turnos de RPG, cobrindo todos os fluxos com suítes de testes unitários avançados utilizando JUnit 5 e MockK.

📁 Estrutura de Pastas Anti-Colisão

Os motores de estado, testes unitários e telas residem na subpasta canônica mobile-android-kotlin/:

catalogo_projetos/android_p20_batalha_states/
├── assets/
│   ├── mockup_batalha_fluxo.svg
│   ├── screenshot_01_batalha_idle.svg
│   ├── screenshot_02_batalha_combate.svg
│   └── screenshot_03_batalha_vitoria.svg
├── mobile-android-kotlin/
│   ├── app/
│   │   ├── src/
│   │   │   ├── main/
│   │   │   │   ├── java/br/com/curso/alliancebattle/
│   │   │   │   │   ├── state/
│   │   │   │   │   │   ├── BattleState.kt
│   │   │   │   │   │   └── BattleIntent.kt
│   │   │   │   │   ├── engine/
│   │   │   │   │   │   └── BattleStateMachine.kt
│   │   │   │   │   └── MainActivity.kt
│   │   │   │   └── res/
│   │   │   └── test/
│   │   │       └── java/br/com/curso/alliancebattle/
│   │   │           └── BattleStateMachineTest.kt
│   │   └── 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: Modelar estados de combate como sealed interface BattleState (Idle, PlayerTurn, EnemyTurn, Victory, Defeat).
• RF-02: Modelar intenções de usuário como sealed interface BattleIntent (Attack, CastSpell, Defend, Restart).
• RF-03: Implementar redutor puro reduce(currentState, intent): BattleState sem efeitos colaterais.
• RF-04: Calcular dano com base em atributos de ataque, defesa e fator de chance crítica.
• RF-05: Transicionar automaticamente para BattleState.Victory ou BattleState.Defeat ao zerar o HP.

Requisitos Não-Funcionais (RNF)

• RNF-01 (Previsibilidade Absoluta): Estados 100% imutáveis (val) sem possibilidade de mutação concorrente.
• RNF-02 (Testabilidade sem Android): Testes unitários executados em JVM pura em milissegundos sem emulador.
• RNF-03 (Exaustividade Kotlin): Proibição do uso de else em blocos when sobre interfaces seladas.
• RNF-04 (Compatibilidade de Versão): Suporte estável desde Android API 21 até Android API 34.
• RNF-05 (Cobertura de Testes): Cobertura de código superior a 90% no módulo de domínio da FSM.

3. Diagrama de Casos de Uso

flowchart TD
    Player([fa:fa-user Jogador])
    FSM[(fa:fa-arrows-split-up-and-left Máquina de Estados FSM)]
    AI[(fa:fa-robot IA do Inimigo)]

    subgraph AppBattle ["⚔️ Alliance Battle (mobile-android-kotlin)"]
        UC01["Emitir Intenção de Ataque"]
        UC02["Processar Redutor de Estado"]
        UC03["Executar Turno do Inimigo"]
        UC04["Avaliar Condição de Término"]
        UC05["Reiniciar Batalha"]
    end

    Player --> UC01
    UC01 --> FSM
    FSM --> UC02
    UC02 -->|Dano Calculado| AI
    AI --> UC03
    UC03 --> FSM
    FSM --> UC04
    UC04 -->|HP Zerado| Player
    Player --> UC05
    UC05 --> FSM

4. Matriz de Rastreabilidade (RTM)

🛠️ Implementação Guiada (BattleStateMachine.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. Navegue até a subpasta do projeto

cd catalogo_projetos/android_p20_batalha_states/mobile-android-kotlin

2. Execute a suíte de testes JUnit 5 na JVM

./gradlew test

🏁 Matriz de Checkpoints de Conclusão