个人记账本（鸿蒙端云一体 App）

使用 ArkTS 开发端侧记账 App，华为云 ECS 自托管 Appwrite 提供数据库、认证与云函数，端云联动完成「记账 → 明细分页 → 云端聚合分类占比统计」的完整闭环。

选择你的阅读路线：想先看到结果 → 快速体验 · 想完整学习 → 完整实践 · 遇到问题 → 验收与排障

1. 案例概览

本项目以一个「一句话需求」为输入，自动完成从需求分析、代码生成到端云联调验收的全链路开发。账目要上云：端侧只带公开的项目 ID 调云函数，业务校验（金额 / 分类 / 归属）与「分类占比图」的聚合逻辑统一收口在云端，密钥只存在于云函数环境变量里。

学到的能力可复用到「账号体系 + 数据列表 + 聚合统计」这类常见端云一体组合，以及任何需要自托管后端（数据库 + 服务端逻辑）而非托管 Serverless 的场景。

用鸿蒙端云一体化开发一个个人记账本，原生鸿蒙 App。云侧采用 ECS 自托管的 Appwrite
账目要上云，并且要有一个云函数在云端聚合出「餐饮/交通…分类占比图」的数据返回给 App 展示。

Appwrite 控制台地址：【IP地址】
管理员账号：【账号】 / 密码：【密码】

有任何不确定的地方，以提问的方式向我确定，优先输出需求文档和开发文档，在我验收没问题后，再继续

核心功能与体验

1. 打开 App 注册 / 登录 → 登录态写入 Preferences，下次启动自动进入主页
2. 在「记账」页选分类、填金额和备注 → 「本月支出」概览卡实时刷新
3. 切到「统计」页切换月份 → 云端按 user_id + 月份 聚合出 7 类「餐饮 / 交通 / 购物 / 娱乐 / 居住 / 医疗 / 其他」占比环形图

记账页	明细分页	统计环形图

技术方案一览

flowchart LR
    A["HarmonyOS App<br/>记账 / 明细 / 统计"] -->|"POST /v1/functions/{fnId}/executions<br/>X-Appwrite-Project 头"| B["Appwrite 1.9.0 自托管<br/>华为云 ECS"]
    B --> C["6 个云函数<br/>node-16 零依赖 CommonJS"]
    C --> D["Appwrite 文档库 account_book_db<br/>users / transactions"]

图里 /v1/functions/{fnId}/executions 是 Appwrite 的云函数执行接口：{fnId} 是目标函数 ID，端侧在 body 字段里塞业务参数 JSON，同步等结果。X-Appwrite-Project 是公开的项目标识头（非密钥），让自托管 Appwrite 路由到对应项目。

一次「记一笔账」会经过：端侧把业务参数 JSON 字符串放进 executions 请求体交给云函数；云函数校验金额 / 分类 / 属主后写入 transactions；「统计」页切换月份时再由 get-stats 云函数在云端拉取该用户当月全部记录并聚合出分类占比，返回给 App 渲染环形图——聚合计算不发生在端侧。

统计页环形图使用 dataviz 校验过的 7 槽浅色分类色板（CVD 安全，即色盲/色弱友好，色值见 Home.ets）。

边界说明

• 本案例聚焦「端云一体」教学闭环，认证用自定义 users 集合实现（自托管 1.9 + node-16 下原生 Auth 联调复杂），不直接覆盖正式上架、HTTPS、细粒度权限与生产级审计。
• 时区按北京时间（UTC+8）硬编码处理（见云函数 bj()）：非东八区部署或跨时区用户，created_at 与「本月」默认归属可能与本地感知错位，生产需改用 Intl.DateTimeFormat 或端侧带时区传 month。
• 云函数 execute 设为 ['any']，配合公开项目 ID 便于端侧无密钥调用，仅适合演示环境；生产请收紧为限定入口并加鉴权（见下文「从演示到生产的最小改造清单」）。

2. 开始之前

先确认下面的准备条件；只列会真正阻塞实践的内容。

环境与资源

