1. Base URL#

https://mum.tonzou.cn

本文接口路径统一包含 /api/v1，与 Base URL 拼接时不重复添加版本前缀。

2. 业务关系#

• 账号、家庭、房间、平台设备和平台场景由 MumIot 管理。
• 中控屏负责自己的界面、本地缓存、本地协议连接和实际执行。
• 每台本地设备在平台上关联唯一执行屏；其他屏通过平台发起控制。
• 本地断网控制保留，过期远程命令不在恢复联网后补执行。
• 状态同步和执行命令是两种消息，收到同步事件不会自动再次执行设备动作。

3. 主通信方式#

本稿以 HTTPS REST 为主，命令领取和事件同步使用有时限的长轮询。屏主动建立连接，不需要平台从公网直接连接屏的地址。

建议默认心跳间隔 30 秒、在线租期 90 秒、单次长轮询最多 20 秒。具体值由会话响应下发；客户端 HTTP 读取超时应大于等待时间并留有传输余量。命令处理、事件同步、心跳分别调度，长轮询不阻塞心跳或回执。

若平台已有网关通信协议，可将本文的命令、状态和回执模型映射到已有通道；本稿不要求平台同时维护多套通信机制。

4. 接口目录#

1. 请求头#

幂等范围为当前租户、调用主体、方法、规范化资源路径及 Idempotency-Key。相同键与相同业务内容返回同一操作结果；相同键但不同内容返回 IDEMPOTENCY_CONFLICT。服务端在产生副作用前原子登记该键，并发重试也只产生一项业务操作。

建议业务幂等记录至少保留 7 天；超过保留期的旧控制请求不得作为自动重试重新提交。命令执行记录与幂等记录的保留期均由平台明确。身份类响应含凭证，按第三节规定处理，不作为普通日志保存。

认证和当前资源权限检查先于幂等结果返回；撤权后不能借旧幂等键取回受限结果或执行许可。长轮询返回命令或事件前也要重查身份，不在等待期间把已经失效的访问继续放行。

对于已有路径，本文新增的必填字段、HTTP 202 和响应模型仅用于明确声明 panel-v1 的调用。原手机/网页请求格式由平台保留兼容，并在内部归入同一设备路由和命令记录；不能直接把新必填字段施加到所有旧客户端。旧调用若没有稳定请求键，不能声称具备本文定义的客户端重试去重保证。

2. 成功响应#

{
  "code": 0,
  "message": "success",
  "data": {}
}

单条结果在 data；分页业务沿用现有 PageResult。中控快照、事件、命令领取及批量上报采用各自定义的数据结构，不强套 PageResult。

业务 code=0 只表示该接口请求处理成功。命令是否执行，以 data.state、data.terminal 及执行证据为准。

3. 错误响应#

{
  "code": 40901,
  "message": "请求编号已用于另一项操作",
  "data": {
    "errorCode": "IDEMPOTENCY_CONFLICT",
    "requestId": "req-example-01",
    "retryable": false
  }
}

错误使用对应非 2xx HTTP 状态。若现有业务接口采用其他错误结构，由平台提供准确映射；屏不能仅凭 HTTP 200 判定设备控制成功。

4. 标识与时间#

设备离线、平台连接中断和状态陈旧分别表示，不互相替代。平台响应中的 serverTime 用于估计时差，执行截止时间在屏内换算为单调时钟，防止系统时间跳变使过期命令继续执行。

1. 身份模型#

新增建议。 平台为屏配置独立的终端身份及家庭关联，签发 ROLE_PANEL 身份。AppSecret 继续留在平台服务端；屏端不持有全应用共享的长期 Secret。

开发阶段为已配置测试板预置终端身份与测试家庭，联网后自动建立会话，不增加用户输入激活码或人工审批。预置终端凭证与对应平台记录由平台方通过受控配置交付；序列号仅用于定位和核对，不能单凭序列号获得授权。终端凭证不能直接固化成所有 APK 共用值。

家庭、会员关联及可执行设备范围由平台决定，不能由屏在请求里任意指定。设备、家庭或成员关系失效后，平台在每次敏感调用及消息投递时重新检查。

