使用 Agent 生成鸿蒙端云一体员工签到 App

使用 HarmonyOS ArkTS、Node.js + Express + MySQL 构建端云协同的员工签到系统，通过 CodeArts Agent 从一句话需求自动生成 PRD/HLD 文档、端侧代码、后端服务并完成部署联调。

项目	内容
适合谁	HarmonyOS 开发者、端云一体实践者、AI 辅助编程感兴趣的开发者
难度与耗时	进阶 · 预计 2–3 小时
你将学到	ArkTS 端侧开发、Node.js 后端搭建、FlexusL 云服务器部署、端云联调、Agent 驱动开发流程
你将完成	可运行的鸿蒙签到 App、后端 API 服务、MySQL 数据表及端云联调验收
验证环境	HarmonyOS 6.1.1 (API 24) · Node.js 20 · MySQL 8.0 · 最后验证于 2026-08-10

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

1. 案例概览

本案例展示如何用 CodeArts Agent 从一句话需求出发，自动生成一个完整的端云一体鸿蒙应用。Agent 自主完成需求文档编写、架构设计、端侧/云侧代码生成、构建部署和端云联调全流程，人工仅提供需求描述和验收反馈。

核心功能与体验

1. 员工输入邮箱注册 → 注册成功获得 userId
2. 员工登录 → 进入签到页面，查看当日提示语
3. 员工点击签到 → GPS 定位 + 位置判定 + 时间判定 → 返回签到结果（正常/迟到/超出范围）
4. 管理员登录 → 配置签到位置、班次时间、提示语 → 查看全员签到列表

登录页	管理员控制台

技术方案一览

flowchart LR
    A["HarmonyOS App<br/>ArkTS"] -->|HTTP JSON| B["Nginx :80"]
    B --> C["Node.js + Express<br/>pm2 :3000"]
    C --> D["MySQL 8.0<br/>连接池"]

员工签到时，端侧 App 获取 GPS 坐标后通过 HTTP POST 请求发送到 Nginx 反代，转发至 Node.js 后端，后端从 MySQL 读取位置配置并计算 haversine 距离，判定是否在有效范围内，同时根据班次时间判定迟到状态，最终写入签到记录并返回结果。

层级	技术/产品	验证版本	作用
端侧	ArkTS / ArkUI	API 24 (6.1.1)	6 页面 + 4 Service + 配置中心
云侧	Node.js + Express	20.20.2	3 路由组 + JWT 鉴权 + 业务逻辑
数据	MySQL	8.0	用户/配置/签到记录三表
部署	Nginx + pm2	1.18 / 7.0.3	反代 :80 + 进程守护
工具	DevEco + hvigor + hdc	6.1.1	构建 HAP + 模拟器安装调试
云资源	华为云 FlexusL	Ubuntu 22.04	2核2G ECS 自建全栈

边界说明

• 本案例用于演示 Agent 驱动的端云一体开发流程，不直接覆盖正式上架、HTTPS 证书、域名绑定。
• 演示期使用 HTTP 明文通信，生产环境需配置 TLS 证书。
• admin 默认密码 654321 仅供演示，生产环境需修改。

2. 开始之前

环境与资源

项目	要求	检查或获取方式
基础知识	ArkTS、HTTP、SQL 基础	HarmonyOS 官方入门教程
开发环境	Windows + DevEco Studio 6.1.1 + JDK	hvigorw.bat 可执行
SDK	HarmonyOS SDK 6.1.1 (API 24)	DevEco Studio → SDK Manager
测试设备	HarmonyOS 模拟器（Pura 90）	hdc list targets
Node.js	v20.x（部署服务器）	node -v
云服务器	华为云 FlexusL 或 ECS	公网 IP + SSH 可达
权限与网络	安全组放行 22/80 端口	VPC 控制台配置

费用与配额

资源	建议规格	计费方式	实践预计费用	结束后如何处理
FlexusL 实例	2核2G Ubuntu 22.04	按需	约 ¥0.3/小时	停止或释放实例

价格验证日期：2026-08-09。实际价格以华为云价格页为准。

配置与敏感信息

占位符	含义	获取位置	安全存放位置
API_BASE_URL	后端 API 地址	部署后获得公网 IP	端侧 ConfigCenter.ets（公开配置）
DB_PASSWORD	MySQL 密码	服务器自行设置	后端 .env（不提交 Git）
JWT_SECRET	JWT 签名密钥	自行生成随机字符串	后端 .env（不提交 Git）