hdc 找不到命令：将 hdc 所在目录加入系统 PATH，或临时指定。临时指定只在当前命令行窗口生效，新开窗口需重执一次：

• Windows cmd：set PATH=%PATH%;C:\Program Files\Huawei\DevEco Studio\sdk\default\openharmony\toolchain
• Windows PowerShell：$env:PATH += ";C:\Program Files\Huawei\DevEco Studio\sdk\default\openharmony\toolchain"
• Git Bash / macOS / Linux：export PATH=$PATH:/c/Program\ Files/Huawei/DevEco\ Studio/sdk/default/openharmony/toolchain

路径仅为示意，以本机 DevEco 安装目录为准（DevEco → Settings → SDK 查看）。详见 docs/BUILD.md §6.3。

费用与配额（使用计费能力）

实际价格以官方定价为准；若使用代金券 / 免费额度，请先确认额度和超额风险。

配置与敏感信息（涉及账号、ID 或密钥）

• .env、签名私钥、部署请求体和本地产物必须加入 .gitignore（根目录规则 .env 已覆盖 harmony_cloud/.env）。
• 客户端（rawfile/app.config.json + Config.ets）只带公开的项目 ID 与端点，不得包含 API key / 密码；密钥仅存于开发者本机 harmony_cloud/.env 与云函数环境变量。
• 截图、日志和演示数据发布前必须脱敏。

3. 快速体验

这条路线面向「先把现成案例跑起来」的读者：不需要自己编写代码，拉取我们已验证的成品后，用 AI 编程助手（以下以华为云码道「鸿蒙开发智能体」为例，其他同类 AI 编程助手同样适用）或手动方式把它部署到你的云端环境（详见完整实践），即可开始记账。

前置：本案例不提供 Appwrite 实例，需自备一台可访问的自托管 Appwrite 1.9（/v1/health 返回正常）及其 API key、项目 ID；若从零准备华为云 ECS + Appwrite，先做完整实践（含云账号开通、实名认证、ECS 购买、Docker 安装与 Appwrite 部署，约半天到一天；仅 ECS 已就绪时约 1-2 小时）。本机需 DevEco Studio + HarmonyOS SDK（compile API 24 / 兼容 6.1.0(23)）。

1）获取已验证版本

git clone https://gitcode.com/harmony-practice-center/account_book.git HarmonyOS-APP-account-book
cd HarmonyOS-APP-account-book

完成标志：当前提交对应 v1.0.0，根目录存在 README.md、harmony_app/、harmony_cloud/、docs/ 和 LICENSE。

2）确认工程结构与前置环境

无需编写任何代码，确认以下内容存在即可：

harmony_app/          端侧工程（entry 模块 + 记账 / 明细 / 统计 3 Tab 页面）
harmony_cloud/        云侧工程（建库脚本 + 6 个云函数 + 部署验证脚本）
docs/BUILD.md         执行者手册（云侧部署 / 端侧编译 / 排障）
harmony_cloud/.env.example   环境变量模板（ECS 公网 IP / 项目 ID / API key 占位符）

完成标志：目录结构完整；node -v ≥ 18（部署脚本使用内置 fetch）；DevEco Studio 能打开 harmony_app/。若有不确定之处，可让 AI 助手先检查当前工程是否完整。

3）部署云侧环境（二选一：Agent 或手动）

方式 A：让「码道」部署（推荐，无需修改代码）

打开华为云码道，选择鸿蒙开发智能体，新建空工作区并让助手把当前仓库同步进去，然后发送：

请按本地 docs/BUILD.md 完成云侧部署，无需我修改任何代码：
1. 确认或协助在已装 Docker、放行 80 端口的华为云 ECS 上部署自托管 Appwrite 1.9，
   直到浏览器访问 http://<ECS 公网 IP>/v1/health 返回正常；
2. 在 Appwrite 控制台创建项目和带合法 scope 的 API key（合法 scope 见 docs/BUILD.md §3.2）；
3. 从 harmony_cloud/.env.example 创建 harmony_cloud/.env，并逐项告诉我需要确认的值
   （ECS 公网 IP / 项目 ID / API key）；
