Persistência local e cache offline

No fim desta aula consegues

• Escolher onde guardar cada tipo de dado: preferências, base de dados, ficheiros ou armazenamento seguro.
• Explicar a sandbox da app, o que sobrevive a atualizações e o que vai para o backup.
• Justificar porque um token nunca vai para shared_preferences.
• Implementar um repository cache-first com drift e mostrar a idade dos dados.
• Deixar a app a funcionar em modo avião com os dados que já tinha.

Onde guardar o quê

Para os testes: preferências para valores pequenos, SQLite para dados que se consultam, secure storage para segredos.

Sandbox: onde ficam os ficheiros da app

• Cada app tem a sua pasta privada. Outra app não a lê; o utilizador não a vê sem root. Android: /data/data/<package>/; iOS: Documents/, Library/, tmp/.
• path_provider abstrai isto: getApplicationDocumentsDirectory() persiste e vai para o backup; getApplicationSupportDirectory() persiste sem aparecer ao utilizador; getTemporaryDirectory() pode ser limpa pelo sistema.
• Atualizações mantêm tudo menos o temporário. Desinstalar apaga tudo, com uma exceção: o Keychain do iOS fica.
• Backup: o iCloud copia Documents/; o Android Auto Backup copia até 25 MB. Cache e tokens devem ficar de fora (android:fullBackupContent, isExcludedFromBackup).
• Exemplo: um jogo guarda o progresso em Documents (vai no backup) e as texturas descarregadas em Support (não vai, descarrega outra vez).

Para os testes: Documents persiste e vai no backup; tmp pode desaparecer a qualquer momento.

Keychain e Keystore: porque um token nunca vai para preferências

• shared_preferences é um ficheiro XML (Android) ou plist (iOS) em texto. Num telemóvel com root lê-se com cat; nos backups vai em claro.
• Keychain (iOS): cifrado com uma chave ligada ao hardware (Secure Enclave). Pode exigir o dispositivo desbloqueado. Sobrevive à desinstalação: cuidado com sessões fantasma.
• Keystore (Android): as chaves vivem em hardware (TEE ou StrongBox) e nunca saem. flutter_secure_storage cifra os valores com AES e guarda a chave AES no Keystore.
• Regra: token, refresh token, chaves do utilizador vão para secure storage. Nunca para preferências, nunca para a base de dados em claro.
• Limite: quem tem o telemóvel desbloqueado tem acesso à app. Protege contra backups, outras apps, e ferramentas de extração.

Para os testes: um token nunca vai para shared_preferences; vai para Keychain ou Keystore via flutter_secure_storage.

Cache-first, network-first, invalidação e migrações

• Invalidação por tempo: guarda obtidoEm e compara: previsão válida 30 min, avisos 5 min, localidades 24 h.
• Migrações: a versão 1.2 da app muda a tabela, mas há utilizadores na 1.0 com a base antiga. schemaVersion + MigrationStrategy no drift; nunca apagar dados do utilizador sem aviso.

Para os testes: cache-first mostra rápido e atualiza depois; network-first garante dados frescos; a invalidação por tempo decide quando a cache expira.

Tamanho, limpeza e o botão "Limpar dados"

• Não há limite fixo, mas o sistema mostra "Armazenamento: 480 MB" nas definições e o utilizador limpa. No iOS, tmp/ é apagado sob pressão de espaço.
• Ordem de grandeza: preferências em KB, base de dados em MB, imagens em cache com limite (cached_network_image: 200 itens ou 7 dias).
• Limpeza própria: apagar previsões com mais de 7 dias, opção "Limpar cache" nas definições.
• "Limpar dados" no Android apaga tudo, incluindo o secure storage. No iOS só desinstalando, e o Keychain fica.
• A app tem de arrancar bem com tudo vazio: é o primeiro arranque outra vez. Se falha sem cache, o erro é da app.

Para os testes: a app tem de funcionar depois de o utilizador limpar os dados, exatamente como no primeiro arranque.

Repositório da aula

git clone https://github.com/pdm-daw-2026/pdm-aula-16.git
cd pdm-aula-16/starter
flutter pub get
flutter run

