飞创 Fitron

主题

IPC 云端通信：Topic 与消息体规范 ​

Topic 命名规范 ​

IoT Explorer 自定义 Topic 格式：{ProductID}/{deviceName}/{suffix}

方向TopicQoS发布方订阅方用途
下行{ProductID}/{deviceName}/control1CPCIPC统一下行（控制、配置、人脸管理等）

首期 ProductID 为 A0VYTK4W4F；deviceName 与设备 SN 一致，注册时由 CPC 返回。
IPC 上行数据统一经 HTTPS POST {cpc_url}/v1/ipc/report 上报，不走 MQTT Topic。

通用字段 ​

HTTPS 上行请求结构（Header + Body） ​

部分关键字段说明
HeaderX-SN、X-Request-ID、X-Timestamp、X-Nonce、X-Signature身份识别 + 验签
Body消息通用格式 JSON与 MQTT 下行消息结构完全一致

约定：Header 已包含的 sn / timestamp，Body 可以不重复携带。若 Body 携带了同名字段，必须与 Header 一致。签名原文格式：uppercase(SN) + ":" + TIMESTAMP + ":" + NONCE + ":" + BODY；BODY 不允许换行，首尾空格不参与签名。

消息通用格式（MQTT 下行 / HTTPS 上行 Body） ​

json
{
  "type": "category:target:action",
  "msg_id": "uuid-v4",
  "reply_msg_id": "uuid-v4",
  "timestamp": 1700000000,
  "sn": "FITRON-0001-0001",
  "data": {}
}
字段必填说明
type是三段式类型，格式 category:target:action
msg_id是本条消息唯一 ID
reply_msg_id否回复某条消息时填写其 msg_id
timestamp是Unix 秒级时间戳
sn是设备 SN
data是业务载荷；无额外字段时传 {}

type 首段 category 取值：

category方向说明
control下行CPC 下发控制、配置、人脸管理等指令
result上行回复某条 control:* 指令的执行结果
report上行设备主动上报（发现、心跳、状态、事件、补偿等）

控制类消息 ​

下行控制指令 ​

json
{
  "type": "control:door:open",
  "msg_id": "f6a7b8c9-d0e1-2345-fabc-456789012345",
  "timestamp": 1700000000,
  "sn": "FITRON-0001-0001",
  "data": {
    "door": "A"
  }
}

上行控制执行结果 ​

json
{
  "type": "result:door:open",
  "msg_id": "b4c5d6e7-f8a9-0123-bcde-234567890123",
  "reply_msg_id": "f6a7b8c9-d0e1-2345-fabc-456789012345",
  "timestamp": 1700000000,
  "sn": "FITRON-0001-0001",
  "data": {
    "result": "success",
    "error_code": 0,
    "error_message": "",
    "door": "A",
    "state": "open",
    "locked": false
  }
}

人脸类消息 ​

扫脸上报（HTTPS 上行） ​

json
{
  "type": "report:face:scan",
  "msg_id": "d6e7f8a9-b0c1-2345-defa-456789012345",
  "timestamp": 1700000000,
  "sn": "FITRON-0001-0001",
  "data": {
    "face_id": "face-U10001-001",
    "user_type": "user",
    "user_id": "U10001",
    "confidence": 0.96,
    "channel": "通道号",
    "side": "entry|exit"
  }
}

人脸下载指令（MQTT 下行） ​

json
{
  "type": "control:face:download",
  "msg_id": "f8a9b0c1-d2e3-4567-fabc-678901234567",
  "timestamp": 1700000000,
  "sn": "FITRON-0001-0001",
  "data": {
    "user_id": "U10001",
    "face_id": "face-U10001-001",
    "face_url": "https://cpc.example.com/faces/U10001/face-001.jpg"
  }
}

人脸管理结果上报（HTTPS 上行） ​

json
{
  "type": "result:face:download",
  "msg_id": "b0c1d2e3-f4a5-6789-bcde-890123456789",
  "reply_msg_id": "f8a9b0c1-d2e3-4567-fabc-678901234567",
  "timestamp": 1700000000,
  "sn": "FITRON-0001-0001",
  "data": {
    "result": "success",
    "error_code": 0,
    "error_message": ""
  }
}

配置与补偿类消息 ​

配置更新通知（MQTT 下行） ​

json
{
  "type": "control:config:update",
  "msg_id": "d2e3f4a5-b6c7-8901-defa-012345678901",
  "timestamp": 1700000000,
  "sn": "FITRON-0001-0001",
  "data": {
    "config_version": "v1.3.0",
    "config_hash": "sha256:xyz789..."
  }
}

配置校验结果（HTTPS 上行） ​

json
{
  "type": "result:config:acceptance",
  "msg_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "reply_msg_id": "d2e3f4a5-b6c7-8901-defa-012345678901",
  "timestamp": 1700000000,
  "sn": "FITRON-0001-0001",
  "data": {
    "result": "success",
    "error_code": 0,
    "error_message": "",
    "config_version": "v1.3.0",
    "config_hash": "sha256:xyz789..."
  }
}

设备发现上报（HTTPS 上行） ​

json
{
  "type": "report:device:discovery",
  "msg_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": 1700000000,
  "sn": "FITRON-0001-0001",
  "data": {
    "controllers": [],
    "sensors": []
  }
}

心跳上报（HTTPS 上行） ​

json
{
  "type": "report:device:heartbeat",
  "msg_id": "b4c5d6e7-f8a9-0123-bcde-234567890123",
  "timestamp": 1700000000,
  "sn": "FITRON-0001-0001",
  "data": {
    "status": "online",
    "software_version": "2.0.0",
    "config_version": 13
  }
}

状态快照上报（HTTPS 上行） ​

json
{
  "type": "report:device:state",
  "msg_id": "c5d6e7f8-a9b0-1234-cdef-456789012345",
  "timestamp": 1700000000,
  "sn": "FITRON-0001-0001",
  "data": {
    "doors": [],
    "controllers": []
  }
}

断网补偿上报（HTTPS 上行） ​

json
{
  "type": "report:device:compensate",
  "msg_id": "e3f4a5b6-c7d8-9012-efab-123456789012",
  "timestamp": 1700000000,
  "sn": "FITRON-0001-0001",
  "data": {
    "offline_from": 1700000000,
    "offline_until": 1700000300,
    "record_count": 3,
    "records": []
  }
}

补偿规则：

  • 缓存上限 1000 条
  • 网络恢复后 30 秒内启动补偿
  • 按原始发生时间升序补传

飞创 Fitron 内部规划文档