本稿建议允许受限屏身份调用既有家庭、设备、场景和必要涂鸦/AI 业务入口。平台负责将屏身份关联到当前家庭的业务上下文，不能把屏 Token 当成管理员 Token，也不要求把会员密码下发到屏。

2. 建立会话#

鉴权：Authorization: PanelBootstrap <终端初始化凭证>

参数：body: PanelSessionRequest

{
  "serialNumber": "PANEL-DEMO-001",
  "installationId": "install-example-01",
  "bootId": "boot-example-01",
  "model": "RK3568-10INCH",
  "appVersion": "1.0.0",
  "protocolVersion": "1",
  "features": ["MATTER", "ZIGBEE", "BLE_GATT"]
}

响应 data: PanelSession

{
  "code": 0,
  "message": "success",
  "data": {
    "panelId": "panel-001",
    "gatewayDeviceId": "gateway-001",
    "homeId": "10001",
    "memberId": "20001",
    "role": "GATEWAY",
    "accessToken": "<panel-access-token>",
    "refreshToken": "<panel-refresh-token>",
    "tokenType": "Bearer",
    "expiresIn": 3600,
    "refreshExpiresIn": 2592000,
    "stateEpoch": 12,
    "heartbeatIntervalSeconds": 30,
    "leaseSeconds": 90,
    "maxWaitSeconds": 20,
    "serverTime": 1792123200000
  }
}

上述有效期仅为建议示例，客户端按实际响应处理。role 为 GATEWAY 或 DISPLAY；同一家庭可有多个网关，但每台本地设备只有一个 executorPanelId。

stateEpoch 是平台为当前 bootId 分配的状态世代。同一 bootId 重试建立会话得到同一世代；新的 bootId 建立有效会话后，旧会话不能继续领取新命令或覆盖当前状态。设备执行中的旧记录按第六节处理，不自动交给新实例重做。

3. 刷新会话#

鉴权：请求体中的 refreshToken；不要求尚未过期的 Access Token。

{
  "refreshToken": "<panel-refresh-token>",
  "bootId": "boot-example-01"
}

成功 data 返回新的 accessToken、refreshToken、expiresIn、refreshExpiresIn 和 serverTime，保留原 panelId/homeId/stateEpoch。

建议刷新凭证轮换，并为同一旧凭证与同一 Idempotency-Key 保留 120 秒的加密响应重放窗口。刷新响应丢失时可用原请求取回同一结果；不同内容不得复用该键。窗口外或凭证撤销后返回明确错误，不放宽家庭范围。

4. 屏信息与心跳#

鉴权：Bearer；panelId 必须为自身。响应含 panelId、gatewayDeviceId、homeId、role、enabled、online、lastSeenAt、features。

参数：body: PanelHeartbeat

{
  "bootId": "boot-example-01",
  "appVersion": "1.0.0",
  "networkType": "ETHERNET",
  "uptimeSeconds": 120,
  "deviceCounts": {"total": 6, "online": 5},
  "protocols": {
    "matter": "READY",
    "zigbee": "NOT_CONNECTED",
    "ble": "READY"
  }
}

bootId 必填；其余运行字段建议上报。协议状态为 READY、NOT_CONNECTED、ERROR 或 UNSUPPORTED。缺少外设只影响相应协议，不使整个屏启动失败。

响应 data：

{
  "serverTime": 1792123230000,
  "leaseSeconds": 90,
  "configurationRevision": 4,
  "homeRevision": 28
}

租期从平台收到有效心跳时计算。领取命令或其他 API 调用不隐式替代心跳。屏离线后，平台拒绝新的远程本地设备控制；本地离线执行不以云端租期为前提。

1. 既有家庭、房间接口#

标记：扩展建议，仅补充屏身份访问规则。

屏只能读取会话绑定的家庭。既有 memberId 等参数即使保留，也必须与屏身份关联校验，不能作为越权选择器。改名、房间编辑等沿用现有接口并受相应管理权限约束。

2. 初始化快照#

参数：query: pageToken（首请求省略）。

响应 data: PanelSnapshotPage

