消防大数据平台数据接口规范

消防大数据平台数据接口规范一、总体要求数据接口是打通消防前端感知设备与后端指挥调度系统的“血管”，任何格式错乱、延迟超标或鉴权失效，均可能导致火情误报、漏报或指挥调度失灵。本规范旨在统一各接入方的数据标准与交互行为，确保数据流转全程可追溯、可执行、可度量。1.1适用范围与对象本规范适用于各类消防物联网终端厂商、建筑消防设施系统提供商、第三方应用平台接入消防大数据平台的数据对接工作。责任主体为接入方开发团队与平台运维团队。1.2术语与定义•接入方：发起数据上报或调用的终端设备、网关或第三方业务系统。•平台方：消防大数据平台运行维护管理方。•AppKey/AppSecret：平台分配给接入方的唯一应用标识与密钥，用于鉴权。•AccessToken：接入方调用业务接口前必须获取的临时访问令牌。1.3接口安全与鉴权机制未授权的接入可能导致虚假警情注入或真实火情数据被篡改，引发错误的消防力量调度。为什么这么做：消防数据涉及公共安全，必须在应用层与网络层实施双重校验，阻断伪造请求与重放攻击。怎么做：1.接入方必须向平台方申请AppKey和AppSecret。2.调用业务接口前，必须使用AppSecret对请求参数按字典序拼接后计算SHA-256摘要，作为signature传入认证接口获取AccessToken。3.AccessToken有效期为7200秒。在请求头中必须携带：Authorization:Bearer<AccessToken>。4.请求体中必须包含timestamp（毫秒级时间戳）与nonce（随机数）。出问题怎么办：•若平台返回HTTP401及错误码40101（Token无效或过期），接入方必须在100毫秒内触发重新获取Token逻辑，并重试原请求。•若平台返回40102（时间戳偏差超限），接入方应当同步本地服务器时间。平台允许时间偏差≤60•严禁在未获取新Token的情况下连续重试原请求（会导致接入方IP被防火墙拉黑，拉黑期24小时）。二、基础通信协议与报文规范统一的通信协议是异构系统互联互通的基石，决定了数据传输的可靠性与解析效率。2.1传输层要求•优先使用HTTPS（TLS1.2及以上）协议进行数据传输；•若终端设备算力极低且不支持TLS，可降级使用MQTToverTCP协议并采用应用层国密SM4加密；•严禁使用明文HTTP或未加密的TCP通道传输消防控制室主机数据（明文传输易被中间人截获并伪造火警信号）。2.2报文结构与通用头统一使用JSON格式报文。字符编码必须为UTF-8。时间字段统一采用ISO8601标准格式（如2024-05-20T14:30:00+08:00）。请求报文通用结构必须包含以下字段：字段名类型是否必填说明deviceIdString是设备唯一识别码（原厂SN码）timestampLong是报文生成时间戳（毫秒）dataTypeString是业务数据类型标识dataObject是业务数据体signatureString是报文签名摘要2.3数据加密与脱敏涉及报警人姓名、联系电话等隐私信息，必须脱敏处理。手机号必须脱敏为`138******格式。身份证号严禁传输明文，必须采用SHA-256`散列后传输。业务数据体优先采用国密SM4加密传输；若接入方硬件不支持，可使用AES-256-CBC加密；严禁使用DES或3DES算法（算力开销大且存在已知安全漏洞）。三、核心业务数据接口业务接口直接映射消防实战需求，其字段完整性与时序逻辑关乎灭火救援的响应速度。3.1消防设施状态接口状态数据是判断设备是否处于战备状态的依据。错误的状态上报会导致火情发生时设备无响应。动作机理：消防主机（FAS）发生状态变化->网关抓取并解析主机协议->转换为标准JSON组包->通过HTTPS发送至平台。

