系列第 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 给实时计分加上离线比分播报，并在失败时不影响手动计分主流程。