Imported from zy-smile/one-note-app (
AGENTS.md). Install upstream withnpx skills add zy-smile/one-note-app. Copyright stays with the author.
项目目标
开发一个移动端离线笔记应用。
第一版目标：
- 用户可以创建文件夹
- 用户可以在文件夹下创建、编辑、删除笔记
- 笔记数据永久保存在本地
- 支持自动保存
- 支持搜索笔记
- 支持本地备份导出
本项目第一阶段不接入服务器，不需要用户系统。
核心理念：
Local First：所有数据默认保存在用户设备，本地数据是唯一数据源。
技术栈要求
Framework
使用：
- Flutter 3.x
- Dart 3.x
状态管理
使用：
- Riverpod
禁止：
- Provider
- Bloc
- GetX
本地数据库
使用：
- SQLite
- Drift ORM
数据必须通过数据库管理。
禁止：
- SharedPreferences 保存业务数据
- JSON 文件作为主要存储
路由
使用：
- go_router
本地存储
使用：
- path_provider
数据模型
使用：
- freezed
- json_serializable
项目架构规范
采用 Feature First 架构。
目录结构：
lib/
├── app/ │ ├── app.dart │ ├── router.dart │ └── theme.dart │ ├── core/ │ ├── database/ │ ├── storage/ │ ├── utils/ │ └── widgets/ │ ├── features/ │ │ ├── folders/ │ │ ├── data/ │ │ ├── domain/ │ │ └── presentation/ │ │ ├── notes/ │ │ ├── data/ │ │ ├── domain/ │ │ └── presentation/ │ │ ├── search/ │ │ │ └── backup/ │ └── main.dart
要求：
- UI 不直接操作数据库
- 页面只能调用 Provider
- Provider 调用 Repository
- Repository 调用 Database
数据流：
Page ↓ Provider ↓ Repository ↓ Drift Database
第一版功能范围
1. 文件夹功能
必须实现：
- 创建文件夹
- 修改文件夹名称
- 删除文件夹
- 查看文件夹列表
数据：
Folder
字段： id name createdAt updatedAt
第一版：
不支持：
- 多级文件夹
- 文件夹排序
- 标签
2. 笔记功能
必须实现：
- 新建笔记
- 编辑笔记
- 删除笔记
- 查看笔记列表
- 查看最近编辑笔记
数据：
Note
字段：
id
folderId
title
content
createdAt
updatedAt
规则：
- 删除文件夹时，同时删除该文件夹下笔记
- 笔记必须属于一个文件夹
3. 编辑器
第一版使用：
Flutter TextField
要求：
支持：
- 标题输入
- 正文输入
- 多行编辑
不实现：
- 富文本
- 图片插入
- Markdown 渲染
4. 自动保存
必须实现。
规则：
用户输入内容后：
输入变化
↓
800ms 防抖
↓
保存 SQLite
↓
更新时间 updatedAt
离开页面：
必须强制保存。
5. 搜索
实现：
搜索全部笔记。
搜索范围：
- 标题
- 内容
SQL：
使用 LIKE 查询。
暂不实现：
- 全文索引
- 标签搜索
6. 本地备份
第一版实现：
导出备份文件。
流程：
SQLite
↓
生成 JSON
↓
保存到本地文件
格式：
backup.json
包含：
folders
notes
backupVersion
createdAt
第一版：
不实现：
- GitHub 上传
- 加密
- 云同步
这些属于第二阶段。
UI要求
整体风格：
简洁、类似系统笔记应用。
页面：
首页
包含：
搜索框
文件夹列表
最近笔记
新建按钮
文件夹页面
包含：
标题
笔记列表
新建笔记按钮
编辑页面
包含：
标题输入框
正文编辑区域
保存状态显示
保存状态：
保存中...
已保存
数据库设计
Drift tables:
folders
FoldersTable
id
name
createdAt
updatedAt
notes
NotesTable
id
folderId
title
content
createdAt
updatedAt
编码规范
Dart
要求：
- 使用 null safety
- 所有变量明确类型
- 禁止 dynamic 滥用
- 方法保持单一职责
Widget
要求：
优先：
StatelessWidget
避免：
巨大 Widget 文件。
页面超过：
300 行
必须拆分。
错误处理
所有数据库操作：
必须捕获异常。
例如：
try {
} catch(e){
}
禁止：
直接 ignore error。
测试要求
第一版至少包含：
Repository 测试：
- 创建文件夹
- 创建笔记
- 删除笔记
Database 测试：
- 插入数据
- 查询数据
Git提交规范
格式：
type: description
例如：
feat: add folder create function
feat: add note editor
fix: fix database migration
开发顺序
严格按照：
Step 1
初始化 Flutter 项目
配置：
- Riverpod
- go_router
- Drift
Step 2
完成数据库
Step 3
完成 Folder CRUD
Step 4
完成 Note CRUD
Step 5
完成编辑页面
Step 6
增加自动保存
Step 7
增加搜索
Step 8
增加本地备份
第一阶段禁止事项
不要实现：
- 登录系统
- 网络请求
- 后端服务
- GitHub同步
- 云数据库
- AI功能
- 富文本编辑器
- 多人协作
- 复杂动画
AI开发原则
生成代码时：
- 优先保证简单可靠
- 不提前设计未来功能
- 不增加没有需求的依赖
- 遵循 Flutter 官方最佳实践
- 每完成一个功能保证项目可以运行
如果存在多个方案：
优先选择：
简单 > 灵活
稳定 > 炫技
可维护 > 快速堆代码
