同一个人、多台设备：vibe 项目离线冲突处理方法论

同一台手机上改了待办，回到电脑前一看，改动不见了；平板上离线写了一段笔记，联网后被旧版本盖掉——这不是用户“不会用”，而是你的同步规则在替用户做决定，而且做错了。本篇只讲一种情况：同一个账号、同一个人在多台设备上用，离线改动撞上了。多人同时改同一文档的协同编辑、整套离线架构选型，都不在本篇范围，文末划界段会说清分工。

一、先看清冲突长什么样

单人多设备的冲突，本质是“昨天的你”和“今天的你”在抢同一条记录。最常见的三种撞法，值得先对号入座。第一种是时间错位：手机在地铁里离线改了购物清单，电脑在有网时改了同一清单，手机一联网，两边都以为自己是最新版。第二种是设备接力断档：平板上写了一半的笔记没同步就合上盖子，晚上在电脑上接着写，系统按“最后写入为准”，直接把平板那半段吞掉。第三种是删除撞修改：一台设备上删了一条记录，另一台离线设备还在改它，同步回来时，这条记录是该复活还是该消失，系统往往随手选了一个。

这三种撞法有个共同点：用户没有做错任何事，错的是规则。规则如果只有一句“后写入的赢”，丢数据只是时间问题；规则如果每次都弹框问用户，用户很快就会乱点一通。所以方法论的第一步不是写代码，而是先给每类数据定好“撞了怎么办”，再让代码去执行这张表。

二、四条原则，先于任何代码

第一，永不静默丢数据。任何一次同步都不允许在没有痕迹的情况下覆盖用户写过的内容；被覆盖的旧版本至少要能找回一次，哪怕只保留七天。第二，字段级裁决，不整条覆盖。一条笔记的标题和正文是两个字段，手机改了标题、电脑改了正文，这根本不算冲突，两边都该留下；只有同一个字段两边都改了，才需要裁决。第三，删除也是改动。删除要先变成“标记删除”，带上删除时间和设备，等所有设备都确认收到，才真正清理；直接物理删除是丢数据的头号来源。第四，别信设备时钟。手机时间可以被用户手动改、可以跨时区跳变，用本地时间戳定胜负，等于把裁决权交给最不可靠的东西；后面会用版本号加逻辑时钟代替它。

三、按数据类型写决策表

一张决策表胜过十处 if 判断。建议按下面这张表起步，之后只增不减地往上加特例。计数器类（比如打卡天数、阅读量）用“增量合并”：两边各加了多少就加总，不要取最大值。开关和单选类（完成与否、置顶与否）用“最后一次人工操作为准”，但要以操作顺序而非时钟为准，顺序来自每台设备递增的操作序号。短文本字段（标题、备注）撞了就走“人工二选一”，系统把两个版本并排给用户挑，挑完旧版本仍进历史。长文本（笔记正文）先按段落拆分合并，实在同段冲突再二选一，不要整篇覆盖。清单顺序用“位置分数”而不是数组下标，下标一插一删就全乱，分数可以在两项之间不断取中值。文件和图片不合并，只保留两份并改名提示，让用户自己删一份。删除撞修改时，默认保留修改、把删除挂起并提示用户确认，因为删错的代价远大于多留一条。

这张表的价值在于可测试：每一行都对应一个测试用例，而不是一句“大概能处理”。上线前把表贴进需求文档，开发、测试、产品三方先对这张表签字，后面扯皮会少一半。

四、最小数据模型：六个字段就够

单人项目不需要上重型协同框架，先把每条记录补齐六个字段。记录编号全局唯一，设备编号标明改动出自哪台设备，基准版本号说明这次改动是基于哪个版本改的，操作序号是本设备单调递增的计数，更新时间只做展示和排查、不做裁决，删除标记区分“删了”和“不存在”。同步时服务端只做一件事：拿客户端的基准版本号和服务端当前版本号比对。相等，说明没人插队，直接接受；不等，说明撞了，按决策表裁决，而不是按时间戳。设备编号加操作序号还有一个好处：排查时一眼看出“这条改动是手机第三次操作、电脑第五次操作”，不用猜。

给 agent 下需求时可以这样写：每条记录必须带这六个字段，缺字段的写入直接拒绝；同步接口返回结果必须说明“接受、合并、待人工裁决”三种状态之一，不许只返回成功。状态不清的同步接口，是线上丢数据的温床。

