鸿蒙个人记账本案例拆解：端云一体架构与云端聚合统计的落地要点

一、为什么选这个案例

鸿蒙开发实践中心的「个人记账本」案例（harmony-practice-center/account_book）是我这两天逐个跑通实践案例里，最能体现"端云一体"设计取舍的一个：手机上记账是弱网高频操作，统计报表却是低频重计算，两者放进同一套数据模型就会互相拖累。案例把这条边界画得很清楚，值得逐层拆开看。

二、整体架构：三层职责分离

把工程目录摊开，职责基本落在三层：

• UI 层（ArkUI）：账单列表、记账表单、统计图表。状态用 @State / @Observed 管理，页面之间靠 Navigation 传递账单 ID 而不是整个对象，避免大对象跨页序列化。
• 领域层：账单实体 + 分类枚举 + 金额精度处理。金额统一用"分"作整数存储，展示时再除 100，这一条在记账类应用里几乎不能妥协，用浮点迟早对不上账。
• 数据层：本地关系型数据库负责"随时可写"，云端（Appwrite）负责"多端可见 + 聚合统计"。写入先落本地，再异步同步，同步失败不影响用户继续记。

三、云端聚合统计的关键点

统计不做在客户端，而是交给云端聚合。原因很直白：按月/按分类的汇总需要扫全量历史，手机端做这件事既费电又容易因为本地数据不完整而算错。

落地时有三个细节必须处理：

1. 同步水位线：本地维护 lastSyncAt，只推增量，避免每次全量上传。断网期间的记录在恢复后按时间戳补推。
2. 幂等写入：每条账单带客户端生成的 UUID 作为主键，重复推送不会产生重复账目。这一步省掉，弱网重试就会把账记两遍。
3. 聚合口径对齐：客户端展示的"本月支出"和云端返回的聚合值必须同口径（是否含转账、是否含退款）。案例里把口径写进常量并随请求带上，避免版本升级后前后端算法漂移。

四、实际动手时值得注意的几处

• 数据库迁移：关系型数据库的版本号一定要在第一次发布前就想清楚，后面加字段要靠 upgrade 回调，临时改表结构在真机上会直接抛错。
• 列表性能：账单列表用 LazyForEach + 数据源，不要用 ForEach 直接渲染上千条。滚动卡顿基本都出在这一处。
• 离线优先的 UI 反馈：写入本地成功后立刻更新界面、把同步状态做成小角标（已同步/待同步），比转圈等待体验好得多，也让"数据有没有丢"这件事对用户透明。
• 云侧权限：Appwrite 的集合权限要按用户维度限制，别图省事开成任意读。记账数据属于隐私数据，读取规则写错一次就是事故。

五、和成长中心其他实践串起来

这个案例的代码仓就在 GitCode 的 harmony-practice-center 组织下，配合鸿蒙开发实践中心的案例详情页一起看效率最高：先看架构说明，再对着源码找对应模块，最后把记账本跑起来验证。顺手把仓库 Star 一下，成长中心的"每日 Star 一个鸿蒙案例代码仓"任务也会一起完成。

另外，如果本地环境配置嫌麻烦，可以直接用华为云 AI 开发者空间的体验版：容器秒级启动、不消耗额度，在里面开 AI Shell 让助手帮忙解释代码或生成一段 Terraform/脚本都很顺。我这两天的实践基本是"本地 IDE + 云端 AI Shell"两条腿走路，遇到看不懂的模块就丢给 AI Shell 让它讲一遍调用链。

六、小结

这个案例真正值得抄的不是某段 ArkUI 代码，而是它对"哪些事必须在端上做、哪些事必须交给云"的划分：写入在端、聚合在云、同步靠幂等增量、金额用整数。把这条线守住，记账类应用最常见的对不上账、多端不同步、统计口径漂移三个坑基本都能提前规避。