• .env、签名私钥等含敏感信息的文件必须加入 .gitignore；部署脚本本身应版本化以便复现。
• 客户端不得包含数据库密码或 JWT 密钥。
• 截图、日志发布前必须脱敏。

3. 快速体验

这条路线面向"先把现成案例跑起来"的读者，目标是在 15 分钟内看到第一个成功结果。

1）获取已验证版本

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

完成标志：根目录存在 README.md、harmony_app/（端侧工程）和 harmony_cloud/（后端工程）。

2）准备最小配置

cp harmony_cloud/.env.example harmony_cloud/.env

1. 编辑 harmony_cloud/.env，设置 DB_PASSWORD、JWT_SECRET 等值。
2. 确认 harmony_app/entry/src/main/ets/config/ConfigCenter.ets 中 API_BASE_URL_DEFAULT 指向你的服务器地址。

完成标志：没有未替换占位符；.env 不会出现在 git status 中。

3）启动云侧

cd harmony_cloud
npm install --production
# 创建数据库与用户（表结构由 app.js 启动时自动初始化）
mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS checkin_db DEFAULT CHARSET utf8mb4; CREATE USER IF NOT EXISTS 'checkin'@'%' IDENTIFIED BY 'YourPassword'; GRANT ALL ON checkin_db.* TO 'checkin'@'%'; FLUSH PRIVILEGES;"
pm2 start ecosystem.config.js

完成标志：curl http://<服务器IP>:3000/health 返回 {"code":"0","message":"ok"}。

4）构建并运行端侧

首次构建前置：@ohos/hvigor-ohos-plugin 不在公共 npm registry 上，需先通过 DevEco Studio 打开 harmony_app 项目一次，IDE 会自动安装依赖到 ~/.hvigor/ 全局缓存。之后命令行构建即可正常使用。

# 请将路径替换为你的 DevEco Studio 安装目录
$deveco = "D:\Program Files\Huawei\DevEco Studio"
$env:DEVECO_SDK_HOME = "$deveco\sdk"
$env:PATH = "$deveco\jbr\bin;" + $env:PATH
cd harmony_app
& "$deveco\tools\hvigor\bin\hvigorw.bat" --mode module -p module=entry --no-daemon assembleHap

$hdc = "$env:DEVECO_SDK_HOME\default\openharmony\toolchains\hdc.exe"
& $hdc file send "entry\build\default\outputs\default\entry-default-unsigned.hap" /data/local/tmp/entry.hap
& $hdc shell bm install -p /data/local/tmp/entry.hap
& $hdc shell aa start -a EntryAbility -b com.pjm.checkin

完成标志：模拟器出现应用图标，启动后显示登录页面。

4. 完整实践

这条路线面向"理解并复现案例"的读者。以下记录了从需求提出到端云联调验收的完整真实对话过程——一共 5 轮对话，每轮只需一句话。你可以按照同样的方式与 AI 交互，复现整个案例。

第 1 轮：提出需求，生成 PRD 文档

你说：

实现一个端云协同的员工签到鸿蒙应用，要求和说明如下： (1)员工注册帐号，使用邮箱作为用户名，密码至少6位； 其中云数据库预制admin帐号，密码654321; (2)admin帐号登陆成功后的界面： 可以配置签到有效的经纬度和范围半径； 考勤班次：开始时间与结束时间； 以及周一到周五签订界面的提示语； 周末不允许签到； 可以查看每天员工签到的情况，是否迟到。 (3)员工登陆成功后的界面： 签到的界面，中心入口有个按钮，可以点击签到，上报位置，服务端判断位置， 数据库记录签到的时间，并返回结果供客户端界面展示; 右上角可以点击，可以进入历史记录界面，查看历史的签订记录； 同一员工当日允许多次签到及覆盖策略（"最早+最晚双记录" - 保留当日最早签到(上班)与最晚签到(下班)两条记录，中间记录留痕）； (4)UI美化。

AI 会：解析需求，生成 PRD 需求文档，包含功能清单、数据模型、接口定义、端云交互时序：

模块	验收项
账号体系	邮箱注册 + 密码 ≥6 位 + admin 预制账号
管理员功能	位置配置 / 班次配置 / 提示语配置 / 签到列表查看
员工功能	GPS 签到 / 历史记录 / 最早+最晚双记录策略
业务规则	周末禁止签到 / 迟到判定 / 范围判定（Haversine 距离）
UI	深色主题 + 卡片式布局 + dark 模式适配

