鸿蒙端云一体员工签到App学习笔记:GPS签到、JWT鉴权与AI DevSpace实测

举报
yd_224048907 发表于 2026/11/19 00:44:06 2026/11/19
【摘要】 一、前言:今天的学习路径今天(2026 年 11 月 19 日)是我在华为云开发者成长中心做当日成长任务的一天,也是旧平台停服升级前最后一个完整任务日。我的学习路径很完整:先在鸿蒙开发实践中心浏览并精读了进阶案例《使用 Agent 生成鸿蒙端云一体员工签到 App》,接着到 GitCode 给该案例的代码仓点了 Star,然后在 AI DevSpace 免费体验版里新建 AI 对话会话,围...

一、前言:今天的学习路径

今天(2026 年 11 月 19 日)是我在华为云开发者成长中心做当日成长任务的一天,也是旧平台停服升级前最后一个完整任务日。我的学习路径很完整:先在鸿蒙开发实践中心浏览并精读了进阶案例《使用 Agent 生成鸿蒙端云一体员工签到 App》,接着到 GitCode 给该案例的代码仓点了 Star,然后在 AI DevSpace 免费体验版里新建 AI 对话会话,围绕这个案例向 AI 提了两个实质技术问题并追问补齐,最后把全天的学习心得整理成这篇笔记发表出来。写这篇笔记的目的,是把案例里的端云一体设计真正拆解清楚:端侧怎么定位、云侧怎么算距离、鉴权怎么做、双记录策略怎么落地、反作弊怎么防、生产部署又该怎么改。

二、案例概览:一个员工签到 App 的端云全貌

这个案例来自鸿蒙开发实践中心,定位是进阶难度,预计学习时长约 150 分钟,代码仓在 GitCode 的 harmony-practice-center/check-in。它的业务目标很明确:替代纸质签到与 Excel 统计,让员工用一部鸿蒙手机完成打卡,让管理员在网页端看到可信的考勤数据。

整体架构是典型的端云一体:端侧用 ArkTS + ArkUI 开发,云侧用 Node.js + Express + MySQL,部署在华为云 FlexusL 轻量服务器上,部署方式是 PM2 + Nginx + HTTPS。全应用包含 6 个页面(登录页、签到页、签到历史页、请假页、员工管理页、考勤统计页)、4 个 Service(AuthService、LocationService、CheckinService、LeaveService)和 3 个路由组。开发流程也很有代表性:先由 Agent 生成应用框架与核心页面,再逐步完善业务逻辑,最后完成前后端联调与云端部署。对我这样的学习者来说,这个案例的价值不在于某一个 API,而在于它把权限、定位、鉴权、数据库、部署这些环节串成了一条完整的链路。

三、端侧:ArkTS 定位能力与权限申请

签到的第一步发生在手机端。HarmonyOS 的定位能力由 geoLocationManager 提供,签到页在点击签到前要先完成三件事:声明权限、动态申请授权、获取一次高精度位置。案例在 module.json5 中声明了 ohos.permission.LOCATION 与 ohos.permission.APPROXIMATELY_LOCATION 两个权限,分别对应精确位置与模糊位置。端侧代码里,LocationService 会先调用 abilityAccessCtrl 检查授权状态,未授权时通过 requestPermissionsFromUser 弹窗申请;用户拒绝后要给出明确提示并引导去系统设置里开启,而不是静默失败。

拿到授权后,调用 geoLocationManager.getCurrentLocation 获取经纬度,关键参数是 requestInfo 的 priority(建议用 PRIORITY_ACCURACY 精确模式)、scenario(建议用 NAVIGATION)与 timeoutMs(建议 10 秒左右)。一次定位会返回经纬度、精度半径 accuracy、时间戳与定位来源。我的学习体会是:定位结果里的 accuracy 字段非常重要,它直接决定了后面云侧要不要放宽判定半径;如果 accuracy 是 200 米,说明定位本身就不可靠,这时候宁可提示用户“定位精度不足,请到开阔处重试”,也不要把一个漂移很大的点直接发给后端。端侧还应把超时、定位服务未开启、权限被永久拒绝这几种异常分别处理,给出不同的提示文案。

import { geoLocationManager } from '@kit.LocationKit';
import { abilityAccessCtrl } from '@kit.AbilityKit';

