江西省安全生产智慧培训考核系统 考勤数据推送接口文档

附件1

江西省安全生产智慧培训考核系统

考勤数据推送接口文档

（试行v0.9.2）

江西省应急管理厅

2026年7月

培训机构考勤设备长连接接入说明及协议规范

一、接入目的

为规范培训机构线下培训考勤设备接入、考勤数据采集和数据安全管理，保障考勤数据真实、完整、及时、可追溯，现对培训机构考勤设备通过长连接方式接入安全生产智慧培训考试系统的有关要求说明如下。

本方案推翻原“培训机构提供数据接口、系统定时拉取数据”的接入模式，调整为“考勤设备主动建立长连接接入我方平台，并按协议实时上报考勤数据”的模式。培训机构和设备方应按照我方统一定义的接入协议完成设备改造、部署、联调和上线。

二、适用范围

本说明适用于已接入或拟接入安全生产智慧培训考试系统的培训机构，以及用于线下培训签到、签退、身份核验、打卡采集等场景的考勤设备。考勤设备包括但不限于人脸识别考勤机、签到终端、打卡机及其他能够采集培训现场考勤数据的设备。

三、总体接入要求

1. 考勤设备应主动通过长连接方式连接我方平台，不再要求培训机构提供由我方系统拉取数据的业务接口。

2. 长连接协议由我方统一定义，设备方应按《考勤设备长连接接入协议规范》完成协议适配。

3. 设备接入应采用加密通道，推荐使用 WSS（WebSocket over TLS）协议。

4. 设备连接平台后，应完成设备认证、心跳保活、状态上报、考勤记录上报、平台回执处理和断线补传。

5. 培训机构应保障设备现场网络能够访问我方平台长连接地址，并配合完成网络放行、设备部署和联调测试。

6. 考勤数据不得通过设备厂商云平台或第三方平台中转、存储、加工或转发。

四、设备管理要求  （培训机构自己在系统操作）

培训机构应在系统中完成考勤设备基础信息登记。系统功能入口为：

教室设备管理 -> 设备管理

培训机构可通过设备名称、设备ID、设备IP等信息添加考勤设备，并对已登记设备进行新增、查询、修改、删除、启用、停用等管理操作。设备信息应与实际接入设备保持一致，设备ID应与设备长连接认证和考勤记录上报中的设备标识一致。

五、培训机构配合要求

1. 完成考勤设备现场安装、网络配置和基础测试，确保设备能够访问我方平台长连接接入地址。

2. 在系统中维护设备名称、设备ID、设备IP、所属教室、设备状态等基础信息。

3. 配合我方为设备生成或下发接入凭证，并妥善管理设备凭证、密钥和网络访问权限。

4. 配合设备方完成长连接协议适配、设备认证、心跳、考勤记录上报、断线重连和数据补传测试。

5. 设备更换、迁移、停用、IP变更、网络调整时，应及时在系统中更新设备信息并通知相关方。

6. 发现设备离线、数据异常、重复上报、漏报、疑似篡改等情况时，应及时排查并配合我方处理。

六、设备方实现要求

1. 按我方协议实现 WSS 长连接客户端能力，设备启动后主动连接我方平台。

2. 按我方分配的设备ID和设备凭证完成认证，认证失败的设备不得上报考勤数据。

3. 按约定频率发送心跳，平台可据此判断设备在线、离线和异常状态。

4. 设备产生考勤记录后应实时上报，并接收平台返回的确认消息。

5. 每条考勤记录必须具备唯一 recordId，平台按 recordId 做幂等处理。

6. 设备未收到平台确认时，应保留本地记录并重试上报。

7. 设备断网或平台不可达期间，应本地缓存考勤记录，重连后按打卡时间顺序补传。

8. 设备应保留必要运行日志、连接日志、认证日志和考勤原始记录，便于问题追溯。

七、数据安全要求

1. 考勤设备必须直接连接我方平台，不得使用设备厂商云平台、第三方云平台或其他非授权平台作为数据通道。