4. 敏感值只放 .env 和服务器上，不要在回复和日志中显示原文；
5. 执行 node deploy/init-database.mjs 与 node deploy/deploy-functions.mjs，
   再运行 node deploy/verify-api.mjs。
涉及付费资源、安装软件、开放端口或真实密钥的操作，先说明影响并等我确认。

方式 B：手动部署

按 docs/BUILD.md §3–§5 操作，核心一步：

cd harmony_cloud
cp .env.example .env        # 填入 ECS 公网 IP / 项目 ID / API key（密钥只放 .env，不入库）
bash deploy/deploy.sh       # 一键：初始化数据库 → 部署 6 个云函数 → 端到端验证

云侧脚本调用系统 tar，需在 Git Bash / WSL / macOS / Linux 下运行；想分步排障时可直接执行 init-database.mjs + deploy-functions.mjs + verify-api.mjs（见 docs/BUILD.md §4/§5）。

完成标志：verify-api.mjs 19/19 通过；Appwrite 控制台 6 个函数状态 ready；http://<ECS 公网 IP>/v1/health 可访问。

4）编译并运行端侧

1. 编辑 harmony_app/entry/src/main/resources/rawfile/app.config.json，填 endpoint / projectId（与 .env 一致）。

2. 编译 — 在 harmony_app 目录内，参考 docs/BUILD.md 选择一种方式：

   方法	一句话	适用场景
   A. 命令行	设环境变量 → hvigorw assembleHap	快速、无 IDE
   B. DevEco Studio	打开 harmony_app → Build → Build HAP(s)	日常开发
   C. Agent (CI/CD)	流水线中执行 hvigorw assembleHap	自动打包

   首次编译需先设置环境变量（指向本机 DevEco 安装位置），各方法详细步骤：

   A. 命令行 — Windows (PowerShell)

   $env:DEVECO_SDK_HOME = "<DevEco安装目录>\sdk"
   $env:NODE_HOME       = "<DevEco安装目录>\tools\node"
   $env:JAVA_HOME       = "<DevEco安装目录>\jbr"
   $env:PATH = "$env:JAVA_HOME\bin;$env:NODE_HOME;<DevEco安装目录>\tools\ohpm\bin;<DevEco安装目录>\tools\hvigor\bin;$env:PATH"
   
   cd harmony_app
   hvigorw assembleHap --no-daemon --mode module -p product=default -p module=entry@default --console=plain
   

   A. 命令行 — macOS / Linux (bash)

   export DEVECO_SDK_HOME="/Applications/DevEco-Studio.app/Contents/sdk"
   export NODE_HOME="/Applications/DevEco-Studio.app/Contents/tools/node"
   export JAVA_HOME="/Applications/DevEco-Studio.app/Contents/jbr"
   export PATH="$JAVA_HOME/bin:$NODE_HOME:/Applications/DevEco-Studio.app/Contents/tools/ohpm/bin:/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin:$PATH"
   
   cd harmony_app
   hvigorw assembleHap --no-daemon --mode module -p product=default -p module=entry@default --console=plain
   

   B. DevEco Studio — 日常开发

   1. 打开 harmony_app 目录（File → Open）
   2. 等待项目同步完成（右下角索引完毕）
   3. Build → Build HAP(s)
   4. 产物位于 harmony_app/entry/build/default/outputs/default/entry-default-unsigned.hap

   如果已连接模拟器或真机，也可以直接点击绿色运行按钮 ▶️，自动完成编译 + 安装 + 启动。

   C. Agent — 自动打包

   在 Agent 中输入下述提示词：

   按照下述命令的方式，帮我编译当前目录下的鸿蒙 App
   
   # 设置环境变量（替换为本机路径）
   export DEVECO_SDK_HOME="/path/to/sdk"
   export NODE_HOME="/path/to/node"
   export JAVA_HOME="/path/to/jbr"
   export PATH="$JAVA_HOME/bin:$NODE_HOME:/path/to/ohpm/bin:/path/to/hvigor/bin:$PATH"
   
   cd harmony_app
   hvigorw assembleHap --no-daemon --mode module -p product=default -p module=entry@default --console=plain
   

   不同开发环境的路径差异详见 docs/BUILD.md §6.2。

   完成标志：产物 harmony_app/entry/build/default/outputs/default/entry-default-unsigned.hap 生成。

