2025 iThome鐵人賽
「 Flutter ：30天打造念佛App，跨平台從Mobile到VR，讓極樂世界在眼前實現 ! 」
Day 21
「 Flutter 資料儲存 實戰應用篇—穿越到Coding世界的勇者啊，你知道裝備可以放哪嗎(1)」

前言

昨天我們已經完成了音訊轉換及念佛計數的單元測試，
今天我們要來接著探索「如何在手機裝置端進行儲存」！
如此一來，使用者下次開啟App時，之前的使用紀錄都能完整保存！

Day21 文章目錄：
一、本機儲存
二、實作選擇
三、實作核心

一、本機儲存

1. 簡介

本機資料儲存是將App資料從記憶體寫到裝置內的持久化媒介。
由Android、iOS 平台提供 檔案系統/資料庫 API，
讓 App 在沙盒內使用這些API進行讀寫。

2. 重要概念

(1) App沙盒機制

• App只能存取自身的沙盒目錄(除非用系統分享/授權機制），
  不能讀取其他App的資料。

• iOS常見子目錄職責：
  • Documents ：長期保存使用者的檔案(預設iCloud會備份)。
  • Library/Application Support ：
    • 資料庫、設定檔、索引等長期資料(預設會備份)。
    • 大檔不想進備份，可以設定 NSURLIsExcludedFromBackupKey。
  • Library/Preferences：UserDefaults、plist（預設會備份）
  • Library/Caches：快取；不備份，空間不足時系統可清除。
  • tmp：臨時檔；不備份，隨時可能被清理。

• Android常見子目錄職責：
  • app_flutter/：Flutter的Documents對應(放長期資料)。
  • files/：長期資料/設定/模型。
  • cache ：快取；不備份，空間不足時系統可清除。
  • databases：SQLite。
  • shared_prefs：偏好設定。

(2) 安全分層

• 資料分類 → 存放對應等級 → 遵守最小揭露、最小權限。
• 資料分類：
  • 公開/一般：非敏感、可重建的資料
  • 一般個人化：與個人使用有關，但風險低
  • 敏感：Token、API KEY
  • 高度敏感：個資、健康資訊、商業機密

(3) 效能

• 小而頻繁的寫入會造成：
  • 效能差（I/O 次數多）、耗電（儲存控制器一直被喚醒）、
    磨損（Flash 壽命跟寫入次數相關）
• 解法：
  • 併批/緩衝→ 多筆累積或固定間隔再寫入；熱資料快取降低 I/O。

備註：

• 熱資料（hot data）：會被頻繁讀取的資料。
• 冷資料（cold data）：不常用的資料。
• 熱資料放記憶體快取，搭配過期時間（TTL）或最近少使用（LRU），讀取免 I/O，速度快、耗電少。

(4) 中途閃退防護

• 緩衝 + 原子寫入，降低遺失與壞檔機率。
• 追加式事件日誌，可截斷修復。

(5) 順序執行

• 任何對「同一資源」的寫入請求，都丟進同一條序列化隊列依序處理，
  避免併發覆蓋與遺失。

二、實作選擇

BLOB 是以二進位形式儲存的大型資料，常見於音訊、影像、影片、壓縮檔等。
BLOB可以存放在資料庫欄位裡，也可以外放在檔案系統。
實務上會建議將中大型檔外放，避免資料庫膨脹、CRUD與備份變慢。

CRUD 是資料存取最基本的四種操作：
Create（建立）：新增一筆資料。
Read（讀取）：查詢或取得資料。
Update（更新）：修改既有資料。
Delete（刪除）：移除資料。

三、實作核心

使用者一次的念佛時間可能是數個小時、累積上萬聲佛號；
念佛 App 的資料屬性是「長時間大量追加、偶爾查詢以簡單總數為主」。

因此目前先採用純檔案(JSON/NDJSON)作為本機儲存，
並以「緩衝 → 單寫者序列化 → 原子寫入」的流程，
兼顧效能、I/O 次數與資料一致性。

1. 資料模型 storage/models.dart

class SessionSnapshot {
  final String sessionId;
  final String userId;
  final String userName;
  final DateTime startedAt;
  final DateTime lastAt;
  final int amitabhaCount;

  SessionSnapshot({
    required this.sessionId,
    required this.userId,
    required this.userName,
    required this.startedAt,
    required this.lastAt,
    required this.amitabhaCount,
  });

  Map<String, dynamic> toJson() => {
    'schemaVersion': 1,
    'sessionId': sessionId,
    'userId': userId,
    'userName': userName,
    'startedAt': startedAt.toUtc().toIso8601String(),
    'lastAt': lastAt.toUtc().toIso8601String(),
    'amitabhaCount': amitabhaCount,
  };

  static SessionSnapshot fromJson(Map<String, dynamic> j) => SessionSnapshot(
    sessionId: j['sessionId'],
    userId: j['userId'],
    userName: j['userName'],
    startedAt: DateTime.parse(j['startedAt']).toUtc(),
    lastAt: DateTime.parse(j['lastAt']).toUtc(),
    amitabhaCount: j['amitabhaCount'] ?? 0,
  );
}

class DailySummary {
  final String yyyymmdd;
  final String userId;
  final String userName;
  final int amitabhaCount;

  DailySummary({
    required this.yyyymmdd,
    required this.userId,
    required this.userName,
    required this.amitabhaCount,
  });

  Map<String, dynamic> toJson() => {
    'schemaVersion': 1,
    'date': yyyymmdd,
    'userId': userId,
    'userName': userName,
    'amitabhaCount': amitabhaCount,
  };

  static DailySummary fromJson(Map<String, dynamic> j) => DailySummary(
    yyyymmdd: j['date'],
    userId: j['userId'],
    userName: j['userName'],
    amitabhaCount: j['amitabhaCount'] ?? 0,
  );
}

2. 緩衝器 storage/buffered_hits.dart

import 'dart:async';

class BufferedHits {
  final Duration flushEvery;  //最長等待多久就flush
  final int maxBuffer;        //滿多少筆就flush
  final Future<void> Function(List<DateTime>) onFlush;
  final _buf = <DateTime>[];
  Timer? _t;

  BufferedHits({
    required this.flushEvery,
    required this.maxBuffer,
    required this.onFlush,
  });

  void add(DateTime t) {
    _buf.add(t);                       //將命中佛號的時間添加到緩衝器    
    if (_buf.length >= maxBuffer) { _flush(); } //量到上限就flush
    else { _t ??= Timer(flushEvery, _flush); }  //時間到就flush
  }
 
  Future<void> _flush() async {
    _t?.cancel(); _t = null;
    if (_buf.isEmpty) return;
    final copy = List<DateTime>.from(_buf);
    _buf.clear();
    await onFlush(copy);
  }

  Future<void> close() => _flush();
}

3. 原子寫入 storage/atomic_io.dart

原子（atomic）：
一個操作不是全部成功，就是完全沒發生，不會出現「寫到一半」的中間狀態。
常用「先寫暫存檔 → 一步置換成正式檔」的手法，來達到近似原子的效果。

import 'dart:convert';
import 'dart:io';

//原子寫入
Future<void> atomicWriteJson(File file, Object jsonObj) async {
  final dir = file.parent;
  if (!await dir.exists()) {
    await dir.create(recursive: true);
  }

  final tmp = File('${file.path}.tmp');
  try {
    final jsonStr = const JsonEncoder.withIndent('  ').convert(jsonObj);
    await tmp.writeAsString(jsonStr, flush: true);
    await tmp.rename(file.path);
  } catch (e) {
    if (await tmp.exists()) {
      try { await tmp.delete(); } catch (_) {}
    }
    rethrow;
  }
}

/// 讀取 JSON
Future<Map<String, dynamic>> readJsonOrEmpty(File file) async {
  if (!await file.exists()) return {};
  String text;
  try {
    text = await file.readAsString();
  } on IOException {
    return {};
  }

  if (text.isEmpty) return {};

  try {
    final obj = jsonDecode(text);
    if (obj is Map<String, dynamic>) return obj;
    return {};
  } on FormatException {
    return {};
  }
}

4. 順序執行器 storage/single_writer.dart

class SingleWriter {
  Future<void> _last = Future.value(); //正在執行或已排序的工作，後續工作都會接後面
  Future<T> run<T>(Future<T> Function() job) { //逐一執行
    final next = _last.then((_) => job()); //last完成，才呼叫job
    _last = next.then((_) {}, onError: (_) {}); 
    return next;
  }
}
final singleWriter = SingleWriter();

5. 數量彙整 storage/daily_repo.dart

import 'atomic_io.dart';
import 'app_paths.dart';
import 'models.dart';
import 'single_writer.dart';

class DailyRepository {
  Future<void> addCount(String yyyymmdd, String userId, String userName, int delta) async {
    final file = await AppPaths.daily(yyyymmdd);
    await singleWriter.run(() async {
      final j = await readJsonOrEmpty(file);
      if (j.isEmpty) {
        final d = DailySummary(
          yyyymmdd: yyyymmdd,
          userId: userId,
          userName: userName,
          amitabhaCount: delta,
        );
        await atomicWriteJson(file, d.toJson());
      } else {
        final d = DailySummary.fromJson(j);
        final updated = DailySummary(
          yyyymmdd: d.yyyymmdd,
          userId: d.userId,
          userName: d.userName,
          amitabhaCount: d.amitabhaCount + delta,
        );
        await atomicWriteJson(file, updated.toJson());
      }
    });
  }
}

6.初始化、呼叫 streaming_asr.dart

Future<void> _initStorage() async {
    _sessionRepo = SessionRepository();
    _dailyRepo = DailyRepository();

    _sessionId = DateTime.now().toUtc().millisecondsSinceEpoch.toString();
    _sessionStartedAt = DateTime.now().toUtc();

    _hitLogger = HitLogger(_sessionId, rotateEvery: 5000); //5000筆換檔
    await _hitLogger.initFromDisk(); //app若重開，先查找上次檔案的最後行數

    _buffer = BufferedHits(
      flushEvery: const Duration(seconds: 3), //設定固定每三秒flush
      maxBuffer: 200,                         //設定滿200筆資料就flush
      onFlush: (hits) async {
        final hitsUtc = hits.map((e) => e.toUtc()).toList(growable: false);
        final lastHit = hitsUtc.isNotEmpty
            ? hitsUtc.last
            : DateTime.now().toUtc();
        await _hitLogger.appendMany(hitsUtc);   //日誌

        final snapshot = SessionSnapshot(       //快照
          sessionId: _sessionId,
          userId: _userId,
          userName: _userName,
          startedAt: _sessionStartedAt,
          lastAt: lastHit,
          amitabhaCount: _asrHitCount,
        );
        await _sessionRepo.upsertSnapshot(snapshot);

        final ymd = nowYmdLocal();
        await _dailyRepo.addCount(ymd, _userId, _userName, hits.length);
      },
    );
  }
  
  
  
// _start()

if (_recognizer!.isEndpoint(_stream!)) {
    _recognizer!.reset(_stream!);
    if (text != '') {
     _last = textToDisplay;
     _index += 1;

     final hitAdd = countAmitabhaOccurrences(text);
     if (hitAdd > 0) {
      setState(() {
       _asrHitCount += hitAdd;
       _asrLastHitAt = DateTime.now();
       debugPrint(
        '[ASR] 阿彌陀佛 HIT=$hitAdd Count = $_asrHitCount '
        ' Time = ${_asrLastHitAt!.toIso8601String()}',
       );
      for (int i = 0; i < hitAdd; i++) {
        _buffer.add(DateTime.now());  //命中佛號添加當前時間至緩衝器
      }
    });
   }
  }
 }

• 測試：/test/storage_test.dart

• 驗證：查看App沙盒(iOS Xcode)

Day21 重點回顧