• starter/ é a app resiliente da aula 14 com shared_preferences, drift, drift_flutter e flutter_secure_storage já no pubspec.yaml, TODOs de 1 a 5 e testes a falhar.
• solucao/ é o estado final: a app funciona em modo avião e diz há quanto tempo os dados foram obtidos.
• O drift gera código: dart run build_runner build depois de mexer nas tabelas. O starter já traz o ficheiro gerado.

1. shared_preferences: unidade, tema, última localidade

class Definicoes {
  Definicoes(this._prefs);
  final SharedPreferences _prefs;

  static Future<Definicoes> carregar() async =>
      Definicoes(await SharedPreferences.getInstance());

  bool get usaFahrenheit => _prefs.getBool('usaFahrenheit') ?? false;
  ThemeMode get tema => ThemeMode.values.byName(_prefs.getString('tema') ?? 'system');
  int? get ultimaLocalidadeId => _prefs.getInt('ultimaLocalidadeId');

  Future<void> guardarUnidade({required bool fahrenheit}) =>
      _prefs.setBool('usaFahrenheit', fahrenheit);
  Future<void> guardarTema(ThemeMode modo) => _prefs.setString('tema', modo.name);
  Future<void> guardarUltimaLocalidade(int id) => _prefs.setInt('ultimaLocalidadeId', id);
}

// main.dart: carregar antes do runApp, para o tema estar certo no primeiro frame
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  final definicoes = await Definicoes.carregar();
  runApp(Provider.value(value: definicoes, child: const TempoApp()));
}

1. Preferências: o que interessa

• Chave-valor com tipos simples: bool, int, double, String, List<String>. Nada de JSON grande aqui.
• Leitura síncrona depois do getInstance(); escrita assíncrona. Por isso carregamos antes do runApp: o tema tem de estar certo no primeiro frame.
• WidgetsFlutterBinding.ensureInitialized() é obrigatório antes de qualquer plugin no main.
• Enums guardam-se pelo name e lêem-se com values.byName. Nunca pelo índice: reordenar o enum partia as preferências guardadas.
• No starter, DefinicoesNotifier envolve esta classe e chama notifyListeners para a UI reagir. A versão 2.3+ do package tem também SharedPreferencesWithCache; a API antiga continua a funcionar.

2. drift: a tabela de previsões

import 'package:drift/drift.dart';
import 'package:drift_flutter/drift_flutter.dart';

part 'base_dados.g.dart';

class Previsoes extends Table {
  IntColumn get localidadeId => integer()();
  TextColumn get json => text()();
  DateTimeColumn get obtidoEm => dateTime()();

  @override
  Set<Column> get primaryKey => {localidadeId};
}

@DriftDatabase(tables: [Previsoes])
class BaseDados extends _$BaseDados {
  BaseDados() : super(driftDatabase(name: 'tempo_acores'));

  @override
  int get schemaVersion => 1;
}

dart run build_runner build --delete-conflicting-outputs

2. drift: inserir, ler, apagar

extension PrevisoesCache on BaseDados {
  Future<Previsao?> lerPrevisao(int localidadeId) async {
    final linha = await (select(previsoes)
          ..where((p) => p.localidadeId.equals(localidadeId)))
        .getSingleOrNull();
    if (linha == null) return null;
    return Previsao.fromJson(jsonDecode(linha.json) as Map<String, dynamic>)
        .copyWith(obtidoEm: linha.obtidoEm);
  }

  Future<void> guardarPrevisao(Previsao p) =>
      into(previsoes).insertOnConflictUpdate(PrevisoesCompanion.insert(
        localidadeId: p.localidadeId,
        json: jsonEncode(p.toJson()),
        obtidoEm: DateTime.now(),
      ));

  Future<int> apagarAntigas({Duration maxIdade = const Duration(days: 7)}) =>
      (delete(previsoes)
            ..where((p) => p.obtidoEm.isSmallerThanValue(DateTime.now().subtract(maxIdade))))
          .go();
}

2. Base de dados: o que interessa

