单词打卡学习（HarmonyOS 应用 + Appwrite Serverless）

使用 ArkTS 和 Appwrite 自托管 Functions 构建一个卡片式单词打卡应用，支持闪卡学习、看词选义测试、进度条与连续打卡。

项目	内容
适合谁	有 HarmonyOS 或后端基础、想学习 Appwrite 端云一体化开发的工程师
难度与耗时	入门 · 新手预计 1.5–2.5 小时
你将学到	ArkTS 端侧开发；Appwrite Functions 编写规范；NoSQL 文档数据库设计；Appwrite 自托管部署与排障
你将完成	可运行的 HarmonyOS 应用、6 个云函数、3 个数据集合（58 词词库）及端云联调验收
验证环境	HarmonyOS / DevEco Studio / Appwrite 自托管 v1.9.0 · 最后验证于 2026-08-14

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

1. 案例概览

单词打卡学习是一个卡片式背单词应用，演示「HarmonyOS 端侧 + Appwrite 自托管 Serverless 云侧」的端云一体化开发流程。与华为云 FunctionGraph/APIG 方案不同，Appwrite 用内建 HTTP 路由 + 文档型 NoSQL，省去了独立 API 网关层。本案例覆盖闪卡学习、测试、打卡统计等完整闭环， 沉淀的 Appwrite Functions 规范与自托管排障经验可复用到其他 Appwrite 后端场景。

核心功能与体验

1. 用户注册并登录 → 进入首页，醒目位置显示今日打卡状态与连续打卡天数。
2. 首页展示今日 10 个未学单词 → 进入闪卡模式，点击卡片翻转查看释义。
3. 完成看词选义测试 → 答对计入学习进度，进度条更新。
4. 学完一个单词 → 打卡状态变为「已完成」，连续天数正确累加。

单词打卡页	单词测试页

技术方案一览

flowchart LR
    A["HarmonyOS App（ArkTS，4 页面）"]
    B["Appwrite Functions（Node.js 16，6 个）"]
    C["Appwrite Database（word_db，文档型 NoSQL）"]
    
    A -->|"POST /v1/functions/{id}/executions"| B
    B --> C

一次核心业务操作（如记录学习）的链路：App 通过 POST /v1/functions/{id}/executions 调用 Function 执行端点，Function 用 Server SDK（API Key）读写 Database，再把结果包在 responseBody 里返回 App。端侧不直接持有数据库凭据，Function 执行端点是唯一入口。

层级	技术/产品	验证版本	作用
端侧	ArkTS / ArkUI	DevEco Studio	4 个页面（登录、首页、闪卡、测试）
云侧	Appwrite Functions	自托管 v1.9.0 / Node.js 16	6 个函数承载注册、登录、取词、进度、学习记录
数据	Appwrite Database	文档型 NoSQL	word_db 库：users_col / words_col / learn_records_col
工具	DevEco / hvigor / hdc	—	编译、构建与安装 HarmonyOS 应用

边界说明

• 本案例面向学习与演示，函数 execute=["any"] 为无鉴权公开访问，不包含正式上架所需的鉴权、限流等生产化改造。
• 自托管 Appwrite 的可用运行时取决于服务器配置，部署前需确认 node-16.0 可用。

2. 开始之前

先确认下面的准备条件，通用安装教程优先参考官方文档。

环境与资源

项目	要求	检查或获取方式
基础知识	ArkTS、HTTP、数据库基础	可选：HarmonyOS 官方 ArkTS 教程
开发环境	Windows/macOS、DevEco Studio、Node.js、Python 3.8+	node -v、python --version、DevEco 界面路径
Python 依赖	无（deploy.py 仅用标准库）	无需 pip install
测试设备	模拟器或真机	hdc list targets
账号与服务	自托管 Appwrite 服务器可达、项目与 API Key 已建	GET /v1/health 返回 pass
权限与网络	服务器 80 端口可达；API Key 含 functions/databases 权限	GET /v1/functions 正常返回

费用与配额

