鸿蒙个人记账本实战笔记：端云一体记账与云端聚合统计

今天在鸿蒙开发实践中心跟完了“个人记账本：鸿蒙端云一体记账与云端聚合统计”这个进阶案例（案例版本 v1.0.0，最后验证于 2026-08-19）。和之前做过的单词打卡、数独这类以端侧为主的案例不同，这只记账本的核心在“端云一体”四个字上：手机端只负责记账、看明细、看统计，金额校验、分类聚合、密码安全这些真正不能出错的逻辑，全部收口在云端。本文把这次实践的关键链路、文档里明确写出的实测坑，以及从演示到生产的改造点整理成笔记。

一、成品长什么样：三 Tab 加六个云函数

端侧是一个 ArkTS 三 Tab 应用：记账页、明细页、统计页。打开 App 先注册、登录，登录态写进 Preferences，下次启动自动进入主页；在记账页选分类、填金额和备注，“本月支出”概览卡实时刷新；切到明细页可以分页翻看账目、删除一笔；切到统计页切换月份，就能看到当月 7 类支出（餐饮、交通、购物、娱乐、居住、医疗、其他）的占比环形图。

云侧是一台华为云 ECS 上自托管的 Appwrite 1.9，数据库 account_book_db 里只有两个集合：users（账号）与 transactions（账目）。业务全部由 6 个 node-16 零依赖 CommonJS 云函数承接：register、login、add-transaction、list-transactions、delete-transaction、get-stats。端侧调云函数的入口只有一个：POST /v1/functions/{fnId}/executions，带上公开的 X-Appwrite-Project 头，把业务参数 JSON 字符串放进 body 同步等结果。一次“记一笔账”的链路是：端侧发 executions 请求，add-transaction 校验金额、分类、属主后写入 transactions；统计页切换月份时，get-stats 在云端拉取该用户当月全部记录做聚合，把分类占比返回给 App 渲染环形图，聚合计算不发生在端侧。

为什么宁可多一次网络请求也要把校验和聚合放云端？记账是最典型的“金额不能错、别人的账不能改”的场景。金额、分类、归属一旦只在端侧校验，任何一个被绕过的客户端就能往库里写脏数据；聚合放云端则保证了同一批数据、同一份口径，端侧只做展示。这个取舍是本案例最值得带走的架构经验：端侧做体验，云端做正确性。

二、数据与约束：先把规则钉死，再写页面

transactions 的核心约束在文档里写得很具体，也正是联调验收要逐条验证的：金额必须大于 0，最多两位小数；分类只能是 7 类固定枚举，多一类少一类都会被云函数拒绝；日期固定 YYYY-MM-DD 格式；删除一笔账只能删自己的，他人数据删除会被拦截。

约束之所以放在云函数而不是端侧表单里，是因为端侧校验只能防“手滑”，防不了“故意”。验收表里专门有一项“非法输入、越权操作被拒”，要求负数金额、他人数据删除均被拦截，并返回明确错误码。写代码时我反复对照这条：先在云函数里把规则写死，再回头做端侧的友好提示，顺序不要反。

密码安全是另一处值得单拎出来写的地方：密码不落明文，存储格式为 scrypt$N$salt$hash，用 node:crypto 的 scrypt 做加盐哈希，比对时用 timingSafeEqual 做常量时间比较，防止攻击者通过响应耗时猜测密码。案例文档特别提醒，这套自定义 users 集合认证是自托管 1.9 加 node-16 下的教学取舍，并不直接覆盖正式上架、HTTPS、细粒度权限与生产级审计，学习时可以抄思路，上生产要按第六节的改造清单升级。

三、部署链路：脚本化，但有三处容易卡住

案例提供“快速体验”和“完整实践”两条路线。快速体验是拉取已验证的成品仓库，再用码道“鸿蒙开发智能体”或手动方式部署；完整实践则是从一句话需求出发，用 AI 编程助手以 vibecoding 对话方式从零生成全套端云代码，分 8 步走完需求、设计、任务拆分、编码、部署、联调、收尾，每一步都有可观察的完成标志。

我按快速体验走，核心命令其实只有几步：

git clone https://gitcode.com/harmony-practice-center/account_book.git HarmonyOS-APP-account-book
cd harmony_cloud
cp .env.example .env
bash deploy/deploy.sh

但有三个点第一次做很容易卡住，案例文档的“高频问题”里也都写了：

1. 云侧部署脚本调用系统 tar，必须在 Git Bash、WSL、macOS 或 Linux 下运行，Windows 原生 cmd 会失败；想分步排障可以直接执行 init-database.mjs、deploy-functions.mjs、verify-api.mjs。
2. 创建 API key 时 scope 报错“非法”：平台上 platforms.、account. 这类列表里有但不可用的 scope 不能勾，只能用 BUILD 文档 3.2 节清单中的合法 scope。
3. 首次调用超时：云函数冷启动实测约 1.5 秒，端侧要有重试策略，函数超时设 30 秒；同时注意 executions 返回 201，响应包在外层包了一层 responseBody，HttpUtil 要按 201 判成功并解包，否则就会“端侧收不到数据”。

