翻了个鸿蒙签到案例:Agent 五轮对话,把 App 从一句话聊到跑起来
本来是想找个鸿蒙练手项目,翻了一圈,停在这个员工签到 App 上了。倒不是签到这个业务多新鲜——谁都知道签到要干什么——而是它这个案例的链路特别完整:CodeArts Agent 从一句话需求出发,5 轮对话,先出 PRD,再出 HLD,然后端侧代码、后端服务,最后部署联调,一口气全干完了。单看某个 API 的 demo 没这个意思,我想看的就是“从需求到跑起来”中间到底长什么样。
仓库在 GitCode,harmony-practice-center/check-in.git,拉下来先看目录。作者留了 output/PRD 和 output/HLD 两份文档,还有一篇 2026-08-09 的踩坑记录。光看这几样东西,基本能还原这个项目是怎么被“聊”出来的。端侧加云侧我数了一下,大概 3100 行,不算大,但层次都在,不是一团浆糊。
后端是 Node.js + Express + MySQL。路由按业务分了三组:auth 管登录和发 token,emp 是员工侧的接口,admin 是管理侧。鉴权走 JWT,库里三张表,用户、配置、签到记录,服务启动的时候自动建表,省了手工导 SQL 的步骤。部署是 Nginx 反代 80 端口,Node 服务交给 PM2 守护。这个组合挺朴素的,没什么花活——我这种半吊子读着不费劲,不用先补一堆框架知识。
端侧是 HarmonyOS ArkTS,6 个页面配 4 个 Service,另外还有个配置中心和全局状态管理。页面只管交互,Service 把网络请求、定位这些能力收拢起来,配置中心管后端地址之类的常量,全局状态管登录态。分得挺规矩的,读的时候每个文件该干什么一眼就能看出来。有些 Agent 生成的代码逻辑到处乱窜,这个没有,算是个优点。
签到逻辑本身不复杂,但串起来有讲究。端侧取 GPS 坐标,POST 给后端,后端拿 Haversine 公式算当前坐标和签到点的距离,先判定在不在范围内,再对照班次时间判定迟没迟到。还有个“最早+最晚”双记录策略,一天能打最早那次和最晚那次卡,上下班两头都要打卡的场景用得上。Haversine 公式本身没什么难的,难的是把它跟“范围判定”“班次判定”这两层业务串到一块,HLD 里这块写得还算清楚。
踩坑记录是这份案例最值钱的部分。两个大坑,全是环境问题,代码没错但就是跑不起来。
第一个是 DEVECO_SDK_HOME 指错了。作者把它指到了 sdk 下面 default 再 openharmony 那个子目录,hvigor 直接报 Invalid value of 'DEVECO_SDK_HOME'。后来改指到 sdk 根目录才好。这坑容易踩,目录一层套一层,看着都像“SDK 所在的位置”,但工具要的是根,不是某个具体版本的子目录。顺着路径点进去,越点越觉得自己找对了,结果错得更深。
第二个在打包阶段,PackageHap 报 spawn java ENOENT,系统 PATH 里没有 Java。解法是把 DevEco 内置的 JBR Java 加进 PATH。这个更隐蔽:IDE 自己能用,不代表命令行调 hvigor 的时候也能找到 Java,两套环境变量根本不是一回事。我以前也在别的工具上吃过这种亏,IDE 里跑得好好的,一上命令行就找不到东西。
还有两个小坑,顺带记一下。build-profile.json5 里 srcPath 写 entry 不行,必须写 ./entry;oh-package.json5 缺 version 字段会报 The version number of the module must be a string。都是格式细节,报错信息其实已经把答案写脸上了,但第一次遇到还是得愣一下。
得交代清楚我做到哪一步了:案例从头读了一遍,仓库拉下来看了结构,但 150 分钟的全程我没跑完,也没做真机联调。所以这篇只是读案例、看仓库的手记,不是一份“跟着做就能跑通”的教程。验证环境作者写的是 HarmonyOS 6.1.1(API 24)、Node.js 20、MySQL 8.0,最后验证于 2026-08-10,云资源是 FlexusL Ubuntu 22.04 2 核 2G,按需大约 0.3 元一小时——这些是案例里的事实,我没亲手复现。
还有一句提醒。演示期用的是 HTTP 明文通信,admin 默认密码 654321 也仅供演示,真要上线,TLS 得换、密码得改,别图省事。
如果有人想跟做,我的建议就两条。先把 output 里的 PRD 和 HLD 读完再动手,别急着敲命令,这两个文档能帮你判断后面生成的代码哪块该在、哪块不对劲。还有,环境变量和 PATH 这类东西,在跑 hvigor 之前就检查一遍,DevEco 内置的 JBR 路径、SDK 根目录,提前确认好,能省掉大半“明明代码没问题”的排查时间。
- 点赞
- 收藏
- 关注作者
评论(0)