{
  "snapshotId": "snapshot-001",
  "homeId": "10001",
  "homeName": "示例家庭",
  "homeRevision": 28,
  "cursor": "cursor-snapshot-001",
  "serverTime": 1792123200000,
  "expiresIn": 120,
  "rooms": [
    {"id": "30001", "name": "客厅", "sortOrder": 0}
  ],
  "devices": [
    {
      "id": "40001",
      "deviceId": "device-001",
      "deviceName": "客厅灯",
      "homeId": "10001",
      "roomId": "30001",
      "productId": "50001",
      "platform": "local",
      "deviceType": "light",
      "executionSource": "LOCAL_PANEL",
      "executorPanelId": "panel-001",
      "routeRevision": 3,
      "schemaRevision": 2,
      "online": true,
      "stateFresh": true,
      "properties": {"switch_1": true},
      "stateVersion": 80,
      "reportedAt": 1792123195000,
      "receivedAt": 1792123195100,
      "quality": "GOOD"
    }
  ],
  "scenes": [],
  "nextPageToken": null
}

平台需在同一逻辑版本上构造所有分页，并使 cursor 与该快照一致，避免分页期间丢失变化。建议单快照缓存 120 秒、每页最多 200 个对象。屏全部拉取成功后原子替换对应家庭的云缓存；失败时保留上一份可用数据。分页过期返回 SNAPSHOT_EXPIRED，重新开始。

删除平台缓存不自动清除屏的本地配网密钥。完整快照里没出现的平台设备可以退出云目录；本地物理解绑仍需明确动作。

3. 增量事件#

{
  "code": 0,
  "message": "success",
  "data": {
    "events": [
      {
        "eventId": "event-001",
        "type": "DEVICE_STATE",
        "homeId": "10001",
        "deviceId": "device-001",
        "createdAt": 1792123230000,
        "originPanelId": "panel-001",
        "reportId": "report-001",
        "stateVersion": 81,
        "payload": {
          "online": true,
          "properties": {"switch_1": false},
          "reportedAt": 1792123229500,
          "receivedAt": 1792123230000,
          "quality": "GOOD"
        }
      }
    ],
    "nextCursor": "cursor-event-001",
    "hasMore": false,
    "serverTime": 1792123230000
  }
}

事件类型建议包括 ROOM_UPSERT、ROOM_DELETED、DEVICE_UPSERT、DEVICE_DELETED、DEVICE_STATE、SCENE_UPSERT、SCENE_DELETED、COMMAND_UPDATED、CONFIGURATION_CHANGED、OTA_TASK_AVAILABLE、HOME_ACCESS_REVOKED。

UPSERT 携带更新后的完整公开对象；DELETED 携带对应 ID 和 revision；STATE 按第七节合并；COMMAND_UPDATED 携带 CommandResult；配置与 OTA 事件只提示重新读取相应接口。权限撤销事件可尽力通知，后续请求仍须独立拒绝，不能依赖客户端收到事件才生效。

平台按家庭顺序产生事件，屏落库和推进游标在同一事务中完成；重复 eventId 不重复应用。建议游标保留至少 24 小时，过期返回 HTTP 410 / CURSOR_EXPIRED，屏重新拉完整快照。没有事件时 events=[]，nextCursor 保持已确认位置。hasMore=true 时立即继续获取，不再等待。

1. 本地设备登记#

鉴权：本屏 gateway.execute 及被授予的登记权限。只登记实际归本屏执行的设备。

参数：body: LocalDeviceRegistration

{
  "localDeviceId": "local-device-001",
  "deviceName": "客厅灯",
  "protocol": "MATTER",
  "deviceType": "light",
  "roomId": "30001",
  "manufacturer": "Example",
  "model": "LIGHT-A",
  "schema": {
    "properties": [
      {
        "code": "switch_1",
        "name": "开关",
        "type": "bool",
        "access": ["read", "write", "notify"],
        "semantic": "ON_OFF",
        "channel": "1",
        "completionMode": "STATE"
      }
    ],
    "actions": []
  }
}

响应 data：

