一、把发现进度保存成可恢复的事实在山海万灵的离线浏览链路里读者会连续完成图鉴发现、区域切换和展厅浏览。应用重启后仍需回到同一段探索而不是重新从一张空白图鉴开始。持久化层保存的对象因此不是页面快照而是一组能够重新计算界面的最小事实已发现神兽 ID、当前区域、当前展厅、数据版本和更新时间。interface ShanhaiLocalProgress { schemaVersion: number discoveredIds: string[] selectedRegionId: string selectedHallId: string updatedAt: number }这组字段都由用户动作直接产生。区域百分比、展厅进度和护照印章则由图鉴目录与发现 ID 在读取阶段计算得到。这样能把输入事实和显示结果分开管理。二、Preferences 的读写边界Preferences 存储使用固定名称保存同一份本地进度。写入时分别落下版本、发现 ID、区域、展厅和更新时间最后再执行一次刷新读取时将字符串恢复为领域对象再交给状态层校验。async function save(progress: ShanhaiLocalProgress): Promisevoid { await preferences.put(schema_version, progress.schemaVersion) await preferences.put(discovered_ids, JSON.stringify(progress.discoveredIds)) await preferences.put(selected_region_id, progress.selectedRegionId) await preferences.put(selected_hall_id, progress.selectedHallId) await preferences.put(updated_at, progress.updatedAt) await preferences.flush() }这里避免把每一张卡片的显示状态逐项写入。卡片是否已发现、某区域收录了几只神兽都应由统一目录和 discoveredIds 推导当目录内容更新时旧数据也不会把过期的百分比继续带回界面。存储结构保持很小也让清除进度、版本迁移和异常恢复都能围绕同一个领域对象进行而不用遍历每个页面组件。三、恢复时先校验再计算恢复过程先处理版本和未知 ID再修正已经不在目录中的区域、展厅选择最后生成首页、区域页和护照页需要的状态。任何一个历史 ID 找不到对应神兽时都会被过滤避免内容更新后出现无法打开的详情入口。恢复阶段输入输出数据清洗存储中的版本与发现 ID可识别、去重后的发现集合位置修正区域与展厅选择仍存在的默认探索位置进度派生目录和发现集合区域、展厅进度与护照印章const discoveredCount region.beastIds .filter((id: string) discoveredIds.includes(id)).length const progress region.beastIds.length 0 ? 0 : Math.round(discoveredCount * 100 / region.beastIds.length)护照印章使用同一套集合判断一个区域内的神兽全部已在发现集合中才派生出该区域的印章。百分比和印章没有独立写入点因此不会出现一边已完成、另一边仍停在旧值的分叉。四、发现动作必须幂等详情页可能被重复进入发现动作不能因为重复点击就多次追加同一个 ID。写入前先判断集合中是否存在该神兽已经存在时保留原集合只记住用户当前浏览的区域与展厅。首次发现才扩展集合并立即保存。const nextIds progress.discoveredIds.includes(beastId) ? progress.discoveredIds : [...progress.discoveredIds, beastId] await repository.save({ ...progress, discoveredIds: nextIds, selectedRegionId: regionId, selectedHallId: hallId, updatedAt: Date.now() })单独切换探索位置时逻辑只替换区域、展厅和更新时间原有发现记录保持不变。这使我看到过什么和我上次停在哪里成为两个可以独立变化、但始终一起恢复的状态。async function load(): PromiseShanhaiLocalProgress { const schemaVersion Number(await preferences.get(schema_version, 1)) const rawIds String(await preferences.get(discovered_ids, [])) const selectedRegionId String(await preferences.get(selected_region_id, )) const selectedHallId String(await preferences.get(selected_hall_id, )) const updatedAt Number(await preferences.get(updated_at, 0)) let discoveredIds: string[] [] try { discoveredIds JSON.parse(rawIds) } catch (_) { discoveredIds [] } return { schemaVersion, discoveredIds: Array.from(new Set(discoveredIds)), selectedRegionId, selectedHallId, updatedAt } }读取逻辑把可能损坏的 JSON、重复 ID 和已经不存在的目录项看作独立问题。先保证返回对象具有稳定形状再把目录相关的过滤交给状态层完成。这样本地存储层不需要知道区域页面如何排版状态层也不需要关心键值读写的细节。五、重启后的恢复结果已记录的发现结果和探索位置在强停重启后会从本地存储恢复并重新生成首页上的发现计数与护照信息。下图展示了恢复后的本地进度界面它用于说明重启后的记录回读不把多次详情交互得到的数量变化归因于一次点击。六、失败不阻断本次探索本地读取失败时应用以空进度继续提供离线内容写入失败时本次进程中的发现状态仍可继续使用但下一次启动不会承诺恢复。这个边界让界面有明确的降级语义浏览和发现不因一次本地写入异常中断跨重启恢复则以成功写入为前提。对于读者而言页面不会把一次短暂的存储异常伪装成已经保存成功也不会因为离线资料仍然可用就阻断接下来的探索。情况当前行为下次启动读取失败以空进度加载本地内容等待下一次可读的恢复机会写入失败保留进程内发现状态不保证已变更内容能够恢复历史 ID 失效过滤失效 ID 并重算进度使用清洗后的有效集合七、验收关注点验收这条链路时应连续完成一次发现和一次区域或展厅切换再结束进程并重新进入。恢复后的计数、探索位置和护照信息应来自同一组本地事实重复发现同一神兽不应增加记录数量删除或失效的目录项不应把旧选择带回界面。若后续加入账号同步仍可沿用这一最小事实模型云端只合并发现集合与位置偏好区域进度和护照展示继续由本地目录派生从而避免把不同设备上的展示缓存当成可合并的业务数据。八、为版本演进留下收口本地记录需要显式携带版本号原因并不在于今天的字段已经复杂而在于图鉴内容、区域划分和默认探索位置都会继续演进。读取旧版本时可以为缺少的字段提供默认值遇到无法识别的版本时则返回安全的空进度并保留当前目录作为唯一展示依据。升级逻辑只处理数据形状不直接修改页面状态能够减少迁移代码和界面渲染相互牵连的风险。版本收口还让测试重点更清晰旧记录能否正常打开、重复 ID 是否收敛、失效选择是否替换为默认位置、升级后的新写入是否带上最新版本。它们分别覆盖历史兼容、数据一致性、导航恢复和后续可维护性。即使存储文件被用户清除应用也应把这视为一份新的空进度而不是把不完整内容解释为已完成的探索记录。function normalize(progress: ShanhaiLocalProgress): ShanhaiLocalProgress { const version progress.schemaVersion || 1 const ids Array.from(new Set(progress.discoveredIds || [])) return { schemaVersion: version, discoveredIds: ids, selectedRegionId: progress.selectedRegionId || , selectedHallId: progress.selectedHallId || , updatedAt: progress.updatedAt || 0 } } function emptyProgress(): ShanhaiLocalProgress { return { schemaVersion: 1, discoveredIds: [], selectedRegionId: , selectedHallId: , updatedAt: 0 } }这套边界也适用于后续增加更多图鉴条目时的持续维护。Preferences 的键值持久化、刷新语义和使用限制可参阅 HarmonyOS Preferences 数据持久化文档。