const request: geoLocationManager.LocationRequest = {
  priority: geoLocationManager.LocationRequestPriority.PRIORITY_ACCURACY,
  scenario: geoLocationManager.LocationRequestScenario.NAVIGATION,
  timeInterval: 0,
  distanceInterval: 0,
  maxAccuracy: 50
};
geoLocationManager.getCurrentLocation(request, (err, location) => {
  if (err) { console.error('定位失败:' + JSON.stringify(err)); return; }
  console.info(`经度:${location.longitude},纬度:${location.latitude},精度:${location.accuracy} 米`);
});

四、云侧:Haversine 公式与签到范围判定

端侧把经纬度发到云侧后,真正的判定发生在后端。案例的后端提供 /checkin/checkin 签到接口,先由鉴权中间件解析 Token 拿到员工身份,再做三步校验:是不是周末、距离够不够近、今天是不是已经签过。距离计算用的是 Haversine 公式,它把经纬度换算成弧度后,用球面三角算出两点之间的大圆距离,地球半径取 6371 公里。公司签到点与允许半径存在 checkin_rules 表里,管理员可以在管理端按部门配置不同的签到点与半径,半径一般设为 200 米。

一个容易被忽略的细节是精度补偿:后端会用员工上报的 accuracy 动态放宽有效半径,有效半径等于配置半径加上 accuracy 再乘一个系数(案例里取 0.5),这样室内定位漂移几十米时不会把正常签到误判为超出范围;但 accuracy 超过阈值(例如 500 米)时,后端会直接拒绝并返回“定位精度不足,请重试”。这种“硬性拒绝 + 弹性补偿”的组合,比单纯用固定半径判定要合理得多。

签到接口的返回也值得学习:正常签到返回成功与当次记录;超出范围返回距离数值与允许半径,方便端侧展示“您距签到点 320 米,超出范围”;周末签到返回 WEEKEND_NOT_ALLOWED;重复签到返回“今日已签到”。状态码上,401 表示未登录或 Token 过期,403 表示角色无权限,两者要严格区分,端侧收到 401 应该跳回登录页,收到 403 应该提示无权限而不是反复重试。

function getDistance(lat1, lon1, lat2, lon2) {
  const R = 6371;
  const dLat = (lat2 - lat1) * Math.PI / 180;
  const dLon = (lon2 - lon1) * Math.PI / 180;
  const a = Math.sin(dLat / 2) * Math.sin(dLat / 2) +
    Math.cos(lat1 * Math.PI / 180) * Math.cos(lat2 * Math.PI / 180) *
    Math.sin(dLon / 2) * Math.sin(dLon / 2);
  const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
  return R * c * 1000;
}

五、鉴权:JWT 与角色拦截怎么做

签到数据涉及考勤与薪酬,必须保证“谁签的、能不能管别人”这两件事不出错。案例的鉴权链路是:注册时密码用 bcrypt 加盐哈希后存进 MySQL,数据库里永远不存明文密码;登录时校验密码,成功后签发 JWT,Token 里带用户 ID 与角色;端侧把 Token 存进 Preferences,每次请求在 Authorization 头里带上 Bearer Token;后端的鉴权中间件用密钥验签,验签通过才把用户信息挂到请求对象上,否则返回 401。

在鉴权之上还有一层角色拦截:路由上挂 requireRole 中间件,员工只能访问自己的签到、请假接口,管理员才能访问员工管理与考勤统计接口,角色不符返回 403。权限矩阵建议写成一张表贴在后端 README 里:登录、注册、签到、查自己历史、请假属于员工;查看全部签到、修改签到规则、管理员工、导出统计属于管理员。学习时我还注意到两个细节:一是 Token 要设合理的过期时间并支持刷新,过期后不要悄悄续期;二是密钥必须放进环境变量,绝不能写死在代码里提交到 GitCode,这也是 Star 代码仓时顺便检查的好习惯。

六、双记录策略:最早与最晚两条记录

案例里最让我印象深刻的设计是“最早 + 最晚双记录策略”。员工每天可能签到多次,但考勤只需要两个时间点:第一次签到算上班打卡,最后一次签到算下班打卡。数据库层面用一张 checkin_records 表承载,字段包括员工 ID、日期、当天最早签到时间、当天最晚签到时间、签到状态、经度、纬度与距离,并在(员工 ID,日期)上建唯一键。

后端逻辑是:每次签到成功后,用 ON DUPLICATE KEY UPDATE 做一次“存在即更新”——如果当天还没有记录就插入一条,最早与最晚都写当前时间;如果已有记录,就把最早时间取两者中更早的,把最晚时间取两者中更晚的。迟到判定取最早签到时间与上班时间(例如 9:00)比较,超过即迟到;早退判定取最晚签到时间与下班时间(例如 18:00)比较,早于即早退;周末则直接在接口入口处拒绝签到,返回 WEEKEND_NOT_ALLOWED。这个设计的好处是写操作只有一条 Upsert 语句,并发下也不会产生重复行,而且统计页只需要按日期查最早与最晚两个字段就能算出勤情况,查询非常简单。