{
  "id": "40001",
  "deviceId": "device-001",
  "productId": "50001",
  "homeId": "10001",
  "parentDeviceId": "gateway-001",
  "executorPanelId": "panel-001",
  "routeRevision": 3,
  "schemaRevision": 2,
  "duplicate": false
}

平台以 panelId + localDeviceId 识别同一登记，不重复创建设备。重复登记相同资料返回同一映射；已登记后名称/房间等资料通过现有设备更新接口处理，schema 通过下方能力更新接口处理，不能借重新登记覆盖正在使用的物模型。没有 productId 时平台按已配置产品模板或确认后的 schema 建立对应产品；无法匹配则返回明确错误，不把空能力设备标成可控。

平台维护设备 id、deviceId、父网关和执行归属，屏不传本地网络密钥、Matter Fabric 密钥或用户口令。端点、属性码和本地协议地址的映射持久化在屏内。

请求体含 expectedSchemaRevision、routeRevision、properties、actions；properties/actions 使用下方定义。平台核对执行归属及期望版本，原子保存并返回新的 schemaRevision。同一幂等请求返回同一版本，版本不符返回 SCHEMA_CHANGED。

更新影响尚未开始的旧模型命令时，旧命令在执行前失败并给出 SCHEMA_CHANGED；已经开始的命令按原模型快照保留执行证据。旧模型状态不得覆盖语义已变化的新属性。

2. 控制模型#

路径沿用；以下 data 结构为补充建议，需要与平台实际模型核对。

{
  "deviceId": "device-001",
  "productId": "50001",
  "schemaRevision": 2,
  "properties": [
    {
      "code": "switch_1",
      "dpId": "1",
      "name": "开关",
      "type": "bool",
      "access": ["read", "write", "notify"],
      "semantic": "ON_OFF",
      "channel": "1",
      "completionMode": "STATE"
    },
    {
      "code": "brightness",
      "name": "亮度",
      "type": "int",
      "access": ["read", "write", "notify"],
      "semantic": "BRIGHTNESS",
      "channel": "1",
      "min": 0,
      "max": 100,
      "step": 1,
      "unit": "%",
      "completionMode": "STATE"
    }
  ],
  "actions": []
}

ActionSpec.parameters 按参数名列出 type、required 和适用的 min/max/step/enumValues；无参数动作使用空对象。请求中的参数必须符合该定义，不能让任意私有 JSON 绕过能力约束。

control-schema 的数值已经是业务值，scale=1；若物模型原始值存在倍率、偏移或反向含义，由平台云驱动或屏本地驱动转换，不能在两端重复转换。dpId 只是映射信息，不保证与 code 数值或格式一致。

请求必须携带所依据的 schemaRevision。版本变化后，旧参数不得照常发送，返回 SCHEMA_CHANGED 并重新读取。不支持的属性明确显示不可控，不猜测用途。

1. 提交控制#

鉴权：屏或会员身份，只能控制授权设备。路径沿用现有接口，补充以下约定。

参数：body: DeviceCommand

{
  "commandType": "set",
  "params": {"switch_1": false},
  "timeout": 30000,
  "schemaRevision": 2
}

action 请求示意：

{
  "commandType": "action",
  "params": {"actionCode": "stop", "arguments": {}},
  "timeout": 10000,
  "schemaRevision": 2
}

动作必须在 schema.actions 中声明，示例 stop 不意味着所有设备都支持。

平台先原子记录幂等请求和命令，再调度执行；不得等待物理动作结束才生成 commandId。接受请求后返回 HTTP 202，data: CommandResult。

{
  "code": 0,
  "message": "success",
  "data": {
    "commandId": "command-001",
    "deviceId": "device-001",
    "state": "QUEUED",
    "terminal": false,
    "executionSource": "LOCAL_PANEL",
    "executorPanelId": "panel-001",
    "routeRevision": 3,
    "createdAt": 1792123200000,
    "expiresAt": 1792123230000,
    "completionMode": "STATE",
    "result": null
  }
}

executionSource 为 CLOUD 或 LOCAL_PANEL。CLOUD 由平台既有云驱动执行；LOCAL_PANEL 只进入指定屏的队列，不能同时调用云驱动。