3. 启动设备并安装 HAP（二选一）：

   • 图形化（推荐）：DevEco Studio → 工具 → 设备管理器 → 启动匹配版本模拟器，把 entry-default-unsigned.hap 拖进模拟器窗口自动安装。
   • 命令行：启动模拟器后用 hdc —— hdc list targets 看到目标设备（模拟器默认 127.0.0.1:5555），再 hdc install -r entry-default-unsigned.hap。找不到 hdc 命令时见第 2 章「测试设备」行的安装与 PATH 说明。

完成标志：模拟器桌面出现「记账本」图标，打开后能进入登录页并完成一笔记账。

4. 完整实践

这条路线面向「理解并复现案例」的读者：从一句大白话的产品想法开始，用 AI 编程助手（vibecoding 对话式开发）从零生成全套端云代码。以下指令以华为云码道「鸿蒙开发智能体」为例，换成其他同类 AI 编程助手同样适用。

新手也不用怕：全程你只需用自己的话描述想法、回答 AI 的问题、确认它给出的方案；需求澄清、技术选型、任务拆分、验收标准这些复杂工作，都由 AI 通过提问引导你完成。每一步都有可观察的完成标志，手动执行的完整命令与故障细节见 docs/BUILD.md。

步骤 1：一句话提出想法，让 AI 帮你想清楚

你发给 AI：

你好，我想做一个鸿蒙记账本 App：账目要存到云上，手机上能记账、看明细，
还能看每个月的分类占比统计。我不太懂技术，请你先问我几个问题，
帮我把需求想清楚，讲得通俗一点。
我想通过华为云 ECS 部署 Appwrite 这样的 BaaS 平台。

提示：加上这最后一句，AI 就会围绕「华为云 ECS 自托管 Appwrite」这个云方案来提问和设计，让最终结果与本案例保持一致；如果你不想限定云端方案，也可以删掉这句，让 AI 自己对比选型。

AI 会通过提问，用大白话帮你定下这几件事：目标用户、第一个版本做哪些功能、数据存在哪、要不要注册登录、统计哪些分类、以及「怎样算做完了」（验收标准）。有拿不准的地方，直接反问它「你建议呢」即可。

完成标志：你回答完问题，AI 把你的需求复述一遍，双方对「做什么 / 不做什么」达成一致。

步骤 2：让 AI 把需求整理成文档

你发给 AI：

把刚才确认的需求整理成 requirements.md，用我能看懂的话写清楚：
功能范围、不做什么、数据与隐私要求、以及每项功能「怎样算做对了」。
有不确定的地方继续问我。

提示：requirements.md 是需求文档的文件名，AI 都认识这个约定，你照抄即可；文档具体怎么写、怎么算完整，AI 会代劳并用大白话讲给你听。

完成标志：AI 生成需求文档，并把要点讲给你听；你确认无误后再进入下一步。

步骤 3：让 AI 设计技术方案

你发给 AI：

需求没问题，请设计一套便于学习和部署的端云方案：
数据存在哪、云函数做什么、App 怎么调、密钥放哪、怎么验收。
方案里有需要我做取舍的地方，用大白话讲清楚影响，我确认后再定。

AI 会基于你第 1 步定下的云端方案（华为云 ECS 自托管 Appwrite，整体架构见第 1 章）来设计，用大白话回答「数据存哪、云函数做什么、端侧怎么调、密钥放哪、怎么验收」，并把需要你拍板的取舍讲清楚；它通常会把方案整理成 design.md 文件留存。

完成标志：你听懂这套方案（数据存哪、云函数做什么、端侧怎么调、密钥放哪、怎么验收），并完成 AI 给出的取舍选择。

步骤 4：让 AI 拆成可持续推进的任务

你发给 AI：

