系列第 10 篇。跨设备、手表、语音、平板展示都离不开一个问题：谁是数据事实来源，断网或冲突时怎么恢复。

一、真实问题背景

羽毛球工具不是社交平台，它首先要在现场可靠。没有账号、没有网络、没有服务器时，组织者仍然要能创建对局、记比分、结算费用。多设备协同是增强，但不能让基础计分变得脆弱。

当前项目采用本地优先：Preferences 负责持久化，AppStorage 负责页面即时刷新。这个基础决定了后续同步策略也应该从本地事实出发，而不是把远端服务当作唯一真相。

二、目标与边界

本地优先同步要解决：

1. App 重启后数据能恢复。2. 手机、平板、手表产生动作时能合并。3. 冲突出现时能解释、能撤销、能回退。4. 用户隐私数据不默认出设备。

边界是：本文不设计服务器数据库，不设计账号体系，不把比赛记录上传到云端。后续如果引入云能力，也应保持用户主动授权。

三、当前存储基线

common/src/main/ets/storage/SessionStore.ets 是对局数据的核心。它先从 Preferences 恢复，再写入 AppStorage。

SessionStore.initPrefs(this.context);
SessionStore.hydrateFromPrefs();
AppStorage.setOrCreate<SessionSummary[]>(SessionStore.KEY_SESSIONS, sessions);

SettingsStore 和 FeeCalcService 也采用类似模式。这个模式很适合本地优先，因为页面刷新和持久化恢复不是混在一起的。

四、为什么需要动作日志

多设备同步不建议直接同步“最终比分对象”，因为两个设备同时修改时很难知道谁先谁后。更好的方式是同步动作日志。

interface SyncAction {
  id: string;
  sourceDeviceId: string;
  sessionId: string;
  matchId: string;
  type: 'teamAPlus' | 'teamBPlus' | 'undo' | 'finish';
  createdAt: number;
}

最终比分可以由动作日志重放得到。这样出现冲突时，也能追踪是哪一个入口提交了动作。

五、冲突合并原则

羽毛球计分的冲突合并要简单可解释：

1. 同一个 actionId 只处理一次。2. 加分动作按时间顺序追加。3. 撤销动作只撤销同一设备或同一用户最近一步。4. 结束比赛动作需要更高确认等级。5. 发生不可合并冲突时，保留手机端主控状态并提示核对。

这套策略比“最后写入覆盖”更适合比赛现场。

六、隐私边界

本地优先也意味着隐私默认收敛。项目中的昵称、头像、对局名单、比分、费用结果都属于用户现场数据。默认策略应该是：

本机保存：默认开启
跨设备局域协同：用户主动触发
导出图片或复制文本：用户主动分享
云端备份：未来单独授权

这和当前 FeeResultPage.ets 的分享闭环一致：用户点击分享，才生成图片并拉起系统分享面板。

七、同步失败时的体验

同步失败不能挡住主流程。建议提示设计是：

1. 平板展示断开：平板提示“等待手机更新”，手机继续计分。2. 手表动作失败：手表震动失败反馈，手机状态不变。3. 语音动作失败：保留文本提示，允许手动确认。4. 持久化失败：页面继续运行，但提示重启后可能无法恢复。

核心原则是比赛不中断。

八、官方参考

本地存储、应用生命周期、文件分享和多设备能力都应以 HarmonyOS 官方文档为准。本文强调当前工程的同步抽象，不把未来能力写死成某个单一实现。

华为开发者文档：HarmonyOS 应用开发

九、工程验收清单

- entry/src/main/ets/entryability/EntryAbility.ets 启动时恢复 SettingsStore、SessionStore、FeeCalcService。- common/src/main/ets/storage/SessionStore.ets 负责对局摘要、详情、活动对局和草稿。- common/src/main/ets/storage/SettingsStore.ets 负责主题、昵称、头像等设置。- common/src/main/ets/service/FeeCalcService.ets 负责费用结果缓存。- features/src/main/ets/fee/FeeResultPage.ets 通过用户主动操作导出分享图片。- 验证时间：2026-06-29；当前工程目标包含 HarmonyOS 6.0/API 20+，昨日 Hvigor 构建已验证 BUILD SUCCESSFUL。

十、小结

本地优先同步的重点不是“永远不要同步”，而是先把本地数据做成可信事实，再让跨设备能力围绕动作日志和用户授权展开。这样手机、平板、手表和语音入口都能加入，但不会破坏现场工具最重要的可靠性。

十一、系列收束

到这一篇，系列从工程基线走到多设备路线图。后续如果真正实现跨设备流转、手表端计分或语音确认，可以继续按“先服务层、再入口、最后 UI”的顺序写进下一组实战文章。