架构说明
Note Sync Now 由一个 React + Vite 客户端、一个 Express + Socket.IO 服务端，以及一套 GitHub Pages 文档站组成。系统设计遵循“客户端负责加密与恢复，服务端负责中转与持久化”的边界。
总体分层
客户端层
- React 负责界面与交互
- Zustand 负责本地状态管理
useSocket负责实时同步链路crypto模块负责密钥派生、加密与解密- 冲突管理模块负责本地与远端内容差异处理
- 本地存储模块负责 IndexedDB / LocalStorage 能力承接
关键路径：
brave-sync-notes/client/src/App.jsxbrave-sync-notes/client/src/hooks/useSocket.jsbrave-sync-notes/client/src/store/useStore.jsbrave-sync-notes/client/src/utils/cryptobrave-sync-notes/client/src/utils/conflictbrave-sync-notes/client/src/utils/storage
服务端层
- Express 暴露健康检查与统计接口
- Socket.IO 处理房间加入、同步广播、错误反馈与成员列表
PersistenceManager负责持久化适配- Redis / SQLite 作为可切换的存储后端
- 内存 Map 作为最后兜底存储
关键路径：
brave-sync-notes/server/index.jsbrave-sync-notes/server/src/persistence/PersistenceManager.jsbrave-sync-notes/server/src/persistence/PersistenceAdapter.js
核心架构原则
- 端到端加密优先：笔记内容在客户端侧加密，服务端只接收密文。
- 助记词驱动恢复：客户端通过助记词派生房间与加密相关信息。
- 服务端尽量无状态：服务端聚焦同步转发、短期内存态与持久化兜底。
- 冲突显式处理：本地编辑与远端更新冲突时，不把所有情况都简化为覆盖写入。
- 多层存储退化：优先使用持久化存储，不可用时回退到内存模式。
同步数据流
- 用户在客户端编辑内容。
- Zustand 更新当前笔记状态。
useSocket对内容进行加密，并按需要拆分为分块载荷。- 客户端通过
push-update将密文发送到服务端。 - 服务端验证房间成员资格、数据格式、大小与频率限制。
- 服务端将最新密文保存在持久化层或内存兜底层。
- 服务端通过
sync-update向房间内其他成员广播更新。 - 接收端客户端解密数据，必要时进入冲突检测与人工解决流程。
关键模块关系
客户端同步引擎
useSocket.js 是客户端同步主入口，承担：
- 创建与维护 Socket 连接
- 首次
join-chain - 断线重连后的重新加入
- 远端
sync-update解密与落库 request-sync主动拉取- 历史记录节流保存
- 冲突管理器调用
服务端事件模型
server/index.js 当前的关键事件包括：
join-chain：加入同步链并返回现有数据push-update：提交最新密文更新request-sync：重连或恢复后请求最新状态room-info：广播房间成员信息update-ack：确认服务端已接收更新error：返回参数、权限或限流错误
当前实现重点
根据现有设计文档与代码实现，本项目当前重点在于：
- 稳定的端到端同步主链路
- 冲突检测与人工解决集成
- 服务端持久化与回退策略
- 后续多笔记、离线队列与更强本地存储能力的可扩展性