提交时若本地执行屏已离线或设备已明确不可控，返回 DEVICE_OFFLINE，不建立等待日后联网自动执行的队列。在线检查后发生断网的已有命令按各自有效期处理。

同一 set 请求包含多个属性时，默认不保证物理原子性。平台先校验全部属性，然后逐项记录结果；部分完成返回 PARTIAL_FAILURE 及每项结果，不显示整体成功。涉及严格原子动作时应由设备原生服务另行声明。

2. 查询控制结果#

返回 CommandResult，只允许本命令关联家庭的合法调用者读取。

QUEUED/DELIVERED 超时后为 EXPIRED；EXECUTING 或等待目标回报超时后为 UNKNOWN，不宣称设备没有动作。终态不再自动重放。迟到状态仍可更新设备状态，并追加 lateEvidence，但不把过期命令重新排队。

3. 领取命令#

参数：body: CommandPullRequest

{
  "bootId": "boot-example-01",
  "waitSeconds": 20,
  "maxItems": 10
}

bootId 必填；maxItems 建议 1–20。每次新的领取使用新 Idempotency-Key；同一次请求网络重试使用原键。平台保留领取结果，不因响应丢失再次创建任务。

响应 data：

{
  "commands": [
    {
      "commandId": "command-001",
      "deviceId": "device-001",
      "localDeviceId": "local-device-001",
      "commandType": "set",
      "params": {"switch_1": false},
      "schemaRevision": 2,
      "routeRevision": 3,
      "deliveryToken": "<delivery-token>",
      "deliveryExpiresAt": 1792123210000,
      "expiresAt": 1792123230000,
      "completionMode": "STATE"
    }
  ],
  "serverTime": 1792123200000
}

只投递当前归本屏负责且有效的命令。建议投递租期 10 秒，且不能晚于命令 expiresAt。屏未申请执行、投递租期已过时，可重新投递并更换 deliveryToken；旧 token 立即失效。已进入 EXECUTING 的命令不能重新投递给其他实例。

4. 申请执行#

{
  "bootId": "boot-example-01",
  "deliveryToken": "<delivery-token>",
  "routeRevision": 3
}

平台原子检查命令状态、有效期、最新执行归属、调用权限和 deliveryToken，成功转为 EXECUTING，返回：

{
  "executionToken": "<execution-token>",
  "state": "EXECUTING",
  "expiresAt": 1792123230000,
  "serverTime": 1792123201000
}

屏收到有效执行许可后才能向设备发送。申请响应丢失时，以同一 Idempotency-Key 重试取得同一许可，平台仍检查当前身份、归属及有效期；屏重新核对截止时间，不能因响应超时自行执行。

在发送物理指令前，屏必须以 commandId 唯一约束原子占用本地执行记录，并先持久化 ATTEMPTING 标记；并发回调不能各执行一次。若进程在发送附近中断，重启后不再重发该动作，查询设备状态并报告 UNKNOWN 或可核实证据。分布式协议不能保证跨设备断电的物理“恰好一次”；本约定优先避免重复动作，并保留无法确定的结果。

5. 报告执行结果#

参数：body: CommandReport

{
  "executionToken": "<execution-token>",
  "reportId": "command-report-001",
  "reportSequence": 2,
  "state": "CONFIRMED",
  "observedAt": 1792123202500,
  "items": [
    {
      "code": "switch_1",
      "state": "CONFIRMED",
      "reportedValue": false,
      "evidence": "DEVICE_REPORT"
    }
  ]
}

ACK_ONLY 动作可报告 ACCEPTED 作为终态，但界面仍显示“已接受”，不能显示“已确认机械停止”等未取得的结果。

平台核对目标、物模型允许的数值精度和执行归属，不接受用旧缓存值直接报告 CONFIRMED。可接受证据为实际设备回报，或指令之后完成且能证明新鲜度的读回；无证据时保留 ACCEPTED/UNKNOWN。命令回执不直接覆盖设备最新状态，设备状态另走第七节并按顺序合并。

响应 data：

