更新记录

1（2026-11-11） 下载此版本

-

平台兼容性

考勤打卡 · 使用说明

基于 uni-app（Vue 2） 的移动考勤打卡应用，一套代码可运行在 App、H5、微信小程序。 考勤规则、打卡位置、允许范围全部可以在界面里改，不需要改代码；数据默认保存在本机，方便在接入后端之前先把流程跑通。

一、功能一览

二、目录结构

考勤打卡/
├── App.vue                  启动时加载本地保存的考勤规则
├── pages.json               页面与 tabBar 配置
├── manifest.json            App / H5 / 小程序配置（地图 Key 在这里）
├── common/
│   ├── config.js            考勤规则：默认值、校验、保存、恢复默认、地图配置
│   ├── utils.js             纯函数：时间换算、距离计算、迟到早退判定、位置状态判定
│   ├── store.js             打卡记录读写、日汇总、月统计
│   └── amap.js              高德 Web 服务：坐标 → 文字地址
├── pages/
│   ├── index/index.vue      打卡首页
│   ├── records/records.vue  打卡记录
│   ├── stats/stats.vue      考勤统计
│   ├── mine/mine.vue        我的
│   └── rules/rules.vue      考勤规则设置
└── static/
    ├── tabbar/              底部导航图标
    └── marker-punch.png     地图上的考勤点标记

三、快速开始

1. 用 HBuilderX 打开本目录（文件 → 打开目录）。
2. 选择运行端：
   • App：运行 → 运行到手机或模拟器（真机需开启定位权限）
   • H5：运行 → 运行到浏览器（需先配好地图 Key，见第四节）
   • 微信小程序：运行 → 运行到小程序模拟器，需先在 manifest.json 填小程序 AppID
3. 首次进入会自动定位。若不在考勤范围内，打卡按钮会置灰并提示距离。

改过 manifest.json（尤其是模块、地图 Key）之后，必须停止运行再重新运行，热更新不会重新读取这些配置。

四、地图配置（重要）

本项目一共用到 3 个不同类型的高德 Key，用途不同，需要分别到高德开放平台创建：

也可以在 HBuilderX 里点开 manifest.json 用可视化界面填（默认就是可视化模式，右上角可切换到源码视图）。

微信小程序额外要求：把 https://restapi.amap.com 加入小程序后台的 request 合法域名，否则逆地理编码会失败（不影响打卡本身）。

五、考勤规则设置

从「我的 → 考勤规则设置」进入，改完点底部「保存规则」立即生效。

关于地图与范围圈：设置页的地图会以考勤点为中心画出蓝色圆圈，圆圈就是允许打卡的范围。切换半径时圆圈实时缩放、地图自动调整缩放级别，可以拖动地图确认范围是否把办公楼完整覆盖。

修改规则对历史记录的影响：打卡当时就已经判定好「迟到 / 早退」并写入记录，之后改规则不会回溯修改旧记录，只影响后续打卡。

六、打卡与位置校验

打卡按钮有四种形态：

位置判定只有四种结果，页面与数据层共用同一套逻辑：

• ok —— 定位成功且在半径内，可打卡
• out —— 定位成功但超出半径，禁止打卡
• failed —— 定位失败，禁止打卡（不会因为定位失败就放行）
• locating —— 定位进行中

两道拦截：页面按钮先拦一次，写入数据前 store.addRecord 再校验一次，防止绕过界面直接调用写入假数据。

七、数据存储

全部数据存在本机 Storage，清除应用数据或点「我的 → 清空考勤数据」会一并丢失。

单条打卡记录的结构：

{
  id: '1731300000000-a1b2c3',
  date: '2026-11-11',
  type: 'in',            // in 上班 / out 下班
  timestamp: 1731300000000,
  timeText: '09:02',
  status: 'late',        // normal 正常 / late 迟到 / early 早退
  location: {
    address: '科技园南路',
    distance: 42,
    inRange: true,
    mock: false,         // 是否定位失败
    simulated: false     // 是否使用了开发期模拟坐标
  },
  remark: ''
}