七、反作弊:GPS 漂移、模拟定位与低精度定位

位置签到最怕的就是作弊,案例和 DevSpace 的回答都把防御分成了端侧与云侧两层。端侧层面:第一,拒绝低精度定位结果,accuracy 超过阈值就提示重试;第二,检测模拟位置,Android 侧可用 isMock 判断,HarmonyOS 侧可结合定位来源与系统设置综合判断,发现模拟定位直接拒绝;第三,做连续定位一致性校验,短时间内位置跳变几公里明显不合理。云侧层面:第一,速度检测,用两次签到的距离除以时间差算速度,速度超过人类步行与驾车合理范围就标记异常;第二,IP 与设备指纹辅助判断,同一账号短时间内在不同城市出现要告警;第三,异常记录进审计表,由管理员人工复核而不是直接封号。需要承认的是,技术手段只能提高作弊成本,不能彻底杜绝作弊,最终还是要技术加管理配合,例如异常申诉流程与定期抽查。

八、生产部署:从 FlexusL 自建到 Nginx + PM2 + HTTPS

案例的后端部署在 FlexusL 上,进程管理用 PM2,反向代理用 Nginx,对外提供 HTTPS。改造成生产部署时要改的配置包括:PM2 的 ecosystem.config.js 里写清应用名、启动脚本、实例数、日志路径与自动重启策略;Nginx 里配好反向代理到 Node.js 端口、静态资源缓存、请求体大小限制与 HTTPS 证书;MySQL 要建独立账号并限制远程访问,定期备份;环境变量里放 JWT 密钥与数据库密码,服务器上用 systemd 让 PM2 开机自启。安全注意事项有:关闭不必要的端口、Nginx 上加限流防刷、接口加请求频率限制、Token 过期时间不宜过长、日志不要打印密码与 Token、定期更新依赖修复漏洞。

九、AI DevSpace 实测:两个问题与三点收获

今天的 DevSpace 体验走的是免费体验版,全程不消耗核时。进入后容器很快就绪,剩余时长约 3 小时;我在 AI Shell 里新建了一个 AI 对话会话,会话名自动生成为“鸿蒙端云一体员工 GPS 签到案例解析”。我提的第一个问题是 GPS 签到全流程(端侧定位、Haversine 计算、阈值与漂移处理、接口返回),第二个问题是 JWT 鉴权、双记录策略与迟到判定、反作弊与生产部署;因为单条回复有长度限制,我又追问了一次补齐了反作弊与部署两部分,三条回复都等到了完整生成。体验中没有出现“同步临时访问凭据(AK/SK)至 AI Shell”协议弹窗,因此不存在勾选问题。问答结束后,我点了顶栏“释放”并在确认弹窗里点了确认,容器进入释放中,随后页面退回开发者官网首页,容器已释放。

三点收获:第一,DevSpace 的 AI 对话很适合“带着案例问技术”,先读案例再提问,回答里的代码可以直接对照案例仓里的实现验证;第二,遇到超长回答被截断时,追问“请继续讲完剩余部分”是最有效的办法;第三,体验版用完一定要记得释放容器,养成好习惯。

十、踩坑记录与总结

今天遇到的坑主要有三个:一是签到时弹出“该身份证下已有其他账号参与成长体系”,签到被拦截,积分没有变化,这是账号维度的限制,按要求只试一次就继续做其他任务;二是博客编辑器在富文本与 Markdown 之间只能选一种,选定后不要中途切换;三是 DevSpace 的 AI 回复较长时会在段落中途结束,需要追问补齐。

总结一下:一个看似简单的“签到 App”,背后是权限、定位、鉴权、数据库、反作弊、部署六条线的交叉。端侧要处理好权限与定位精度,云侧要算准距离、分清角色、写对 Upsert,部署要配好 PM2 与 Nginx,安全上还要防住模拟定位与 Token 泄露。把这条链路走通一次,再去看其他端云一体案例就会快很多。案例链接与代码仓:鸿蒙开发实践中心案例页 https://harmonybp.developer.huaweicloud.cn/cases/bff1556a1ad24181be82eba6f77b1ed9 ,GitCode 代码仓 https://gitcode.com/harmony-practice-center/check-in ,有兴趣的同学可以照着案例亲手跑一遍。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。