产出：output/PRD-HarmonyOS-EmployeeCheckIn-*.md

知识点：PRD（Product Requirements Document）是产品需求文档，定义"做什么"和"验收标准"。端云一体项目需在 PRD 阶段就明确端侧与云侧的职责边界，避免后期接口契约不一致。

---

第 2 轮：生成架构设计

你说：

根据该需求文档生成一份架构设计 （1）服务端使用FlexusL，在其上用 Node.js + Express 后端 + 自建 MySQL完成全部功能； （2）端侧通过鸿蒙SDK获取Location经纬度，服务端判断位置范围是否有效；

AI 会：生成 HLD 架构设计文档，确定端云两层架构：

端侧 (harmony_app/)
  ├── pages/        ← 6 个 ArkUI 页面
  ├── service/      ← 4 个 Service（HTTP 封装 + 业务调用）
  ├── config/       ← ConfigCenter（运行时 API 地址配置）
  ├── context/      ← AppContext（token + user 全局状态）
  └── util/         ← ErrorCode / GeoUtil / TimeUtil

云侧 (harmony_cloud/)
  ├── routes/       ← 3 路由组（pjm-auth / pjm-admin / pjm-emp）
  ├── services/     ← 业务逻辑层
  ├── dao/          ← 数据访问层
  ├── middleware/   ← JWT 鉴权 + 错误捕获
  └── db/           ← MySQL 连接池 + 建表初始化

技术选型：HarmonyOS ArkTS + Node.js/Express + MySQL + JWT/bcrypt + PM2 + Nginx

产出：output/HLD-HarmonyOS-EmployeeCheckIn-*.md

知识点：HLD（High-Level Design）定义"怎么做"——技术选型、分层架构、接口路径、数据库表结构。本案例 API 路径统一使用 pjm- 前缀，便于反代路由隔离。

---

第 3 轮：生成端侧与云侧代码

你说：

根据需求文档和架构设计生成App前后端代码

AI 会：一次性生成完整端云工程——工程配置 + 全部业务源文件：

端侧（harmony_app/，17 个 .ets 文件）：

层	文件	关键设计
Pages	LoginPage / RegisterPage / CheckinPage / HistoryPage / AdminHomePage / AdminCheckinListPage	深色主题 + 卡片布局
Service	ApiService / AuthService / CheckinService / AdminService	HTTP 封装 + 空 URL 拦截 + JWT 注入
Config	ConfigCenter.ets	preferences 持久化 BaseUrl，默认空（安全）
Context	AppContext.ets	token + user 全局管理 + 登录态持久化
Util	ErrorCode.ets / GeoUtil.ets / TimeUtil.ets	统一错误码 + Haversine 距离 + 班次/迟到判定
Model	Models.ets	ApiResp / User / Checkin / Config 数据类型

云侧（harmony_cloud/，22 个 .js 文件）：

层	文件	关键设计
Routes	auth.js / admin.js / emp.js	pjm-auth / pjm-admin / pjm-emp 三路由组
Services	auth.js / admin.js / emp.js	注册/登录 + 配置管理 + 签到/历史
DAO	user.js / config.js / checkin.js	SQL 封装 + 连接池复用
Middleware	auth.js / error.js	JWT 鉴权 + 角色拦截 + 统一错误捕获
DB	pool.js / init.js	MySQL 连接池 + 启动时自动建表
Config	index.js	环境变量加载 + 生产模式 fail closed
部署	ecosystem.config.js / nginx/checkin.conf / .env.example	PM2 + Nginx 反代 + 占位符配置

避坑要点：

• @ohos/hvigor-ohos-plugin 不在公共 npm registry，需先通过 DevEco Studio IDE 打开 harmony_app 项目一次来初始化依赖
• oh-package.json5 中不应声明 hvigor 插件（它是 npm 包不是 ohpm 包，ohpm install 会报 404）
• ConfigCenter.ets 默认 API URL 必须为空字符串，防止读者意外将凭据发送到演示服务器
• API 24 Kit 名称变更：@kit.ArkDataKit → @kit.ArkData
• network_security_config.json 需配置允许明文 HTTP（仅开发调试用，生产环境必须 HTTPS）

产出：完整可编译的端云工程（harmony_app/ + harmony_cloud/ 目录）

---

第 4 轮：部署后端到服务器

你说：