五、同步流程五步走

第一步，离线写本地。没网时所有操作先落本地数据库，界面要明确显示“未同步”而不是假装已保存；用户合上盖子、杀掉进程，数据都不能丢。第二步，联网先拉后推。先把服务端的最新版本拉下来，在本地做裁决，再把结果推上去；先推后拉的顺序，会让本地旧版本先盖掉服务端新版本。第三步，本地裁决。按决策表自动合并能合并的，合并不了的生成一条“待裁决”记录，绝不擅自选边。第四步，推回并确认。服务端接受后返回新版本号，客户端只有收到确认才清除“未同步”标记；没收到确认就当没同步成功，下次继续推，幂等键保证重复推不会重复加计数。第五步，提示用户。自动合并成功的，在界面角落轻提示一句即可；待人工裁决的，要在显眼位置留一个入口，用户点开才能二选一。

六、冲突界面：给用户三次机会

人工裁决界面要同时做到三件事：看得懂、选得快、选错能反悔。看得懂，指的是两个版本并排展示差异，而不是只给两个时间戳让用户猜；标题、正文、清单项的差异要高亮出来。选得快，指的是默认提供“保留手机版、保留电脑版、两份都保留”三个按钮，不要让用户复制粘贴。选错能反悔，指的是选完之后旧版本进历史记录，七天内可以在历史里一键恢复；没有反悔通道的二选一，用户点错一次就再也不信你的同步。

一个常见的反面例子是：弹窗只写“检测到冲突，是否覆盖？”用户根本不知道覆盖的是哪边，只能凭运气点。另一个反面例子是：每次同步都弹框，连标题改动这种本可自动合并的也问，用户点到第三次就会开始闭眼点确定，真正重要的冲突反而被放过去。界面上的克制，和决策表上的严格，是一体两面。

七、上线前跑一遍八个用例

这八个用例跑通，再谈上线。手机离线改标题、电脑在线改正文，同步后两边都要在。手机和电脑离线各改同一标题，同步后必须出现二选一，不能自动丢一边。平板离线删记录、手机在线改同一记录，同步后记录保留并提示删除被挂起。手机时间往后拨一年再同步，裁决结果不能变。同一条记录在三台设备上轮流离线改，全部联网后最终一致。同步中途断网重推，计数器不能 double 计。用户在二选一里选错，七天内能从历史恢复。旧版本客户端连上新版本服务端，缺字段的写入被拒绝并给出可读提示。每个用例写清前置状态、操作顺序、期望结果，跑不通的用例不许用“用户一般不会这样”带过——用户一定会这样。

八、六个反模式，见一个改一个

后写入为准且不留历史，是最贵的反模式，省下的代码量会在客服和差评里加倍还回来。拿设备时钟当裁决依据，跨时区旅行一次就可能丢一批数据。删除直接物理删，离线设备一回来就复活或丢数据，两头不讨好。同步失败静默重试到天荒地老，用户以为已保存，换设备才发现没有。所有冲突都弹框问用户，等于把规则缺失的成本转嫁给用户。最后一类是只在单设备上测试同步功能，上线第一天多设备用户就会教你做人。

九、同步失败时，用户界面该说什么

同步失败的文案，决定了用户是安心等一等，还是恐慌地反复点、甚至卸载重装。好的文案只讲三件事：现在是什么状态、数据安不安全、下一步该做什么。状态要具体：“三条改动尚未同步，已保存在本机”，而不是一句含糊的“同步失败”。安全要先说：“你的改动没有丢失，联网后会自动重试”，这句话要放在最前面，因为用户最怕的是丢数据。下一步要给得起：是“保持联网即可”，还是“请检查网络后点重试”，不要让用户猜。反面文案有三种：一是只报错误码，用户看不懂；二是谎报成功，界面显示已同步、实际还在本地排队，这是最伤信任的一种；三是把技术细节全倒出来，比如把版本号冲突堆栈贴给用户，用户除了焦虑什么也做不了。

