Add architecture documentation and retail system workshop PPT

2026-08-12 17:49:57 +08:00
commit 54c001a793
26 changed files with 9618 additions and 0 deletions
@@ -0,0 +1,158 @@
+# 06. 本地存储方案
+
+## 决策
+
+按数据类型分三档存储，全部封装在 `core_storage` 包内，`feature_*` 不直接依赖底层存储库：
+
+| 数据类型 | 方案 | 版本（2026-08 快照） |
+|---|---|---|
+| 结构化/关系型数据（门店列表缓存、订单历史等） | **[Drift](https://pub.dev/packages/drift)** | `^2.34.3` |
+| 敏感数据（token、refresh token） | **[flutter_secure_storage](https://pub.dev/packages/flutter_secure_storage)** | `^11.0.0` |
+| 简单非敏感 KV（是否看过引导页、用户偏好设置） | **[shared_preferences](https://pub.dev/packages/shared_preferences)** | `^2.5.5` |
+
+## 依赖
+
+```yaml
+dependencies:
+  drift: ^2.34.3
+  sqlite3_flutter_libs: ^0.5.0
+  flutter_secure_storage: ^11.0.0
+  shared_preferences: ^2.5.5
+
+dev_dependencies:
+  drift_dev: ^2.34.3
+  build_runner: ^2.4.0
+```
+
+## 使用规则
+
+- 全仓库**只有一个 Drift 数据库实例**，定义在 `core_storage` 里，不允许每个 `feature_*` 各自建一个 SQLite 文件——避免多个数据库文件之间做跨 feature 查询/事务的麻烦。
+- 每个 feature 拥有自己的表（`Table` 类）和 DAO（`DriftAccessor`），表名加 feature 前缀（如 `store_cache`、`payment_history`）避免命名冲突，但都注册进同一个 `AppDatabase`。
+- feature 的 `data` 层 `local_datasource` 只依赖自己的 DAO 类型，不直接操作 `AppDatabase` 或访问其他 feature 的表。
+- token / refresh token 只能经过 `core_auth` 包里封装的 secure storage 读写方法，不允许其他 `core_*`/`feature_*` 直接调用 `FlutterSecureStorage` 实例。
+- 数据库表结构变更必须写 migration（`onUpgrade` + `schemaVersion` 递增），不允许直接改字段定义后期望"重装了事"——线上用户已有数据需要平滑迁移。
+
+## 参考链接
+
+- [Drift 官方文档](https://drift.simonbinder.eu/)
+- [drift | Dart package](https://pub.dev/packages/drift)
+- [flutter_secure_storage | Dart package](https://pub.dev/packages/flutter_secure_storage)
+- [shared_preferences | Dart package](https://pub.dev/packages/shared_preferences)
+
+## 附录：Drift 是什么，日常怎么用
+
+给还没接触过这套本地数据库封装方式的同学看的入门说明。
+
+### 要解决的问题
+
+Flutter 生态里直接操作本地 SQLite 最常见的是 [`sqflite`](https://pub.dev/packages/sqflite)，但它是纯 SQL 字符串拼接：
+
+```dart
+// sqflite 写法，容易手滑打错字段名/表名，编译期完全发现不了
+await db.rawQuery('SELECT * FROM stroe WHERE nmae = ?', [name]);
+```
+
+字段名、表名全靠字符串，拼错了只有运行时才报错；查询结果是 `Map<String, Object?>`，还得手动转成业务对象；数据变化了想让 UI 自动刷新，也得自己手写一套通知机制。
+
+**Drift** 在 `sqflite`（或更底层的 `sqlite3`）之上加了一层代码生成：用 Dart 类定义表结构，`build_runner` 生成类型安全的查询代码，写错字段名/类型在编译期就会报错；查询结果直接是强类型的 Dart 对象；还内置了 `.watch()` 方法，数据变化时自动推送新结果，天然适合配合 Riverpod 的 `StreamProvider`/`AsyncNotifier` 做响应式 UI。
+
+### 核心概念
+
+1. **`Table` 类**：用 Dart 代码声明表结构（字段名、类型、约束），而不是手写 `CREATE TABLE` 语句。
+2. **`DriftAccessor`（DAO）**：给一组相关表写查询/增删改方法的地方，业务代码只调用 DAO 方法，不直接写 SQL。
+3. **`.watch()` vs `.get()`**：`.get()` 是一次性查询，`.watch()` 返回一个 `Stream`，只要底层数据变化（哪怕是另一个页面改的）就会自动推送新结果——不需要手动刷新。
+4. **`schemaVersion` + `onUpgrade`**：数据库版本号和迁移回调，改表结构时递增版本号并在 `onUpgrade` 里写迁移逻辑（加字段、建索引等），保证已安装用户的本地数据不会因为升级直接报错或丢失。
+
+### 使用示例（`feature_store`：门店列表本地缓存）
+
+```dart
+// packages/core_storage/lib/src/tables/store_table.dart
+class StoreCache extends Table {
+  TextColumn get id => text()();
+  TextColumn get name => text()();
+  RealColumn get lat => real()();
+  RealColumn get lng => real()();
+  DateTimeColumn get cachedAt => dateTime()();
+
+  @override
+  Set<Column> get primaryKey => {id};
+}
+```
+
+```dart
+// packages/core_storage/lib/src/daos/store_dao.dart
+part 'store_dao.g.dart';
+
+@DriftAccessor(tables: [StoreCache])
+class StoreDao extends DatabaseAccessor<AppDatabase> with _$StoreDaoMixin {
+  StoreDao(super.db);
+
+  Future<void> upsertAll(List<StoreCacheCompanion> stores) =>
+      batch((b) => b.insertAllOnConflictUpdate(storeCache, stores));
+
+  Stream<List<StoreCacheData>> watchAll() => select(storeCache).watch();
+}
+```
+
+```dart
+// packages/core_storage/lib/src/app_database.dart
+@DriftDatabase(tables: [StoreCache, PaymentHistory], daos: [StoreDao, PaymentHistoryDao])
+class AppDatabase extends _$AppDatabase {
+  AppDatabase() : super(_openConnection());
+
+  @override
+  int get schemaVersion => 2;
+
+  @override
+  MigrationStrategy get migration => MigrationStrategy(
+    onUpgrade: (m, from, to) async {
+      if (from < 2) {
+        await m.addColumn(storeCache, storeCache.cachedAt);
+      }
+    },
+  );
+}
+```
+
+```dart
+// feature_store 的 local_datasource 只依赖 StoreDao，不直接碰 AppDatabase
+class StoreLocalDataSource {
+  final StoreDao _dao;
+  StoreLocalDataSource(this._dao);
+
+  Stream<List<Store>> watchCachedStores() =>
+      _dao.watchAll().map((rows) => rows.map(Store.fromCacheRow).toList());
+}
+```
+
+配合 Riverpod 做响应式 UI（离线也能展示上次缓存的门店列表，等网络数据回来再刷新）：
+
+```dart
+@riverpod
+Stream<List<Store>> cachedStores(Ref ref) {
+  final localDataSource = ref.watch(storeLocalDataSourceProvider);
+  return localDataSource.watchCachedStores();
+}
+```
+
+### secure storage 使用示例（token 存取）
+
+```dart
+// packages/core_auth/lib/src/token_storage.dart
+class TokenStorage {
+  final FlutterSecureStorage _storage;
+  TokenStorage(this._storage);
+
+  Future<void> saveTokens({required String accessToken, required String refreshToken}) =>
+      Future.wait([
+        _storage.write(key: 'access_token', value: accessToken),
+        _storage.write(key: 'refresh_token', value: refreshToken),
+      ]);
+
+  Future<String?> readAccessToken() => _storage.read(key: 'access_token');
+
+  Future<void> clear() => _storage.deleteAll();
+}
+```
+
+`TokenStorage` 是全仓库唯一直接持有 `FlutterSecureStorage` 实例的类，其他包只能通过 `core_auth` 暴露的 provider 间接读写 token。