错误后果：若网关轮询间隔过长，会导致火警信号延迟上报；若采用并发上报，未做限流，会导致网关内存溢出崩溃，丢失报警数据。接口路径：POST/api/v1/device/status业务数据体data必须包含：•systemType（系统类型）：如fire_alarm、sprinkler、smoke_exhaust•deviceStatus（设备状态）：枚举值normal（正常）、fault（故障）、alarm（报警）•location（安装位置）：精确到楼层与具体防区状态变化时必须立即上报（延迟≤33.2消防警情流转接口警情流转接口用于将确认识别后的火警信息推送至指挥中心。接口路径：POST/api/v1/alarm/fire警情数据必须包含：发生时间、设备ID、建筑ID、警情级别（1-4级）、经纬度坐标。警情数据产生后，必须在5秒内完成上报。平台收到后返回200OK及流水号，接入方应当将流水号本地留存至少30天，用于后续追溯。3.3消防水位与水压监测接口用于监测消防水池水位及管网末端水压，确保消防供水系统有效。风险演化叙事：•起因：传感器电池电量低或环境温度骤降。•传播途径：传感器采样频率被迫下降->网关接收数据周期拉长->平台数据更新停滞。•触发条件：水压低于0.15MPa时平台触发预警。•最终后果：因数据未更新，平台无法预警真实管网无水情况，火灾发生时消防水泵无水可抽，导致火势失控。因此，水压/水位监测数据必须同时上报设备电池电量（百分比）。当电量≤15%时，必须在deviceStatus字段标记为四、异常处理与重试机制网络抖动与设备离线是常态化场景，健壮的异常处理机制是保障数据不丢失的最后防线。4.1错误码定义与分级错误响应分为三级，接入方必须根据级别执行不同策略：级别错误码区间含义判定标准启动权限处置原则一级40000-40999客户端参数错误缺失必填字段或格式非法接入方本地处理立即终止上报，写入本地错误日志，修正后重发二级50000-50999平台服务异常平台网关超时或内部错误平台运维人员触发指数退避重试，超过5次转死信队列三级90000-99999安全与鉴权违规Token失效、IP被封平台安全模块停止上报，告警通知接入方运维负责人4.2重试策略与死信队列当遇到网络超时或平台5xx错误时：1.优先使用指数退避策略进行重试（等待1秒、2秒、4秒、8秒、16秒）。2.若重试5次仍失败，必须将报文写入本地SQLite死信队列，并触发本地蜂鸣告警。3.严禁在遇到4xx错误（参数错误）时进行重试（会产生大量无效请求，拖垮网关性能）。4.3断连恢复与数据补偿网络恢复后，接入方必须从本地死信队列或断点日志中，按时间戳顺序补传断连期间的数据。补传数据的timestamp必须保持原始发生时间，并在请求头增加X-Retry:true标识。平台方应当对该类数据降低处理优先级，避免补传洪峰冲垮实时警情处理通道。五、接口测试与验收标准上线前的严苛测试是防止“带病运行”的唯一手段，必须通过量化指标卡死接入质量。5.1测试流程与用例要求测试环境必须与生产环境物理隔离。接入方必须提供至少100条覆盖正常、故障、报警场景的模拟数据用例。所有涉及消防联动控制的数据上行，必须提供第三方检测机构出具的协议一致性测试报告。5.2性能与并发验收指标平台接口响应时间必须≤2005.3安全性校验测试期间必须通过越权访问测试（使用A设备的Token上报B设备数据，应返回40301）。必须通过SQL注入测试（在location字段拼接;DROPTABLE语句，平台应拦截并返回40001）。严禁在生产环境进行破坏性安全测试。六、运维监控与故障排查接口上线并非终点，持续的链路监控与快速定位能力是维持平台长效运行的保障。6.1核心监控指标接入方网关应当暴露Prometheus格式的监控指标端点。核心指标必须包含：•fire_alarm_push_total（火警推送总数，按1分钟粒度聚合）•api_request_duration_seconds（接口请求延迟直方图）•dead_letter_queue_length（死信队列积压数，阈值>506.2故障排查SOP当平台侧发现某接入方数据断流超过10分钟时：1.平台运维发送告警短信至接入方第一联系人。2.接入方必须在15分钟内响应，检查本地网关运行状态及网络连通性。3.若30分钟内未恢复，应当启动应急接管流程，通知该片区消防控制室恢复人工24小时值守，严禁在此期间脱岗。6.3数据校验与对账每周一上午9:00，平台自动执行对账脚本。对账逻辑比对接入方本地日志上报条数与平台入库条数。若差异率>0.1七、附件7.1消防数据接口接入检查表此表供接入方完成对接后自检及平台方现场验收使用，必须逐项打勾确认。序号检查项量化标准与要求自检结果验收结果1鉴权配置已配置AppKey/AppSecret，Token刷新逻辑测试通过[]是[]否[]是[]否2传输加密生产环境已启用HTTPS或MQTT+SM4加密，无明文传输[]是[]否[]是[]否3隐私脱敏报警人手机号、身份证号等字段已按规范脱敏或散列[]是[]否[]是[]否4时延测试状态变化上报延迟≤3秒，警情上报延迟≤[]是[]否[]是[]否5重试机制已实现指数退避重试，死信队列写入功能正常[]是[]否[]是[]否6压测达标99分位响应时间≤200[]是[]否[]是[]否7监控暴露网关已暴露Prometheus指标，死信积压