一句话需求到端云联调：鸿蒙员工签到 App 案例拆解与踩坑清单

写在前面

华为云鸿蒙开发实践中心有一个案例：使用 Agent 生成鸿蒙端云一体员工签到 App（难度标注「进阶」，预计 150 分钟）。它把 CodeArts Agent 从一句话需求一路推到端云联调验收：端侧 HarmonyOS ArkTS，云侧 Node.js + Express + MySQL。我把案例文档完整读了一遍，把架构、流程和真正会踩的坑整理在这里。

一、案例要做什么

需求只有一句话：员工注册（邮箱 + 密码不少于 6 位）、admin 配置签到位置和班次、员工 GPS 签到、管理员查看签到列表。Agent 用 5 轮对话把它做完：需求 → PRD → HLD → 端云代码 → 部署联调，每轮只需补一句话。

产出物：

• 鸿蒙 App：6 页面 + 4 Service + ConfigCenter + AppContext + Util 层，共 17 个 .ets 文件
• 后端：3 路由组 + JWT 鉴权 + MySQL 连接池，共 22 个 .js 文件
• 数据表：user / config / checkin 三表，启动时自动建表
• 部署：Nginx 反代 + PM2 进程守护

二、端云两层架构

云侧接口统一带 pjm- 前缀（pjm-auth / pjm-admin / pjm-emp），作者给的理由是便于反代做路由隔离。端侧分层也值得照抄：Pages 六个页面（Login / Register / Checkin / History / AdminHome / AdminCheckinList），Service 四个（ApiService / AuthService / CheckinService / AdminService，统一做 JWT 注入和空 URL 拦截），Util 三个（ErrorCode 统一错误码、GeoUtil 算 Haversine 距离、TimeUtil 判班次与迟到）。

三、签到链路与两条业务规则

主链路：端侧用 @ohos.geoLocationManager 取 GPS 坐标 → HTTP POST → Nginx 反代 → Node 后端 → MySQL 读配置 → Haversine 距离计算 → 班次时间判定 → 写入签到记录 → 返回结果。

• 双记录策略：同一员工当日允许多次签到，只保留最早（上班）和最晚（下班）两条作为结果，中间记录留痕。比「一天只能签一次」贴合真实场景。
• 周末禁止签到由服务端按星期判定，而不是端侧判断。位置和时间这类业务规则的裁决权必须留在云侧，否则改一次规则要发一次版。

四、安全设计：三处 fail-closed

这是整个案例我觉得最值得说的部分，它不是「加了鉴权」这种笼统话，而是三个具体动作：

• ConfigCenter.ets 里 API_BASE_URL_DEFAULT 默认空字符串，配合 Service 层的空 URL 拦截，防止读者不改配置就把请求（含凭据）打到演示服务器上。
• .env 生产模式 fail closed：密钥缺失或过短直接 process.exit(1) 拒绝启动，而不是拿默认值凑合跑起来。
• 密码用 bcrypt hash 存储；端侧不持有数据库密码或 JWT 密钥。

五、会踩的坑（按环节）

构建

• 报 DEVECO_SDK_HOME invalid：路径要指向 sdk 根目录，不是子目录。
• 报 spawn java ENOENT：把 DevEco Studio 的 jbr bin 目录加进 PATH。
• @ohos/hvigor-ohos-plugin 404：这个插件不在公共 npm registry 上，先用 DevEco Studio 打开项目一次，依赖会落到 ~/.hvigor 全局缓存，之后命令行构建才可用。
• oh-package.json5 里不要声明 hvigor 插件——它是 npm 包，不是 ohpm 包。

编译

• API 24 的 Kit 名称变更：@kit.ArkDataKit 要改成 @kit.ArkData。

联调

• 端侧 HTTP 请求毫无响应：HarmonyOS 默认禁止明文 HTTP，开发期在 resources 下加 network_security_config.json 放行；生产环境必须上 HTTPS。

安装与部署

• 报 install version downgrade：升 versionCode 重新构建，或先 bm uninstall 再装。
• Ubuntu apt 装出来是 Node v12、npm 不可用：改用 NodeSource 的 setup_20.x。
• PM2 的 ecosystem.config.js 里 cwd 用 __dirname，别硬编码路径。
• Nginx 配置要拷到 /etc/nginx/conf.d/ 再 nginx -s reload。

模拟器

• hdc shell snapshot 不存在：用 hdc shell uitest screenCap -p /data/local/tmp/screenshot.png 替代。

仓库里还有一份 21 条的踩坑库（output/踩坑记录.md），比这里列的多。

六、验收标准

5 项全过才算跑通：health 接口返回 code 0 且 message ok；admin 默认账号登录拿到 JWT 并跳转管理台；员工注册返回 userId；员工登录 + 签到返回判定结果（正常 / 迟到 / 超出范围）；管理员能看到全员签到列表。

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

七、几点判断

• 「进阶 · 2~3 小时」不虚。真正耗时的不是让 Agent 生成代码，而是环境对齐：SDK 路径、JBR、Node 版本、明文 HTTP 白名单，每一个都能卡住半小时。
• 「每轮只需一句话」的前提是 PRD 阶段就把端云接口契约写清楚。契约模糊，后面就是反复返工。
• 三处 fail-closed 建议直接搬进自己的工程模板，成本极低，挡掉的是「把凭据发给别人的服务器」这类事故。

资源

• 案例详情页：https://harmonybp.developer.huaweicloud.com/cases/bff1556a1ad24181be82eba6f77b1ed9
• 代码仓：https://gitcode.com/harmony-practice-center/check-in
• 组织主页（81 个案例仓）：https://gitcode.com/harmony-practice-center

验证环境：HarmonyOS 6.1.1 (API 24) · Node.js 20 · MySQL 8.0。