📚 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 07 — Spring Boot + React ➔ React Native

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

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

💡 “Construa interfaces com componentes e deixe o ecossistema complementar.”

Enquanto na Web tradicional montamos interfaces manipulando elementos HTML (<div>, <button>, <input>) renderizados através da árvore do Virtual DOM nos navegadores, no ecossistema mobile com React Native utilizamos o mesmo modelo mental de componentes e estados (useState, useEffect), porém renderizando componentes nativos reais de Android e iOS (<View>, <Text>, <TouchableOpacity>, <FlatList>) através do motor de layout Yoga Flexbox e empacotados com a produtividade do Expo.

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

Tanto a aplicação Web SPA em React quanto o cliente móvel em React Native operam como consumidores diretos da nossa Fonte Única da Verdade (SSOT): a API REST desenvolvida em Spring Boot na porta 8080, padronizada sob o contrato canônico { id, descricao, concluida }.

Por que a combinação React + React Native (Expo)?

• Mesmo Modelo Mental (Learn Once, Write Anywhere): Componentes funcionais, hooks modernos (useState, useCallback, useFocusEffect) e fluxo de dados unidirecional compartilhados entre Web e Mobile.
• Componentes Nativos Genuínos: Diferente de WebViews híbridas puras, o React Native renderiza widgets e controles nativos do sistema operacional mobile com fluidez a 60/120 FPS.
• Expo Framework: Conjunto completo de ferramentas que simplifica o desenvolvimento, hot reloading instantâneo e suporte a emuladores Android/iOS e teste em celulares físicos via Expo Go.
• Motor Yoga Flexbox: Posicionamento de tela responsivo baseado nas regras mundiais do Flexbox CSS aplicado nativamente no ecossistema mobile.
• Comunicação REST Desacoplada: Interação assíncrona robusta via biblioteca Axios configurada com detecção inteligente de ambiente.

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

Um dos aspectos cruciais do cliente móvel é a resolução dinâmica de rede para alcançar a API na máquina de desenvolvimento:

1. No Navegador Web / SPA: O app dispara requisições HTTP para http://localhost:8080/api/tarefas.
2. No Emulador Android (AVD): O emulador Android roda em uma máquina virtual isolada onde localhost representa o próprio celular emulado. Para alcançar a API que roda no computador, o serviço utiliza o alias de rede: \(\text{URL no Emulador Android} = \mathbf{http://10.0.2.2:8080/api/tarefas}\)
3. No Dispositivo Físico (Expo Go via Wi-Fi): Quando conectado na mesma rede sem fio, o app utiliza o IP privado do computador hospedeiro (ex: http://192.168.1.50:8080/api/tarefas).

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

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

• US-R01: Como usuário da aplicação, desejo visualizar minhas tarefas de forma clara com status atualizado e ordenação, para organizar minhas prioridades.
• US-R02: Como usuário da aplicação, desejo adicionar uma nova tarefa digitando sua descrição e acionando o botão de envio, recebendo feedback visual imediato.
• US-R03: Como usuário da aplicação, desejo alternar o status de conclusão tocando na caixa de seleção, visualizando a atualização instantânea e o texto tachado.
• US-R04: Como usuário da aplicação, desejo editar a descrição de uma tarefa existente através de formulário dedicado com validação de preenchimento.
• US-R05: Como usuário da aplicação, desejo excluir uma tarefa através de diálogo de confirmação nativo, prevenindo remoções 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 React / React Native"
        UC01["UC01: Listar Tarefas em FlatList"]
        UC02["UC02: Inserir Nova Tarefa via FAB"]
        UC03["UC03: Alternar Conclusão da Tarefa"]
        UC04["UC04: Editar Tarefa em Tela Própria"]
        UC05["UC05: Excluir Tarefa com Diálogo Nativo"]
    end

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

UC01: Listar Tarefas em FlatList

• Fluxo Principal:
  1. A tela HomeScreen carrega os dados invocando TaskService.getAll().
  2. O componente renderiza a lista virtualizada com FlatList.
  3. Se o usuário arrasta o topo da lista para baixo, o RefreshControl dispara onRefresh() para recarga instantânea.

UC02: Inserir Nova Tarefa via FAB

• Fluxo Principal:
  1. O usuário clica no botão flutuante + (FAB).
  2. O React Navigation navega até a tela TaskFormScreen.
  3. O usuário digita a descrição e clica em “Criar Tarefa”.
  4. O sistema valida que o texto não está em branco e envia POST /api/tarefas.
  5. Após o retorno 201 Created, o app retorna à tela inicial e atualiza a listagem.

UC03: Alternar Conclusão da Tarefa

• Fluxo Principal:
  1. O usuário toca na caixa de seleção de um cartão.
  2. O app despacha PATCH /api/tarefas/{id}/status com { "concluida": novoStatus }.
  3. O estado local da lista é atualizado de forma otimista/reativa e o texto ganha efeito tachado.

UC04: Editar Tarefa em Tela Própria

• Fluxo Principal:
  1. O usuário toca em “Editar” no cartão da tarefa.
  2. A tela TaskFormScreen é aberta com os parâmetros de rota { id: item.id }.
  3. Os dados da tarefa são recuperados via GET /api/tarefas/{id} e preenchem os campos.
  4. Ao clicar em “Atualizar Tarefa”, a API recebe PUT /api/tarefas/{id} e persiste as alterações.

UC05: Excluir Tarefa com Diálogo Nativo

• Fluxo Principal:
  1. O usuário clica no botão “Excluir”.
  2. O sistema exibe diálogo nativo via Alert.alert solicitando confirmação.
  3. Confirmada a operação, envia-se DELETE /api/tarefas/{id} e a tarefa desaparece da lista.

3.5. Matriz de Rastreabilidade (RTM)

🛠️ 4. Estrutura de Pastas da Parte 07

O projeto organiza-se em dois módulos front-end complementares consumindo a mesma API central:

fullstack_tarefas_07_spring_react/
├── assets/
│   ├── arquitetura_react_native_ecosystem.svg  ← Diagrama conceitual React Web para Mobile
│   └── fluxo_sincronizacao_expo_api.svg        ← Diagrama do ciclo de rede com Expo
├── web-react/                                   ← Web SPA em React 19 + Vite
│   ├── src/
│   │   ├── pages/
│   │   │   ├── HomePage.jsx                    ← Listagem com filtros e estilo moderno
│   │   │   └── TaskFormPage.jsx                ← Formulário com validação e foco
│   │   ├── services/
│   │   │   ├── api.js                          ← Axios configurado em localhost:8080
│   │   │   └── TaskService.js                  ← Métodos HTTP de CRUD de tarefas
│   │   ├── App.jsx                             ← Configuração de rotas com React Router
│   │   └── main.jsx                            ← Ponto de entrada React 19
│   ├── package.json
│   └── vite.config.js
├── mobile-reactnative/                                     ← Cliente Mobile com React Native + Expo
│   ├── src/
│   │   ├── screens/
│   │   │   ├── HomeScreen.js                   ← FlatList, RefreshControl e FAB
│   │   │   └── TaskFormScreen.js               ← Tela de formulário com Switch de status
│   │   └── services/
│   │       ├── api.js                          ← Resolução inteligente de host (10.0.2.2)
│   │       └── TaskService.js                  ← Cliente REST para tarefas
│   ├── App.js                                  ← Navegação em pilha (Stack Navigator)
│   ├── app.json                                ← Configuração do ecossistema Expo
│   ├── package.json                            ← Dependências React Native e Expo
│   └── README.md                               ← Guia de execução mobile
└── index.md                                    ← Este Guia Padrão Ouro Educacional

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

5.1. Resolução Dinâmica de Rede no React Native (mobile-reactnative/src/services/api.js)

O serviço detecta a plataforma em tempo de execução via Platform.OS:

import axios from 'axios';
import { Platform } from 'react-native';

const getBaseUrl = () => {
    if (Platform.OS === 'android') {
        return 'http://10.0.2.2:8080/api';
    }
    return 'http://localhost:8080/api';
};

const api = axios.create({
    baseURL: getBaseUrl(),
    headers: {
        'Content-Type': 'application/json',
    },
    timeout: 10000,
});

export default api;

5.2. Lista Virtualizada e Pull-to-Refresh (mobile-reactnative/src/screens/HomeScreen.js)

A tela principal do cliente móvel implementa FlatList com RefreshControl:

<FlatList
    data={tasks}
    keyExtractor={item => item.id.toString()}
    renderItem={renderItem}
    refreshControl={
        <RefreshControl
            refreshing={refreshing}
            onRefresh={onRefresh}
            colors={['#6366f1']}
        />
    }
    ListEmptyComponent={
        <View style={styles.emptyContainer}>
            <Text style={styles.emptyTitle}>Nenhuma tarefa encontrada</Text>
            <Text style={styles.emptySub}>Puxe para atualizar ou toque no botão + para adicionar.</Text>
        </View>
    }
    contentContainerStyle={{ paddingBottom: 80 }}
/>

🚀 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 o modelo { id, descricao, concluida }.

2. Executar o Frontend Web React Tradicional

Em outro terminal:

cd catalogo_projetos/fullstack_tarefas_07_spring_react/frontend
npm install
npm run dev

✅ Checkpoint: Abra http://localhost:5173 no navegador e valide a listagem, os filtros por status, a criação e a exclusão de tarefas.

3. Executar o Cliente Mobile React Native com Expo

Em um terceiro terminal:

cd catalogo_projetos/fullstack_tarefas_07_spring_react/mobile
npm install
npx expo start

✅ Checkpoint: Pressione a para iniciar no emulador Android já aberto. Teste o gesto de pull-to-refresh, a alternância de status tocando no checkbox e a adição de tarefas pelo FAB (+).

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

🧯 7. Tabela de Troubleshooting

🔮 8. Próxima Etapa: Parte 08 — Spring Boot + Angular Standalone ➔ Ionic Framework

Com a equivalência React ➔ React Native concluída com sucesso, avançaremos para o terceiro vértice da trilha:

• Parte 08 (fullstack_tarefas_08_spring_angular): Transição de Angular Standalone para Ionic Framework + Capacitor, com a filosofia “Use um framework completo com arquitetura definida”.