羽毛球工具 App HarmonyOS 6.0 实战（10/10）：本地优先同步策略

系列第 10 篇。跨设备、手表、语音、平板展示都离不开一个问题谁是数据事实来源断网或冲突时怎么恢复。一、真实问题背景羽毛球工具不是社交平台它首先要在现场可靠。没有账号、没有网络、没有服务器时组织者仍然要能创建对局、记比分、结算费用。多设备协同是增强但不能让基础计分变得脆弱。当前项目采用本地优先Preferences负责持久化AppStorage负责页面即时刷新。这个基础决定了后续同步策略也应该从本地事实出发而不是把远端服务当作唯一真相。二、目标与边界本地优先同步要解决1. App 重启后数据能恢复。2. 手机、平板、手表产生动作时能合并。3. 冲突出现时能解释、能撤销、能回退。4. 用户隐私数据不默认出设备。边界是本文不设计服务器数据库不设计账号体系不把比赛记录上传到云端。后续如果引入云能力也应保持用户主动授权。三、当前存储基线common/src/main/ets/storage/SessionStore.ets是对局数据的核心。它先从Preferences恢复再写入AppStorage。SessionStore.initPrefs(this.context); SessionStore.hydrateFromPrefs(); AppStorage.setOrCreateSessionSummary[](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”的顺序写进下一组实战文章。