From 2e5e124efb42ed91f4592de3a65209508aa95f36 Mon Sep 17 00:00:00 2001
From: liangqiang <78248678@qq.com>
Date: Wed, 22 Apr 2026 13:47:37 +0800
Subject: [PATCH] readme

---
 Readme.md | 1673 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 1673 insertions(+)
 create mode 100644 Readme.md

diff --git a/Readme.md b/Readme.md
new file mode 100644
index 0000000..cba2621
--- /dev/null
+++ b/Readme.md
@@ -0,0 +1,1673 @@
+# 智能锁新实时系统方案
+
+本文档面向一个“全新项目”的设计，但明确采用 `starcloud` 作为共享业务能力云平台，`starlock` 作为其租户化应用层入口，不重复建设通用业务能力。
+
+## 1. 目标与约束
+
+### 1.1 已知现状
+
+- `starcloud`：共享云平台，向下游业务应用提供可复用 API 与业务能力。
+- `starlock`：PHP 业务后台，负责 APP 用户注册、登录、权限、家庭/门锁归属和其它业务规则。
+- `app-starlock`：Flutter APP。
+- `starchart-sls1 - 0304`：现有中央通信层，承担注册、发现、转发、对讲相关职责。
+- 目标方向：
+  - 发现服务迁移到 Apache BifroMQ
+  - 音视频不再默认全部走中心服务器转发，但保留中心转发兜底
+  - 按网络质量动态选择 WebRTC P2P 或 `ZLMediaKit` 转发
+  - 在 P2P 不稳定时，可切回中心服务器转发或 ZLMediaKit 转发
+
+### 1.2 新方案目标
+
+新项目应满足以下目标：
+
+1. `starcloud` 作为共享业务能力主平台，承载可复用的业务 API。
+2. `starlock` 作为面向 APP 的租户化业务入口和编排层。
+3. 实时控制面与媒体面彻底分离。
+4. 设备发现、在线状态、会话信令交给 Apache BifroMQ。
+5. 音视频链路不固定单一路径，而是按网络质量动态选路：中好网络优先 P2P，弱网优先 `ZLMediaKit` 转发，`TURN` 作为 RTC 路径补位。
+6. AI 通过旁路式能力接入，不破坏主对讲链路。
+
+### 1.3 设计原则
+
+- `starcloud` 负责可复用业务能力与共享策略，
+    `starlock` 负责租户化编排和对外 API 聚合。
+- 新实时系统只做连接、会话编排、信令分发和媒体接入。
+- App 与设备获取到的是短期会话权限，不直接暴露业务后台内部权限模型。
+- AI 接入必须解耦于主通话状态机。
+- 所有大流量音视频传输采用网络自适应策略：中好网络优先标准 RTC P2P，弱网由 `ZLMediaKit` 作为优先实现方案。
+
+## 2. 角色划分
+
+### 2.1 `starcloud` 共享能力职责
+
+`starcloud` 继续承担：
+
+- 可复用用户/权限策略能力
+- 设备与家庭关系的共享模型能力
+- 通用套餐、计费、审计、风控能力
+- 标准化业务 API（供 `starlock` 等下游应用调用）
+- 可复用的业务规则引擎与跨租户能力演进
+
+### 2.2 `starlock` 租户应用层职责
+
+`starlock` 继续承担：
+
+- 面向 `app-starlock` 的统一业务入口
+- 结合租户/渠道配置编排 `starcloud` 共享能力
+- 聚合会话、通知、AI 与设备业务流程
+- 面向 APP 的主业务 API 与体验层策略
+- 仅保留强租户定制逻辑，不重复实现通用业务能力
+
+### 2.3 新实时系统承担职责
+
+新项目承担：
+
+- 设备在线状态管理
+- 设备能力声明与发现
+- 实时会话创建与编排
+- WebRTC signaling
+- WebRTC 媒体接入
+- TURN/STUN 基础设施
+- 中心媒体转发兜底
+- `ZLMediaKit` 转发接入
+- AI 会话桥接
+- 调试日志、会话追踪、弱状态缓存
+
+## 3. 总体架构图
+
+说明：如果你当前 Markdown 查看器不支持 Mermaid，请直接看 `3.0.1` 与 `3.0.2` 的纯文本结构图。
+
+### 3.0.1 纯文本结构图（精简版）
+
+```text
+app-starlock
+  -> starlock (租户应用层)
+    -> starcloud (共享业务能力 API)
+    -> session-orchestrator (独立服务)
+      -> Apache BifroMQ (发现/在线/信令)
+      -> 媒体选路: P2P / TURN / ZLMediaKit / relay
+  <-> Lock/Gateway (对讲设备)
+  -> ai-gateway -> xiaozhi_server (AI旁路)
+```
+
+### 3.0.2 纯文本结构图（详细版）
+
+```text
+[Client]
+  app-starlock
+  Lock/Gateway
+
+[Business]
+  starlock (租户应用层，面向APP)
+    - 聚合业务 API
+    - 编排实时会话
+    - 调用共享能力
+  starcloud (共享业务云平台)
+    - 用户/权限/套餐/审计等通用能力
+
+[Session & Control]
+  session-orchestrator (phase1+, 独立服务形态)
+  device-bootstrap
+  Apache BifroMQ
+  MQTT event worker
+  realtime-store
+
+[Media]
+  优先策略(自适应):
+    1) 中好网络 -> WebRTC P2P
+    2) RTC补位   -> TURN
+    3) 弱网优先  -> ZLMediaKit
+    4) 最终兜底  -> media-relay
+
+[AI]
+  ai-gateway -> xiaozhi_server
+```
+
+```mermaid
+graph TB
+    subgraph Client
+        APP[app-starlock\nFlutter App]
+        LOCK[Lock / Gateway\n门锁或网关]
+    end
+
+    subgraph Business
+      STARCLOUD[starcloud\n共享业务云平台]
+        STARLOCK[starlock\n租户应用层]
+        PUSHSVC[Push / Callback\n推送与业务通知]
+    end
+
+    subgraph Realtime
+        ORCH[session-orchestrator\n会话编排服务]
+        BIFROMQ[Apache BifroMQ\n发现/在线/信令]
+        TURN[coturn\nSTUN/TURN]
+      RELAY[media-relay\n中心音视频转发]
+      ZLM[ZLMediaKit\n标准流媒体转发]
+        TRACE[realtime-store\n会话状态/日志缓存]
+    end
+
+    subgraph AI
+        AIGW[ai-gateway\nAI桥接层]
+        XIAOZHI[xiaozhi_server\nAI实时服务]
+    end
+
+    APP -->|HTTPS| STARLOCK
+    STARLOCK -->|共享业务 API| STARCLOUD
+    LOCK -->|HTTPS / bootstrap| STARLOCK
+
+    STARLOCK -->|内部 API| ORCH
+    STARLOCK --> PUSHSVC
+
+    APP <-->|MQTT over WSS| BIFROMQ
+    LOCK <-->|MQTT / MQTT over TLS| BIFROMQ
+
+    APP <-->|WebRTC P2P / TURN| LOCK
+    APP -. fallback .-> TURN
+    LOCK -. fallback .-> TURN
+    APP -. relay fallback .-> RELAY
+    LOCK -. relay fallback .-> RELAY
+    APP -. optional relay .-> ZLM
+    LOCK -. optional relay .-> ZLM
+
+    ORCH --> BIFROMQ
+    ORCH --> RELAY
+    ORCH --> ZLM
+    ORCH --> TRACE
+    STARLOCK --> TRACE
+
+    LOCK -. AI side channel .-> AIGW
+    APP -. AI assisted mode .-> AIGW
+    AIGW --> XIAOZHI
+    AIGW --> STARLOCK
+```
+
+### 3.1 架构解读
+
+- `starcloud` 是跨项目可复用业务能力平台，`starlock` 是租户化编排入口。
+- `session-orchestrator` 是会话状态机中心，但不保存完整业务模型。
+- `Apache BifroMQ` 只承接设备发现、在线状态和 signaling，不承接大媒体流。
+- `coturn` 是 WebRTC 的第一层兜底中继。
+- `media-relay` 是中心服务器音视频转发能力层，作为 P2P/TURN 失败后的工程兜底。
+- `ZLMediaKit` 可以直接承担这层能力，实现 WebRTC 失败后的中心转发，因此通常不需要再长期维护一套独立自研 relay。
+- `ai-gateway` 把 AI 从实时媒体层中解耦出来。
+
+### 3.2 基于现有项目的迁移版架构图
+
+下面这张图不是“完全脱离现状的理想图”，而是基于你当前项目角色关系做的迁移版架构图。
+
+对应关系如下：
+
+- 现有 `scd` 的“注册/发现/心跳”职责，迁移到 `Apache BifroMQ + device bootstrap + session-orchestrator`
+- 现有 `scrd` 的“媒体中继/NAT 穿透”职责，迁移到 `WebRTC P2P + coturn + 中心媒体转发兜底`
+- 现有 `rpcd` 不再承担实时转发中心角色，只保留必要的业务桥接，长期建议并入 `starlock` 内部服务调用
+- 现有 `event_listener` 继续保留在事件上报链路，但不再参与主媒体链路
+- 新增 `media-relay` 能力层，优先采用 `ZLMediaKit` 落地
+- 新增 `ai-gateway + xiaozhi_server` 作为 AI 能力面
+
+当前项目约束补充：`WiFi锁` 默认就是“网关锁形态”，因此可直接承接 `网关设备` 角色。
+
+```mermaid
+graph LR
+  subgraph AppSide[APP侧]
+    APP[app-starlock\nFlutter APP]
+  end
+
+  subgraph BizSide[业务后台]
+    STARCLOUD[starcloud\n共享业务云平台]
+    STARLOCK[starlock\n租户应用层]
+    CALLBACK[推送/回调/业务通知]
+  end
+
+  subgraph RealtimeCloud[新实时云]
+    BOOT[device-bootstrap\n设备接入与临时凭证]
+    BIFROMQ[Apache BifroMQ\n发现/在线/信令]
+    ORCH[session-orchestrator\n会话编排]
+    TURN[coturn\nTURN/STUN]
+    RELAY[media-relay\n中心音视频转发]
+    ZLM[ZLMediaKit\n流媒体转发]
+    EVT[event-listener\n事件监听/媒体落库]
+  end
+
+  subgraph AIPlane[AI能力]
+    AIGW[ai-gateway]
+    XIAOZHI[xiaozhi_server]
+  end
+
+  subgraph DeviceSide[智能锁设备侧]
+    GW[WiFi网关锁\nWebRTC/AI优先承载]
+    BLE[蓝牙锁]
+  end
+
+  APP -->|HTTPS业务API| STARLOCK
+  STARLOCK -->|共享业务 API| STARCLOUD
+  STARLOCK -->|内部调用| BOOT
+  STARLOCK -->|内部调用| ORCH
+  STARLOCK --> CALLBACK
+
+  GW -->|设备认证/换取MQTT凭证| BOOT
+
+  APP <-->|MQTT over WSS| BIFROMQ
+  GW <-->|MQTT/TLS| BIFROMQ
+
+  ORCH --> BIFROMQ
+  BOOT --> BIFROMQ
+
+  APP <-->|WebRTC P2P / ZLM 自适应| GW
+  APP -. P2P失败走TURN .-> TURN
+  GW -. P2P失败走TURN .-> TURN
+  APP -. TURN仍失败走中心转发 .-> RELAY
+  GW -. TURN仍失败走中心转发 .-> RELAY
+  APP -. 可选切到ZLM .-> ZLM
+  GW -. 可选切到ZLM .-> ZLM
+
+  GW -->|事件上报| EVT
+  GW -. 蓝牙透传 .-> BLE
+  EVT -->|HTTP回调| STARLOCK
+
+  GW -. AI音频旁路 .-> AIGW
+  APP -. AI辅助模式 .-> AIGW
+  AIGW --> XIAOZHI
+  AIGW --> STARLOCK
+```
+
+### 3.3 这张迁移图怎么理解
+
+- 对你当前项目，`WiFi锁` 就是 `网关设备` 形态，可直接承接 WebRTC、双讲、AI 音频旁路能力。
+- 图中已合并为单节点 `WiFi网关锁`，避免角色重复表达。
+- `Apache BifroMQ` 取代了原先 `scd` 的发现中心角色，但不再承接媒体搬运。
+- `TURN` 是 RTC 路径的补位能力，但不是所有场景的首选。
+- `media-relay` 继续保留中心服务器音视频转发能力，便于兼容旧设备和极端网络环境。
+- `ZLMediaKit` 可以作为更标准的中心转发实现，在弱网场景下可优先于 P2P 成为首选媒体路径。
+- `event_listener` 继续服务事件回调、图片/视频处理、业务通知，不进入主实时链路。
+- `starlock` 仍然是外部唯一可信业务入口，APP 不直接向 `session-orchestrator` 暴露业务接口。
+
+### 3.4 第一阶段落地架构图（`session-orchestrator` 独立）
+
+按当前决策，第一阶段就独立部署 `session-orchestrator`，不再采用内嵌 `starlock` 的过渡形态。
+
+这样做的目的：
+
+- 从一开始就把业务编排与实时状态机解耦
+- 统一会话控制协议，替代历史 UDP 协议分散控制
+- 提前建立可扩容、可观测、可回放的会话控制平面
+- 后续只做横向扩容，不再经历二次拆分改造
+
+对应第一阶段架构图如下：
+
+```mermaid
+graph LR
+  subgraph AppSide[APP侧]
+    APP[app-starlock\nFlutter APP]
+  end
+
+  subgraph BizSide[业务后台]
+    STARCLOUD[starcloud\n共享业务云平台]
+    STARLOCK[starlock\n租户应用层]
+    CALLBACK[推送/业务通知]
+  end
+
+  subgraph RealtimeInfra[实时基础设施]
+    ORCH[session-orchestrator\n独立会话控制服务]
+    BOOT[device-bootstrap\n设备接入与临时凭证]
+    BIFROMQ[Apache BifroMQ\n发现/在线/信令/事件总线]
+    TURN[coturn\nTURN/STUN]
+    RELAY[media-relay\n中心音视频转发]
+    ZLM[ZLMediaKit\n流媒体转发]
+    EVT[MQTT event worker\n原event-listener演进]
+  end
+
+  subgraph AIPlane[AI能力]
+    AIGW[ai-gateway]
+    XIAOZHI[xiaozhi_server]
+  end
+
+  subgraph DeviceSide[智能锁设备侧]
+    GW[WiFi网关锁\nWebRTC/AI优先承载]
+    BLE[蓝牙锁]
+  end
+
+  APP -->|HTTPS业务API| STARLOCK
+  STARLOCK -->|共享业务 API| STARCLOUD
+  STARLOCK -->|内部调用| ORCH
+  STARLOCK --> CALLBACK
+
+  GW -->|认证/换取MQTT凭证| BOOT
+  STARLOCK -->|内部调用| BOOT
+
+  APP <-->|MQTT over WSS| BIFROMQ
+  GW <-->|MQTT/TLS| BIFROMQ
+
+  ORCH --> BIFROMQ
+  ORCH --> RELAY
+  ORCH --> ZLM
+
+  APP <-->|WebRTC P2P / ZLM 自适应| GW
+  APP -. P2P失败走TURN .-> TURN
+  GW -. P2P失败走TURN .-> TURN
+  APP -. TURN失败走中心转发 .-> RELAY
+  GW -. TURN失败走中心转发 .-> RELAY
+  APP -. 可选切ZLM .-> ZLM
+  GW -. 可选切ZLM .-> ZLM
+
+  GW -->|事件上报| BIFROMQ
+  BIFROMQ --> EVT
+  EVT -->|HTTP回调/业务处理| STARLOCK
+
+  GW -. 蓝牙透传 .-> BLE
+
+  GW -. AI音频旁路 .-> AIGW
+  APP -. AI辅助模式 .-> AIGW
+  AIGW --> XIAOZHI
+  AIGW --> STARLOCK
+```
+
+### 3.5 第一阶段图的关键变化
+
+与前面的“目标态迁移图”相比，第一阶段版本有三个关键变化：
+
+1. 第一阶段即独立部署 `session-orchestrator`
+2. `starlock` 只做业务授权与编排，不承载会话状态机
+3. `event_listener` 不再作为协议接收器，而是变成 `MQTT event worker`
+
+### 3.6 第一阶段图的实际含义
+
+- `starlock` 负责业务授权与会话编排入口，实时状态流转由 `session-orchestrator` 统一管理。
+- MQTT 上只跑发现、在线、signaling 和事件通知，不跑大媒体流。
+- 主媒体链路采用自适应策略：中好网络优先 `WebRTC P2P`，弱网优先 `ZLMediaKit`，`TURN` 负责 RTC 路径补位，中心转发能力持续保留。
+- `Apache BifroMQ -> MQTT event worker -> starlock` 负责事件消费、回调、媒体后处理等异步任务。
+- 后续如果会话量上来，优先扩容 `session-orchestrator` 实例与会话存储层，不再做架构拆分。
+
+### 3.6.1 `session-orchestrator` 如何控制视频会话（详细）
+
+你们之前“通过 UDP 协议字段通知 APP 和锁端开始/结束”的模式，本质是点对点控制，状态一致性和故障收敛依赖端侧实现，云端很难统一治理。
+
+新方案里，`session-orchestrator` 用“会话状态机 + 控制指令 + ACK/超时机制”统一控制视频会话。
+
+核心机制如下：
+
+1. 建会话：`starlock` 完成权限校验后调用 `session-orchestrator` 创建会话，返回 `sessionId`、topic、短期 token、媒体策略。
+2. 发起呼叫：`session-orchestrator` 下发 `invite` 控制事件，设备侧回 `ringing/accept/reject`。
+3. 信令协商：APP/设备仅在约定 topic 交换 `offer/answer/candidate`，`session-orchestrator` 只做状态编排与超时控制，不搬运大媒体流。
+4. 建链判定：`session-orchestrator` 收集两端链路质量上报（RTT、丢包、抖动、可用带宽、candidate 类型），进入 `connecting -> connected`。
+5. 动态选路：当指标降级，发 `switch-route` 控制指令，从 `p2p` 切 `turn` 或 `zlmediakit`；若仍失败，再切 `relay`。
+6. 结束会话：任一端发送 `hangup` 或超时触发 `terminate`，`session-orchestrator` 统一写入终态并清理 token/资源。
+
+推荐状态机：
+
+- `pending` -> `ringing` -> `accepted` -> `connecting` -> `connected`
+- 通话中可进入：`degraded` -> `switching_route` -> `recovered`
+- 结束态：`ended` / `rejected` / `timeout` / `failed`
+
+和旧 UDP 控制的关系：
+
+- 旧模型：端到端 UDP 协议字段直接表达“开始/结束”，中心侧难追踪完整会话。
+- 新模型：开始/结束只是状态机中的两个事件，所有控制动作都有 `sessionId`、事件序号、ACK、超时重试与最终态落库。
+- 结果：可审计、可回放、可补偿，且便于联调和问题追踪。
+
+### 3.7 现状与第一阶段对照图
+
+这张图适合给团队评审时使用，左边是你们当前主要链路，右边是第一阶段目标链路。
+
+```mermaid
+graph LR
+  subgraph NOW[当前架构]
+    APP1[app-starlock]
+    STAR1[starlock]
+    SCD[scd\n注册/发现/心跳]
+    SCRD[scrd\n媒体转发/NAT]
+    RPCD[rpcd\n业务桥接]
+    EVT1[event_listener]
+    DEV1[锁/网关设备]
+
+    APP1 --> STAR1
+    STAR1 --> RPCD
+    DEV1 --> SCD
+    APP1 --> SCD
+    APP1 --> SCRD
+    DEV1 --> SCRD
+    DEV1 --> EVT1
+    EVT1 --> STAR1
+  end
+
+  subgraph PHASE1[第一阶段架构]
+    APP2[app-starlock]
+    STAR2[starlock]
+    ORCH2[session-orchestrator]
+    BOOT2[device-bootstrap]
+    BIFROMQ2[Apache BifroMQ]
+    TURN2[coturn]
+    RELAY2[media-relay]
+    ZLM2[ZLMediaKit]
+    EVTW[MQTT event worker]
+    AIGW2[ai-gateway]
+    XIAO2[xiaozhi_server]
+    DEV2[锁/网关设备]
+
+    APP2 --> STAR2
+    STAR2 --> ORCH2
+    STAR2 --> BOOT2
+    ORCH2 --> BIFROMQ2
+    APP2 --> BIFROMQ2
+    DEV2 --> BOOT2
+    DEV2 --> BIFROMQ2
+    APP2 --> TURN2
+    DEV2 --> TURN2
+    APP2 --> RELAY2
+    DEV2 --> RELAY2
+    APP2 --> ZLM2
+    DEV2 --> ZLM2
+    BIFROMQ2 --> EVTW
+    EVTW --> STAR2
+    ORCH2 --> RELAY2
+    ORCH2 --> ZLM2
+    DEV2 -. AI旁路 .-> AIGW2
+    AIGW2 --> XIAO2
+    AIGW2 --> STAR2
+  end
+```
+
+### 3.8 `xiaozhi_server` 的 MQTT 网关策略（已定）
+
+策略已定：主方案不使用 `xiaozhi-mqtt` 网关。
+
+- 智能锁主链路只使用 `Apache BifroMQ`
+- AI 面只使用 `ai-gateway <-> xiaozhi_server` 的 HTTP/WebSocket 会话
+- 不引入第二套 MQTT broker，不保留双 broker 共存方案
+
+### 3.9 改进后的推荐方案
+
+推荐做法是：
+
+- 智能锁主实时链路只保留一套 MQTT 基础设施，即 `Apache BifroMQ`
+- `xiaozhi_server` 只保留在 AI 能力面，负责 ASR、TTS、Agent、知识库、工具调用
+- 明确禁用 `xiaozhi-mqtt` 网关，不在任何环境接入智能锁主链路
+
+对应理解是：
+
+- 锁、APP、网关设备的发现、在线、signaling、事件总线，都走 `Apache BifroMQ`
+- WebRTC signaling 仍然走 `Apache BifroMQ`
+- 音视频主链路走 `WebRTC + coturn`，P2P/TURN 失败后切到中心媒体转发或 `ZLMediaKit`
+- `xiaozhi_server` 只通过 `ai-gateway` 接入，不直接成为锁侧 MQTT broker
+
+这样改完以后，`xiaozhi_server` 不会和 `Apache BifroMQ` 在主方案中发生正面冲突。
+
+### 3.10 执行规范（禁用 `xiaozhi-mqtt`）
+
+为避免双 broker 风险，执行层按以下规范落地：
+
+1. 仅部署并对外开放 `Apache BifroMQ` 的 MQTT 接入。
+2. 不部署 `xiaozhi-mqtt-gateway`，或在配置中明确关闭其对外监听。
+3. 智能锁、APP、网关设备统一接入 `Apache BifroMQ`。
+4. AI 功能统一走 `ai-gateway <-> xiaozhi_server` 的 HTTP/WebSocket，不走 MQTT。
+5. 运维检查项中增加“第二 MQTT broker 禁入”巡检规则。
+
+### 3.11 最终建议
+
+对你这个智能锁项目，最稳的版本是：
+
+- `Apache BifroMQ` 是唯一主 MQTT 平台
+- `starcloud` 是共享业务能力平台，`starlock` 是租户应用层入口
+- `xiaozhi_server` 是 AI 引擎，不是主消息总线
+- 不启用 `xiaozhi-mqtt`，避免双 broker 架构复杂度
+
+### 3.12 按你项目落地的真实接线图，Broker 改为 Apache BifroMQ
+
+```mermaid
+flowchart LR
+  subgraph ClientSide[用户侧]
+    APP[app-starlock]
+  end
+
+  subgraph BizSide[业务与控制面]
+    STARCLOUD[starcloud]
+    STARLOCK[starlock]
+    BOOT[device-bootstrap]
+    ORCH[session state machine]
+    EVTW[MQTT event worker]
+  end
+
+  subgraph BrokerSide[消息面]
+    BIFROMQ[Apache BifroMQ]
+  end
+
+  subgraph MediaSide[实时媒体]
+    TURN[coturn]
+    RELAY[media-relay]
+    ZLM[ZLMediaKit]
+  end
+
+  subgraph DeviceSide[设备侧]
+    GW[WiFi网关锁]
+    BLE[蓝牙锁]
+  end
+
+  subgraph AIPlane[AI能力面]
+    AIGW[ai-gateway]
+    XIAOZHI[xiaozhi_server]
+  end
+
+  APP -->|HTTPS 业务 API| STARLOCK
+  STARLOCK -->|共享业务 API| STARCLOUD
+  STARLOCK -->|内部调用| BOOT
+  STARLOCK -->|内部调用| ORCH
+  STARLOCK -->|事件消费/回调| EVTW
+
+  GW -->|认证/换 MQTT 凭证| BOOT
+
+  APP <-->|MQTT over WSS| BIFROMQ
+  GW <-->|MQTT over TLS| BIFROMQ
+
+  ORCH -->|signaling/session control| BIFROMQ
+  EVTW <-->|订阅事件| BIFROMQ
+
+  APP <-->|WebRTC P2P / ZLM 自适应| GW
+  APP -. TURN fallback .-> TURN
+  GW -. TURN fallback .-> TURN
+  APP -. relay fallback .-> RELAY
+  GW -. relay fallback .-> RELAY
+  APP -. optional ZLM relay .-> ZLM
+  GW -. optional ZLM relay .-> ZLM
+  GW -. 蓝牙透传 .-> BLE
+
+  GW -. AI 音频旁路 .-> AIGW
+  APP -. AI 辅助模式 .-> AIGW
+  AIGW --> XIAOZHI
+  AIGW --> STARLOCK
+```
+
+这张图对应的边界是：
+
+- `Apache BifroMQ` 只承接在线、发现、signaling、事件通知，不承接大媒体流。
+- 主音视频链路按网络质量自适应选择：中好网络优先 `WebRTC + coturn`，弱网优先 `ZLMediaKit`。
+- `media-relay` 承接 P2P/TURN 不可用时的中心音视频转发。
+- `ZLMediaKit` 提供标准化流媒体转发方案，可作为中心转发实现之一。
+- `starcloud` 提供可复用业务能力，`starlock` 负责租户化编排与 APP 入口。
+- `xiaozhi_server` 只在 `ai-gateway` 后面提供 ASR、TTS、Agent、知识库、工具调用。
+- 用户、权限、套餐、审计等可复用能力优先沉淀在 `starcloud`，`starlock` 负责租户侧业务编排与体验层策略。
+
+### 3.13 精简业务图（管理/评审）
+
+这张图只保留关键角色和主链路，适合评审会快速对齐。
+
+```mermaid
+flowchart LR
+  APP[app-starlock]
+  STARLOCK[starlock\n租户应用层]
+  STARCLOUD[starcloud\n共享业务能力]
+  SESSION[session-orchestrator]
+  MQ[Apache BifroMQ]
+  MEDIA[ZLMediaKit / TURN / relay]
+  DEV[Lock/Gateway]
+  AI[ai-gateway + xiaozhi]
+
+  APP -->|业务 API| STARLOCK
+  STARLOCK -->|共享业务 API| STARCLOUD
+  STARLOCK -->|会话编排| SESSION
+  SESSION --> MQ
+  APP <-->|信令| MQ
+  DEV <-->|信令| MQ
+  APP <-->|音视频自适应| DEV
+  APP -. 弱网优先 .-> MEDIA
+  DEV -. 弱网优先 .-> MEDIA
+  APP -. AI模式 .-> AI
+  DEV -. AI旁路 .-> AI
+```
+
+### 3.14 详细业务图（研发/实现）
+
+这张图包含业务层、会话层、媒体层、事件回调与 AI 旁路，适合研发实现和联调。
+
+```mermaid
+flowchart TB
+  subgraph Client[客户端与设备]
+    APP[app-starlock]
+    GW[Gateway/Lock]
+  end
+
+  subgraph Biz[业务层]
+    STARLOCK[starlock\n租户应用层]
+    STARCLOUD[starcloud\n共享业务API]
+    PUSH[push/callback]
+  end
+
+  subgraph SessionPlane[会话与控制面]
+    SESSION[session-orchestrator]
+    BOOT[device-bootstrap]
+    MQ[Apache BifroMQ]
+    EVT[MQTT event worker]
+    TRACE[realtime-store]
+  end
+
+  subgraph MediaPlane[媒体面]
+    P2P[WebRTC P2P]
+    TURN[coturn]
+    ZLM[ZLMediaKit]
+    RELAY[media-relay]
+  end
+
+  subgraph AIPlane[AI面]
+    AIGW[ai-gateway]
+    XZ[xiaozhi_server]
+  end
+
+  APP -->|HTTPS 业务请求| STARLOCK
+  STARLOCK -->|共享能力调用| STARCLOUD
+  STARLOCK -->|创建会话| SESSION
+  STARLOCK --> PUSH
+
+  GW -->|设备认证| BOOT
+  STARLOCK -->|内部调用| BOOT
+
+  SESSION -->|会话信令编排| MQ
+  APP <-->|MQTT/WSS| MQ
+  GW <-->|MQTT/TLS| MQ
+
+  APP -->|网络探测上报| SESSION
+  GW -->|链路质量上报| SESSION
+  SESSION -->|中好网络| P2P
+  SESSION -->|RTC补位| TURN
+  SESSION -->|弱网优先| ZLM
+  SESSION -->|最终兜底| RELAY
+
+  APP <-->|媒体| P2P
+  GW <-->|媒体| P2P
+  APP -. fallback .-> TURN
+  GW -. fallback .-> TURN
+  APP -. weak network .-> ZLM
+  GW -. weak network .-> ZLM
+  APP -. emergency fallback .-> RELAY
+  GW -. emergency fallback .-> RELAY
+
+  GW -->|事件上报| MQ
+  MQ --> EVT
+  EVT -->|业务回调| STARLOCK
+  SESSION --> TRACE
+
+  GW -. AI音频旁路 .-> AIGW
+  APP -. AI辅助模式 .-> AIGW
+  AIGW --> XZ
+  AIGW --> STARLOCK
+```
+
+## 4. 控制面与媒体面分层
+
+### 4.1 控制面
+
+控制面使用：
+
+- HTTPS
+- MQTT
+
+控制面承载：
+
+- 登录与鉴权
+- 设备绑定与发现
+- 会话创建
+- 呼叫控制
+- 开锁命令
+- 在线状态
+- 事件通知
+
+### 4.2 媒体面
+
+媒体面使用：
+
+- WebRTC
+
+媒体面承载：
+
+- 视频上行
+- 双向音频
+- DataChannel 辅助消息
+- 录制或云存的旁路扩展
+- P2P/TURN 失败后的中心媒体转发
+- 基于 `ZLMediaKit` 的流转发
+
+### 4.3 AI 面
+
+AI 面使用：
+
+- `ai-gateway` 与 `xiaozhi_server` 的 WebSocket/HTTP 会话
+- 不使用 `xiaozhi` 原生 MQTT+UDP 网关能力，避免引入第二套 MQTT 基础设施
+
+AI 面承载：
+
+- 语音转文本
+- TTS
+- 意图识别
+- 工具调用
+- 智能应答
+- AI 辅助摘要/关键词提取
+
+## 5. 核心时序图
+
+### 5.1 设备上线与发现
+
+```mermaid
+sequenceDiagram
+    participant Lock as Lock/Gateway
+    participant Starlock as starlock
+    participant BifroMQ as Apache BifroMQ
+    participant App as APP
+
+    Lock->>Starlock: 设备认证/获取 MQTT 临时凭证
+    Starlock-->>Lock: mqtt username/password 或 JWT
+    Lock->>BifroMQ: 建立 MQTT 连接
+    Lock->>BifroMQ: 发布 retained presence=online
+    Lock->>BifroMQ: 发布 retained capabilities
+
+    App->>Starlock: 获取门锁列表与权限
+    App->>Starlock: 申请查看设备在线态
+    App->>BifroMQ: 订阅锁相关 presence/status topic
+    BifroMQ-->>App: 推送设备在线与能力信息
+```
+
+### 5.2 App 发起对讲，媒体路径自适应
+
+```mermaid
+sequenceDiagram
+    participant App as APP
+    participant Starlock as starlock
+    participant Orch as session-orchestrator
+    participant BifroMQ as Apache BifroMQ
+    participant Lock as Lock/Gateway
+    participant TURN as coturn
+    participant Relay as media-relay
+    participant ZLM as ZLMediaKit
+
+    App->>Starlock: 发起视频/对讲请求
+    Starlock->>Starlock: 校验用户对该锁的权限
+    Starlock->>Orch: 创建 realtime session
+    Orch-->>Starlock: sessionId + signaling topics + rtc config + token
+    Starlock-->>App: 返回 session 启动信息
+
+    Starlock->>BifroMQ: 通知目标锁有呼叫请求
+    BifroMQ-->>Lock: 推送 incoming call
+
+    App->>BifroMQ: 发布 offer
+    BifroMQ-->>Lock: 转发 offer
+    Lock->>BifroMQ: 发布 answer
+    BifroMQ-->>App: 转发 answer
+
+    App->>BifroMQ: 发布 ICE candidate
+    Lock->>BifroMQ: 发布 ICE candidate
+
+    Orch->>Orch: 根据 RTT/丢包/NAT/终端能力选择媒体路径
+    alt 网络良好，优先 P2P
+      App-->>Lock: WebRTC P2P 建链
+    else RTC 可用但 P2P 不理想
+        App-->>TURN: 使用 TURN 中继
+        Lock-->>TURN: 使用 TURN 中继
+    else 弱网或高丢包，优先中心转发
+      Orch->>ZLM: 创建 ZLMediaKit 转发会话
+      App->>ZLM: 拉流/推流
+      Lock->>ZLM: 推流/拉流
+    else P2P/TURN/ZLM 都受限
+      Orch->>Relay: 创建中心媒体转发会话
+      App->>Relay: 接入中心音视频转发
+      Lock->>Relay: 接入中心音视频转发
+    end
+
+    App->>BifroMQ: 会话控制消息 accept/hangup
+    Lock->>BifroMQ: 会话状态更新
+    Orch->>Orch: 聚合状态并记录 trace
+```
+
+  ### 5.2.1 弱网判定与自动切换规则
+
+  为了让“弱网优先 `ZLMediaKit`”可执行，建议 `session-orchestrator` 在建链前和通话中都持续评估以下指标：
+
+  - RTT：连续 3 个采样窗口平均 RTT `> 250ms`
+  - 丢包率：上行或下行连续 3 个窗口丢包率 `> 8%`
+  - 抖动：连续 3 个窗口抖动 `> 30ms`
+  - 实际可用上行带宽：低于当前音视频档位最低要求的 `1.3x` 安全阈值
+  - NAT/连通性：ICE 在限定时间内无法形成稳定 candidate pair，或只剩高成本 relay 路径
+
+  建议默认策略如下：
+
+  1. 建链前网络探测显示 RTT、丢包、抖动都健康时，优先 `WebRTC P2P`。
+  2. 建链前就已经出现高丢包、复杂 NAT、运营商弱网或企业网限制时，直接优先 `ZLMediaKit`。
+  3. P2P 已建成但连续 `5-10s` 质量低于阈值时，先尝试降码率、降分辨率、关闭非关键视频层。
+  4. 降档后仍连续 `10-15s` 不达标时，从 P2P/TURN 自动切到 `ZLMediaKit`。
+  5. 只有在 `ZLMediaKit` 也不可用，或该设备型号暂不支持对应接入方式时，才退回通用 `media-relay` 兜底。
+
+  建议把这些阈值做成可配置项，而不是写死在代码里；不同设备型号、码率档位、音频优先级和运营商环境下，实际阈值会有差异。
+
+### 5.3 AI 旁路模式
+
+```mermaid
+sequenceDiagram
+    participant Lock as Lock/Gateway
+    participant App as APP
+    participant Starlock as starlock
+    participant Orch as session-orchestrator
+    participant AIGW as ai-gateway
+    participant Xiao as xiaozhi_server
+
+    App->>Starlock: 请求开启 AI 模式
+    Starlock->>Starlock: 校验 AI 权限/套餐/设备能力
+    Starlock->>Orch: 为当前会话启用 AI sidecar
+    Orch->>AIGW: 创建 ai session
+    AIGW->>Xiao: 建立 AI 对话会话
+
+    Lock->>AIGW: 推送音频副本或独立音频流
+    AIGW->>Xiao: 转发音频
+    Xiao-->>AIGW: ASR / 意图 / TTS / 工具调用结果
+
+    alt AI 辅助模式
+        AIGW-->>Starlock: 摘要/关键词/告警事件
+    else AI 应答模式
+        AIGW-->>Lock: TTS 音频或文本应答
+        AIGW-->>App: AI 状态与结果
+    end
+```
+
+## 6. 服务清单与职责设计
+
+### 6.1 `starlock`
+
+角色：租户应用层业务入口。
+
+关键职责：
+
+- 对外提供 APP 业务 API
+- 编排 `starcloud` 共享业务能力
+- 管理租户/渠道差异化配置
+- 生成实时会话请求
+- 向 APP 返回会话入口信息
+
+不负责：
+
+- 长连接连接保持
+- WebRTC signaling 分发
+- 大媒体转发
+- 重复实现本应沉淀到 `starcloud` 的通用业务能力
+
+### 6.1.1 `starcloud`
+
+角色：共享业务能力云平台。
+
+关键职责：
+
+- 对下游应用（包括 `starlock`）输出可复用业务 API
+- 沉淀用户、权限、套餐、审计等通用能力
+- 承载跨项目可复用的业务规则与模型
+- 减少同类项目重复开发，提升统一治理能力
+
+### 6.2 `session-orchestrator`
+
+角色：实时会话编排中心。
+
+关键职责：
+
+- 创建 `sessionId`
+- 生成 signaling topic
+- 生成短期 session token
+- 聚合会话状态：`pending`、`ringing`、`accepted`、`connected`、`ended`
+- 管理媒体兜底策略：`p2p`、`turn`、`relay`、`zlmediakit`
+- 根据网络质量阈值执行媒体路径切换
+- 管理 AI sidecar 生命周期
+- 写会话 trace、诊断日志
+
+不负责：
+
+- 用户权限判断
+- 业务订单/套餐判断
+- 持久化完整业务模型
+
+#### 为什么需要它
+
+`session-orchestrator` 这个名字容易让人误以为它是一个很重的“中央调度服务”，其实不是。
+
+它本质上只是一个“实时会话状态机”，作用是把下面几类逻辑从 `starlock` 的普通业务接口里剥出来：
+
+- 创建一次实时会话
+- 给这次会话分配 `sessionId`
+- 给 APP 和设备生成本次会话可用的 signaling topic
+- 生成短期 session token / TURN 凭证
+- 在需要时切换中心媒体转发或 `ZLMediaKit` 流转发
+- 维护这次会话的状态变化：响铃、接听、连接成功、挂断、异常结束
+
+换句话说，它不决定“这个人有没有权限打这个锁”；这类权限决策通常由 `starlock` 发起并结合 `starcloud` 共享能力完成。它只负责“既然已经允许打了，那这通会话怎么被安全地建起来并结束”。
+
+#### 为什么必须独立服务
+
+按当前决策，`session-orchestrator` 必须从第一阶段独立部署，理由是：
+
+- 视频会话控制与业务 API 解耦，避免 `starlock` 发布节奏被实时链路牵制
+- 统一替代历史 UDP 分散控制，形成中心化状态机治理
+- 路由切换策略（`p2p/turn/zlmediakit/relay`）可独立演进
+- 会话可观测性（trace、失败原因、切路记录）可统一沉淀
+
+落地约束：
+
+1. `starlock` 只负责权限校验、业务编排、对外 API。
+2. `session-orchestrator` 负责会话状态机、控制命令、超时收敛、媒体路径决策。
+3. APP/设备只认会话级 topic 与短期 token，不直接依赖业务后台内部状态。
+
+#### 会话控制协议建议（替代旧 UDP 开始/结束协议）
+
+建议把“开始/结束”从 UDP 专用协议，升级为统一会话控制事件：
+
+- `sessions/{sessionId}/control`：`invite`、`ringing`、`accept`、`reject`、`hangup`、`switch-route`、`terminate`
+- `sessions/{sessionId}/status`：`pending`、`connecting`、`connected`、`degraded`、`switching_route`、`ended`、`failed`
+
+每条控制事件都带：
+
+- `sessionId`
+- `eventId`（单调递增）
+- `from`（app/device/orchestrator）
+- `ts`
+- `ackTimeoutMs`
+
+处理规则：
+
+1. 未 ACK 的控制事件按策略重发。
+2. 超过最大重试进入 `timeout` 或 `failed`。
+3. 任一终态都由 `session-orchestrator` 写最终状态并触发资源清理。
+
+#### 归属结论与简化实现（提炼版）
+
+归属结论：
+
+- `session-orchestrator` 属于云端实时基础设施层，不属于 APP 端，也不属于设备端。
+- 它是被 `starlock` 调用的独立服务。
+- `starlock` 负责业务授权与编排，`session-orchestrator` 负责视频会话控制与状态机收敛。
+
+技术建议：
+
+- 首选 Go 实现独立服务（更适合高并发会话状态控制）。
+
+
+简单实现方法（MVP）：
+
+1. 先独立部署 `session-orchestrator`，并配套 `Redis`（热状态/重试队列）与 `MySQL`（会话记录/审计）。
+2. 先开三个内部接口：创建会话、结束会话、开启 AI sidecar，`starlock` 只通过这三个接口编排实时流程。
+3. APP/设备统一使用会话级 topic：`sessions/{sessionId}/control` 与 `sessions/{sessionId}/status`，不再用旧 UDP 协议字段直接控制开始/结束。
+4. 按固定状态机落地：`pending -> ringing -> accepted -> connecting -> connected -> ended/failed`，并实现 ACK 超时重试。
+5. 媒体选路先做最小闭环：`p2p -> turn -> zlmediakit -> relay`，由 `session-orchestrator` 统一下发 `switch-route`。
+6. 灰度迁移旧方案：先镜像上报、再双栈并行、最后下线旧 UDP 开始/结束控制。
+
+### 6.3 `Apache BifroMQ`
+
+角色：发现、在线、信令总线。
+
+关键职责：
+
+- 设备 presence
+- retained capabilities
+- signaling 消息传递
+- 控制类 topic 分发
+- ACL 与连接鉴权
+
+不负责：
+
+- 大媒体流
+- 复杂业务校验
+
+### 6.4 `coturn`
+
+角色：RTC 网络兜底。
+
+关键职责：
+
+- STUN
+- TURN relay
+- 临时凭证校验
+
+### 6.4.1 `media-relay`
+
+角色：中心服务器音视频转发兜底。
+
+关键职责：
+
+- 在 P2P/TURN 都不可用时承接音视频转发
+- 兼容旧设备或弱网场景
+- 为录制、审计、媒体后处理保留中心接入点
+- 作为一个能力层存在，不要求必须单独做成自研服务
+
+### 6.4.2 `ZLMediaKit`
+
+角色：中心媒体转发能力的优先实现方案。
+
+关键职责：
+
+- 提供比自定义 relay 更标准的媒体转发实现
+- 支持 WebRTC、推流、拉流、转协议和中心媒体接入
+- 可直接承接 `media-relay` 这层能力，逐步替代自研转发逻辑
+- 在弱网、高抖动、高丢包场景下，可作为比 P2P 更稳的优先媒体方案
+
+#### 结合 WebRTC 怎么理解
+
+- 中好网络时，首选仍然是 App 与设备直接做 WebRTC P2P。
+- 弱网、高丢包、复杂 NAT 或需要录制审计时，可以直接优先 `ZLMediaKit`。
+- 如果仍希望保持 RTC 直连能力，可让 `coturn` 作为 RTC 路径补位。
+- 当 `ZLMediaKit` 也受限或需要特殊兼容时，再切到更通用的中心转发能力。
+- 这时中心转发不一定再单独做一套自研 `media-relay` 服务，可以直接由 `ZLMediaKit` 承担。
+
+#### 弱网下哪个更适合作为首选
+
+- 如果目标是“弱网下更稳”，通常优先 `ZLMediaKit` 转发，而不是 WebRTC P2P。
+- 原因是 P2P 更依赖两端实时网络质量、NAT 情况和上行稳定性；弱网下抖动、重传、带宽突降会更明显暴露出来。
+- `ZLMediaKit` 走中心接入点，更容易做统一的拥塞控制、转协议、录制和链路治理，所以在弱网场景更适合作为首选方案。
+- 只有在网络质量较好、希望最低时延和最低中心带宽成本时，才应把 WebRTC P2P 放到第一位。
+
+
+- 如果你的意思是“完全不要中心转发能力”，不建议。
+- 原因是 WebRTC P2P 和 TURN 仍然会遇到设备兼容性、弱网、企业网限制、录制审计、协议桥接等场景，这些场景仍需要中心接入点。
+- 更合理的做法是：保留中心转发这层能力，但把实现尽量收敛到 `ZLMediaKit`，不要长期维护两套并行转发系统。
+
+### 6.5 `ai-gateway`
+
+角色：AI 桥接层。
+
+关键职责：
+
+- 为设备或会话创建 AI session
+- 对接 `xiaozhi_server`
+- 在 AI 模式和业务模式之间做协议适配
+- 把 AI 结果回送 `starlock`、APP 或设备
+
+不负责：
+
+- 用户体系
+- 主对讲状态机
+
+### 6.6 `event-listener` 是否还能保留
+
+这个问题要拆成两类：
+
+#### 类别一：实时通知分发
+
+这部分很多是可以用 MQTT 做的。
+
+例如：
+
+- 设备上线/下线通知
+- 门锁状态变化通知
+- 振铃通知
+- 会话状态变化通知
+- AI 摘要完成通知
+
+这类消息天然适合通过 MQTT 分发，因为它们是轻量消息、低延迟、面向订阅者的实时通知。
+
+#### 类别二：业务事件消费与回调
+
+这部分不建议只靠 MQTT 替代。
+
+例如：
+
+- 设备上报开锁记录
+- 报警事件
+- 图片/视频文件处理
+- 回调 `starlock` 或其它 HTTP 接口
+- 做重试、幂等、失败补偿、落库
+
+这些更像“异步业务任务”，而不只是“通知”。如果只用 MQTT 裸消费，后面你很容易遇到这些问题：
+
+- 消费失败后的补偿不清楚
+- 回调重试策略分散
+- 消息被订阅了，但业务并没有真正处理成功
+- 文件处理、转码、上传对象存储这类任务不适合留在纯通知链路里
+
+所以更合理的做法是：
+
+- 用 MQTT 承担“事件通知总线”
+- 保留一个事件消费器来做“业务处理和回调”
+
+这个消费器仍然可以继续叫 `event-listener`，但它的角色要重新定义。
+
+#### 推荐的新定义
+
+建议把 `event-listener` 改成：
+
+- 订阅 MQTT 事件主题
+- 负责把事件写入业务处理流水
+- 负责做 HTTP 回调、对象存储、媒体后处理、重试和幂等
+
+也就是说，它不再是老架构里“星图协议事件接收器”，而是“MQTT 事件消费器 + 业务回调 worker”。
+
+这个改法是最平滑的，因为：
+
+- 设备侧事件入口可以改成 MQTT
+- 你们现有很多事件处理逻辑还能保留
+- `starlock` 不需要直接订阅所有低层设备消息
+
+## 6.7 对你当前项目的更实际建议
+
+结合你现在的系统，我建议这样落：
+
+### 第一阶段
+
+- 独立部署 `session-orchestrator` 服务
+- `starlock` 专注业务授权与编排，实时会话状态机由 `session-orchestrator` 承担
+- 新增通用业务能力优先落在 `starcloud`，再由 `starlock` 编排调用
+- 用 Apache BifroMQ 做 presence + signaling
+- 保留现有中心服务器音视频转发作为兜底
+- 直接把 `ZLMediaKit` 作为中心转发优先实现，逐步下线自研 relay
+- 保留一个 `event-listener` worker，改为订阅 MQTT 事件并做业务回调
+
+### 第二阶段
+
+- 根据会话量扩容 `session-orchestrator`（多实例 + 会话分片/一致性哈希）
+- 如果事件量很大，再把 `event-listener` 拆成多类 worker：
+  - 业务回调 worker
+  - 媒体处理 worker
+  - AI 结果消费 worker
+
+### 一句话判断
+
+- `session-orchestrator` 从第一阶段就独立部署，“实时会话状态机”不内嵌到 `starlock`
+- `event-listener` 的通知入口可以迁到 MQTT，但“业务处理与回调”仍然建议保留专门消费者，不要只靠 MQTT 本身完成
+
+## 7. 设备形态建议
+
+### 7.1 推荐的设备侧分层
+
+对你当前项目，`WiFi锁` 默认按网关锁能力建设，可直接承接高能力终端职责。
+
+如果后续扩展到多设备形态（低功耗锁体 + 高能力网关），再按下面方式分层：
+
+- 锁体 MCU：负责电机、门磁、电池、基础控制协议
+- 网关/猫眼/门口机/Linux SoC：负责摄像头、麦克风、编码、WebRTC、AI 侧接入
+
+### 7.2 不建议的做法
+
+当前项目因为 `WiFi锁` 已是网关锁形态，本节主要用于后续低功耗设备线扩展时参考。
+
+不建议把完整 WebRTC 栈强行压到能力非常有限的锁体 MCU 上，除非你已经确认：
+
+- 编码能力足够
+- 网络和 TLS 栈足够稳定
+- 长连接状态机可维护
+- 双讲回声、抖动和弱网体验可接受
+
+如果只是探索方向，可以参考 `libpeer-main` 作为设备侧 C WebRTC 库候选，但量产方案仍应优先基于更成熟的端侧平台或网关代理。
+
+## 8. 接口草案
+
+以下接口草案按“APP -> starlock -> realtime services”关系设计。
+
+### 8.1 APP 调 `starlock`
+
+#### 创建会话
+
+`POST /api/realtime/sessions`
+
+请求示例：
+
+```json
+{
+  "deviceId": "lock_123456",
+  "sessionType": "talk",
+  "mediaPolicy": {
+    "strategy": "adaptive",
+    "preferP2PWhenGoodNetwork": true,
+    "preferZlmWhenWeakNetwork": true,
+    "autoSwitch": true
+  },
+  "media": {
+    "audio": true,
+    "video": true,
+    "dataChannel": true
+  },
+  "aiMode": "disabled"
+}
+```
+
+响应示例：
+
+```json
+{
+  "sessionId": "sess_01HT...",
+  "role": "caller",
+  "mqtt": {
+    "brokerUrl": "wss://mq.example.com:8084/mqtt",
+    "clientId": "app_user_1001_sess_01HT",
+    "username": "app_user_1001",
+    "password": "temp-password",
+    "topics": {
+      "signalPublish": "sessions/sess_01HT/signal/app",
+      "signalSubscribe": "sessions/sess_01HT/signal/device",
+      "control": "sessions/sess_01HT/control"
+    }
+  },
+  "rtc": {
+    "iceServers": [
+      {
+        "urls": ["stun:turn.example.com:3478"]
+      },
+      {
+        "urls": ["turn:turn.example.com:3478?transport=udp"],
+        "username": "turn-user",
+        "credential": "turn-pass"
+      }
+    ]
+  },
+  "mediaRoute": {
+    "selected": "p2p",
+    "candidates": ["p2p", "turn", "zlmediakit", "relay"],
+    "switchPolicy": {
+      "rttMs": 250,
+      "packetLossRate": 0.08,
+      "jitterMs": 30,
+      "degradeDurationSec": 10
+    }
+  },
+  "sessionToken": "jwt-or-paseto"
+}
+```
+
+#### 结束会话
+
+`POST /api/realtime/sessions/{sessionId}/terminate`
+
+#### 查询会话详情
+
+`GET /api/realtime/sessions/{sessionId}`
+
+#### 开启 AI 模式
+
+`POST /api/realtime/sessions/{sessionId}/ai`
+
+请求示例：
+
+```json
+{
+  "mode": "assistant",
+  "voiceProfile": "default",
+  "intentScope": ["intercom", "unlock", "qa"]
+}
+```
+
+### 8.2 `starlock` 调 `session-orchestrator`
+
+#### 创建内部会话
+
+`POST /internal/realtime/sessions`
+
+请求示例：
+
+```json
+{
+  "sessionId": "sess_01HT...",
+  "tenantId": 1,
+  "userId": 1001,
+  "deviceId": "lock_123456",
+  "sessionType": "talk",
+  "mediaPolicy": {
+    "audio": true,
+    "video": true,
+    "p2pPreferred": true,
+    "turnFallback": true,
+    "zlmPreferredWhenWeakNetwork": true,
+    "autoSwitch": true,
+    "thresholds": {
+      "rttMs": 250,
+      "packetLossRate": 0.08,
+      "jitterMs": 30,
+      "degradeDurationSec": 10
+    }
+  },
+  "authContext": {
+    "familyId": 2002,
+    "permissionSnapshot": ["device.talk", "device.view"]
+  }
+}
+```
+
+响应示例：
+
+```json
+{
+  "sessionId": "sess_01HT...",
+  "mqttTopics": {
+    "deviceSignal": "sessions/sess_01HT/signal/device",
+    "appSignal": "sessions/sess_01HT/signal/app",
+    "control": "sessions/sess_01HT/control"
+  },
+  "sessionToken": "signed-token",
+  "mediaRoute": {
+    "selected": "p2p",
+    "fallbackOrder": ["turn", "zlmediakit", "relay"]
+  },
+  "turnCredential": {
+    "username": "turn-u",
+    "credential": "turn-c",
+    "ttl": 300
+  }
+}
+```
+
+#### 上报业务结束态
+
+`POST /internal/realtime/sessions/{sessionId}/finalize`
+
+#### 开启 AI sidecar
+
+`POST /internal/realtime/sessions/{sessionId}/ai-sidecar`
+
+### 8.3 设备 bootstrap 接口
+
+设备不应长期写死 MQTT 密钥，建议通过 `starlock` 或设备接入子服务换取短期凭证。
+
+`POST /internal/device/bootstrap`
+
+请求示例：
+
+```json
+{
+  "deviceId": "lock_123456",
+  "firmwareVersion": "2.3.1",
+  "nonce": "abc123",
+  "signature": "device-signature"
+}
+```
+
+### 8.4 `starlock` 调 `starcloud` 共享业务 API
+
+#### 权限快照与策略校验
+
+`POST /internal/starcloud/policy/evaluate`
+
+请求示例：
+
+```json
+{
+  "tenantId": 1,
+  "userId": 1001,
+  "deviceId": "lock_123456",
+  "action": "device.talk",
+  "context": {
+    "familyId": 2002,
+    "channel": "app-starlock"
+  }
+}
+```
+
+响应示例：
+
+```json
+{
+  "allow": true,
+  "policyVersion": "pcv_20260422_01",
+  "permissionSnapshot": ["device.talk", "device.view"],
+  "reason": "matched-tenant-policy"
+}
+```
+
+响应示例：
+
+```json
+{
+  "mqtt": {
+    "clientId": "lock_123456",
+    "username": "lock_123456",
+    "password": "temporary-secret",
+    "expireAt": 1713700000
+  },
+  "topics": {
+    "presence": "locks/lock_123456/presence",
+    "capabilities": "locks/lock_123456/capabilities",
+    "commands": "locks/lock_123456/commands",
+    "signal": "locks/lock_123456/signals"
+  }
+}
+```
+
+## 9. Apache BifroMQ Topic 设计
+
+### 9.1 设备级 topic
+
+- `locks/{deviceId}/presence`
+- `locks/{deviceId}/capabilities`
+- `locks/{deviceId}/status`
+- `locks/{deviceId}/commands`
+- `locks/{deviceId}/events`
+- `locks/{deviceId}/signals`
+
+#### 用途说明
+
+- `presence`：在线/离线，建议 retained + LWT
+- `capabilities`：设备支持的编码、AI、摄像头、麦克风等能力，建议 retained
+- `status`：电量、网络质量、门状态、当前是否忙
+- `commands`：来自后台或 APP 的设备控制命令
+- `events`：设备产生的业务事件
+- `signals`：设备级呼叫通知或预唤起 signaling
+
+### 9.2 会话级 topic
+
+- `sessions/{sessionId}/signal/app`
+- `sessions/{sessionId}/signal/device`
+- `sessions/{sessionId}/control`
+- `sessions/{sessionId}/status`
+- `sessions/{sessionId}/ai-events`
+
+### 9.3 消息类型建议
+
+`signal/*` 统一使用以下类型：
+
+- `offer`
+- `answer`
+- `candidate`
+- `restart-ice`
+
+`control` 使用：
+
+- `ringing`
+- `accept`
+- `reject`
+- `hangup`
+- `mute`
+- `unmute`
+- `pause-video`
+- `resume-video`
+
+`status` 使用：
+
+- `pending`
+- `connecting`
+- `connected`
+- `reconnecting`
+- `ended`
+- `error`
+
+### 9.4 ACL 建议
+
+APP 在某个会话中只允许：
+
+- 发布：`sessions/{sessionId}/signal/app`
+- 订阅：`sessions/{sessionId}/signal/device`
+- 发布/订阅：`sessions/{sessionId}/control`、`sessions/{sessionId}/status`
+
+设备在某个会话中只允许：
+
+- 发布：`sessions/{sessionId}/signal/device`
+- 订阅：`sessions/{sessionId}/signal/app`
+- 发布/订阅：`sessions/{sessionId}/control`、`sessions/{sessionId}/status`
+
+这样可以避免跨会话串话和 topic 污染。
+
+## 10. Session Token 设计
+
+### 10.1 设计目标
+
+session token 只表达“某个主体在某个短会话里的实时权限”，不重复承载完整业务模型。
+
+### 10.2 推荐字段
+
+推荐使用 JWT 或 PASETO，字段如下：
+
+```json
+{
+  "iss": "starlock",
+  "aud": "realtime",
+  "sub": "user:1001",
+  "sid": "sess_01HT...",
+  "did": "lock_123456",
+  "role": "caller",
+  "scp": ["signal", "rtc", "ai:disabled"],
+  "tenant": 1,
+  "family": 2002,
+  "exp": 1713700300,
+  "nbf": 1713700000,
+  "jti": "uuid"
+}
+```
+
+### 10.3 说明
+
+- `sid`：绑定单个会话
+- `did`：绑定单个设备
+- `role`：`caller`、`callee`、`observer`、`ai-sidecar`
+- `scp`：实时权限范围，如 `signal`、`rtc`、`ai`、`record`
+- 过期时间建议 5 到 10 分钟
+
+### 10.4 验证位置
+
+- `session-orchestrator` 验证 token
+- MQTT ACL 网关可基于 token 生成动态权限
+- TURN 凭证由 `session-orchestrator` 基于 session token 派生
+- `ai-gateway` 验证是否允许 AI 接入
+
+## 11. 数据模型建议
+
+### 11.1 `starlock` 保存
+
+- `users`
+- `families`
+- `locks`
+- `family_lock_members`
+- `device_permissions`
+- `realtime_session_records`
+- `ai_usage_records`
+
+### 11.2 新实时项目保存
+
+- `device_presence_snapshot`
+- `device_capability_snapshot`
+- `realtime_session_state`
+- `realtime_session_trace`
+- `signaling_audit_log`
+- `ai_session_state`
+
+### 11.3 数据归属原则
+
+- 用户与业务归属只认 `starlock`
+- 新实时项目只保存运行时弱状态和诊断数据
+- 异常恢复时可允许丢失部分弱状态，但不能影响业务主数据
+
+## 12. AI 接入策略
+
+### 12.1 三种模式
+
+#### 模式一：`human_to_human`
+
+纯 APP 与设备对讲。
+
+#### 模式二：`human_assisted`
+
+AI 作为旁路助手，提供：
+
+- 转写
+- 摘要
+- 关键词告警
+- 指令识别
+
+#### 模式三：`human_to_ai`
+
+用户直接与设备上的 AI 交互，设备通过 `ai-gateway` 接入 `xiaozhi_server`。
+
+### 12.2 推荐优先级
+
+上线顺序建议是：
+
+1. 先做人对人对讲
+2. 再做 AI 辅助
+3. 最后做设备直连 AI 应答
+
+### 12.3 为什么 AI 必须旁路化
+
+因为 AI 是高延迟、可失败、可替换的能力。如果把它直接嵌入主通话状态机：
+
+- AI 延迟会拖慢接听体验
+- AI 故障会中断主通话
+- 后续替换 `xiaozhi_server` 成本高
+
+## 13. 演进路径
+
+### Phase 1：发现与在线迁移
+
+目标：把设备发现、在线状态、基础 signaling 从 `scd` 拆到 Apache BifroMQ。
+
+交付：
+
+- 设备 bootstrap
+- MQTT 连接鉴权
+- presence / capability / status topic
+- APP 通过 `starlock` 获取设备在线态
+
+### Phase 2：WebRTC 对讲上线
+
+目标：让音视频主链路切到 WebRTC。
+
+交付：
+
+- APP 端 WebRTC
+- 设备或网关端 WebRTC
+- TURN 兜底
+- 中心媒体转发兜底
+- `ZLMediaKit` 转发方案打通
+- signaling 全链路打通
+
+### Phase 3：AI 辅助模式上线
+
+目标：接入 `xiaozhi_server`，但不侵入主媒体链路。
+
+交付：
+
+- ai-gateway
+- AI sidecar
+- 转写/摘要/命令识别
+
+### Phase 4：旧通信层逐步退役
+
+目标：减少对 `starchart-sls1` 中发现和媒体 relay 能力的依赖。
+
+保留项可按实际评估：
+
+- 某些设备尚未迁移时的兼容 relay
+- 某些 RPC 查询能力
+- 事件回调历史逻辑
+
+## 14. 风险与决策点
+
+### 14.1 最大技术风险
+
+- 设备端是否真有能力稳定跑 WebRTC
+- 音频 codec 选型是否统一
+- 双讲回声与弱网体验是否可接受
+- TURN 成本与带宽预算
+
+### 14.2 关键决策点
+
+已经定下：
+
+1. WebRTC 终端跑在锁体、网关
+2. 音频 codec 兼容 G711 桥接
+3. 会话信令完全走 MQTT
+4. AI 能提供的功能都用上
+
+## 15. 推荐结论
+
+最终推荐方案如下：
+
+- `starcloud`：共享业务能力主平台
+- `starlock`：租户化应用层与 APP 业务入口
+- `Apache BifroMQ`：发现、在线、会话 signaling
+- `session-orchestrator`：实时会话编排中心
+- `coturn`：RTC 第一层兜底
+- `media-relay` 能力层，由 `ZLMediaKit` 优先实现：P2P/TURN 失败后的中心转发兜底
+- `ai-gateway + xiaozhi_server`：AI 能力面
+- 设备侧优先由网关/高能力终端承担 WebRTC 与 AI，而不是全部压到低功耗锁体
+
+这套方案能把你现在的“中央通信系统”拆成可演进的分层结构，同时把通用业务能力沉淀到 `starcloud`，由 `starlock` 聚焦租户化编排与应用体验层。
\ No newline at end of file