资源	建议规格	计费方式	实践预计费用	结束后如何处理
Appwrite 自托管	单机服务器	自托管	服务器自身成本	删除测试函数与集合

价格验证日期：2026-08-14。自托管方案无按量计费的云资源，主要成本为承载服务器的费用。

配置与敏感信息

占位符	含义	获取位置	安全存放位置
APPWRITE_HOST	服务器地址	服务器 IP + 端口	端侧公开配置
<project_id>	Appwrite 项目 ID	控制台 → 项目设置	端侧公开配置
<api_key>	服务器级 API Key	控制台 → API Keys	仅函数环境变量 / .env

• .env、签名私钥、部署请求体和本地产物必须加入 .gitignore。
• 客户端不得包含 API Key；函数用 Server SDK 在服务端持有。

3. 快速体验

这条路线面向「先把现成案例跑起来」的读者，目标是约 1–2 小时（含一次性云环境准备）内看到第一个成功结果。原理和完整搭建过程见完整实践。

0）用 AI 辅助配置云环境（可选）

想跳过下面的手动步骤？把本仓库 README.md 与 SKILL.md 交给 AI 编程助手（码道 / CodeArts、Cursor 等），让它读完自动配置并部署云环境：

请阅读本仓库 README.md 与 SKILL.md，帮我自动配置并部署「单词打卡」云环境：
1. 按第 2 章「配置与敏感信息」列出需要我填写的占位符（Appwrite 地址、Project ID、API Key），等我填好 harmony_cloud/.env；
2. 运行 deploy/deploy.py 部署 6 个云函数（自动 npm install 并打包 tar.gz）；
3. 调用 db-init 建集合与种子数据；
4. 把服务器地址与 Project ID 填入 HttpUtil.ets，编译并安装端侧；
5. 按第 5 章验收表逐项联调。
每完成一步报告结果；报错时贴完整日志并定位根因；API Key 只写本地 .env，不写入代码、不提交仓库。

注意：AI 只能操作你授权的环境。API Key 等敏感信息请只放在本地 .env（已被 .gitignore 忽略），不要让 AI 把凭据写进代码或提交。部署完成后，仍建议按下面各步骤的「完成标志」人工复核一遍。

1）获取已验证版本

git clone https://gitcode.com/harmony-practice-center/word-check-in.git
cd word-check-in

完成标志：根目录存在 README.md、harmony_app/ 和 harmony_cloud/。

2）准备最小配置

cp harmony_cloud/.env.example harmony_cloud/.env

1. 将 .env 中的 API Key、APPWRITE_HOST、Project ID 替换为第 2 章收集的值。
2. 在 harmony_app/entry/src/main/ets/utils/HttpUtil.ets 填入 APPWRITE_HOST 和 PROJECT_ID。

完成标志：没有未替换占位符；敏感配置不会出现在 git status 中。

3）启动云侧

cd harmony_cloud
python deploy/deploy.py
curl -X POST http://<host>/v1/functions/db-init/executions \
  -H "Content-Type: application/json" \
  -H "X-Appwrite-Project: <project_id>" \
  -d '{"body":"{}","async":false}'

deploy.py 会为每个函数自动执行 npm install --omit=dev 并打包依赖，无需手动安装 node-appwrite。

完成标志：db-init 执行后，word_db 下 3 个集合、58 个单词和管理员 admin@company.com / 123456 已创建。

4）构建并运行端侧

首次编译前，先用 DevEco Studio 打开 harmony_app 目录，让它自动生成 local.properties（填入 sdk.dir）；命令行编译还需设置环境变量 DEVECO_SDK_HOME。缺失会报 00303217，sdk.dir 被改写会报 00308018，路径含空格会报 Space is not supported in HVIGOR_USER_HOME。详见 SKILL.md 的「全量故障速查表」。

Set-Location 'harmony_app'
ohpm install
hvigorw assembleHap --mode module -p module=entry -p product=default -p buildMode=debug --no-daemon
hdc install -r entry/build/default/outputs/default/entry-default-unsigned.hap