2. 考勤数据不得上传至设备厂商云端或其他第三方平台，防止第三方平台对考勤数据进行伪造、留存、转卖、泄露或二次使用。

3. 长连接通道应采用 TLS 加密，设备认证应校验设备ID、时间戳、随机数和签名等要素。

4. 培训机构和设备方不得通过人工补录、脚本造数、接口模拟等方式伪造考勤记录。

5. 平台有权对设备上报记录与设备本地原始记录进行核验。

6. 培训机构应保留设备原始考勤记录和必要日志，以便监管核验、异常追溯和争议处理。

八、接入流程

1. 设备登记：培训机构在“教室设备管理 -> 设备管理”中维护设备基础信息。

2. 凭证分配：我方平台为设备生成设备ID、接入密钥等接入凭证。

3. 协议适配：设备方按照长连接接入协议完成设备端开发或配置。

4. 网络联调：确认设备现场网络可访问我方 WSS 接入地址。

5. 认证联调：验证设备连接、认证、心跳、在线状态识别是否正常。

6. 数据联调：验证考勤记录实时上报、平台回执、重复上报幂等处理是否正常。

7. 补传联调：验证断网缓存、断线重连、未确认记录补传能力。

8. 上线运行：联调和验收通过后，设备纳入平台正式管理。

九、异常处理要求

1. 设备认证失败时，设备方应检查设备ID、密钥、签名、时间戳和设备启用状态。

2. 设备长时间离线时，培训机构应检查现场供电、网络、防火墙和设备运行状态。

3. 考勤记录上报失败时，设备应保留本地记录并按协议重试，直至收到平台确认或进入人工处理流程。

4. 发现重复上报时，平台按 recordId 幂等处理，设备方应排查重试策略是否符合协议要求。

5. 发现漏报或补传失败时，培训机构和设备方应提供设备原始记录、连接日志和上报日志进行核验。

6. 发现数据疑似被篡改、伪造、删除或异常留存时，应立即暂停相关设备接入并配合调查。

十、验收要求

1. 系统能够通过设备名称、设备ID、设备IP查询到已登记设备。

2. 系统能够对考勤设备进行新增、查询、修改、删除、启用、停用等管理操作。

3. 设备能够通过 WSS 主动连接我方平台并完成认证。

4. 平台能够识别设备在线、离线、未认证和异常状态。

5. 设备能够实时上报考勤记录，平台能够返回确认消息。

6. 设备断网后能够本地缓存数据，重连后能够补传未确认记录。

7. 重复上报的考勤记录不会重复入库。

8. 考勤数据不经过设备厂商云平台或第三方平台中转、存储和处理。

9. 平台能够根据设备ID、打卡时间、教室部署关系匹配出勤和学时。

10. 培训机构和设备方能够提供设备原始记录、连接日志、上报日志和必要排查材料。

一、文档说明

本文档用于规范考勤设备通过长连接方式接入我方平台的协议要求。接口协议由我方统一定义，设备方应按照本文档完成设备端开发、配置、联调和上线。设备不得通过设备厂商云平台或第三方平台中转考勤数据。

二、总体架构

考勤设备主动连接我方平台长连接接入服务，平台完成设备认证、连接管理、消息校验、考勤记录接收、回执确认、数据入库和后续出勤学时核验。

考勤设备

  -> WSS 长连接接入服务

  -> 设备认证与连接管理

  -> 消息校验与幂等处理

  -> 考勤数据入库

  -> 出勤/学时核验

三、接入地址与协议要求

四、连接流程

1. 平台完成设备登记，并为设备分配 deviceId、accessKey、secretKey 等接入凭证。

2. 设备启动后主动连接平台 WSS 接入地址。

3. 设备连接建立后，应立即发送 AUTH 认证消息。

4. 平台校验设备ID、机构归属、设备状态、时间戳、随机数和签名。

5. 认证通过后，平台返回 AUTH_ACK，设备进入已认证在线状态。

6. 设备按约定频率发送 HEARTBEAT 心跳消息。

