从“别忘了一句话”到一条完整的数据链

一个想法刚出现时通常只有一句话。真正让它留下来的难点不是输入框,而是后续每一步都不会把它弄丢:

快速记录
  → 标签 / 来源 / 附件
  → AI 分析
  → 思维导图 / 关联
  → 转成项目
  → 拆分任务
  → 回顾与报告

很多笔记工具只解决第一步,后面的“这条想法现在处于什么状态”仍然散落在收藏、待办和文档里。FlashNote 想做的就是让同一份灵感沿着这条链继续走。

这不是一个纯界面问题,底层需要稳定的数据模型、可恢复的数据库迁移、可合并的同步格式,以及对 AI 请求边界的控制。

技术栈与分层

FlashNote 使用 Flutter 开发,主要技术栈如下:

层次选择
状态管理Riverpod
路由go_router
本地数据库drift / SQLite
代码生成freezed + json_serializable
HTTPDio
凭据存储flutter_secure_storage
AI 接口OpenAI-compatible / Anthropic-compatible 策略模式

代码按 Clean Architecture 拆分:

presentation  →  Riverpod providers / 页面
domain        →  实体、仓储接口、AI 服务接口
data          →  drift、WebDAV、AI strategy、导入导出
core          →  常量、错误、通用工具

页面不直接读 SQLite,而是通过 domain 层接口拿到实体。这样 AI、WebDAV 和本地存储可以分别替换,不会把网络请求或数据库表结构泄漏到 UI 里。

数据模型:自增 ID 留给 UI,UUID 负责跨设备身份

早期版本使用 SQLite 的自增整数作为主键。它在单机没有问题,但一旦把两台设备的数据合并,两个设备生成同一个 id=7 是非常正常的事情。

当前 schema 保留自增 id 供 UI、路由和仓储使用,同时增加跨设备唯一 uuid:

class Inspirations extends Table {
  IntColumn get id => integer().autoIncrement()();
  TextColumn get content => text().withLength(min: 1)();
  TextColumn get source => text().nullable()();
  TextColumn get tags => text().withDefault(const Constant("[]"))();
  TextColumn get aiAnalysis => text().nullable()();
  TextColumn get mindMapData => text().nullable()();
  BoolColumn get isPinned => boolean().withDefault(const Constant(false))();
  IntColumn get createdAt => integer()();
  IntColumn get updatedAt => integer()();
  IntColumn get reviewedAt => integer().nullable()();
  BoolColumn get needsFollowUp => boolean().withDefault(const Constant(false))();
  TextColumn get uuid => text().clientDefault(newUuidV4)();
}

uuid 上有唯一索引,id 不变。这样现有 UI 不需要全部重写,同步层可以使用稳定身份。

灵感、项目和任务通过普通外键关联:

Inspirations 1 ── 0..1 Projects
Projects     1 ── N   Tasks
Inspirations 1 ── N   Attachments / ChatMessages / InspirationLinks

删除则单独记录在 deleted_records:

entity_type + entity_uuid + deleted_at

墓碑必须有删除时间,否则同步合并时无法判断“是旧设备还没收到删除”还是“另一台设备重新创建了同名记录”。

本地优先不等于把数据关进本机

FlashNote 没有托管后端。灵感、项目、任务、报告和设置都存在本机 SQLite,AI 请求直接发送到用户配置的接口,跨设备同步使用用户自己的 WebDAV。

这种结构意味着三件事必须同时成立:

  1. 没有网络也能完整记录和整理;
  2. AI Key 和 WebDAV 密码不进入普通导出文件;
  3. 同步失败时不能把旧数据覆盖成半成品。

API Key 与 WebDAV 密码存放在平台安全存储中。JSON 导出和 WebDAV 快照会剥离这些凭据,恢复后需要重新填写。这个选择有一点麻烦,但比把密码写进一个可能被备份、上传或转发的 JSON 文件要可靠。

同步不是覆盖文件,而是合并实体

FlashNote 的同步快照包含灵感、项目、任务、来源、附件、对话、关联、聚类、报告、回顾状态、图谱布局和墓碑。

