用 Agent 思路做一个鸿蒙端云一体员工签到 App 的实践笔记

本文是对鸿蒙开发实践中心案例《使用 Agent 生成鸿蒙端云一体员工签到 App》的阅读笔记。梳理该案例公开的流程、架构与注意事项，供按案例复现时参考，不含本文作者自行部署的实测数据与截图。

一、端云一体签到场景拆解

按案例描述，该应用要解决的是一个完整的签到闭环，而不是只有一个签到按钮的演示页。账号体系方面，员工用邮箱加密码注册，密码不少于 6 位，另有预制的管理员账号。管理员功能包括配置签到位置与班次、配置提示语、查看全员签到列表。员工功能包括用 GPS 完成签到、查看自己的历史记录，案例采用最早加最晚的双记录策略。业务规则方面，周末禁止签到，迟到判定与签到范围判定都要做，范围判定用服务端 Haversine 距离计算。技术分层上，案例是端云两层架构：端侧为 HarmonyOS ArkTS，6 个页面加 4 个 Service，另有配置中心与全局状态管理；云侧为 Node.js 加 Express，3 个路由组加 JWT 鉴权；数据层为 MySQL，三张表分别为用户表、配置表与签到记录表，启动时自动建表；部署层为 Nginx 反代加 PM2 进程守护。

二、Agent 分工

案例的核心思路不是让人逐行写出全部代码，而是把工作拆成 5 轮对话，每轮只需一句话，Agent 自主完成文档编写、代码生成、部署联调，人工的角色是提需求与按验收标准确认。第 1 轮提出需求，生成 PRD：定义做什么与验收标准，明确端侧与云侧的职责边界，产出功能清单、数据模型、接口定义与端云交互时序。案例强调，PRD 阶段就明确端云接口契约，可以避免后期接口不一致导致的返工。第 2 轮生成架构设计 HLD：定义怎么做，包括技术选型、分层架构、接口路径与数据库表结构。案例中接口路径统一使用 pjm 前缀，便于反代路由隔离。第 3 轮生成端侧与云侧代码：端侧包括登录、注册、签到、历史、管理台等页面与 ApiService、AuthService、CheckinService、AdminService 等服务层；云侧包括 auth、admin、emp 三个路由组，及对应的业务层、数据访问层与鉴权中间件。第 4 轮部署后端到服务器：安装 Node.js、MySQL、Nginx 与 PM2，配置环境变量并用 PM2 启动，再配置 Nginx 反代。第 5 轮构建端侧并安装到模拟器，逐项截图验收。案例给出的验收清单共 5 项：后端健康检查、管理员登录、管理台跳转、员工注册、员工登录加签到、管理员查看签到列表。

三、关键踩坑点

以下均为案例正文与高频问题中列出的要点，复现时可先对照检查。构建依赖方面，@ohos/hvigor-ohos-plugin 不在公共 npm registry 上，案例建议先通过 DevEco Studio 打开项目一次，由 IDE 初始化依赖；oh-package.json5 中不应把 hvigor 插件声明为 ohpm 包。SDK 与 Java 环境方面，DEVECO_SDK_HOME 应指向 SDK 根目录而非子目录；构建报 spawn java ENOENT 时，案例给出的方向是把 JBR 的 Java 加入 PATH。Kit 名称变更方面，API 24 中 @kit.ArkDataKit 已变更为 @kit.ArkData，编译报错时先核对 Kit 名称。网络与安全配置方面，端侧默认禁止明文 HTTP，开发调试阶段需按案例配置 network_security_config；ConfigCenter 默认 API 地址应为空字符串，避免把地址或凭据写死进代码；环境变量文件不应进入版本控制，案例还提到后端在生产模式下对缺失或过短密钥会直接退出，属于 fail closed 的做法，复现时不要用弱密钥绕过。部署细节方面，Ubuntu 自带 apt 的 Node 版本较旧，案例建议用 NodeSource 安装 Node 20；PM2 的工作目录建议用 __dirname 而非硬编码路径；Nginx 配置需拷贝到 conf.d 后重新加载；安装报版本降级时，可升级 versionCode 或先卸载旧版本。

四、复现步骤与注意事项

案例给出了一条约 10 分钟的快速体验路线，目标是先把现成版本跑起来，再走完整实践。1. 获取已验证版本：克隆案例公仓 check-in，确认根目录同时存在 README、端侧工程与后端工程。2. 准备最小配置：复制后端示例环境变量文件，设置数据库密码与 JWT 密钥等值；确认端侧 ConfigCenter 中的默认接口地址指向自己的服务器地址，且没有未替换的占位符。3. 启动云侧：安装生产依赖，创建数据库与用户，表结构由后端启动时自动初始化；用健康检查接口验证，案例给出的正常返回为 code 为 0、message 为 ok。4. 构建并运行端侧：先按上文完成 DevEco Studio 的依赖初始化，再构建 HAP 并用 hdc 安装到模拟器，启动后应能看到登录页面。注意事项：案例标注华为云 FlexusL 实例按需计费约 0.3 元每小时，实践结束后可释放实例停止计费，复现前应自行确认当前计费规则；明文 HTTP 配置仅用于开发调试，正式环境应按案例的拓展建议改用 HTTPS 与域名绑定；案例还给出了另外两条拓展方向，分别是把自建后端迁移到 AppGallery Connect 云函数加云数据库，以及在签到结果产生后增加消息推送。

结语：这篇笔记的价值不在于复述一遍代码，而在于把签到场景先拆成账号、配置、签到判定与历史查询，再用 PRD、HLD、代码、部署、联调五步把 Agent 的产出串起来。按案例的验收清单逐项核对，比一次性把全部功能跑通后再排错要省事得多。