部署后端到 <服务器公网IP>，root/<SSH密码>，路径 /opt/checkin/backend

安全提示：服务器 IP、SSH 密码等敏感信息仅在交互时提供给 Agent，不会写入仓库。提交到 Git 的文件中不包含任何真实凭据。请替换为你自己的服务器信息。

AI 会：

1. SSH 登录服务器，安装 Node.js 20（NodeSource）、MySQL 8、Nginx、PM2
2. 创建数据库与用户，SFTP 上传后端代码
3. npm install --production + 配置 .env（填入真实密码和密钥）+ pm2 start
4. 配置 Nginx 反代 :80 → :3000

# 服务器端操作
cd /opt/checkin/backend
npm install --production
cp .env.example .env
# 编辑 .env 填入 DB_PASSWORD / JWT_SECRET 等真实值
pm2 start ecosystem.config.js

避坑要点：

• .env.example 使用占位符，生产模式缺少或过短的密钥会直接 process.exit(1) 拒绝启动
• Ubuntu apt 默认 Node 版本太旧（v12），需用 NodeSource setup_20.x 安装 Node 20
• PM2 cwd 使用 __dirname 而非硬编码路径，部署到任意目录均可
• Nginx 配置文件 checkin.conf 需拷贝到 /etc/nginx/conf.d/ 后 nginx -s reload

产出：后端服务上线，curl http://<服务器IP>/health 返回 {"code":"0","message":"ok"}

---

第 5 轮：构建端侧并安装到模拟器，截图验收

你说：

构建并安装到模拟器，截图确认登录界面正常

AI 会：

1. 确认模拟器在线：hdc list targets → 127.0.0.1:5555
2. 构建端侧 HAP：

$deveco = "D:\Program Files\Huawei\DevEco Studio"  # ← 替换为你的实际路径
$env:DEVECO_SDK_HOME = "$deveco\sdk"
$env:PATH = "$deveco\jbr\bin;$env:PATH"
cd harmony_app
& "$deveco\tools\hvigor\bin\hvigorw.bat" --mode module -p module=entry --no-daemon assembleHap

3. 安装到模拟器：

$hdc = "$env:DEVECO_SDK_HOME\default\openharmony\toolchains\hdc.exe"
& $hdc file send "entry\build\default\outputs\default\entry-default-unsigned.hap" /data/local/tmp/entry.hap
& $hdc shell bm install -p /data/local/tmp/entry.hap
& $hdc shell aa start -a EntryAbility -b com.pjm.checkin

4. 逐项验收结果：

#	操作	预期结果	实际结果
1	curl http://<IP>/health	{"code":"0","message":"ok"}	✅ 通过
2	admin/654321 登录	返回 JWT token + 跳转管理台	✅ 通过
3	员工注册 test@pjm.com	返回 userId	✅ 通过
4	员工登录 + 签到	返回签到结果（正常/迟到/超出范围）	✅ 通过
5	管理员查看签到列表	显示全员签到记录	✅ 通过

完成标志：5/5 全部通过，模拟器显示登录页面，admin 登录后跳转管理员控制台，员工注册 → 登录 → 签到全流程通畅。

避坑要点：

• hdc install 遇 install version downgrade 需先 bm uninstall 再安装
• 端侧首次启动时 API URL 为空，需在登录页设置服务器地址后才能通信
• ArkTS 严格模式禁止 showToast 在 try-catch 中直接调用，需用 promptAction.showToast

5. 验收与排障

业务验收

#	操作	预期结果	证据/检查方式
1	curl http://<IP>/health	{"code":"0","message":"ok"}	接口响应
2	admin/654321 登录	返回 JWT token + 跳转管理台	模拟器截图
3	员工注册 test@pjm.com	返回 userId	接口响应
4	员工登录 + 签到	返回签到结果（正常/迟到/超出范围）	模拟器操作
5	管理员查看签到列表	显示全员签到记录	管理台页面

技术检查与验收环境

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

项目	内容
验证日期	2026-08-10
分支/标签/提交	master / v1.0.1
设备与系统	Pura 90 模拟器 / HarmonyOS 6.1.1
云区域与关键版本	华南-广州 / FlexusL Ubuntu 22.04 / Node 20.20.2 / MySQL 8.0
验收结论	5/5 通过；演示期 HTTP 明文，生产需 TLS

高频问题

