📚 Pré-requisitos Teóricos: este projeto consome os serviços da Parte 01 — Spring Boot API e a infraestrutura conteinerizada da Parte 05 — Docker + PostgreSQL.

📝 Projeto Lista de Tarefas 08 — Spring Boot + Angular ➔ Ionic Framework

Seja muito bem-vindo à Parte 08 da série de projetos Lista de Tarefas!

Nesta etapa prática, você aprenderá a dominar a terceira grande trilha de equivalência entre desenvolvimento Web e Mobile Híbrido / Cross-platform:

💡 “Use um framework completo com arquitetura definida.”

Enquanto no Angular tradicional para desktop desenvolvemos interfaces baseadas em tabelas, formulários convencionais e navegação em tela cheia, o ecossistema móvel exige uma experiência tátil rica: gestos de deslize (swipe actions), puxar para atualizar (pull-to-refresh), diálogos nativos modais e notificações toast. O Ionic Framework sobre o Capacitor permite que toda a elegância da arquitetura Angular (TypeScript, injeção de dependências e programação reativa com RxJS) seja transferida diretamente para o smartphone, gerando pacotes nativos para Android (APK/AAB) e iOS (IPA) com uma única base de código.

🗺️ 1. Visão Geral da Arquitetura & Papel no Ecossistema

Tanto o aplicativo Web SPA em Angular quanto o cliente móvel híbrido em Ionic operam consumindo a nossa Fonte Única da Verdade (SSOT): a API REST Spring Boot na porta 8080, conectada ao banco de dados relacional e padronizada com o modelo canônico { id, descricao, concluida }.

Por que a combinação Angular + Ionic Framework?

• TypeScript & Tipagem Rigorosa: Interfaces e modelos de domínio consistentes entre serviços, controllers e visualizações.
• Componentes Standalone: Arquitetura moderna do Angular, dispensando a complexidade legada de NgModule e simplificando rotas e injeção com provideIonicAngular().
• Componentes Móveis Especializados: O Ionic entrega componentes prontos com fidelidade Material Design e iOS nativo (ion-item-sliding, ion-refresher, ion-checkbox, ion-badge, ion-spinner).
• Capacitor como Runtime Moderno: A evolução do Apache Cordova: rápido, leve, compatível com as APIs nativas mais modernas e com suporte a cleartext: true para homologação local.
• Programação Reativa com RxJS: Gerenciamento assíncrono robusto de requisições HTTP e fluxos de dados com Observables.

⚡ 2. Fluxo Reativo, Gestos Mobile e Resolução de Plataforma

No desenvolvimento mobile híbrido com Capacitor, a resolução de endereço de rede depende do ambiente de execução do aplicativo:

1. No Navegador Web / PWA: O app faz chamadas HTTP diretamente para http://localhost:8080/api/tarefas.
2. No Emulador Android (AVD): O emulador opera em uma rede virtual isolada onde localhost refere-se ao próprio dispositivo virtual. O Capacitor detecta a plataforma via Capacitor.isNativePlatform() e redireciona automaticamente para o gateway da máquina hospedeira: \(\text{URL no Emulador Android} = \mathbf{http://10.0.2.2:8080/api/tarefas}\)
3. No Dispositivo Físico (Wi-Fi): Configura-se o IP privado da máquina de desenvolvimento (ex: http://192.168.1.100:8080/api/tarefas).

📑 3. Engenharia de Software & Especificação de Requisitos

3.1. Histórias de Usuário (Web & Mobile Ionic)

• US-I01: Como usuário móvel, desejo visualizar minha lista de tarefas de forma clara com badges de status, para acompanhar o progresso das minhas atividades diárias.
• US-I02: Como usuário móvel, desejo adicionar uma nova tarefa digitando no campo de entrada e tocando em “Adicionar”, recebendo feedback imediato via notificação toast.
• US-I03: Como usuário móvel, desejo alternar o status de uma tarefa tocando diretamente em sua caixa de seleção, visualizando a atualização instantânea e o texto riscado.
• US-I04: Como usuário móvel, desejo deslizar um item para o lado (swipe left) para revelar o botão de edição rápida em diálogo modal nativo.
• US-I05: Como usuário móvel, desejo deslizar um item para excluir a tarefa com diálogo de confirmação, garantindo segurança contra toques acidentais.

3.2. Requisitos Funcionais (RF)

3.3. Requisitos Não-Funcionais (RNF)

3.4. Casos de Uso do Sistema

flowchart LR
    User(("👤 Usuário Web / Mobile"))

    subgraph "Aplicação Angular / Ionic"
        UC01["UC01: Listar Tarefas com Pull-to-Refresh"]
        UC02["UC02: Inserir Nova Tarefa"]
        UC03["UC03: Alternar Status via Checkbox"]
        UC04["UC04: Editar Tarefa com Swipe Action"]
        UC05["UC05: Excluir Tarefa com Swipe Action"]
    end

    User --> UC01
    User --> UC02
    User --> UC03
    User --> UC04
    User --> UC05

UC01: Listar Tarefas com Pull-to-Refresh

• Fluxo Principal:
  1. A página inicializa ou o usuário arrasta o topo da lista para baixo.
  2. O componente invoca tarefaService.listar().
  3. O ion-refresher exibe o indicador visual circular.
  4. O array reativo de tarefas é atualizado e o indicador é finalizado com event.target.complete().

UC02: Inserir Nova Tarefa

• Fluxo Principal:
  1. O usuário digita a descrição no card superior e clica no botão “Adicionar”.
  2. Valida-se que o campo não está em branco.
  3. Dispara-se requisição POST /api/tarefas com { "descricao": "...", "concluida": false }.
  4. A nova tarefa é inserida no topo da lista e o ToastController confirma a ação.

UC03: Alternar Status via Checkbox

• Fluxo Principal:
  1. O usuário toca na caixa de seleção (ion-checkbox).
  2. O serviço aciona PATCH /api/tarefas/{id}/status.
  3. A resposta do backend confirma a alteração e atualiza os contadores de tarefas.

UC04: Editar Tarefa com Swipe Action

• Fluxo Principal:
  1. O usuário desliza o item para a esquerda, revelando o botão azul de edição.
  2. O sistema fecha a aba deslizante e apresenta um AlertController nativo com campo de texto.
  3. Ao salvar, a requisição PUT /api/tarefas/{id} persiste o novo texto na API.

UC05: Excluir Tarefa com Swipe Action

• Fluxo Principal:
  1. O usuário desliza o item e clica no botão vermelho de lixeira.
  2. Um diálogo de confirmação é exibido.
  3. Confirmada a operação, envia-se DELETE /api/tarefas/{id} e exibe-se um toast informativo.

3.5. Matriz de Rastreabilidade (RTM)

🛠️ 4. Estrutura de Pastas da Parte 08

O projeto está dividido entre a aplicação Web SPA tradicional e o cliente móvel híbrido:

fullstack_tarefas_08_spring_angular/
├── assets/
│   ├── arquitetura_angular_ionic_ecosystem.svg  ← Diagrama conceitual Angular para Ionic
│   └── fluxo_gestos_ionic_api.svg               ← Diagrama de gestos móveis e REST
├── web-angular/                                    ← Web SPA Standalone (Angular 20)
│   ├── src/
│   │   ├── app/
│   │   │   ├── components/
│   │   │   │   ├── tarefa-form/                 ← Formulário Web de criação/edição
│   │   │   │   └── tarefa-list/                 ← Tabela responsiva de listagem
│   │   │   ├── models/tarefa.model.ts           ← Interface { id, descricao, concluida }
│   │   │   └── services/tarefa.service.ts       ← Cliente HttpClient (Porta 8080)
│   │   └── main.ts                              ← Bootstrap Angular Standalone
│   └── package.json
├── mobile-ionic/                                ← Cliente Mobile Híbrido (Ionic 8 + Capacitor)
│   ├── capacitor.config.json                    ← Configuração com cleartext: true
│   ├── ionic.config.json                        ← Integração Ionic CLI
│   ├── package.json                             ← Dependências Ionic, Angular e Capacitor
│   └── src/
│       ├── app/
│       │   ├── models/tarefa.model.ts           ← Modelo unificado com a API central
│       │   ├── pages/tarefas/
│       │   │   ├── tarefas.page.ts              ← Lógica mobile, gestos e diálogos
│       │   │   ├── tarefas.page.html            ← Template com ion-item-sliding e refresher
│       │   │   └── tarefas.page.scss            ← Estilização mobile refinada
│       │   ├── services/tarefa.service.ts       ← Detecção de host (10.0.2.2 vs localhost)
│       │   ├── app.component.ts                 ← Container ion-app e router-outlet
│       │   └── app.routes.ts                    ← Roteamento do app
│       ├── theme/variables.css                  ← Paleta de cores do Ionic
│       └── main.ts                              ← provideIonicAngular e provideHttpClient
└── index.md                                     ← Guia Didático Padrão Ouro Educacional

💻 5. Implementação Prática & Destaques de Código

5.1. Resolução Dinâmica de Rede no Ionic (mobile-ionic/src/app/services/tarefa.service.ts)

O serviço detecta em tempo de execução a plataforma nativa do Capacitor:

import { Injectable, inject } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { Observable } from 'rxjs';
import { Capacitor } from '@capacitor/core';
import { Tarefa } from '../models/tarefa.model';

@Injectable({
  providedIn: 'root'
})
export class TarefaService {
  private http = inject(HttpClient);

  private get baseUrl(): string {
    const isNative = Capacitor.isNativePlatform();
    const platform = Capacitor.getPlatform();
    if (isNative && platform === 'android') {
      return 'http://10.0.2.2:8080/api/tarefas';
    }
    return 'http://localhost:8080/api/tarefas';
  }

  listar(): Observable<Tarefa[]> {
    return this.http.get<Tarefa[]>(this.baseUrl);
  }

  criar(tarefa: Tarefa): Observable<Tarefa> {
    return this.http.post<Tarefa>(this.baseUrl, tarefa);
  }

  atualizar(id: number, tarefa: Tarefa): Observable<Tarefa> {
    return this.http.put<Tarefa>(`${this.baseUrl}/${id}`, tarefa);
  }

  alternarStatus(id: number, concluida: boolean): Observable<Tarefa> {
    return this.http.patch<Tarefa>(`${this.baseUrl}/${id}/status`, { concluida });
  }

  excluir(id: number): Observable<void> {
    return this.http.delete<void>(`${this.baseUrl}/${id}`);
  }
}

5.2. Gestos de Swipe no Template Ionic (tarefas.page.html)

A experiência móvel tira proveito do componente ion-item-sliding:

<ion-list lines="full">
  <ion-item-sliding *ngFor="let tarefa of tarefasFiltradas" #slidingItem>
    <ion-item class="tarefa-item" [class.concluida]="tarefa.concluida">
      <ion-checkbox
        slot="start"
        [checked]="tarefa.concluida"
        (ionChange)="alternarStatus(tarefa)"
      ></ion-checkbox>
      <ion-label>
        <h2>{{ tarefa.descricao }}</h2>
        <p>ID #{{ tarefa.id }} · Deslize para opções</p>
      </ion-label>
      <ion-badge slot="end" [color]="tarefa.concluida ? 'success' : 'warning'">
        {{ tarefa.concluida ? 'Concluída' : 'Pendente' }}
      </ion-badge>
    </ion-item>

    <ion-item-options side="end">
      <ion-item-option color="primary" (click)="abrirEdicao(tarefa, slidingItem)">
        <ion-icon slot="icon-only" name="create-outline"></ion-icon>
      </ion-item-option>
      <ion-item-option color="danger" (click)="confirmarExclusao(tarefa, slidingItem)">
        <ion-icon slot="icon-only" name="trash-outline"></ion-icon>
      </ion-item-option>
    </ion-item-options>
  </ion-item-sliding>
</ion-list>

🚀 6. Roteiro de Execução e Homologação

1. Iniciar a API Spring Boot Central (SSOT)

Abra um terminal na pasta do backend oficial:

cd catalogo_projetos/fullstack_tarefas_01_spring_api
./mvnw spring-boot:run

✅ Checkpoint: Acesse http://localhost:8080/api/tarefas no navegador e certifique-se de receber a lista em formato JSON com as propriedades id, descricao e concluida.

2. Executar o Frontend Web Angular Tradicional

Em outro terminal:

cd catalogo_projetos/fullstack_tarefas_08_spring_angular/frontend
npm install
npm start

✅ Checkpoint: Abra http://localhost:4200 e teste o cadastro e a listagem das tarefas na interface Web.

3. Executar o Cliente Mobile Ionic no Navegador

Em um terceiro terminal:

cd catalogo_projetos/fullstack_tarefas_08_spring_angular/mobile-ionic
npm install
npm start

✅ Checkpoint: Acesse http://localhost:4200 (ou a porta atribuída pelo Ionic CLI), abra o Device Mode nas ferramentas do desenvolvedor (F12) e teste os gestos de arrasto e os componentes Ionic.

4. Sincronizar e Rodar no Emulador Android

Com o Android Studio e o emulador instalados:

npm run build
npx cap sync android
npx cap open android

No Android Studio, clique em Run ‘app’ (ícone do play verde). O aplicativo inicializará no emulador conectando-se ao host via http://10.0.2.2:8080/api/tarefas.

5. Matriz de Homologação & Checkpoints de Validação

🧯 7. Tabela de Troubleshooting

🏁 8. Conclusão da Tríade de Equivalências Web ➔ Mobile Cross-Platform

Com a entrega da Parte 08 (Angular ➔ Ionic Framework), consolidamos a trilha completa de arquitetura híbrida e cross-platform:

• Parte 06: Vue.js ➔ Quasar Framework (Componentes fáceis de entender com uma estrutura progressiva)
• Parte 07: React ➔ React Native (Construa interfaces com componentes e deixe o ecossistema complementar)
• Parte 08: Angular ➔ Ionic Framework (Use um framework completo com arquitetura definida)

👉 Próximo Passo: Parte 09 — Evolução Arquitetural Desktop: De Swing para JavaFX Moderno

Avançamos a seguir para a modernização da engenharia desktop corporativa em Java: aprendendo como e por que o mercado migrou do Swing clássico para JavaFX moderno com FXML, folhas de estilo CSS, propriedades reativas e arquitetura MVC rigorosa!