129 lines
4.9 KiB
Markdown
129 lines
4.9 KiB
Markdown
---
|
||
title: 数据层
|
||
updated: 2026-06-07
|
||
status: active
|
||
tags: [isar, offline-first, sync, repository-pattern]
|
||
---
|
||
|
||
# 数据层 — Isar 本地存储 + SyncEngine 离线同步
|
||
|
||
> 从 [[index]] 导航。关联: [[handwriting-engine]] [[frontend]] [[erp-diary]]
|
||
|
||
## 1. 设计决策
|
||
|
||
### Q: 为什么离线优先？
|
||
|
||
小学生使用场景中网络不稳定（校园 WiFi 信号差、家庭网络波动）。所有功能必须离线可用，联网后自动同步。
|
||
|
||
### Q: 为什么选 Isar 不用 SQLite？
|
||
|
||
Isar 提供 FTS 全文搜索、内置加密、零配置 Flutter 原生支持、类型安全的查询 API。对 Flutter 项目比 SQLite+drift 更轻量。
|
||
|
||
### Q: 为什么用版本号冲突检测？
|
||
|
||
离线编辑 → 联网同步场景下，同一条数据可能在多端修改。version 字段做乐观锁，Phase 1 使用"本地优先"策略（本地版本覆盖远端），Phase 2 提供 UI 手动解决。
|
||
|
||
### Q: 为什么 Repository 抽象接口？
|
||
|
||
`JournalRepository` 抽象接口 → `IsarJournalRepository`（本地）+ `RemoteJournalRepository`（远程）。BLoC 只依赖抽象，切换实现不影响业务逻辑。
|
||
|
||
## 2. 关键文件 + 数据流
|
||
|
||
### 核心文件
|
||
|
||
| 文件 | 行数 | 职责 |
|
||
|------|------|------|
|
||
| `data/local/isar_database.dart` | 72 | 单例管理，3 Schema 注册 |
|
||
| `data/repositories/isar_journal_repository.dart` | 333 | CRUD + 乐观锁 + 软删除 |
|
||
| `data/repositories/remote_journal_repository.dart` | 114 | Dio HTTP API 代理 |
|
||
| `data/repositories/journal_repository.dart` | 184 | 抽象接口 + InMemory 测试实现 |
|
||
| `data/services/sync_engine.dart` | 338 | WiFi 增量同步 + Isar 队列持久化 |
|
||
| `data/local/collections/` | 3+3 文件 | Isar Collection 定义 + 生成 Schema |
|
||
|
||
### 数据流
|
||
|
||
```
|
||
UI 操作
|
||
│
|
||
▼
|
||
EditorBloc.onSave (2s debounce)
|
||
│
|
||
├─→ IsarJournalRepository.createJournal() [首次]
|
||
├─→ IsarJournalRepository.updateJournal() [后续]
|
||
│ └─ 乐观锁: version 匹配 → +1 → 写入
|
||
│ └─ 不匹配 → throw StateError('版本冲突')
|
||
│
|
||
└─→ SyncEngine.enqueue() [待同步操作入队]
|
||
│ WiFi 可用时
|
||
▼
|
||
trySync() → RemoteJournalRepository → API → PostgreSQL
|
||
│ 成功
|
||
▼
|
||
persistPendingQueue() [更新 Isar 队列]
|
||
```
|
||
|
||
### 集成契约
|
||
|
||
| 方向 | 组件 | 接口 | 触发时机 |
|
||
|------|------|------|---------|
|
||
| 被调用 ← | EditorBloc | `onSave(EditorState)` | 笔画/元素变更 2s 后 |
|
||
| 调用 → | IsarJournalRepository | `createJournal/updateJournal` | 首次/后续保存 |
|
||
| 调用 → | SyncEngine | `enqueue/trySync` | 数据变更/网络恢复 |
|
||
| 启动时 → | SyncEngine | `restorePendingQueue()` | app.dart 创建时 |
|
||
|
||
## 3. 代码逻辑
|
||
|
||
### 不变量
|
||
|
||
⚡ **Isar 扩展方法需显式 import** — `import 'package:isar/isar.dart'` 不会随传递 import 传播，必须在使用 `findAll()`/`findFirst()` 的文件中显式导入
|
||
|
||
⚡ **笔画序列化固定 ID** — `${journalId}_strokes` 保证每次覆盖而非重复创建
|
||
|
||
⚡ **SyncEngine 双写** — 操作同时存在于内存 Queue 和 Isar PendingOperationCollection
|
||
|
||
⚡ **乐观锁** — updateJournal 比对 version，不匹配抛 StateError
|
||
|
||
⚡ **软删除级联** — 删除日记时关联元素的 isDeleted 也设为 true
|
||
|
||
### 3 个 Isar Collection
|
||
|
||
| Collection | Isar 主键 | 业务 ID | 用途 |
|
||
|------------|----------|---------|------|
|
||
| JournalEntryCollection | autoIncrement | id (indexed) | 日记条目 |
|
||
| JournalElementCollection | autoIncrement | id (indexed) | 日记元素 |
|
||
| PendingOperationCollection | autoIncrement | id (indexed) | 同步操作队列 |
|
||
|
||
### 初始化链
|
||
|
||
```dart
|
||
// main.dart
|
||
WidgetsFlutterBinding.ensureInitialized();
|
||
await IsarDatabase.init(); // 注册 3 个 Schema
|
||
|
||
// app.dart
|
||
final syncEngine = SyncEngine(apiClient: apiClient);
|
||
syncEngine.restorePendingQueue(); // fire-and-forget 恢复队列
|
||
```
|
||
|
||
## 4. 活跃问题 + 陷阱
|
||
|
||
| 问题 | 级别 | 状态 | 说明 |
|
||
|------|------|------|------|
|
||
| authorId 硬编码 'local' | HIGH | 待修 | EditorPage 未接入 AuthBloc 获取真实用户 |
|
||
| SyncEngine 仅 WiFi | MEDIUM | Phase 2 | 蜂窝数据同步未实现 |
|
||
| 版本冲突静默覆盖 | MEDIUM | Phase 2 | "本地优先"策略，需 UI 手动解决 |
|
||
| ~~编辑器未加载已有数据~~ | ~~MEDIUM~~ | ✅ 已修复 | _loadExistingJournal 读取日记 + 元素 + 笔画 |
|
||
|
||
### 历史教训
|
||
|
||
- Isar `findAll()` 编译报"未定义" — 原因是扩展方法不随 import 传播，需显式 `import 'package:isar/isar.dart'`
|
||
- Isar 3.x 查询链必须通过 `.filter()` 过渡才能调用 `.findAll()`
|
||
|
||
## 5. 变更记录
|
||
|
||
| 日期 | 变更 |
|
||
|------|------|
|
||
| 2026-06-07 | 编辑器加载已有数据已修复、打开已有日记默认查看模式 |
|
||
| 2026-06-01 | Isar 集成完成：3 Collection + Repository + SyncEngine 持久化 (2481c8f) |
|
||
| 2026-06-01 | 初始创建 — 数据层架构、Isar 踩坑记录 |
|