{
  "commandId": "command-001",
  "state": "CONFIRMED",
  "terminal": true,
  "duplicate": false
}

reportId 重复且内容相同返回同一结果；不同内容返回冲突。旧 reportSequence 不回退状态。中途会话刷新不影响有效 executionToken；新 bootId、撤权或路由变化后只能追加经平台核验的旧执行证据，不能凭旧 executionToken 获取新执行权。

6. 屏上本地点击与回声处理#

负责该设备的屏可直接执行本地操作，随后上报状态及活动；这种操作不再同时向平台提交一条待下发控制命令。

本地操作以 localOperationId 标记来源。平台因该上报产生的事件只是同步，不重新生成控制命令。其他屏控制该设备时通过平台提交，仍由唯一执行屏领取。

同一屏对同一设备的本地操作与远程操作进入同一个串行执行入口；不能因来源不同并行修改同一属性。相互冲突的请求分别保留结果，不使用先前另一条命令的回报冒充当前命令完成。

此接口面向网关状态与本地活动，复用平台已有设备、数据和活动存储。屏使用此入口后，不再把同一条状态重复提交到其他状态接口。

参数：body: PanelReportBatch

{
  "bootId": "boot-example-01",
  "stateEpoch": 12,
  "reports": [
    {
      "reportId": "report-001",
      "deviceId": "device-001",
      "sequence": 18,
      "schemaRevision": 2,
      "routeRevision": 3,
      "kind": "STATE",
      "mode": "DELTA",
      "online": true,
      "observedAt": 1792123229500,
      "properties": {"switch_1": false},
      "quality": "GOOD",
      "commandId": "command-001"
    }
  ]
}

平台只接受当前执行归属的上报。状态顺序按 stateEpoch、sequence 判断；不能以 HTTP 到达顺序决定新旧。bootId 改变后由平台分配新 stateEpoch，屏首次上报应为 FULL；旧世代补传只可留作历史，不覆盖新状态。

DELTA 需要按属性保存最近一次序号，避免序号较大的单个属性先到时，误丢另一个属性的较早有效变化。更旧的 FULL 不覆盖新属性，FULL 中未提供的属性只有在其序号比该属性更新时才标为未知；不能默认写成 0/false。

响应逐项给结果：

{
  "code": 0,
  "message": "success",
  "data": {
    "results": [
      {
        "reportId": "report-001",
        "accepted": true,
        "duplicate": false,
        "appliedToCurrentState": true,
        "stateVersion": 81
      }
    ],
    "serverTime": 1792123230000
  }
}

accepted 表示该记录已被持久接收；appliedToCurrentState 表示是否改变当前状态。旧记录可以 accepted=true、appliedToCurrentState=false。部分失败逐条返回 errorCode；屏只重试可重试项，不能因整批 code=0 删除失败记录。

云端来源设备由平台云驱动按同样的对外状态模型提供 stateVersion 和新鲜度。客户端不能把读接口的响应时间伪装成真实设备上报时间。

1. 多屏执行归属#

DeviceRoute 由平台维护：

{
  "deviceId": "device-001",
  "executionSource": "LOCAL_PANEL",
  "executorPanelId": "panel-001",
  "routeRevision": 3
}

• DISPLAY 屏读取同一家庭的状态并向平台提交控制，不取得其他屏的本地协议密钥。
• 一台设备只对应一个执行屏，不按谁先领取就临时决定归属。
• 屏离线不会自动把本地设备切换给另一屏；协议网络绑定不一定可转移。
• 归属变更必须完成明确交接并增加 routeRevision。旧执行屏仍可能离线控制时不得直接启用新执行方；在无法确认旧绑定已解除时停止交接。
• 旧 routeRevision 的新 start 请求拒绝；已经发到物理设备的动作无法由云端撤回，应保留结果不确定或迟到证据，不能虚报取消成功。

2. 平台场景和规则#

沿用 scenes、scenes/v2、rules 的现有入口。家庭范围、动作执行与结果增加以下约定：