合并规则可以概括为:

有 UUID:按 UUID 对应同一条实体
实体都存在:比较 updatedAt,保留较新的版本
一边已删除:比较 deletedAt 与另一边 updatedAt
删除墓碑:按 entityType + entityUuid 取最大的 deletedAt
导入:先完整校验,再在单个事务中写入

这里有两个容易忽略的细节。

第一,删除墓碑不能只按自增 ID 记录。旧设备可能还没有 UUID 字段,迁移时需要生成确定性的 legacy UUID;否则一次同步就会把旧删除记录和新记录混在一起。

第二,快照导入不能边解析边写数据库。当前流程会先校验整个快照,再做版本升级校验,最后把所有写入放进事务。解析失败或校验失败时,本地数据库保持不变;附件文件不会被删除。

WebDAV 发布:优先原子移动,失败再降级

同步最容易出错的时刻不是下载,而是“新版本写到一半,旧版本已经被覆盖”。

FlashNote 优先采用“临时对象 + MOVE”:

PUT 临时快照
  → HEAD 校验大小与 ETag
  → 检查正式文件是否被其他设备改动
  → MOVE 临时文件到正式路径

如果 WebDAV 服务器不支持 MOVE(返回 405/501),会降级为两个槽位加一个指针文件:

快照 A       快照 B
   ↑            ↑
   └── pointer.json

写入 B 前先读取指针,写入后再次确认指针没有变化;只有两次检查都通过,才更新指针。这样失败时远端仍然指向旧槽位,不会留下“指针指向半个文件”的状态。

强 ETag 才会用于 If-Match,弱 ETag 不参与条件写入;写请求也不盲目跟随重定向。这些规则看起来琐碎,但直接决定了并发同步时是“检测到冲突”还是“静默覆盖”。

数据库升级前先备份,失败就不升级

SQLite schema 升级比普通功能更新危险,因为它会修改用户唯一的本地数据库。

原生端在升级前会复制:

flashnote.db
flashnote.db-wal
flashnote.db-shm

到:

flashnote_backups/vX_to_vY_<timestamp>/
  flashnote.db
  flashnote.db-wal
  flashnote.db-shm
  backup_complete

backup_complete 最后写入。没有这个标记,备份目录被视为不完整;读取版本失败或复制失败时,启动直接中止,不会在没有可恢复副本的情况下继续迁移。迁移在事务里执行,失败后展示恢复页和备份路径。

第 11 版到第 12 版的迁移还把墓碑从“实体类型 + 自增 ID”升级为“实体类型 + UUID”,并在迁移后做自检,确认没有空 entity_uuid。这类修复不能靠“下次同步再看”,否则错误会先扩散到其他设备。

AI 是工具,不是数据仓库

AI 分析、思维导图、单条灵感对话、全局助手、周报和月报都使用用户自己的接口和 Key。FlashNote 不托管模型,也不要求在云端注册一个 FlashNote 账号。

这意味着 AI 结果属于本地记录的一部分:分析结果会写回灵感,思维导图按灵感缓存,报告写入本地 reports 表。换设备同步时同步的是这些结果和原始数据,而不是某个服务端的会话状态。

当前多设备 UUID 迁移已在 feature 分支实现,但尚未合入 main,因此 README 仍明确标注多设备合并可能受到自增 ID 冲突影响。这个限制不应该被“支持 WebDAV”这句话掩盖。

实际界面

当前边界

  • Android、Windows、Linux 是一等支持;
  • iOS、macOS 是实验性支持,签名和沙盒权限仍不完整;
  • Web 版目前不可用,缺少 Web SQLite 资源且部分服务依赖 dart:io;
  • JSON 导入是覆盖语义,不是合并;
  • 跨设备稳定 UUID 尚未合入主分支;
  • WebDAV 自动同步依赖浏览器/应用处于运行状态,休眠后可能推迟。

项目地址:SiRan-Dev/Flash-Note。当前版本 v1.3.6,GPLv3 许可。