完成标志：生成 HAP 并安装到设备，应用能启动到登录页并完成一次登录。

4. 完整实践

这条路线面向「理解并复现案例」的读者。步骤按真实工作流排列，每一步都有可观察的完成标志。云函数编写规范、代码模板、打包与排障细节见 SKILL.md。

一句话让 AI 工作

不想手动逐项操作？把下面这句话发给码道（华为云 CodeArts 鸿蒙开发智能体，或任意支持 HarmonyOS / Node.js 的 AI 编程助手），即可让它从需求澄清一路推进到端云联调。你也可以把词库规模、打卡规则换成自己的版本。

我想开发一款「单词打卡学习」HarmonyOS 端云一体化应用：端侧 ArkTS/ArkUI（登录、首页、闪卡、测试 4 个页面），云侧 Appwrite 自托管 Functions（Node.js，6 个云函数）+ Appwrite Database（word_db，3 个集合、58 词词库），支持注册登录、每日单词列表、闪卡翻转学习、看词选义测试、进度条与连续打卡。

请按照标准研发流程推进：先提问澄清需求，再依次产出 requirements.md、design.md、tasks.md；然后分批实现 6 个云函数（注意 ESM 默认导出、node-appwrite v11、execute=["any"]）、3 个集合的数据模型和端侧页面；最后给出部署（deploy.py 打包上传）与端云联调验收步骤。

每一步都要有可观察的完成标志，关键节点停下来等我确认。

如何指挥 AI 工作

「一句话」只是开工信号，真正决定质量的是后续每一轮的指挥方式：

• 一次只给一个明确目标：每轮指令聚焦单一产出（需求 / 设计 / 任务 / 某一批代码 / 部署），让 AI 给出可观察结果，而不是一次铺开。
• 要求可观察的完成标志：每步都让 AI 明确「做完是什么样子」，你据此判断能否进入下一步。
• 关键节点人工确认：需求澄清、技术选型、Appwrite 配置、部署上线等不可逆或高成本节点，先看 AI 的方案再放行。
• 把真实报错带回去：编译或部署失败时，把完整日志原文贴给 AI 定位，而不是让它凭空猜测。

下面的步骤 1–5 每一步都附了「推荐指令」，可照此逐条指挥 AI；想对照手动操作时，看同一步骤的「操作」。

步骤 1：确认 Appwrite 服务器与收集信息

目标：确认自托管 Appwrite 可用，收集 Project ID 与 API Key。

为什么这样做：自托管环境的可用运行时与端口取决于运维配置，先确认能避免后续部署返工。

推荐指令：

请帮我梳理这个案例需要确认的 Appwrite 环境信息：服务器地址、Project ID、API Key（含 functions 读写、databases 读写权限）、可用运行时（node-16.0）。把每项的获取位置和安全存放位置整理成表，并给出 /v1/health、/v1/functions/runtimes 等健康检查与权限验证方式。

操作：

1. 访问 /v1/health 确认服务器 pass。
2. 在控制台创建项目，记录 Project ID。
3. 创建 API Key（含 functions.write/read、databases.write/read 权限）。
4. 调用 GET /v1/functions/runtimes 确认可用运行时（本例 node-16.0）。

完成标志：信息清单填齐，APPWRITE_HOST / <project_id> / <api_key> 均可用。

如果失败：missing scopes (["projects.read"]) 说明 API Key 权限不足，用 GET /v1/functions 验证，见验收与排障。

步骤 2：编写并打包 6 个云函数

目标：在本地把 6 个云函数代码写对，并装好依赖备打包。

为什么这样做：Appwrite v1.9.0 不会自动安装依赖，且函数入口用 ESM 默认导出，写错会导致运行时报错。

推荐指令：

请按 Appwrite Functions 编写规范实现 6 个云函数（register、login、getDailyWords、learnWord、getProgress、db-init）。注意：ESM 默认导出、node-appwrite@^11.0.0（Node 16 兼容）、Server SDK 用 API Key 读写数据库、统一 {code,data,msg} 返回。完成后给出每个函数的依赖安装与 tar.gz 打包要求（根目录含 main.js + node_modules）。