• 每个场景或自动化配置明确 executionOwner 为 CLOUD 或指定 PANEL。
• 同一定时/自动化只由一个执行方调度；屏展示云场景不自动再建一份本地定时任务。
• CLOUD 场景涉及本地设备时，动作转为第六节设备命令，经过所属执行屏。
• PANEL 离线场景仅对本屏可执行的本地动作运行，并在恢复后补传运行记录；不回放已过期的云端动作。
• 场景执行接口建议返回 sceneRunId、state、terminal 及各动作 commandId；设备动作关联失败或未知时，场景不能整体标记成功。

响应 data：

{
  "sceneRunId": "scene-run-001",
  "sceneId": "60001",
  "state": "RUNNING",
  "terminal": false,
  "actions": [
    {"index": 0, "commandId": "command-001", "state": "EXECUTING"}
  ]
}

state 为 QUEUED/RUNNING/ACCEPTED/CONFIRMED/PARTIAL_FAILURE/FAILED/UNKNOWN。全部动作均确认时为 CONFIRMED；全部动作均已完成各自约定、但至少一项只能确认协议接受时，汇总为 ACCEPTED、terminal=true，不能把它改写成所有物理效果已确认。存在失败或未知时，按各项结果返回部分失败、失败或未知。

PANEL 执行的离线场景结果通过 diagnostics 的结构化事件记录可用于追踪；若需要平台场景历史与管理，则建议统一增加运行报告：

请求含 sceneRunId（屏生成 UUID）、sceneId、configurationRevision、startedAt、finishedAt、state、actions（localOperationId 与各项结果）；幂等按 sceneRunId，平台核对该规则当时的 PANEL 执行归属，只记录历史，不再执行动作。

3. AI 控制#

沿用 text、targetType、targetId 等现有请求字段。平台需要明确回复是只解释、等待确认，还是已经提交执行。

建议 data 包含 status（ANSWER/NEED_CONFIRMATION/SUBMITTED/REJECTED）、message，以及执行时的 commandIds 或 sceneRunId。NEED_CONFIRMATION 额外返回 confirmationId、候选目标及 expiresAt。

二次请求在既有目标字段之外携带 confirmationId，平台绑定原始请求、家庭、目标和有效期；同一确认只产生一次执行。屏收到 SUBMITTED 后只跟踪结果，不把同一动作再次交给本地解析器执行。

4. 配网#

本地 Matter/Zigbee/BLE 配网继续由屏对应协议栈完成，成功后走设备登记。平台已有涂鸦 Wi-Fi/Matter/Zigbee 配网 Token 仅按其配套 SDK 和账号体系使用，不能当作通用本地协议凭证。

1. 屏配置#

query: knownRevision（可选）。

响应 data：

{
  "revision": 4,
  "unchanged": false,
  "settings": {
    "screenOffSeconds": 120,
    "proximityWakeEnabled": true
  },
  "content": [],
  "automationAssignments": []
}

本版本列出的 settings 为示例拟定键；平台与屏需要维护明确的支持键、类型和范围，不能把任意 JSON 当系统命令执行。content 每项包含 id、type、title、url、revision；automationAssignments 包含规则 ID、revision、executionOwner 及平台已定义的结构化条件/动作。

只有完整校验成功后才原子应用新配置，失败继续使用上一有效配置并上报原因。knownRevision 相同返回 unchanged=true，可省略主体。云端配置缺失不阻塞本地页面启动。

2. 诊断事件#

参数：body 包含 events，建议每批最多 100 条：

{
  "events": [
    {
      "eventId": "diag-001",
      "bootId": "boot-example-01",
      "time": 1792123200000,
      "category": "NETWORK",
      "level": "WARN",
      "code": "PLATFORM_UNREACHABLE",
      "message": "平台连接暂时不可用",
      "commandId": null
    }
  ]
}

响应按 eventId 返回 accepted/duplicate/errorCode。不得包含 Token、Secret、Wi-Fi 密码、协议密钥或完整用户音频。诊断上传失败不影响本地控制。

3. 屏查询升级任务#

query: appVersionCode、systemVersion、supportedPackageTypes。平台只返回分配给该屏且适用的任务，无任务时 data=null。