八、常见问题

1. 点打卡按钮没反应 / 一直显示「正在校验考勤范围…」 定位还没返回结果。进入页面会自动定位，若长时间无结果，点一下顶部定位条或提示条上的「重新定位」。 代码里做了 10 秒超时兜底，超时后会明确提示失败原因，不会一直卡住。

2. 明明在公司，却提示「不在考勤范围」

• 先确认考勤点坐标是否正确：我的 → 查看考勤点
• 再看顶部定位条显示的距离与半径是否合理
• 室内定位误差可能上百米，可把半径调大一些（如 500 米）

3. 设置页地图是空白的

• App 端：检查高德 Android / iOS Key 是否绑定正确的包名与 SHA1。用 HBuilderX 标准基座调试时包名是 io.dcloud.HBuilder，需要把该包名和对应 SHA1 加入 Key 的白名单；正式打包则填你自己的包名。
• H5 端：manifest.json → H5 配置 → 地图 里的 JS API Key 和安全密钥是否已填。
• 地图加载失败时页面会显示「地图未能加载」占位，此时仍可用「用当前位置」保存坐标。

4. 地图选点打不开，提示「地图选点不可用」 uni.chooseLocation 依赖地图模块与 Key。App 端确认 manifest.json → App 模块配置 已勾选 Maps；H5 端确认已填 JS API Key。临时可用「用当前位置」代替。

5. App 端改了配置不生效 manifest.json 的改动必须重新编译运行，热更新无效。

6. 打卡页显示「模拟定位」 这是开发期的兜底：模拟器拿不到真实定位时，会用考勤点坐标代替，方便验证流程。正式打包（NODE_ENV=production）后此逻辑自动失效。可在 common/config.js 的 debug.mockLocationOnFail 关掉。

7. 清空数据后规则还在 「清空考勤数据」只删打卡记录。要恢复出厂规则用规则设置页的「恢复默认」。

九、接入后端要改哪里

页面只依赖 common/store.js 暴露的函数，把存储换成接口即可，页面几乎不用动：

// common/store.js 里这几个函数改成请求后端
readRecords()  →  GET  /api/attendance/records
writeRecords() →  POST /api/attendance/records
addRecord()    →  保留位置校验，再提交到服务端

其余对外函数（getTodaySummary / getMonthStat / getMonthDayMap / getRecords / removeRecord / clearRecords）签名保持不变即可。

员工资料在 common/store.js 的 DEFAULT_PROFILE 与 common/config.js 的 DEFAULT_CONFIG.company 里，目前是占位数据（林嘉怡 / 产品设计部 / 深圳南山），上线前记得替换。

十、开发注意事项

1. ATTENDANCE_CONFIG 必须就地改字段

common/config.js 导出的 ATTENDANCE_CONFIG 是运行期共享的同一个对象，页面 data 里持有的是它的引用。改规则一律通过 applyConfig / saveConfig 就地赋值，不要整体替换对象，否则已经渲染的页面收不到更新。

2. 配置校验有两套模式

normalizeConfig(input, { strict: true })   // 保存时：收集错误，有问题拒绝落库
normalizeConfig(input, { strict: false })  // 读缓存时：静默钳制回合法范围，防止手改存储把应用搞挂

3. 历史记录不回溯

迟到 / 早退在打卡当时判定并写死，改规则只影响之后的打卡。如果要让历史统计也跟随规则变化，需要在记录里额外冗余一份规则快照。

4. 单位换算

样式统一用 rpx，逻辑里的距离单位是米、时间单位是分钟。经纬度统一使用 gcj02（高德 / 微信 / uni.getLocation({type:'gcj02'}) 一致），与考勤点坐标同坐标系，计算距离才不会偏。

十一、默认账号与初始数据

以上均为演示用占位数据，可在 common/config.js 与规则设置页中修改。