操作：

1. 按 SKILL.md 的「云函数编写规范」与「代码模板」编写 6 个函数。
2. 每个函数目录执行 npm install --omit=dev（依赖 node-appwrite@^11.0.0）。

完成标志：6 个函数目录都含 main.js、package.json 和 node_modules/node-appwrite。

如果失败：EBADENGINE 说明 node-appwrite v14 与 Node 16 不兼容，降级到 ^11.0.0。

步骤 3：部署云侧（手动或自动，二选一）

目标：把 6 个函数部署到 Appwrite，配置环境变量与 execute=["any"]，并初始化数据库。

为什么这样做：手动路线便于逐项确认权限与运行时，自动路线适合批量复用；两条路线产出相同，交叉创建同名资源会导致冲突。

推荐指令：

请编写部署脚本 deploy.py（为每个函数执行 npm install --omit=dev 并打包成 tar.gz 上传），并说明 db-init 建集合与种子数据（3 个集合、58 个单词、管理员 admin@company.com / 123456）的执行方式。同时给出为每个函数配置 API_KEY、DATABASE_ID 环境变量与 execute=["any"] 的要点。

操作：

1. 选择一条路线：手动在控制台逐项创建，或自动用 Python 脚本（见 SKILL 的「部署与打包」）。
2. 为每个函数设 API_KEY、DATABASE_ID 环境变量，并显式设 execute=["any"]。
3. 打包 .tar.gz 上传（根目录含 main.js + node_modules）。
4. 调用 db-init 完成建库、建集合与种子数据。

完成标志：6 个函数调用全部返回 code:0，word_db 下 3 个集合与 58 个单词就绪。

如果失败：storage_file_type_unsupported（传了 .zip）、Param "functionId" is not optional（functionId 放错位置）等见 SKILL 的「全量故障速查表」。

步骤 4：配置、编译并安装端侧

目标：把服务器地址与 Project ID 填入端侧，编译并安装 HAP。

为什么这样做：端侧通过 HttpUtil.ets 指向 Appwrite 执行端点；SDK 版本、工具链路径等环境问题会阻塞编译。

推荐指令：

请实现端侧 ArkTS 工程：在 HttpUtil.ets 统一配置 APPWRITE_HOST（http:// 协议）与 PROJECT_ID，并确认 functionId 映射与部署一致；4 个页面（登录、首页、闪卡、测试）通过函数执行端点调用云侧。注意配置 ohos.permission.INTERNET 权限；编译前核对 SDK 版本与 DEVECO_SDK_HOME，遇报错先定位根因再做最小修改。

操作：

1. 在 HttpUtil.ets 填入 APPWRITE_HOST（http:// 协议）和 PROJECT_ID，确认 functionId 映射与部署一致。
2. 核对 SDK 版本、local.properties 与 DEVECO_SDK_HOME，并配置 ohos.permission.INTERNET 权限。
3. 执行 ohpm install + hvigorw assembleHap 编译，再用 hdc install 安装。

完成标志：App 图标出现，能启动到登录页。

如果失败：00303217（缺 SDK 环境变量）、路径含空格（Space is not supported in HVIGOR_USER_HOME）等见 SKILL 的「端侧集成」。

步骤 5：端云联调验收

目标：端到端走通核心业务，确认学习进度与打卡状态正确。

为什么这样做：这是验证「命令提交成功 ≠ 部署完成」的关键一步，只有实际调用通过才算完成。

推荐指令：

请给我一份端云联调验收清单：逐项列出注册/登录、查看今日单词、闪卡翻转、看词选义测试、打卡状态与连续天数等操作与预期结果。并在模拟器/真机上执行一轮自动测试，逐项记录结果；发现问题先定位相关代码，修复后做针对性回归。

操作：按第 5 章的业务验收表逐项执行。

