4. 考勤数据流解析：从采集到入库的完整路径

数字工地班组考勤数据的可靠性，取决于数据流中每个节点的稳定传递。本节将完整拆解考勤数据从终端采集到最终入库的路径、节点间的数据传递机制，以及常见的数据丢失原因。

4.1 考勤数据流全景架构

考勤数据流通常经过四个核心层级：采集层 → 边缘网关层 → 平台服务层 → 持久化层。每个层级内部又包含多个子节点，数据在节点间通过特定协议和消息格式传递。

4.2 节点间数据传递机制

每个层级之间的数据传递采用不同的机制，理解这些机制是调试数据流问题的前提。

4.3 数据流关键节点详解

4.3.1 采集层：原始数据生成

采集设备生成的数据记录通常包含以下核心字段：

{
  "device_id": "CAM-03-B2",       // 设备唯一标识
  "timestamp": 1712563200,        // Unix 时间戳（秒）
  "employee_id": "EMP20240301",   // 人员编号
  "event_type": "check_in",       // 事件类型：check_in / check_out
  "verify_mode": "face",          // 验证方式：face / card / bluetooth
  "temperature": 36.5,            // 体温（可选）
  "snapshot_url": ""              // 抓拍图片URL（可选）
}

4.3.2 边缘网关层：协议转换与清洗

网关层执行三个关键操作：

1. 协议转换： 将 RS485 二进制帧或私有协议统一转换为标准 JSON。
2. 数据清洗： 过滤重复记录（同一设备、同一员工、5秒内相同事件类型）、补全缺失字段、校正时间偏差。
3. 本地缓存： 当平台不可用时，数据暂存本地 SQLite 或环形缓冲区，网络恢复后按序补传。

4.3.3 平台服务层：业务校验与分发

平台层通过消息队列（如 RabbitMQ）实现削峰填谷，消费者服务执行：

• 人员有效性校验： employee_id 是否在班组白名单中。
• 时间合理性校验： 打卡时间是否在排班窗口 ±30 分钟内。
• 重复数据去重： 基于 device_id + employee_id + timestamp 的联合哈希。
• 异常事件分发： 迟到、早退、缺卡等事件推送至告警服务。

4.4 常见数据丢失原因与排查矩阵

根据现场调试经验，90% 的考勤数据丢失可归因于以下 6 类原因：

4.5 数据流调试工具与命令

以下是在现场调试中常用的工具和命令：

# 1. 查看网关层 MQTT 订阅日志（实时监控原始数据）
journalctl -u edge-gateway -f | grep "MQTT_RECV"

# 2. 检查网关本地缓存队列长度
curl -s http://192.168.1.100:8080/api/v1/cache/status | jq '.queue_length'

# 3. 模拟平台层消息消费（手动确认数据是否到达 RabbitMQ）
rabbitmqadmin get queue=attendance.queue count=10

# 4. 查询 MySQL 中某设备最近 1 小时的考勤记录数
SELECT COUNT(*) FROM attendance 
WHERE device_id = 'CAM-03-B2' 
AND create_time > NOW() - INTERVAL 1 HOUR;

# 5. 触发网关补传所有未同步数据
curl -X POST http://192.168.1.100:8080/api/v1/cache/resync

4.6 数据流健康度监控指标

建议在运维监控面板中持续跟踪以下指标，提前发现数据流异常：

• 采集成功率： 设备上报次数 / 预期上报次数 × 100%，低于 98% 触发告警。
• 网关处理延迟： 从设备时间戳到网关确认的时间差，超过 10 秒需排查。
• 消息队列积压量： 队列中未消费消息数，超过 1,000 条需扩容消费者。
• 入库写入速率： 每秒写入数据库的记录数，低于设备上报速率时出现瓶颈。
• 数据完整率： 平台接收数 / 设备上报数 × 100%，低于 99.5% 需启动数据补传流程。