文档索引¶

欢迎来到 随手记 Sui 的文档中心。本目录收录项目的全部详细文档；根目录的 README.md（总览）、ARCHITECTURE.md（架构入口）、DEVELOPMENT.md（开发入口） 只作薄入口，深入内容都在这里。

按角色找文档¶

目录¶

入门¶

• 快速开始 —— 环境搭建、构建、测试、端到端联调
• 用户指南 —— 整体概念、安装客户端、日常使用、多端同步、版本历史、数据导出
• 网页剪藏 —— Chrome / Edge 扩展的安装、配置与使用

深入¶

• 系统架构 —— 分层、数据模型、同步协议、附件策略、平台分层、目录结构
• API 参考 —— HTTP 端点清单与 push / pull 载荷
• 架构决策记录（ADR）—— 关键决策的背景与权衡（随项目技术文档单独维护，不随本仓库发布）
• 代码示例 —— 端到端 REST 调用示例

运维¶

• 部署指南 —— 服务端部署、反向代理、备份恢复、安全与生产化
• 故障排查 —— 常见问题与排查思路

项目现状速览¶

• 版本：0.12.1
• 里程碑：M0–M12 全部完成（M3 与 M11 编号有意留空，为让里程碑号与版本号对应）：框架与基本功能 / 笔记本分组与标签同步 / 整理与格式化编辑 / 单用户服务化与安全加固 / 编辑器增强 / 全页快照与离线自持剪藏 / 桌面端界面布局优化 / 桌面端独立笔记窗口 / 编辑器编辑能力与附件体验增强 / 认证与笔记安全加固（短时访问令牌 + 可撤销刷新令牌、HTTP 下的应用层受保护通道、可单独加密的笔记本）/ 最新 M12 = v0.12.0「逐项同步状态与云端核对补齐」：笔记 / 笔记本（标签共用同一机制）各有本地逐项同步状态，可单项重试、可一键「全部重新同步」（核对 → 补齐），并能识别云端实例身份变化（换库 / 重建）后按提示自愈；补丁 v0.12.1（FR-56）：各客户端「关于」显示当前版本号（桌面「帮助 → 关于随手记 Sui」/ 移动端与 Web 顶栏「更多」/ 剪藏扩展弹出面板与设置页），版本号仍出自 pubspec.yaml 单一真源；修订 v0.12.2（FR-57~FR-59）：会话入口统一（客户端与剪藏扩展一律用账号密码登录，不再手工粘贴令牌）、桌面端本地存储位置可迁移（旧目录保留、失败回退）、登录失败防护（失败计数 + 指数退避 + 锁定 + 审计，配套 nginx 反代限流）
• 测试：服务端 go test ./... 全绿、note_core 329/329、flutter_app 171/171 全绿；两个 Dart 包 analyze 零问题
• 已知限制：
• 搜索为 title / content 的 LIKE 子串匹配（FTS5 仅架构预留，未启用）
• 编辑器为「格式 / 源码 / 预览」三态，Markdown 为正本，暂无富文本 WYSIWYG
• Web 端附件缓存为进程内内存态（刷新后按需重下）
• 首次「全部重新同步」会做一次带正文的全量 pull（核对用的精简清单为演进项），笔记很多时首轮较慢
• 内置服务端不终止 TLS：公网部署请用反向代理承载 HTTPS（见部署指南）

变更历史见 CHANGELOG.md；缺口明细见 系统架构 · 当前状态与已知缺口。