鸿蒙数独案例拆解：从纯函数到文件存档的端侧闭环

最近在华为云鸿蒙开发实践中心读了“数独小游戏：HarmonyOS + ArkUI 纯端侧开发”案例。它没有先堆云服务、登录或排行榜，而是把纯端侧应用最需要验证的三件事放在前面：界面状态怎样更新，游戏规则怎样独立校验，进度怎样可靠落盘。

这篇笔记按案例公开的源码目录和验收步骤整理。重点不是复述界面效果，而是拆开工程边界，给后续做同类离线应用留一套可检查的路径。

三层结构先划清职责

案例把工程分成页面层、数独逻辑层和存储层：

• 页面层由 Index、GamePage、PuzzleListPage 组成，分别负责首页入口、棋盘交互和按难度选题。
• 逻辑层的 SudokuLogic 和 SudokuPuzzleLibrary 不依赖 UI，负责冲突校验、通关判定和题库生成。
• 存储层的 SudokuStore 通过 @ohos.file.fs 直接读写本地文件。

这个拆分让 ArkUI 页面只消费状态，不把规则判断塞进组件事件。填数时，页面把棋盘状态交给纯函数，拿回冲突位置后再刷新棋盘；通关判断同样由逻辑层完成。界面改动不会顺手改坏算法，算法也可以脱离页面检查。

案例中两个入口函数很重要：computeConflicts 返回冲突掩码，棋盘据此高亮同行、同列或同宫的重复数字；isSolved 负责判定整盘是否完成。它们都用固定输入输出验证，截图只能证明某个界面状态，不能替代算法复核。

54 道题如何做到可复现

题库没有在运行时随机拼出任意盘面，而是先准备一个合法的完整终盘，再通过行交换、列交换和数字替换做等价变换，保持数独合法性；最后用确定性 PRNG mulberry32 选择要挖掉的格子。

同一份代码和同一种子会生成同一批题，困难、中等、简单各 18 道，总共 54 道。这比“每次随机、每次结果不同”更适合教学和回归验证，因为排查问题时至少知道题目从哪里来。

这里有一个容易被忽略的边界：案例的盲挖阶段不做唯一解校验，所以每道题都有解，但不保证只有一个解。作为离线练习和课程案例，这个取舍能控制实现复杂度；如果要上线正式题库、做难度评级或把题目同步到云端，就需要增加求解器计数、唯一性筛选和更明确的难度指标。

进度存档为什么直接读文件

进度只保存通关题目的标识，结构可以收敛成 { solvedIds: [] }。案例没有使用 dataPreferences，而是用 @ohos.file.fs 直读应用沙箱 filesDir 下的 sudoku_progress.json。

原因不是文件存储一定优于偏好存储，而是这个场景对跨页面读取新鲜度有要求。案例记录过 dataPreferences 单例缓存导致首页读到旧进度的问题；改成每次 load() 都从磁盘读取后，通关写文件、返回首页刷新这条链路更容易确认。

对应到使用流程：通关时写入文件，首页在 onShow 时重新加载；重置进度时调用 SudokuStore.reset()，把内容改回空数组；卸载应用时沙箱文件自动清除。验收要覆盖“通关后加一、重启后保留、重置后归零”三个状态，而不是只看一次界面提示。

一套可复现的检查顺序

如果要在本地或云端实践环境复现，可以按以下顺序检查：

git clone https://gitcode.com/harmony-practice-center/Harmony-APP-sudoku.git
cd Harmony-APP-sudoku/harmony_app
ohpm install
hvigorw assembleHap --mode module -p module=entry -p product=default -p buildMode=debug --no-daemon

案例给出的 SDK 基线是 compatibleSdkVersion 6.1.0(23)，compileSdkVersion 和 targetSdkVersion 为 6.1.1(24)。命令行安装还需要先完成调试签名，再用 hdc install 安装，用 hdc shell aa start 启动；如果使用 DevEco Studio，直接运行可以省掉手动签名步骤。

启动后不要只确认“页面能打开”。至少依次验证：

1. 同行、同列和同宫重复数字会即时高亮。
2. 预填数字不能修改，正确填满后出现庆祝卡片。
3. 返回首页进度加一，重启应用后仍保留。
4. 重置进度经过二次确认，文件内容回到空数组。
5. computeConflicts、isSolved 和题库不变量用固定样例得到预期结果。

这套顺序把“能运行”和“逻辑正确”分开。前者看启动与交互，后者靠固定输入输出和持久化状态复核。

可以继续往哪里扩展

案例列出的笔记模式、计时与最佳成绩、云题库同步都属于可选拓展。前两项可以继续沿用当前数据流，把候选数字或单局统计并入本地存档；接入云端时则要额外处理题目唯一性、版本迁移、多设备冲突和排行榜的公平性。

棋盘高亮、规则校验和本地存档这组能力也能迁移到扫雷、华容道、记忆翻牌等离线逻辑游戏。真正复用的是分层方式和验证方法，数独只是把问题限制在了一个足够清楚的范围内。