阅读鸿蒙端云签到案例：从接口契约到上线前检查

阅读华为云鸿蒙开发实践中心的“使用 Agent 生成鸿蒙端云一体员工签到 App”案例后，我整理了一份接口与上线检查清单。本文是对案例设计的阅读笔记，尚未实际部署或验证案例。

先把端云边界写清楚

案例介绍了 ArkTS 端侧、Node.js 与 Express 后端和 MySQL 数据层。手机负责界面、定位与请求；服务端负责鉴权、业务规则和持久化。即使用 Agent 生成代码，也需要人在需求阶段明确谁负责什么，以及出错时用户看到什么。

可以先为签到接口写一份约定：请求包含哪些定位字段，坐标使用什么单位和坐标系，时间以服务器还是设备为准，成功与失败分别返回哪些字段。具体字段名称要以实际仓库为准。

三类容易遗漏的验收情形

1. 定位权限被拒绝或定位失败时，端侧应展示可理解的提示；不要把空坐标当成有效位置提交。
2. 当请求超时但服务端可能已经写入记录时，简单重复提交可能产生重复记录。需要结合服务端的幂等设计或查询结果处理，不能只靠按钮防抖。
3. 分别验证未登录、普通员工访问管理员接口、登录过期等情况。管理员权限应由服务端检查，不能只隐藏前端按钮。

签到范围边界也值得单独测试：距离刚好等于阈值、略小和略大，以及定位精度较差的情况。距离计算采用什么模型、误差如何处理，需要业务方明确；不应把手机坐标当作无法伪造的证明。

上线前检查

案例页面把 HTTPS 作为拓展实践。实际使用涉及账号和位置数据时，应配置 TLS、妥善管理数据库密码和签名密钥，并限制数据库和管理接口的访问范围。演示用的默认账号、密码和明文 HTTP 不应直接用于生产。

日志应帮助定位请求失败，但避免记录密码、令牌或完整的敏感位置数据。对于位置与考勤记录，还需要根据实际用途确定保留期限和访问权限。

最后不要只看服务进程是否启动：健康检查通过、员工登录签到、查看历史、管理员查询及权限拦截都应覆盖。失败用例和回滚方案同样要记录。若使用按量计费云资源，实践结束后检查并释放不再需要的资源。

参考：华为云鸿蒙开发实践中心案例《使用 Agent 生成鸿蒙端云一体员工签到 App》。本文是阅读整理，具体实现和计费以官方页面及实际部署配置为准。