L1→L3 迁移：对用户几乎无感，分阶段推进
这份文档只讲两件事：① 从用户视角，把设备从「a4x authority」切到「传音 authority」的过程，在绝大多数情况下完全无感——并用三种请求路径（只读属性 / 写设置 / 媒体）对照切换前后的 authority 归属，看清切换改了什么、没改什么；② 项目怎么分阶段推进，每个阶段交付哪些功能。切换的技术内核（role switch / rollback / 阻挡机制）作为技术附录另述。
1用户视角：切换几乎无感
迁移换的是「设备听谁的」（控制权），不是搬用户的东西。视频、录像永远留在原处；切换只是控制面的一次翻转，设备照常工作。对绝大多数用户来说，切换发生了他们也不会察觉。
为什么无感
🎥 媒体永不受影响
直播、回放、云端录像始终在同一处，切换完全不碰媒体。看直播、翻历史录像不会中断、不会丢。
🔄 App 自动跟随
事件与设置在切换点自动迁移，App 自动切到新的数据来源。用户不需要做任何操作，也不用重新绑定。
↩️ 可随时回滚
切换后设有回滚窗口，一旦异常可秒级切回；对用户侧同样是自动恢复，不需要用户介入。
不同用户在切换时看到什么
| 用户 | App 版本 | 切换时的体验 |
|---|---|---|
| 机主 | 已更新（常态） | 完全无感 直播 / 事件 / 设置一切照旧，察觉不到切换发生。 |
| 被共享成员 | 已更新 | 完全无感 与机主一致，无任何变化。 |
| 被共享成员 | 旧版未更新 | 直播 / 回放照常能看；打开设备状态或改设置时，会看到一次「请升级 App」提示。升级后一切恢复正常。 |
机主和已更新的用户零感知；唯一会遇到一次提示的，是还在用旧版 App 的被共享用户——而且他仍然能看直播，只是查看设备状态 / 改设置时被引导升级，升级后即恢复。整个过程没有任何用户需要重新绑定设备、也不会丢失任何视频或历史。
一台设备开始切换，需要满足两个前提：① 设备已通过 OTA 升级到支持新模式的固件（升级后先「休眠待命」，仍按老模式运行，用户无感）；② 机主的 App 已是新版本。两者就绪后才对该设备执行切换——这正是「机主无感、切换即成功」的保障。
2三种请求路径（按 authority 归属）
这三种请求在 a4x 的架构里落到两套不同的平台：只读属性、写设置属于会参与角色切换的 IoT Platform；媒体（直播/回看/AI）属于永不参与切换的 IPC Capability Platform。authority 归属是每设备独立的——在 L3 迁移窗口内，全量设备里两种 authority 并存，由 Role Manifest 逐设备决定控制面走哪套 IoT Platform。下图用 Authority / Projection Slot 表示：控制面永远发给 Authority Slot，只是哪套平台坐这个槽位随该设备状态翻转；媒体则永远走 a4x。谁切、何时切、怎么回滚见 §3。
runtimeAuthority 路由——每设备可能不同（同一 App 里，设备 A 走 a4x、设备 B 走传音）。
roleEpoch 互换槽位（可切 / 可回滚）
| 请求类型 | 命中的功能节点（a4x 设计） | authority=a4x （未切） | authority=传音 （已切） | 是否变 |
|---|---|---|---|---|
| 只读属性 状态/在线/device card/事件摘要 |
IoT Platform · Device Shadow(reported) / device card / 事件摘要 | a4x IoT Authority |
传音 IoT Authority |
换 Slot |
| 写设置 灵敏度/布防/侦测区域 |
IoT Platform · Device Shadow(desired)；projection 侧改动经 command ingress 回流 authority | a4x IoT Authority |
传音 IoT Authority |
换 Slot |
| 媒体 直播/回看/录像/AI |
IPC Capability Platform · WebRTC / GASS / DEM / AI（media token + traceId） |
a4x IPC Cap. | a4x IPC Cap. | 不变 |
切换只是让控制面（只读属性 + 写设置）在两套 IoT Platform 之间换 Authority Slot——非 authority 的一侧经 Projection Bridge 保留只读镜像；对新版 App 是按 Role Manifest 自动路由的，用户看不到。媒体走的 IPC Capability Platform（WebRTC/GASS/DEM/AI）从不参与切换，直播、回看在切换前后是同一条 a4x 通道，不中断、不丢；事件只用 traceId 引用视频对象。
唯一会看到差别的情况：切换后，旧版 App 的被共享用户走「只读属性 / 写设置」时仍朝 a4x 的 IoT Platform 发——而 a4x 此时是 projection、不是 authority，会回一个 migrated（请升级）。它的媒体路径（IPC Capability）不受影响，直播照常。升级后 App 按 Role Manifest 走传音，三条路径全部恢复（阻挡机制详见技术附录《老 App 阻挡》）。
3authority 归属与切换过程
authority 归属是每设备决定的，不是「整个 L3 阶段一刀切」。设备默认 authority 在 a4x；只有同时满足准入门、并被 Migration Control Plane 触发，才切到传音。加上灰度分批与可回滚，所以在 L3 迁移窗口内，全量设备是混合态——一部分 authority 仍在 a4x，一部分已在传音。
控制面 authority 两种并存（上图颜色）；媒体无论哪台，永远 → a4x IPC Capability。App 打开某台设备时，按该设备的 authority 决定 §2 图里谁坐 Authority Slot。
一台设备怎么从 a4x authority 切到传音 authority
② 机主 App ≥ 基线
③ projection 就绪
下发 switch
roleEpoch +1
谁拍板 · 各方怎么知道
Migration Control Plane（独立于两套业务平台的编排层）判定准入、决定何时切，并把每设备的 authority 写进 Role Manifest（runtimeAuthority + roleEpoch）——这是「谁是 authority」的唯一真相源。设备、App、两朵云都只读它、跟随，谁都不自己拍板、也不互相商量。
关键：设备被「推」、App 靠「拉」，都以 roleEpoch 为唯一依据。设备由 a4x 通道下行命令触发（push）；App 每次开设备主动读 manifest 得知 authority（pull）。因为都认同一个 roleEpoch，不会出现「设备以为切了、App 还没切」的错位——谁落后一步就按老 epoch 走，直到读到新 epoch 为止。
三种原因，任一不满足，设备就安全地留在「authority=a4x」、用户照常使用：① 没 OTA 到位——固件还不是 L3 版本；② 机主没升级 App——不满足 APP_FW_READY；③ 还没轮到它——灰度按 SKU / 区域 / 固件批次分批推进，未进入本批次的设备不下发触发。
这张流程决定的，正是 §2 图里每台设备谁坐 Authority Slot：处在「authority=a4x」的设备，Authority Slot 是 a4x IoT Platform；处在「authority=传音」的，Authority Slot 是传音 IoT Platform。媒体两种情况都指向 a4x IPC Capability，切换过程从不触碰。
4分阶段推进计划
项目按下面的阶段推进（不含日期，排期另议；顺序表达依赖关系）。下表逐阶段给出传音侧 / a4x 侧的具体工作内容与准出标准；对用户的影响标在阶段名下。
| 阶段 | 传音 · 工作内容 | a4x · 工作内容 | 准出标准 |
|---|---|---|---|
| L1 · GA 产品上线 用户：拿到可用产品 |
集成 a4x App SDK + 云端 API；App 扩展 IPC 模块（复用账号 / 家庭 / 共享）；上线接入 / 直播 / 事件 / 基础设置；锁定设备身份（sn/deviceSecret→deviceId）稳定映射；合同锁保留期 / 回放 / 回填 / 导出。 |
提供 IPC 固件与云端能力（IoT Platform 为 authority + IPC Capability Platform）；现有 REST / webhook（BIND / PIR / CALL…）可用；承载设备接入 / 直播 / 事件 / 媒体。 | 产品功能就绪、用户可用；设备身份稳定可映射；L1 合同含保留期 / 回放 / 回填 / 导出条款。 |
| M0 · 迁移契约 纸面 用户：无感 |
牵头起草迁移契约；定义 Role Manifest / roleEpoch / Migration Ledger / device-id 映射 / rollback delta / 版本矩阵；确认 L1/L3 分级与 SKU 边界。 |
与传音共同定稿契约；给出现有 API / webhook 的覆盖与缺口清单；确认 OTA authority 归属（ADR）。 | App / 云 / 固件 / OTA / 支持五方能按同一状态机与契约实现；唯一 authority 与回滚材料均可定义。 |
| M1 · L1 迁移就绪 内部就绪 用户：无感 |
App 消费 Role Manifest、内置 L1 / L3 双 route；云端建 Migration Ledger；设备身份映射落库。 | 固件支持 A/B（或等价）可回滚；保证 L1 checkpoint 完整；事件 eventId / traceId 幂等。 |
一台 L1 设备可被纳入迁移批次（仍由 a4x authority 服务）；旧 App 占比可控、固件可回滚。 |
| M2a · L3 固件试运行 a4x 主导 用户：无感 |
提供 L3 控制面接入契约（SDK / 物模型）供固件对接；接收遥测 / 诊断。 | 新硬件跑 L3 目标固件；验证硬件 / 固件连接 / OTA fallback / 诊断日志（＝固件改造）。 | 试运行指标达标；固件能力 / 失败模式 / 诊断证据写入 L3 Ready 准入材料；OTA 回滚可用。 |
| M2b · L3 Ready 平台就绪 用户：无感 |
IoT Platform 具备 authority 准入（九维对齐：物模型 / 身份 / 权限 / desired-reported / 命令 ACK-错误码 / 幂等-顺序 / 生命周期 / 观测）；建 projection 读侧 + command ingress。 | 与传音 projection 互通、搭 Projection Bridge（云对云）；物模型 / capability mapping 对齐；媒体 token 验签就绪。 | 双写投影延迟 / 字段映射 / 权限 / 事件摘要 / 诊断链路达标（阈值内）；M2a 证据纳入。 |
| M3 · 角色切换灰度 canary 用户：灰度无感切换 |
经 Migration Control Plane 对小批设备写 Role Manifest（authority=传音）；App 按 manifest 路由；备好回滚通道（传音下发）与监控 / guardrail。 |
控制通道下发 switch 指令给设备；projection 态控制面回 migrated；媒体照常；配合回滚演练。 |
完成 role switch + 双写投影 + IPC 授权 + 回滚演练；guardrail（连接失败 / route 错误 / 投影延迟 / 核心操作失败）未触发。 |
| M4 · 分批生产迁移 全量 用户：全量无感切换 |
按 SKU / 区域 / 固件批次分批推进；备 runbook / dashboard / oncall / 支持话术；切换点从 a4x 回填历史。 | 各批次固件 / OTA 就绪；保持 projection + 回滚料；媒体入口稳定。 | 每批进入 L3_ROLE_STABLE；回滚窗口结束后归档材料；错误率 / 回滚率 / support ticket / 媒体入口失败率在 guardrail 内。 |
L1·GA 是先把产品做出来、让用户用上；M0 / M1 是低成本地把 L1 变得「可被迁移」（M0 纯纸面，用户无感）；M2a / M2b 才是造出 L3 能力的主体工作；M3 / M4 是执行切换——用户在这两步经历的，就是 §1 描述的无感体验。
5术语表
本文档架构术语统一用 a4x 英文原词（与 a4x 设计 / 字段零漂移）；下表给出中文与说明。code 样式的是 App / 设备实际读写的字段或标记名。
| 术语 | 中文 | 说明 |
|---|---|---|
| authority | 权威 | 设备 runtime 的唯一写权威；同一时刻每设备只有一个。L1=a4x，L3=传音。 |
| projection | 投影 / 只读镜像 | 非 authority 的一侧，经 Projection Bridge 接收镜像；只读，不接受设备写入。 |
| Authority Slot / Projection Slot | 权威槽位 / 投影槽位 | 两个角色槽位；迁移＝两套 IoT Platform 互换槽位。 |
| role switch | 角色切换 | 翻转 Authority / Projection 槽位；rollback ＝ 反向 role switch。 |
roleEpoch | 角色纪元 | 标识「这一代 authority 归属」的单调递增版本号；拒绝旧纪元写入、防脑裂。 |
runtimeAuthority | 运行时权威归属 | Role Manifest 里标明该设备当前 authority 是谁的字段。 |
| Role Manifest | 角色清单 | 每设备的 authority 真相源；App / 固件 / 云读它拿 runtimeAuthority / roleEpoch / route。 |
| Migration Control Plane | 迁移控制面 | 独立于两套业务平台的编排层：判定准入、决定切换 / 回滚、维护 Role Manifest 与 Migration Ledger。 |
| Migration Ledger | 迁移账本 | 驱动每设备状态机推进；App / 固件只上报、不自行推进。 |
| Projection Bridge | 投影桥 | 云对云复制流，把 authority 的状态镜像给 projection；角色翻转时方向随之翻转。 |
| command ingress | 命令回流 | projection 侧 UI 产生的写意图，回流给当前 authority 裁决（防出现第二条写通道）。 |
| Device Shadow | 设备影子 | 设备属性 reported / desired 状态；对应「只读属性」与「写设置」。 |
| IoT Platform | 物联网平台 | 承载绑定 / 属性 / 事件摘要 / 设置 / 命令，参与角色切换；a4x、传音各一套。 |
| IPC Capability Platform | 媒体能力平台 | 承载直播 / 回看 / 录像 / AI，永不参与切换，永远归 a4x。 |
| WebRTC / GASS / DEM / AI | — | IPC Capability Platform 的组件：WebRTC＝直播，GASS / DEM＝回看·录像·事件，AI＝识别 / tags。 |
migrated | （已迁移标记） | 设备切换后，a4x（此时是 projection）对控制面读 / 写返回的标记；App 据此提示升级。 |
traceId | 视频引用标识 | 事件里指向 a4x 视频对象的引用；切换 / 回滚都不改变，视频永远从 a4x 取。 |
| OTA | 固件在线升级 | 只把 L3 能力装进固件（休眠），不改变 authority 归属；切分点是角色翻转，不是 OTA。 |
L3_READY / APP_FW_READY | （每设备状态） | 切换的两个前置：OTA 到 L3 版本(休眠) / 机主 App ≥ 基线且 projection 就绪。 |