方案可以。请把开发拆成几小批，每批做完能自己验证，做完一批再进下一批。
先给我任务清单，我确认后你再开始写代码。

提示：AI 会把这份任务清单整理成 tasks.md，并在每完成一批后更新它，方便你随时看到进度。

完成标志：AI 给出分批任务清单（每批写明做什么、怎么验证、完成标志），你确认后进入编码。

步骤 5：按批次生成和验证代码（本地可编译）

从这一步开始，所有「你发给 AI」的指令都可以直接照抄发送，你不用理解里面的术语（比如 hvigor、云侧脚本）；第 5 步把批次信息填进模板，后面几步整段发送即可。遇到报错，也把现象直接发给 AI。

注意：这一步只在本地验证两端代码能否各自编译，不涉及真正的云端部署（云端部署在第 6 步）。

每一批使用下面的指令模板，将 {批次} 和 {本批范围} 换成任务清单中的内容：

现在开始第 {批次} 批：{本批范围}。
开始前请读取 requirements.md、design.md 和 tasks.md，确认本批依赖已经满足。
按照任务顺序创建或修改文件；每完成一项就更新 tasks.md。
完成本批后进行本地校验（云侧脚本语法检查、端侧 hvigor debug 构建），
先把编译问题就地修复到通过，再汇总：改了哪些文件、验证结果、已知问题、
下一批的前置条件，然后等待我确认。

完成标志：本批两端代码在本地可编译（端侧 BUILD SUCCESSFUL、云侧脚本语法通过）；云端尚未部署，也不需要它参与。

步骤 6：让 AI 部署云侧并自测

你发给 AI：

本地代码已就绪。请先依据 docs/BUILD.md §3 给出云侧部署计划、所需费用和需要我确认的操作（ECS 规格、地域、付费方式、80 端口放行），说明影响后等我确认。
确认后协助在 ECS 上部署自托管 Appwrite 1.9，创建项目与带合法 scope 的 API key；
生成 harmony_cloud/.env；执行 init-database.mjs 和 deploy-functions.mjs 完成建库与部署云函数；
最后跑 verify-api.mjs 复核，报错就在云端就地修复到全绿。

完成标志：Appwrite 已可访问，6 个云函数状态 ready，verify-api.mjs 全绿（19/19）。

步骤 7：编译 App、装进模拟器，做端云联调验收

云端已在第 6 步就绪，这一步开始真正「端云打通」。

你发给 AI：

云端已就绪。请先把端侧指向已部署的云端，编译并安装到匹配版本的模拟器，然后执行一轮端云联调验收：
1. 注册账号 → 登录 → 记 7 笔支出（覆盖 6 个分类）→ 明细分页 → 切月查看分类占比环形图 → 删除一笔 → 非法输入 / 越权操作被拒；
2. 重启 App，检查登录态保留与数据正常；
3. 检查 hilog 无 FATAL / JsError / CppCrash。

编译或联调报错时，定位代码、修复、重新编译并回归，直到全部通过。
最后输出端云联调验收表与仍建议人工体验的项目。

完成标志：App 在模拟器里完成一整套端云联调（注册 → 记账 → 统计 → 删除全通），AI 输出验收表。

步骤 8：最终复核与收尾（报告 / 安全 / 清理）

你发给 AI：

联调已全部通过。请做一轮最终验收与收尾：
1. 云端复核 verify-api.mjs 19 项全绿；
2. 安全与脱敏检查：.env 和含敏感信息的文件不入库，端侧只含公开项目 ID，日志与截图无真实凭据；
3. 输出验收报告（验收环境 / 版本 / 结果），并给出清理与回滚步骤（如何删测试数据、停用或释放资源）。

完成标志：验收报告完整可执行，清理 / 回滚方法明确；账目数据已上云，App 可正常使用。

提示：实践过程中遇到任何报错或不符合预期的行为，直接把现象发给 AI，它会分析代码并修复——这种「描述 → 修改 → 编译 → 复查」的对话式开发，就是本案例推荐的 vibecoding 方式。

5. 验收与排障

业务验收

技术检查与验收环境

