数据同步机制

架构概述

轻笺采用服务端存储、实时读写的同步模式。所有数据（书签、笔记、文件、标签）存储在云端 MySQL 数据库中，每次操作直接读写数据库。

同步方式

核心原则

• 写入即持久化：每次新增、编辑、删除操作直接写入 MySQL，不依赖本地缓存
• 读取即最新：每次页面加载或操作刷新时从数据库拉取最新数据
• 会话无关：数据不绑定 Session，任意设备登录同一账号读到同一份数据

数据流

用户操作 → 前端 API 请求 → Express 路由 → 参数校验 → MySQL 写入/读取 → 响应 → 前端更新视图

多端实时性

当前实现

• 当前页面内操作：立即生效（前端更新状态 + 后端确认）
• 跨设备同步：需要手动刷新页面获取最新数据
• 不支持服务端主动推送数据变更

关于 WebSocket

代码仓库中包含独立的 WebSocket 服务（端口 3000），但未接入主应用的数据同步流程。目前 WebSocket 仅作为基础示例存在，未用于推送数据变更。

冲突处理

• 多端同时编辑同一笔记：以最后一次保存的内容为准，不做合并
• 文件上传重名：支持覆盖 / 自动改名 / 取消三种处理方式
• 删除操作：逻辑删除（标记 del_flag=1），数据不立即物理清除

缓存机制

知识库缓存

• 知识库检索结果缓存 5 分钟（helpCache 内存缓存）
• 5 分钟后自动失效，下次查询时重新从数据库加载

API 日志

• 日志写入不影响业务响应速度（异步写入）
• Agent 调用日志同样异步写入 agent_logs 表

数据安全

逻辑删除

• 所有主要资源表（bookmark、note、files、tag 等）都有 del_flag 列
• 删除操作为逻辑删除（del_flag = 1）
• 回收站数据保留 30 天后自动物理清理

数据库备份

• 数据库定期备份（由服务器运维策略决定）
• 安全事件、操作日志等数据长期保留

存储说明

• 文件存储于 OBS 对象存储或本地 www/wwwroot/images 目录
• 数据库仅存储文件元数据，不存储文件二进制内容