界面细节同样重要。未同步的条目要在列表里留一个肉眼可见的标记，比如灰色小圆点加“待同步”三个字；点开条目能看到“本机已保存、等待联网”；同步恢复后标记自动消失，不需要用户手动清除。重试按钮要做节流：点一次就进入重试，短时间内重复点击不产生重复提交；重试失败三次以上，再提示用户检查网络或联系客服，而不是无限转圈。给 agent 的需求可以写成一句话：任何一次同步失败，界面必须在三秒内给出状态、安全承诺和下一步，三者缺一不可。

十、四周落地计划：别想一口气做完

第一周只做决策表和数据盘点。把全部数据类型列出来，逐行填好撞了怎么办，空行不许留；同时给每条记录补齐六个字段的现状评估，缺字段的表先列出来，不要急着改代码。第二周做最小模型和同步接口。先实现拉取、本地裁决、推送、确认这条主链路，人工裁决界面可以先用最简版本：并排展示加三个按钮，不做花哨的差异高亮。第三周跑测试矩阵。八个用例逐一跑通，跑不通的记成缺陷而不是“已知问题”；同时补齐冲突历史保留和恢复入口，这是上线前最容易被砍、事后最难补的一块。第四周灰度放量：先给自己和身边三五个真实用户用，盯一周的同步成功率、待裁决量、历史恢复量三项指标；待裁决量突然暴涨，说明决策表有漏行，先补表再放量，而不是先放量再补表。四周做完，同步功能才算从“能跑”变成“敢用”。

十一、版本历史：冲突裁决的最后一道保险

决策表再严密，也会有用户选错、规则漏行的时刻，版本历史就是兜底。历史记录至少要存三样东西：每次同步前的旧版本快照、裁决结果（自动合并还是人工二选一、选了哪边）、操作来源（哪台设备、哪个操作序号）。恢复入口要放在用户找得到的地方：记录详情页里的“历史版本”，而不是埋在设置三级菜单里。恢复动作本身也要走一次同步流程：把历史版本当成一次新的编辑提交，重新跑裁决，而不是直接改数据库绕过规则；绕过规则的恢复，很容易制造新的冲突。保留期写清楚：默认保留三十天，人工裁决过的版本保留九十天，到期自动清理并在产品说明里写明，不要让用户以为历史是永久的。

历史记录还有一个容易被忽略的用途：排查。用户说“我的内容不见了”，客服第一件事不是问用户“你是不是删了”，而是查历史：哪次同步做了合并、哪次做了人工裁决、裁决时两个版本分别是什么。查得到，用户就信得过；查不到，再好的文案也只是安慰。给 agent 提需求时，把历史查询接口和恢复接口一起列进去，缺了查询接口的历史，等于只存不用的保险柜。

十二、常见问答：上线前先统一口径

问：单设备用户需要这套东西吗？答：需要，因为今天的单设备用户，明天可能换手机、加平板；规则先立好，设备增加时不用返工。问：人工裁决会不会打扰用户？答：只有同字段冲突才问，标题改动和正文改动这种跨字段情况自动合并，实测中需要人工裁决的比例通常不到同步总量的百分之五。问：旧版本客户端怎么办？答：缺字段的写入直接拒绝并提示升级，不要为了兼容旧客户端放宽规则，放宽一次，决策表就破一个洞。问：同步失败时数据存在哪？答：存在本机数据库，联网后自动重试；卸载应用会清除本机数据，这一点要在产品说明里提前讲清，不能等用户卸载后才说。口径统一了，客服、文档、界面文案才不会各说各话。还有一句要提前想好：用户问“同步会不会丢我的数据”，标准回答不是“不会”，而是“自动合并的不会丢，需要你选的会留着两个版本让你挑，选错了七天内能恢复”。把这句话写进帮助文档首页，比写十页同步原理更能让用户放心。用户要的不是技术保证，而是丢了能找回的确定性。

十三、上线清单：贴在发布前检查

先把这份清单打印出来贴在显示器边上，发布前逐项打勾、逐项留档，缺项不放行。决策表是否覆盖全部数据类型，有没有“其他情况待定”这种空行；删除是否全走标记删除，清理任务是否有全设备确认；同步接口是否返回接受、合并、待裁决三种状态；断网重推是否有幂等保护；冲突历史保留期是否写进了产品说明；八个用例是否全部通过并留档。六项全打勾，再把同步功能放给第一批真实用户；缺任何一项，先补再发，因为同步丢数据的口碑伤害，比晚发一周大得多。