完成标志：第 5 章验收项全部通过，打卡与进度数据正确。

5. 验收与排障

业务验收

#	操作	预期结果	证据/检查方式
1	用 admin@company.com / 123456 登录	进入首页，显示打卡状态和连续天数	端侧页面截图
2	新用户注册（邮箱 + 密码）	提示「注册成功」，可登录	接口返回 code:0
3	首页查看今日单词列表	显示 10 个未学单词	列表展示
4	闪卡模式点击翻转	卡片翻转显示释义，动画流畅	端侧演示
5	完成看词选义测试	答对计入学习进度	进度条变化
6	学习一个单词后查看打卡	打卡状态「已完成」，连续天数正确	端侧展示 + 接口响应

技术检查与验收环境

• 端侧可编译、安装和启动。
• 云侧 6 个函数调用全部返回 {"code":0,"data":{...}}。
• 核心数据可写入、读取并在端侧正确展示（从 responseBody 二次解析）。
• 错误场景反馈清楚，日志中无真实 API Key 或未处理异常。

项目	内容
验证日期	2026-08-14
分支/标签/提交	main
设备与系统	mobile / HarmonyOS 6.1.0
云区域与关键版本	Appwrite 自托管 v1.9.0 / node-16.0
验收结论	已验收

高频问题

现象/错误码	环节	常见原因	处理与恢复标志
Runtime "node-18.0" is not supported	部署	自托管未启用该运行时	改 node-16.0，先查 runtimes
Cannot find package 'node-appwrite'	云函数	依赖未打包	npm install --omit=dev 后重打 tar.gz
storage_file_type_unsupported	部署	传了 .zip	打 .tar.gz
前端调用 401	权限	execute 不是 public	设 execute=["any"]

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

完整故障库：SKILL.md 的「全量故障速查表」。

6. 安全与清理

实验配置与生产要求

项目	本案例演示配置	生产要求
API 认证	execute=["any"] 公开执行	应用层鉴权、execute=["users"]、限流
网络	HTTP（80 端口）	HTTPS、TLS 反代、证书
凭据	环境变量 + .env	密钥管理、最小权限、轮换
数据	演示数据 + 种子账号	隐私、备份、保留与删除策略

清理资源

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

1. 禁用或删除 db-init 函数。
2. 删除 6 个测试函数。
3. 删除 word_db 下的 3 个集合。
4. 吊销测试 API Key。
5. 删除本地 .env 和脱敏前日志。

完成标志：控制台中不再存在本案例的测试函数与集合，临时 API Key 已吊销。

7. 项目导览与进阶

关键目录

word-check-in/
├── README.md                  # 案例入口与学习主线
├── SKILL.md                   # 可复用技巧、代码模板与排障知识
├── harmony_app/               # HarmonyOS 端侧工程
└── harmony_cloud/             # 云侧工程
    ├── .env.example           # 环境变量模板
    ├── functions/             # 6 个云函数
    └── deploy/                # 部署脚本

完成回顾

完成本案例后，你已经：

• 掌握 ArkTS 端侧开发与端云联调的完整流程。
• 掌握 Appwrite Functions 编写规范（ESM 默认导出、node-appwrite v11、NoSQL 操作）。
• 掌握 Appwrite 自托管部署、tar.gz 打包与排障。
• 交付一个可运行的闪卡式单词打卡应用。

深入阅读与扩展

• SKILL.md —— Appwrite 函数规范、代码模板、全量排障与复用清单
• 扩展方向：为 execute 接入正式鉴权、为服务器配置 HTTPS 反代、把 db-init 改为幂等可重复执行。

8. 参考与维护

官方资料与帮助

• Appwrite Functions 文档
• Appwrite Databases 文档
• node-appwrite SDK
• HarmonyOS 开发文档

维护与版本

项目	内容
维护团队	鸿蒙实践案例开发团队
当前案例版本	v1.0.0
最后验证日期	2026-08-14
兼容范围	Appwrite 自托管 v1.9.0 / node-16.0 / node-appwrite v11

许可证

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