7. 设备产生考勤记录后发送 ATTENDANCE_RECORD 消息。

8. 平台接收并处理后返回 ATTENDANCE_ACK 确认消息。

9. 设备未收到确认时应保留本地记录并重试；断线后应重连并补传未确认记录。

五、通用消息结构

所有业务消息均应包含统一消息头，业务数据放入 payload。

{

  "messageId": "MSG202607030001",

  "messageType": "AUTH",

  "deviceId": "KQ001",

  "timestamp": "2026-07-03 09:30:00",

  "payload": {}

}

六、消息类型

七、设备认证

设备建立连接后必须先发送 AUTH 消息。未认证或认证失败的连接不得上报考勤记录。

签名建议采用 HMAC-SHA256，签名原文由 deviceId、timestamp、nonce 按顺序拼接生成，密钥使用平台分配的 secretKey。平台可根据安全要求调整签名规则，设备方应按我方最终联调口径实现。

八、心跳机制

设备认证成功后应每 30 秒发送一次 HEARTBEAT 消息。平台连续 3 个心跳周期未收到设备心跳或业务消息时，可将设备标记为离线。设备断线后应自动重连，重连成功后继续发送心跳并补传未确认考勤记录。

{

  "messageId": "MSG202607030002",

  "messageType": "HEARTBEAT",

  "deviceId": "KQ001",

  "timestamp": "2026-07-03 09:30:30",

  "payload": {

    "status": "ONLINE",

    "localRecordCount": 0

  }

}

九、考勤记录上报

设备产生打卡记录后，应通过 ATTENDANCE_RECORD 消息实时上报。每条考勤记录必须包含唯一 recordId。

十、设备状态上报

设备发生启动、关机、故障、恢复、存储不足、摄像头异常等状态变化时，应主动上报 DEVICE_STATUS 消息。

十一、确认、重试与补传

1. 平台收到 ATTENDANCE_RECORD 并完成基础校验后，应返回 ATTENDANCE_ACK。

2. 平台已接收过相同 recordId 的记录时，应返回成功确认，并按幂等规则避免重复入库。

3. 设备未收到 ATTENDANCE_ACK 时，不得删除本地原始记录，应在不低于 10 秒的间隔后重试。

4. 设备断网或平台不可达期间，应本地缓存考勤记录，缓存能力原则上不少于 7 天或 10000 条记录。

5. 设备重连成功后，应按实际打卡时间顺序补传未确认记录。

6. 补传数据必须保留实际 punchTime，同时由平台记录数据上报时间。

7. 平台对重复消息按 messageId 去重，对重复考勤记录按 recordId 去重。

十二、错误码

十三、安全要求

1. 长连接必须使用 TLS 加密通道，不得明文传输考勤数据和设备凭证。

2. 设备必须使用平台分配的设备凭证完成认证，不得共用其他设备凭证。

3. 设备凭证不得泄露给无关单位或个人，不得写入公开文档、日志或可被直接读取的位置。

4. 考勤设备不得连接设备厂商云平台或第三方云平台作为考勤数据通道。

5. 设备方不得伪造、篡改、删除、选择性上报考勤记录。

6. 平台应记录连接日志、认证日志、消息日志、异常日志和数据入库日志。

7. 培训机构和设备方应配合我方对设备原始记录与平台接收记录进行核验。

十四、验收标准

1. 设备可通过 WSS 主动连接我方平台。

2. 平台可完成设备认证，并拒绝未登记、停用、签名错误或时间戳异常的设备。

3. 设备可按约定频率发送心跳，平台可识别在线和离线状态。

4. 设备产生考勤记录后可实时上报到平台。

5. 平台收到记录后可返回确认消息。

6. 设备断线后可自动重连。

7. 设备断网期间可本地缓存数据，重连后可补传。

8. 重复上报的考勤记录不会重复入库。

9. 考勤数据不经过设备厂商云平台或第三方平台。

10. 平台可根据设备ID、打卡时间、教室部署关系匹配出勤和学时。