• 端侧可编译、安装和启动。
• 云侧健康检查通过，核心接口返回 {code,message,data} 约定结构。
• 核心数据可写入、读取并在端侧正确展示。
• 错误场景反馈清楚，日志中无真实凭据或未处理异常。

高频问题

排查顺序：环境与版本 → 配置与权限 → 网络与资源状态 → 云侧日志 → 接口响应 → 端侧日志。

完整故障库：见 docs/BUILD.md §8「故障速查」。

6. 安全与清理（涉及云资源、账号或个人数据）

实验配置与生产要求

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

上面表格给了方向，具体可按这 6 项动手（Appwrite 字段语义以 官方文档 为准）：

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

清理资源

清理会删除实验资源和数据。先核对资源名称、区域、项目和依赖关系，并导出需要保留的数据。

1. 删除测试数据与临时云函数（只清理本项目所属的集合 / 函数）。
2. 删除项目专属的 API key，收回临时凭据。
3. 释放弹性公网 IP 与 ECS 实例（如不再使用），停止计费。
4. 删除本地 harmony_cloud/.env、构建产物与含敏感信息的日志。

完成标志：计费控制台中不存在本案例的持续计费资源，临时凭据已撤销。

7. 项目导览与进阶

关键目录

HarmonyOS-APP-account-book/
├── README.md                  # 案例入口与学习主线（本文档）
├── LICENSE                    # MIT 许可证
├── docs/
│   ├── BUILD.md               # 构建 / 部署 / 排障 / 回滚（执行者手册）
│   └── images/                # README 截图（已提交，发布前须脱敏）
├── harmony_app/               # HarmonyOS 端侧工程
│   ├── AppScope/app.json5     # bundleName com.example.accountbook / versionName 1.0.0
│   ├── build-profile.json5    # compile API 24 / 兼容 6.1.0(23)
│   └── entry/src/main/
│       ├── ets/
│       │   ├── entryability/EntryAbility.ets
│       │   ├── pages/Login.ets    # 登录 / 注册
│       │   ├── pages/Home.ets     # 3 Tab：记账 / 明细 / 统计（含环形图）
│       │   └── utils/             # Config（读 rawfile）/ HttpUtil / Session
│       └── resources/rawfile/app.config.json  # 端点 / 项目 ID（占位符入库，填本机值后不入库）
└── harmony_cloud/             # 云侧工程（ECS 自托管 Appwrite）
    ├── database/schema.appwrite.json   # users / transactions 集合 / 属性 / 索引定义
    ├── functions/<函数名>/index.js     # 6 个零依赖云函数（含 _lib.js）
    └── deploy/                # 一键部署：deploy.sh + init-database / deploy-functions / verify-api

完成回顾

完成本案例后，你已经：

• 掌握端侧三 Tab 页面与 Preferences 登录态的常见写法；
• 理解「业务校验 + 统计聚合收口云端」的职责划分及其原因；
• 走通自托管 Appwrite 建库 → 部署云函数 → 端侧联调 → 端到端验证的脚本化流程；
• 绕开 Appwrite 1.9 + node-16 的 8 个实测坑（CommonJS、JSON 查询、float 精度、limit 100、scrypt、时区、entrypoint、分页，详见 docs/BUILD.md §4.1）。

深入阅读与扩展

• 构建 / 部署 / 排障 / 回滚与清理
• HarmonyOS 应用开发文档
• Appwrite 官方文档（含自托管）

扩展方向：接入 HTTPS 与自有域名；改 Appwrite 原生 Auth 或正式签名上架；增加收入 / 预算与多端同步；把 get-stats 扩展为按月汇总报表下钻。

8. 参考与维护

官方资料与帮助

• HarmonyOS 应用开发官方文档
• Appwrite Docs（含自托管部署）
• 使用问题：在仓库提 Issue。

维护与版本

• v1.0.0（2026-08-19）：端云一体化完成，注册 / 登录 / 记账 / 明细分页 / 删除 / 占比环形图验收通过，verify-api.mjs 19/19。

许可证

本项目采用 MIT。第三方依赖及素材遵循各自许可证。