# 手札用户功能指南
# 1. 产品定位
手札是一个本地优先的加密笔记应用，专注于快速记录和个人数据安全。
| 核心理念 | 说明 |
|---|---|
| 本地优先 | 数据默认存储在本地，不依赖网络 |
| 隐私安全 | 端到端加密，服务端无法查看内容 |
| 跨设备同步 | 加密导出/导入，或通过 Yjs 增量同步 |
| 快速启动 | 即开即用，无需登录等待 |
# 2. 功能全景
# 2.1. 已实现功能
| 功能 | 状态 | 入口 |
|---|---|---|
| 手札 CRUD | ✅ 创建/读取/编辑/软删除 | 首页列表 + 编辑页 |
| 手札列表 | ✅ 按更新时间排序，显示标签 | 首页 |
| 搜索过滤 | ✅ 按标题和标签搜索 | 首页搜索栏 |
| 标签管理 | ✅ 常用标签快速选择 + 自定义标签 | 编辑页 |
| 加密保护 | ✅ 敏感标签自动触发 AES-GCM 加密 | 编辑页 |
| 解密查看 | ✅ 加密内容可临时解密查看 | 编辑页 🔓 按钮 |
| 导出备份 | ✅ 全量加密导出 JSON 文件 | 设置页 |
| 导入恢复 | ✅ 加密文件导入（含 ID 冲突处理） | 设置页 |
| 密钥备份 | ✅ 账户密钥导出/导入 | 设置页 |
| 自动保存 | ✅ 2秒防抖自动保存草稿到 localStorage | 编辑页 |
| 快捷键 | ✅ Ctrl+S 保存 | 编辑页 |
| 首次引导 | ✅ 首屏欢迎向导，自动创建账户密钥 | 首次启动 |
| 空状态 | ✅ 无数据时显示友好的空页面提示 | 首页 |
| 响应式布局 | ✅ 移动端优先，桌面端居中布局 | 全局 |
| 用户注册/登录 | ✅ 用户名+密码注册/登录 | /login |
| 设备注册 | ✅ 首次同步前注册设备 | 自动 + API |
| Yjs 增量同步 | ✅ 3-5秒防抖异步 CRDT 同步 | 自动 |
# 2.2. 未实现功能（计划中）
| 功能 | 优先级 | 说明 |
|---|---|---|
| 实时多人协作 | 未来 | 需要启用 WebSocket（当前 Yjs CRDT 架构已支持） |
| 邀请码系统 | 待定 | 用户注册邀请码生成和管理 |
| PWA 离线支持 | 已规划 | Service Worker + 离线缓存 |
| 富文本编辑 | 已规划 | Markdown 或所见即所得编辑器 |
| 主题切换 | 已规划 | 深色模式 |
# 3. 快速开始
# 3.1. 纯本地使用（无需注册）
打开应用 → 首次引导（自动生成账户密钥）→ 开始记录手札
↓
所有数据存储在本地 IndexedDB，导出备份到 JSON 文件
# 3.2. 跨设备同步（需注册）
1. 注册/登录 → 2. 开始记录（自动同步）→ 3. 其他设备登录同一账号 → 数据自动同步
# 4. 页面说明
# 4.1. 首页（手札列表）
┌─────────────────────────────────────┐
│ 手札 [🔍][⚙][新建] │
├─────────────────────────────────────┤
│ [🔍 搜索手札... ][✕] │ ← 搜索栏
├─────────────────────────────────────┤
│ 共 12 条 刷新 │
├─────────────────────────────────────┤
│ ┌─────────────────────────────┐ │
│ │ 工作笔记 🔒 🗑 │ │ ← 手札卡片
│ │ 今日完成了三个任务... │ │
│ │ 刚刚 [工作] [+2] │ │
│ └─────────────────────────────┘ │
│ │
│ ┌─────────────────────────────┐ │
│ │ 私密日记 🔒 🗑 │ │
│ │ （加密内容） │ │ ← 加密手札
│ │ 昨天 [#私密] │ │
│ └─────────────────────────────┘ │
│ │
│ 📝 还没有手札 │ ← 空状态
│ 点击"新建"按钮开始记录 │
└─────────────────────────────────────┘
| 元素 | 说明 |
|---|---|
| 🔍 | 展开/收起搜索栏 |
| ⚙ | 进入设置页 |
| 🔒 | 手札已加密 |
| 🗑 | 软删除（可在设置中恢复） |
# 4.2. 编辑页
┌─────────────────────────────────────┐
│ [← 返回] 已保存 🔓 [保存] │ ← 状态栏
├─────────────────────────────────────┤
│ 标题 │ ← 标题输入
├─────────────────────────────────────┤
│ 标签: [#私密] [工作] [灵感] [待办] │ ← 标签选择
│ [学习] [添加标签___] │
├─────────────────────────────────────┤
│ │
│ 在此输入内容... │ ← 正文编辑区
│ │
│ │
├─────────────────────────────────────┤
│ ⚠️ 检测到敏感标签，保存后将自动加密 │ ← 加密警告
└─────────────────────────────────────┘
| 状态 | 说明 |
|---|---|
| 已保存 | 上次保存成功 |
| 保存中… | 正在保存到 IndexedDB |
| 🔒 | 手札已加密 |
| 🔓 | 解密查看模式 |
# 4.3. 设置页
┌─────────────────────────────────────┐
│ [← 返回] 设置 │
├─────────────────────────────────────┤
│ 设备信息 │
│ 设备 ID: xxxx-xxxx... │
│ 创建时间: 2026-05-26 15:30 │
├─────────────────────────────────────┤
│ 备份与恢复 │
│ [📥 导出备份] [📤 导入备份] │
│ ✓ 导入成功：5 条 │
│ 跳过：2 条（已存在） │
├─────────────────────────────────────┤
│ 账户密钥 │
│ 导出密钥可用于在其他设备恢复数据 │
│ [🔑 导出密钥] │
├─────────────────────────────────────┤
│ 关于 │
│ 手札 ShouZha │
│ 本地优先的加密笔记应用 │
│ 版本：0.1.0 │
└─────────────────────────────────────┘
# 4.4. 登录页
┌─────────────────────────────────────┐
│ │
│ 手札 │
│ 登录以同步数据 │
│ │
│ ┌─────────────────────────┐ │
│ │ 用户名 │ │
│ └─────────────────────────┘ │
│ ┌─────────────────────────┐ │
│ │ 密码 │ │
│ └─────────────────────────┘ │
│ │
│ [ 登录 ] │
│ │
│ 还没有账户？注册 │
│ │
│ ┌─── 注册新账户（展开） ───┐ │
│ │ 用户名 │ │
│ │ 密码 │ │
│ │ [注册] [返回登录] │ │
│ └───────────────────────────────┘ │
└─────────────────────────────────────┘
# 5. 数据安全
# 5.1. 加密层级
| 层级 | 加密方式 | 说明 |
|---|---|---|
| 手札内容 | AES-256-GCM | 敏感标签（#私密、#密码 等）自动触发加密 |
| 账户密钥 | IndexedDB 存储 | 浏览器安全环境，可导出备份 |
| 同步传输 | AES-256-GCM | Yjs 同步数据端到端加密，服务器不解密 |
| 导出文件 | AES-256-GCM | 全量数据加密导出，需账户密钥才能导入 |
# 5.2. 账户密钥
- 首次使用自动生成
- 存储在浏览器 IndexedDB 中
- 建议导出备份，设备丢失后无法恢复加密数据
# 6. 跨设备同步
# 6.1. 方案 A：手动导出/导入（无需账户）
设备 A: 设置 → 导出备份 → 生成 .json 文件
↓
设备 B: 设置 → 导入备份 → 选择 .json 文件
# 6.2. 方案 B：Yjs 自动同步（需账户）
设备 A: 注册 → 登录 → 编辑手札
↓
自动同步（3-5秒）
↓
设备 B: 登录同一账号 → 自动接收变更
| 特性 | 手动导出 | 自动同步 |
|---|---|---|
| 是否需要账号 | ❌ 否 | ✅ 是 |
| 实时性 | 手动操作 | 3-5秒自动 |
| 冲突处理 | 最后导入胜出 | Yjs CRDT 自动合并 |
| 网络要求 | 仅导出时 | 需要后端服务 |
# 7. 加密说明
# 7.1. 何时触发加密
| 场景 | 是否加密 | 说明 |
|---|---|---|
添加 #私密 标签 |
✅ 自动加密 | 敏感标签检测 |
添加 #密码 标签 |
✅ 自动加密 | 敏感标签检测 |
| 内容包含"密码" | ✅ 自动加密 | 内容敏感词检测 |
| 普通工作笔记 | ❌ 不加密 | 明文存储 |
| 导出备份文件 | ✅ 强制加密 | 无论手札是否加密 |
# 7.2. 加密标记
手札卡片上的 🔒 图标表示该手札已加密。 内容预览显示"（加密内容）"而非实际文本。
# 8. 常见问题
# 8.1. Q: 数据存储在哪儿？
所有手札数据存储在浏览器的 IndexedDB 中。后端服务器仅存储加密后的同步数据（无法解密查看内容）。
# 8.2. Q: 如何备份数据？
设置页 → 导出备份 → 保存 .json 文件。建议同时导出账户密钥。
# 8.3. Q: 换手机后如何恢复？
新设备上安装应用 → 设置 → 导入备份 → 选择备份文件。 如果手札有加密，还需要导入之前导出的账户密钥。
# 8.4. Q: 加密手札的密码是什么？
手札没有独立的密码。加密使用的是账户密钥（AES-256-GCM），密钥存储在浏览器中。导出密钥到安全位置即可实现跨设备解密查看。
# 8.5. Q: 同步会泄露我的内容吗？
不会。同步数据使用账户密钥加密后再传输，服务器端无法解密。这是端到端加密。
# 8.6. Q: 清除浏览器数据会怎样？
IndexedDB 数据会被清除。务必在清除前导出备份，否则数据无法恢复。
最后更新: 2026-07-31 19:58:33 +0800