现象/错误码	环节	常见原因	处理与恢复标志
DEVECO_SDK_HOME invalid	构建	路径指向子目录	指向 sdk 根目录后构建成功
spawn java ENOENT	构建	JBR Java 不在 PATH	加入 jbr\bin 到 PATH
@kit.ArkDataKit 不存在	编译	API 24 Kit 改名	改为 @kit.ArkData
HTTP 请求无响应	联调	默认禁明文 HTTP	添加 network_security_config.json
install version downgrade	安装	HAP 版本号未变	升级 versionCode 或先 uninstall
Node v12 无 npm	部署	Ubuntu apt 源太旧	用 NodeSource setup_20.x
snapshot not found	测试	模拟器无此命令	用 uitest screenCap 替代
安全键盘遮挡按钮	测试	密码输入后键盘弹出	先 keyEvent Back 再点击

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

完整故障库：output/踩坑记录.md

6. 安全与清理

实验配置与生产要求

项目	本案例演示配置	生产要求
API 认证	JWT Bearer Token	正式鉴权 + 限流 + 审计
网络	HTTP 明文 + IP 直连	HTTPS + 自有域名 + TLS 证书
凭据	.env 文件明文存放	密钥管理服务 + 最小权限 + 轮换
数据	演示数据 + admin 默认密码	隐私合规 + 备份 + 保留删除策略

清理资源

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

1. pm2 delete pjm-checkin 停止后端进程
2. 删除 Nginx 配置 + MySQL 数据库
3. 释放 FlexusL 实例公网 IP
4. 撤销安全组临时放行规则
5. 删除本地 .env、部署脚本和脱敏前日志

完成标志：华为云控制台中不再存在本案例的持续计费资源。

7. 项目导览与进阶

关键目录

check-in/
├── README.md                  # 案例入口与学习主线
├── harmony_app/               # HarmonyOS 端侧工程
│   ├── AppScope/app.json5     # 应用级配置（版本号、bundleName）
│   ├── entry/src/main/
│   │   ├── ets/
│   │   │   ├── pages/         # 6 个页面
│   │   │   ├── service/       # 4 个 Service
│   │   │   ├── config/        # ConfigCenter 运行时配置
│   │   │   ├── context/       # AppContext 全局状态
│   │   │   ├── model/         # Models 数据类型
│   │   │   └── util/          # ErrorCode / GeoUtil / TimeUtil
│   │   └── resources/         # base/dark 双主题 + profile 配置
│   └── build-profile.json5    # 工程构建配置
├── harmony_cloud/             # Node.js 后端工程
│   └── src/
│       ├── routes/            # auth / admin / emp 三路由组
│       ├── services/          # 业务逻辑层
│       ├── dao/               # 数据访问层
│       ├── middleware/        # JWT 鉴权 + 错误捕获
│       ├── db/                # 连接池 + 建表初始化
│       └── util/              # jwt / password / geo / time
├── output/                    # 文档与产物
│   ├── PRD-*.md               # 需求文档
│   ├── HLD-*.md               # 架构设计
│   └── 踩坑记录.md            # 21 个踩坑问题与解法
└── README.md                  # 案例入口与学习主线

完成回顾

完成本案例后，你已经：

• 掌握了 Agent 驱动的端云一体开发流程（需求→文档→代码→部署→联调）
• 学会了 HarmonyOS API 24 端侧开发与模拟器调试
• 实践了 Node.js 后端部署到华为云 FlexusL 的完整流程
• 积累了 21 个端云协同开发高频踩坑的解决方案

深入阅读与扩展

• 踩坑记录 — 21 个问题与解法速查
• PRD 需求文档
• HLD 架构设计
• 扩展方向：HTTPS + 域名绑定、AGC 云函数替代自建后端、消息推送通知签到结果

8. 参考与维护

官方资料与帮助

• HarmonyOS 开发文档
• 华为云 FlexusL 文档
• PptxGenJS（npm）
• 使用问题：在当前仓库提 Issue

维护与版本

项目	内容
案例维护	华为云 CodeArts 团队
代码来源	CodeArts Agent 自动生成
案例版本	v1.0.1
Git 分支	master
最后验证日期	2026-08-10
兼容范围	HarmonyOS 6.1.1 (API 24) / Node.js 20+ / MySQL 8.0+

• v1.0.1（2026-08-10）：添加员工退出按钮、解除周末签到限制、重新部署后端
• v1.0.0（2026-08-09）：初始版本，端云一体签到系统完整交付

许可证

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