从“别忘了一句话”到一条完整的数据链
一个想法刚出现时通常只有一句话。真正让它留下来的难点不是输入框,而是后续每一步都不会把它弄丢:
快速记录
→ 标签 / 来源 / 附件
→ AI 分析
→ 思维导图 / 关联
→ 转成项目
→ 拆分任务
→ 回顾与报告
很多笔记工具只解决第一步,后面的“这条想法现在处于什么状态”仍然散落在收藏、待办和文档里。FlashNote 想做的就是让同一份灵感沿着这条链继续走。
这不是一个纯界面问题,底层需要稳定的数据模型、可恢复的数据库迁移、可合并的同步格式,以及对 AI 请求边界的控制。
技术栈与分层
FlashNote 使用 Flutter 开发,主要技术栈如下:
| 层次 | 选择 |
|---|---|
| 状态管理 | Riverpod |
| 路由 | go_router |
| 本地数据库 | drift / SQLite |
| 代码生成 | freezed + json_serializable |
| HTTP | Dio |
| 凭据存储 | 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。
这种结构意味着三件事必须同时成立:
- 没有网络也能完整记录和整理;
- AI Key 和 WebDAV 密码不进入普通导出文件;
- 同步失败时不能把旧数据覆盖成半成品。
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”这句话掩盖。
实际界面

灵感列表:来源筛选、标签与快速记录

AI 分析:可行性、潜力和风险

由灵感生成的思维导图

灵感关联与知识图谱

从灵感转成项目并继续拆任务

本地保存的周报与回顾
当前边界
- Android、Windows、Linux 是一等支持;
- iOS、macOS 是实验性支持,签名和沙盒权限仍不完整;
- Web 版目前不可用,缺少 Web SQLite 资源且部分服务依赖
dart:io; - JSON 导入是覆盖语义,不是合并;
- 跨设备稳定 UUID 尚未合入主分支;
- WebDAV 自动同步依赖浏览器/应用处于运行状态,休眠后可能推迟。
项目地址:SiRan-Dev/Flash-Note。当前版本 v1.3.6,GPLv3 许可。