• Uma tabela por tipo de cache, com a chave natural (localidadeId) como chave primária e insertOnConflictUpdate para "guardar ou substituir".
• Guardar o JSON inteiro numa coluna é pragmático para cache: a estrutura da previsão não interessa ao SQL, só a chave e a data.
• O drift gera previsoes, PrevisoesCompanion e os tipos das colunas. Um erro de nome de coluna é erro de compilação, não de runtime como no sqflite.
• obtidoEm é o que permite dizer "de há 12 min" e invalidar: sem ele a cache é eterna.
• Quando mudares a tabela: schemaVersion: 2 e uma MigrationStrategy com onUpgrade. Nunca apagar a base para "resolver".

3. Repository cache-first

class PrevisaoRepositoryCache implements PrevisaoRepository {
  PrevisaoRepositoryCache(this._api, this._db);
  final PrevisaoApiDataSource _api;   // Future<Previsao> previsao(int id), da aula 12
  final BaseDados _db;
  static const validade = Duration(minutes: 30);

  @override
  Stream<Previsao> previsao(int localidadeId) async* {
    final emCache = await _db.lerPrevisao(localidadeId);
    if (emCache != null) yield emCache;                       // 1. mostra já o que há

    final valida = emCache != null &&
        DateTime.now().difference(emCache.obtidoEm) < validade;
    if (valida) return;                                       // 2. ainda fresca: fica

    try {
      final fresca = await _api.previsao(localidadeId);       // 3. vai à rede
      await _db.guardarPrevisao(fresca);
      yield fresca.copyWith(obtidoEm: DateTime.now());
    } catch (_) {
      if (emCache == null) rethrow;                           // sem cache e sem rede: erro
    }
  }
}

3. Cache-first: o que interessa

• O repository devolve um Stream porque pode emitir duas vezes: a cache logo, os dados frescos depois. Com Future só havia uma resposta.
• async* e yield tornam isto legível: é código sequencial que emite valores pelo caminho.
• Se a cache é recente, não há pedido de rede. É aqui que a invalidação por tempo vive, não na UI.
• Falha de rede com cache: engole-se e o utilizador fica com dados antigos e a hora. Falha de rede sem cache: erro, como na aula 14.
• O notifier consome o stream com await for e notifica a cada emissão:

Future<void> carregar(int id) async {
  try {
    await for (final p in _repo.previsao(id)) {
      estado = Dados(p, obtidoEm: p.obtidoEm);
      notifyListeners();
    }
  } catch (e) {
    if (estado is! Dados) estado = Erro(mensagemPara(e));
    notifyListeners();
  }
}

4. Modo avião ligado: a app continua a mostrar dados

1. Com rede, abre a previsão de duas localidades. Confirma no log que foram guardadas (guardarPrevisao chamado duas vezes).
2. Liga o modo avião. Fecha a app com swipe (não só o botão home) e abre de novo.
3. As duas localidades mostram os dados com "de há X min". Uma terceira, nunca aberta, mostra o erro humano "Sem ligação", não um crash.
4. Desliga o modo avião e puxa para atualizar: "Atualizado agora". Passados 30 minutos, o próximo carregar vai sozinho à rede.

5. flutter_secure_storage para o token

class TokenStorage {
  TokenStorage([FlutterSecureStorage? storage])
      : _storage = storage ??
            const FlutterSecureStorage(
              iOptions: IOSOptions(
                accessibility: KeychainAccessibility.first_unlock_this_device,
              ),
            );
  final FlutterSecureStorage _storage;
  static const _chave = 'access_token';

  Future<String?> ler() => _storage.read(key: _chave);
  Future<void> guardar(String token) => _storage.write(key: _chave, value: token);
  Future<void> apagar() => _storage.delete(key: _chave);
}

• API igual a um mapa assíncrono: read, write, delete. Por baixo, Keychain no iOS e Keystore + AES no Android.
• first_unlock_this_device: acessível depois do primeiro desbloqueio e não migra para outro telemóvel via backup. É o que queres para um token.
• Amanhã, o AuthClient lê daqui, renova em 401 e volta a guardar. Hoje só fica o token do arranque.

Até amanhã