{
  "taskId": "70001",
  "attemptId": "ota-attempt-001",
  "firmwareId": "80001",
  "deviceId": "gateway-001",
  "packageType": "APK",
  "version": "1.0.1",
  "versionCode": 101,
  "targetModel": "RK3568-10INCH",
  "downloadUrl": "https://mum.tonzou.cn/example-package.apk",
  "size": 12345678,
  "integrity": {
    "algorithm": "SHA-256",
    "digest": "<package-digest>"
  },
  "signatureRequirement": "EXISTING_APP_SIGNATURE",
  "expiresAt": 1792209600000
}

这是升级包元数据示例，不是可下载任务。重复查询返回同一任务的同一 attemptId，不因 GET 查询产生新的安装动作；平台明确安排新一轮重试时才分配新的 attemptId。packageType 至少区分 APK 与 ANDROID_AB；不兼容的系统更新形式返回 UNSUPPORTED。平台已有 fileMd5 可保留作兼容字段，实际包完整性与签名检查不能被任务查询成功替代。这里的包摘要只用于固件传输完整性，不扩展为普通业务文件的校验要求。

下载地址不得要求把屏 Bearer Token 转发给任意第三方域名。使用受控平台下载或明确的临时下载授权；系统包和 APK 保留各自的本地验证与安装流程。

4. 升级回报#

原 deviceId、success、version 用于最终结果；建议增加 attemptId、reportId、reportSequence、stage、progress、errorCode、message。

stage 为 DOWNLOADING/VERIFYING/INSTALLING/REBOOTING/SUCCEEDED/FAILED/CANCELLED。progress 为当前阶段的 0–100 进度。中间阶段 success 省略，最终成功/失败才填写；CANCELLED 不使用 success 冒充设备安装失败。以 attemptId、reportId 和递增 reportSequence 去重与排序，同阶段进度不回退，不允许旧轮次或迟到下载进度覆盖新的安装结果。

示例：

{
  "deviceId": "gateway-001",
  "attemptId": "ota-attempt-001",
  "reportId": "ota-report-001",
  "reportSequence": 5,
  "stage": "SUCCEEDED",
  "progress": 100,
  "success": true,
  "version": "1.0.1"
}

升级任务和本地控制解耦。安装/重启条件需由屏核对；OTA 接口接通不表示可以跳过型号、包类型、签名或用户已确定的设备操作规则。

新增接口建议使用下表。HTTP 状态与业务 code 为评审建议，平台既有错误码可映射保留，但同一含义应稳定一致。

建议退避加入随机抖动并有上限；恢复联网后不集中重放过期控制。业务过期处理独立于 HTTP 重试。

字段在对应接口中规定。对外数据不包含底层协议密钥；原始厂商私有属性须有明确类型和权限后才暴露。

建议按以下依赖顺序实现完整连接：

1. 终端身份与家庭范围，确认当前屏可读取的目录。
2. 设备/物模型映射和初始化快照、增量状态。
3. 云端设备控制，以及本地设备登记与上报。
4. 本地网关命令领取、执行许可、回执和超时恢复。
5. 多屏、场景、AI 及配置、诊断和 OTA 的相应接线。

协议实施完成后统一从屏和手机/网页验证：同一家庭数据一致、命令只走一个执行来源、回执能证明实际结果、断线与重启不重复执行、旧状态不覆盖新状态；无外设只影响对应协议功能。

本稿请平台方重点确认：

• 是否已有终端身份和网关协议，可用现有契约替换哪些“新增建议”路径。
• 是否接受屏受限身份访问既有业务接口，以及明确的家庭范围校验。
• control-schema、通用控制参数和命令结果的最终字段。
• 执行归属、投递与结果状态、事件游标及状态序号的语义。
• 场景/AI/OTA 等已有实现如何对应本文模型及默认时间参数。

确认后的路径和字段维护在同一份协议中，再按定稿实施。以上接口不是对现网行为的测试结论。

现有路径与业务用途参考： 概览↗、 授权对接↗、 会员与家庭↗、 设备管理↗、 产品与物模型↗、 涂鸦云集成↗、 规则与场景↗、 AI 智能↗、 数据模型↗。