另外三处也值得记下来：Appwrite 查询要用 JSON 字符串格式，旧格式 equal(“a”,“b”) 会报 Invalid query: Syntax error；Appwrite 单次查询 limit 是 100，明细分页和 get-stats 的全量拉取都要按这个上限设计；时区按北京时间（UTC+8）在云函数 bj() 里硬编码处理，非东八区部署或跨时区用户，“本月”的默认归属可能错位，生产要改用 Intl.DateTimeFormat 或端侧带时区传 month。

部署完成的标志很明确：verify-api.mjs 19 项端到端验收全绿、Appwrite 控制台 6 个函数状态 ready、http://<ECS 公网 IP>/v1/health 可访问。端侧配置在 harmony_app/entry/src/main/resources/rawfile/app.config.json 里填 endpoint 与 projectId（与 .env 一致），编译用 hvigorw assembleHap 或 DevEco Studio 的 Build HAP(s)，产物是 harmony_app/entry/build/default/outputs/default/entry-default-unsigned.hap，拖进模拟器或用 hdc install -r 安装，就能在模拟器看到“记账本”图标。

环境准备上，ECS 建议 2vCPU / 4GB 起、40GB 以上云硬盘、装好 Docker，安全组放行 80 端口。有意思的是，同一天我在 AI Shell 里追问过一个相关问题：运行中的 ECS 实例挂载 EVS 云硬盘后系统里看不到新磁盘该如何排查。AI Shell 给出的排查链路是先确认控制台挂载状态与实例、磁盘同可用区，再在系统里用 lsblk、fdisk -l 看设备是否出现，未出现就重扫 SCSI 总线，出现后区分“全新盘要分区格式化挂载”与“已有数据盘要按 UUID 写 /etc/fstab”。这正好是本案例 ECS 环境准备的前置技能：云硬盘挂载这一层没通，后面 Appwrite 的数据卷也没法落盘。

四、验收：19 项全绿才是“做完了”

案例的验收分两层。第一层是云侧脚本 verify-api.mjs 的 19 项端到端验收，覆盖注册、登录、记账、明细、统计、删除与非法输入；第二层是 6 项业务联调验收：注册新账号，登录成功进入主页，users 集合出现新记录；记 7 笔支出（覆盖 6 个分类），概览卡与明细列表出现记录；切换统计页月份，环形图按当月 7 类占比渲染，get-stats 返回 categories 且占比和为 100%；删除一笔，列表与统计同步移除，数据库中该文档被删；非法输入、越权操作被拒，返回明确错误码；全程无崩溃，hilog 无 FATAL、JsError、CppCrash。

我在这一步的体会是：验收脚本不是“跑完就行”，而是开发过程的刻度。案例把“怎样算做完了”写成可执行的脚本和一张表，比口头说“功能都实现了”可靠得多；以后自己做端云项目，也应该先把这类验收表写出来，再动手写业务代码。

五、从演示到生产的最小改造清单

案例文档第六章把演示配置与生产要求对照得很坦率，值得原样记下来，动手做的顺序也按这个来：

1. 收紧集合权限：移除 read(“any”) 与 documentSecurity: false，改为仅 API key 服务端访问或 documentSecurity: true 配合按用户授权。当前配置下任何人只要知道项目 ID 就能读全部数据（含密码哈希），必须优先关闭。
2. 收紧函数执行入口：把 execute: [‘any’] 改为 [‘users’] 或 [‘user:<uid>’]，让未登录调用直接被网关拦截。
3. 接 Appwrite 原生 Auth 或 JWT：登录改走 Appwrite Account API，业务函数从认证上下文（req.headers[‘x-appwrite-jwt’]）派生 user_id，不再信任客户端传入。
4. 上 HTTPS 与自有域名：在 ECS 前加 Nginx 或 Caddy 反代加证书，端侧 endpoint 改为 https://。本案例密码以明文经 HTTP 传输，生产必须加密。
5. API key 最小权限加轮换：只授必要 scope，定期轮换。
6. 限流与审计：在反代层限流，开启 Appwrite 的 log.read/write，定期导出访问日志。

另外三点同样重要：.env、签名私钥与本地产物必须加入 .gitignore，根目录的 .env 规则已覆盖 harmony_cloud/.env；客户端只带公开的项目 ID 与端点，密钥只存本机 .env 与云函数环境变量；截图、日志与演示数据发布前必须脱敏。实践结束后按清单清理：删测试数据与临时云函数、删项目专属 API key、释放弹性公网 IP 与 ECS 实例、删本地 .env 与构建产物，计费控制台里不再有持续计费资源才算收尾。

六、小结

这只记账本案例的难度标的是进阶、180 分钟，8 个核心知识点，覆盖端侧三 Tab 页面与 Preferences 登录态、云函数收口业务校验与统计聚合、自托管 Appwrite 建库、部署、验证的脚本化流程。它真正教的东西不是“写一个记账 App”，而是一套可复用的端云一体组合：账号体系加数据列表加聚合统计，这个组合换个壳就是待办、打卡、订单列表。下一步我打算沿着文末的扩展方向走两步：先把 get-stats 扩展成按月汇总报表下钻，再把 execute: any 收紧为按用户授权，顺手把这篇笔记里的改造清单逐项落地。

仓库：GitCode harmony-practice-center/account_book，案例版本 v1.0.0；验证环境：compile API 24、兼容 6.1.0(23)，Appwrite 1.9.0，node-16.0，hvigor 6.24.4。