羽毛球工具 App HarmonyOS 6.0 实战（03/10）：本地优先数据方案
系列第 3 篇。本文讲数据层：一个比赛工具要在没有账号、没有服务器、没有网络的情况下稳定记录对局、费用、比分和用户设置。
一、真实问题背景
羽毛球组局现场不适合复杂登录，也不应该把比赛记录依赖在网络上。组织者真正关心的是：刚输入的费用不要丢，刚生成的对阵不要丢，计分退到后台再回来还能看，重启 App 后历史仍在。
所以这个项目采用本地优先策略：持久化用@kit.ArkData的 Preferences，页面响应式状态用AppStorage。Preferences 解决“下次启动还在”，AppStorage 解决“当前页面立刻刷新”。
二、目标与边界
本文目标是拆解当前项目已经落地的数据模式：
1. 设置数据怎么恢复。2. 对局列表和对局详情怎么持久化。3. 费用计算的最近输入和结果怎么缓存。4. 为什么服务层要同时写 Preferences 和 AppStorage。
边界是：当前基础版不讲云同步、不讲多设备冲突合并、不讲账号体系。跨设备数据流转会作为后续路线图文章，单独讨论“本地优先如何走向多端协同”。
三、启动时先恢复本地数据
在EntryAbility的onCreate中，项目先初始化三个存储服务，再把 Preferences 数据恢复到 AppStorage。
SettingsStore.initPrefs(this.context); SettingsStore.hydrateFromPrefs(); SessionStore.initPrefs(this.context); SessionStore.hydrateFromPrefs(); FeeCalcService.initPrefs(this.context); FeeCalcService.hydrateFromPrefs();这段顺序很关键。页面加载前先恢复状态，页面出现时读取到的是最新镜像，而不是默认空数据。这样首页可以展示“我的对局”，排名页能拿到当前对局，费用页也能回填最近输入。
四、设置数据：小而稳定
common/src/main/ets/storage/SettingsStore.ets管理昵称、深浅色、主题色、头像预设等设置。设置项数量不多，但对体验影响很明显。
static initPrefs(context: Context): void { SettingsStore.prefs = preferences.getPreferencesSync(context, { name: 'settings_store' }); } private static persistSetting(key: string, value: string): void { const p = SettingsStore.prefs; if (p === undefined) { return; } p.putSync(key, value); p.flush(); }保存设置时，项目先写AppStorage，再写 Preferences。前者让 UI 立即变化，后者让下次启动仍然恢复。
static saveThemeTone(tone: string): void { AppStorage.setOrCreate<string>(SettingsStore.KEY_THEME_TONE, tone); SettingsStore.persistSetting(SettingsStore.KEY_THEME_TONE, tone); }五、对局数据：列表与详情分开
对局数据比设置复杂。一个SessionSummary用于首页列表，一个SessionDetail保存参与人和每场比赛。项目把列表和详情分开持久化，避免每次展示首页都处理完整大对象。
核心文件是common/src/main/ets/storage/SessionStore.ets：
static readonly KEY_SESSIONS: string = 'g_sessions'; static detailKey(id: string): string { return `g_session_detail_${id}`; } private static persistSessions(): void { const sessions = SessionStore.list(); SessionStore.persist(SessionStore.KEY_SESSIONS, JSON.stringify(sessions)); }创建对局时，先调用PairingAlgorithm.generate生成比赛，再同时写列表、详情和当前激活对局。
const matches: MatchItem[] = PairingAlgorithm.generate( draft.participants, draft.courtCount, draft.roundCount, draft.pairingMode ); AppStorage.setOrCreate<SessionSummary[]>(SessionStore.KEY_SESSIONS, sessions); AppStorage.setOrCreate<SessionDetail>(SessionStore.detailKey(session.id), detail); SessionStore.persistSessions(); SessionStore.persistDetail(detail);六、响应式刷新里的一个细节
ArkUI 中数组和对象状态很容易因为“原地修改”导致刷新不稳定。项目里更新列表时通常会先slice()复制，再替换 AppStorage 中的值。例如保存比分后，重新生成matches数组并写回详情。
这种做法比直接push/splice更啰嗦，但换来的是更可预测的 UI 刷新。对比赛工具来说，比分和排名不能靠“退出再进页面”刷新，必须在当前页面立刻更新。
七、取舍与风险
Preferences 适合轻量本地数据，但它不是复杂关系型数据库。当前项目选择它，是因为基础版目标是单机离线、低权限、低打扰。风险在于：如果未来要做跨设备数据流转，必须补同步层、版本号、冲突合并和删除标记，不能把当前本地 key 直接当成云端协议。
另一个风险是旧版本数据迁移。项目已经有一些兼容逻辑，例如头像预设的 legacy hash、旧 scope key 迁移。后续每次新增字段，都应该给默认值和恢复策略。
八、验证命令
构建验证：
& 'D:\HuaweiDevelopFormalStudy\DevEco Studio\tools\hvigor\bin\hvigorw.bat' assembleHap --mode module -p product=default --no-daemon验证时间：2026-06-28。当前结果为BUILD SUCCESSFUL。功能验收应覆盖：创建对局、录入比分、退出重进、查看排名、重置数据、切换主题。
九、官方参考
Preferences 属于 ArkData 能力，API 行为应以 HarmonyOS ArkData 官方文档 为准。不同 SDK 版本对同步、异常和容量约束可能有细节差异，正式发布前需要按目标 SDK 复核。
十、工程验收清单
- 启动时先 hydrate，再加载首页。- 设置、费用、对局分别有独立存储服务。- 列表和详情分开保存，减少首页读取压力。- 更新数组状态时先复制再写回。- 重置数据只清用户状态，不破坏静态资源。- 后续跨设备能力不能直接复用本地 key 当同步协议。
十一、小结
本地优先不是“不做云”，而是先保证没有网络也能完成核心流程。对羽毛球工具来说，这比一开始就上账号和同步更贴近现场使用。等本地模型稳定后，再做手机、平板、手表之间的数据流转，风险会小很多。
十二、下一篇衔接
下一篇进入系统 AI 能力：如何用 Core Speech Kit 给实时计分加上离线比分播报，并在失败时不影响手动计分主流程。