eHome App 端详细需求设计文档

M08 智能场景联动（对应需求：FR-1701~1706）

项目	内容
所属项目	eHome 智能家居硬件配套 APP + 云端后台定制开发项目
设计依据	《eHome智能家居项目需求文档（PRD V1.1）》场景联动章节、第8章、NFR-02（本地联动响应≤1s / 云端≤3s）/NFR-04（可用性99.9%）；《eHome项目页面功能工时费用明细表》M08模块
范围说明	本模块覆盖场景（手动一键执行）与自动化（条件触发）两类智能联动的创建、编辑、执行、日志、模板市场、冲突与防环治理；不包含单设备控制（属 M04）、告警通知分发（属 M06，本模块仅可调用"发送通知"动作）、传感器校准（属 M07）、定时任务作为触发源之一被引用但调度器由云端统一提供
编号衔接说明	M05 文档中提及的"场景自动化"即本模块 M08；M04-R05 单设备快捷操作可被本模块动作编排复用；本文档 FR 编号按工时表 M08 行顺延为 FR-1701~1706
优先级	P0（MVP必须；场景联动是智能家居差异化体验核心，决定用户从"控制设备"到"享受生活"的价值跃迁）
里程碑	M2 完整功能期开发（依赖 M01 账号、M02 家庭/房间/设备与权限、M03 配网、M04 设备控制与状态、M06 告警通知、M09 OTA 能力模型）
文档用途	直接交付 UI 设计、Flutter 开发（APP端）、云端开发、规则引擎工程师、固件联调、测试QA

需求编号映射（以工时表 M08 功能项为准）：

需求编号	功能项
FR-1701	场景管理中心（手动场景/自动化列表、启停、复制、排序、分组、批量管理）
FR-1702	场景编辑器（触发条件、执行动作、生效条件三段式编排、能力驱动动态表单）
FR-1703	场景执行引擎对接（一键执行、条件触发、执行反馈、部分失败处理与重试）
FR-1704	自动化执行日志与调试（执行历史、命中原因、失败诊断、模拟运行）
FR-1705	场景模板市场（官方/品类模板、一键应用、参数适配、自定义模板保存）
FR-1706	智能场景联动 UI 设计（编排组件、双主题、7语种、无障碍）

1. 模块概述与设计原则

1.1 模块范围

序号	页面/功能项	需求编号	类型	优先级
1	场景管理中心页（含首页场景快捷区联动）	FR-1701	APP+云端	P0
2	场景编辑器（三段式编排）	FR-1702	APP+云端	P0
3	执行反馈与部分失败处理	FR-1703	APP+云端+固件	P0
4	自动化日志与模拟运行页	FR-1704	APP+云端	P0
5	场景模板市场页	FR-1705	APP+云端	P0
6	场景联动 UI 规范	FR-1706	UI	P0

边界与衔接说明：

入口A：首页 Tab「场景」→ 本模块 S01（场景管理中心）；
入口B：首页顶部场景快捷区（M01-P01 首页）横向卡片 → 一键执行 / 长按编辑 → S02；
入口C：M02 房间详情页【该房间场景】→ S01（预筛房间）；
入口D：M04-R01 设备详情页【参与的场景】→ S01（预筛该设备相关场景）；
入口E：M06-A03 告警详情【创建联动场景】→ S02（预填触发条件为告警事件）；
出口：S02 动作选择器复用 M04 设备控制能力；"发送通知"动作调用 M06 通道；场景失效设备引导 M02 设备列表/M09 OTA；S05 模板应用回 S02 适配参数；语音生态（M11）同步暴露场景为可语音触发实体。

1.2 设计原则

三段式心智模型：统一为「当（触发条件）→ 并且（生效条件）→ 就执行（动作）」，手动场景为「触发条件=点击执行」的特例；用户学习一次即通用，降低认知负担。
能力驱动动态编排：触发器/条件/动作的可选项完全由设备能力模型（M02/M09 提供）动态生成，不做硬编码品类分支；新品类接入零 APP 发版。
执行确定性优先：动作按序执行并逐项回执；部分失败明确告知哪些设备未生效并提供一键重试；不静默失败。
防环与限流：自动检测场景互相触发形成的环路（A→B→A）并阻断保存；单场景/单家庭执行频率限流，避免设备抖动引发风暴。
本地优先降级：支持本地联动的网关类设备（Zigbee/蓝牙 Mesh 子设备）规则下沉网关，断网仍可执行；纯 Wi-Fi 设备走云端；编辑器明示"断网时是否可用"。
可解释可调试：每次自动执行记录命中原因（哪个触发器、什么值、什么时间）与逐动作结果；提供"模拟运行"干跑（dry-run）验证逻辑而不真操作设备。
权限与安全：家庭管理员可创建/编辑/删除场景；普通成员仅可执行被授权场景；场景不能绕过 M02 设备权限（无权限设备不出现在动作选择器）；删除家庭/移除设备联动失效处理。
双主题 + 7语种：触发器/条件/动作描述文案采用「参数化句式模板」由 7 语种分别撰写（不做机器拼接），保证语法自然；深色模式全适配。

1.3 用户与前置条件

用户状态：必须已登录（M01）；未登录拦截跳转登录页，成功回跳来源页。
家庭前置：已创建/加入家庭（M02）；无家庭→S01 展示引导态跳转 M02。
设备前置：创建自动化至少需 1 台支持触发的设备 + 1 台可执行动作的设备；无设备→引导 M03 配网。
能力前置：设备能力模型声明 scene_trigger / scene_condition / scene_action 支持项；无相应能力的设备在选择器中置灰并说明原因。
权限前置：管理员全权；普通成员执行权限按场景授权范围（创建时指定"全体成员可执行/仅管理员"）；无编辑权时 S02 为只读预览态。
网络前置：一键执行需网络（APP→云/网关）；断网时首页场景卡片置灰并提示"网络不可用"；本地场景由网关执行不受 APP 断网影响。
配额前置：单家庭自动化上限 50 条、手动场景上限 30 条（云端可配）；超限提示升级或清理。

2. 页面结构与流程图

2.1 页面导航结构

入口A：首页Tab[场景] ──► S01
入口B：首页场景快捷卡[点击]──► 一键执行 ；[长按]──► S02
入口C：M02房间详情[该房间场景] ──► S01(预筛房间)
入口D：M04-R01[参与的场景] ──► S01(预筛设备)
入口E：M06-A03[创建联动场景] ──► S02(预填告警触发)

S01 场景管理中心
 ├─ 顶部分段控件：手动场景 / 自动化
 ├─ 分组与筛选（房间/设备/标签/启停状态/搜索）
 ├─ 手动场景区：卡片网格（图标+名称+[执行]）；长按→编辑/复制/删除/置顶
 ├─ 自动化区：列表卡片（名称+摘要句+启停开关+最近执行状态徽标）
 ├─ [新建场景] ──► S02-类型选择（手动/自动化）
 ├─ [模板市场] ──► S05
 ├─ [执行日志] ──► S04
 └─ [批量管理]（多选删除/启停/移动分组）

S02 场景编辑器（三段式）
 ├─ Step0 基础信息（名称/图标/颜色/所属房间/可执行成员范围/标签）
 ├─ Step1 触发条件（IF）
 │     ├─ 设备状态触发（开关/门窗/人体存在/漏水…）
 │     ├─ 传感器阈值触发（>/</区间/持续时间）
 │     ├─ 定时触发（每日/工作日/周末/自定义重复/日出日落偏移）
 │     ├─ 场景触发（其他场景执行后·防环校验）
 │     └─ 手动触发（=手动场景，无IF）
 ├─ Step2 生效条件（AND，可选）
 │     ├─ 时间范围（仅在 18:00-23:00 生效）
 │     ├─ 设备状态约束（仅当空调处于关闭）
 │     ├─ 传感器数值约束（仅当室温>28℃）
 │     └─ 家庭状态（仅当"离家模式"激活·联动M04模式）
 ├─ Step3 执行动作（THEN，有序列表）
 │     ├─ 设备控制动作（能力驱动，如 开灯/调亮度到60%/设温26℃）
 │     ├─ 延时（等待N秒/分）
 │     ├─ 执行其他场景（防环校验）
 │     ├─ 发送通知（调用M06通道，文案自定义）
 │     └─ 变量/模式设置（激活"睡眠模式"）
 ├─ 冲突与防环检测面板（保存前自动扫描）
 ├─ [模拟运行] ──► S04 干跑结果
 ├─ [保存] / [保存并启用]
 └─ [另存为我的模板] ──► S05

S04 自动化日志与调试页
 ├─ Tab：执行历史 / 模拟运行
 ├─ 执行历史：时间线（场景名+触发原因+结果徽标 成功/部分失败/失败/被抑制）
 ├─ 单条详情：触发快照(设备+值+时间) → 生效条件判定明细 → 逐动作结果(设备/指令/回执/耗时/错误)
 ├─ 失败项：[重试该动作] / [查看设备] → M04-R01
 ├─ 抑制记录：限流/防环/免打扰导致的跳过原因
 └─ 模拟运行：选择场景+[干跑]→输出"是否会触发+将执行哪些动作"，不真操作设备

S05 场景模板市场
 ├─ 分类导航（回家/离家/睡眠/起床/影音/安防/节能/节气）
 ├─ 模板卡片（封面图+名称+适用品类+应用量+评分）
 ├─ 模板详情：说明+所需设备能力清单+参数预览+[应用]
 ├─ 应用流程：能力匹配检测 → 缺设备提示[去添加] / 匹配成功 → S02预填 → 参数适配(选设备/调阈值) → 保存
 ├─ 我的模板：自定义保存的模板列表（重命名/删除/应用）
 └─ 搜索（关键词+品类筛选）

2.2 核心状态机一：场景（自动化）生命周期

[草稿·编辑中]（本地暂存/云端草稿）
   │
   ├──(保存并启用，校验+防环+配额通过)──► [已启用]
   │        │
   │        ├──(触发器命中 + 生效条件满足 + 未被抑制)──► [执行中]
   │        │        │
   │        │        ├──(全部动作成功)──► [执行成功] ──► 写日志 + 首页徽标绿
   │        │        ├──(部分动作失败)──► [部分失败] ──► 写日志 + 徽标橙 + 可重试
   │        │        └──(全部失败/超时)──► [执行失败] ──► 写日志 + 徽标红 + M06通知(可选)
   │        │
   │        ├──(触发但生效条件不满足)──► [已跳过·条件未满足]（日志记录判定明细）
   │        ├──(触发但命中限流/防环/免打扰)──► [已抑制]（日志记录抑制原因）
   │        │
   │        ├──(用户关闭开关)──► [已停用]（保留配置，停止监听触发）
   │        ├──(关联设备被移除/离线超阈值)──► [部分失效] ──► 徽标灰 + 提示"X台设备不可用" + [修复]
   │        │        ├──(设备恢复/替换后重映射)──► [已启用]
   │        │        └──(用户确认删除失效项)──► [已启用]（配置更新）
   │        ├──(全部关联设备失效)──► [已失效] ──► 自动停用 + 通知用户
   │        ├──(规则引擎版本升级不兼容)──► [需更新] ──► 提示重新编辑保存
   │        └──(用户删除)──► [已删除]（软删除30天可恢复，日志保留）
   │
   └──(保存校验失败)──► [保存失败] ──► 定位到问题段落 + 红色错误文案

2.3 核心状态机二：场景执行事务（云端/网关-设备）

[触发事件到达]（手动点击 / 设备状态上报 / 定时调度 / 场景链式触发）
   │
   ├──(规则引擎匹配)──► [命中场景]
   │        │
   │        ├──(生效条件求值)──► 条件不满足 ──► [跳过]（日志）
   │        │        │
   │        │        └──满足──► (抑制检查：限流/防环/免打扰/设备锁)
   │        │                 │
   │        │                 ├──被抑制──► [抑制]（日志+原因）
   │        │                 └──通过──► [事务创建 txId · 参数快照]
   │        │
   │        └──[执行模式判定]
   │                 ├──(全部设备同网关/支持本地)──► [本地执行·网关下沉]（断网可用，P90≤1s）
   │                 └──(含Wi-Fi/跨网关)──► [云端执行]（P90≤3s）
   │
   └──[事务创建]
            │
            ├──(动作按序下发，逐项等待回执)
            │        │
            │        ├──动作i ACK成功──► 记录耗时──► 执行动作i+1
            │        ├──动作i NACK/超时(单动作15s)──► 记录失败──► 策略判定
            │        │        ├──(配置=继续)──► 执行下一动作
            │        │        └──(配置=中止)──► 事务终止 ──► [执行失败]
            │        ├──延时动作──► 定时器等待（最长30min，超时事务标记中止）
            │        └──链式"执行其他场景"──► 递归调用（深度≤3，防环表校验）
            │
            ├──(全部动作完成)──► [事务结束·汇总]
            │        ├──(全成功)──► [执行成功]
            │        ├──(有失败有成功)──► [部分失败] ──► 失败动作可重试(保留快照, 24h内)
            │        └──(全失败)──► [执行失败]
            │
            └──(通知策略)──► 失败/部分失败按场景配置经 M06 通道提醒（默认关闭，安防类默认开）

3. 页面级详细需求

S01 场景管理中心（FR-1701）

页面目标：集中管理手动场景与自动化，一眼看清可用性与最近执行情况，快速触达执行。

页面元素：

元素	规格与规则
顶部导航	标题"场景"；右侧[+]新建、[日志]→S04、[批量管理]；下拉刷新
分段控件	手动场景 / 自动化；带数量角标；切换保留各自滚动位置与筛选
筛选与搜索栏	房间多选+设备多选+标签+启停状态+搜索框（名称/动作关键词）；筛选后顶部展示筛选条件芯片可单独移除
手动场景网格	2列卡片（平板3列）：图标+名称+动作数摘要；卡片主区域点击=一键执行；右下角[···]菜单；执行中显示loading环
自动化列表	卡片：启停开关+名称+摘要句（"当门窗传感器打开，就开灯"）+最近执行徽标（成功绿/部分失败橙/失败红/被抑制灰/未执行无）+最后执行时间；点击进入S02编辑
分组区	按房间/标签分组的可折叠区块；支持拖拽排序（仅管理员）；排序结果云端同步
长按菜单	[编辑][复制][重命名][移动分组][置顶/取消置顶][删除]；复制生成"名称-副本"（自动化默认停用态）
失效提示条	存在部分失效/已失效场景时顶部黄色横幅"N个场景设备不可用"+[查看]
配额提示	接近上限（≥90%）时提示"自动化数量已达45/50"
空态	无场景：插画+"创建你的第一个智能场景"+[新建场景]+[浏览模板]；筛选无结果：独立空态+[清除筛选]
无家庭/无设备引导	无家庭→引导M02；无设备→引导M03配网

逻辑规则：

数据来源：GET /scenes?familyId=&type=manual|auto&rooms=&tags=&status=&keyword=&page=；返回场景摘要+最近执行状态（联表 logs 最新1条）；本地缓存最近列表（TTL 5min），进入即显缓存后增量刷新；
一键执行：点击手动场景→POST /scenes/{id}/execute（返回 txId）→乐观更新为执行中→MQTT scene/exec/{txId} 回执驱动结果；执行反馈三态：成功轻震动+卡片绿色闪烁1次；部分失败Toast"3个动作中1个失败"+[查看]跳S04；失败Toast+错误码文案；
执行节流：同一场景执行中禁止重复触发（按钮置灰+loading）；同一场景最短触发间隔3s（云端限流，客户端同步禁用）；
开关乐观更新：切换启停即时反馈，失败回滚+Toast；
拖拽排序：仅管理员；排序变更 PUT /scenes/order 批量提交；失败回滚原顺序；
删除：二次确认弹窗（展示场景名+动作数+"删除后不可恢复（30天内可在回收站恢复）"）；软删除；批量删除上限20条/次；
权限：普通成员隐藏[新建][批量管理]与长按菜单中的编辑/删除项，仅保留[执行]（且仅授权范围内场景）；
与首页联动：置顶场景同步至首页快捷区（M01-P01），最多8个；
语音联动：已启用场景自动注册为语音实体（M11），场景重命名后语音名称同步更新（云端处理）；
埋点：手动场景执行次数/成功率、自动化启停率、筛选使用率、长按菜单各项点击率、空态引导转化率。

异常与边界：执行接口超时（>10s）→Toast"执行超时，请查看日志确认结果"+S04深链；MQTT断连→执行结果走HTTP轮询兜底（2s×5次）；场景被其他成员同时删除→执行返回404→Toast"场景已被删除"并刷新列表；离线设备场景执行→按动作策略（跳过/中止）处理并在结果中明示。

验收要点：两分段列表与筛选正确；一键执行三态反馈与节流生效；长按菜单六操作闭环；权限隔离（成员只可执行）；失效横幅与修复入口；配额提示；置顶同步首页；语音实体同步。

S02 场景编辑器（FR-1702）

页面目标：以三段式模型完成任意复杂度联动编排，保存前完成合法性、冲突与防环校验。

页面元素：

元素	规格与规则
顶部导航	返回（有改动时拦截确认）+标题"编辑场景/新建场景"+[保存]；右上角[模拟运行][更多：复制/删除/另存为模板]
Step0 基础信息	图标选择器（40+预设图标+12色）；名称输入（1~30字符，家庭内唯一）；所属房间（可空=全屋）；标签（多选，最多3个）；可执行成员范围（全体成员/仅管理员/指定成员）
Step1 触发条件 IF	[+添加触发器]→触发器类型选择页（设备状态/传感器阈值/定时/场景/告警事件）；已添加项列表可拖拽排序；多触发器关系单选：任一满足(OR)/全部满足(AND)；每项支持编辑/删除
Step2 生效条件 AND	可选段落；[+添加条件]；条件类型：时间范围/设备状态/传感器数值/家庭模式/星期几；多条件恒为 AND；折叠展示"不添加则任何时候生效"
Step3 执行动作 THEN	[+添加动作]；动作有序列表，拖拽排序；类型：设备控制/延时/执行场景/发送通知/设置模式；每项含参数摘要句+编辑/删除/复制；底部"失败策略"单选：继续执行后续/中止场景（默认继续）
冲突与防环面板	保存前自动扫描；展示：①与现有场景的动作冲突（同设备同属性被多场景以不同值设置）②环路检测（A触发B、B触发A）③限流风险（触发器为高频抖动源如人体存在传感器未加持续时间）；每项[忽略并继续]/[去修改]
断网可用性提示	底部说明条："本场景包含Wi-Fi设备，断网时无法执行"或"本场景全部设备在同一网关，断网可本地执行"
草稿暂存	返回/退出时弹窗[保存草稿][放弃]；草稿本地+云端保留7天，S01顶部展示"继续编辑未完成的场景"

触发器配置规格：

触发器类型	参数与校验
设备状态	选择设备（按房间分组，仅有 scene_trigger 能力）→选择属性（开/关、打开/关闭、有人/无人、有水/无水）→选择目标值；支持"从X变为Y"与"变为Y"两种语义
传感器阈值	选择设备→指标→比较符(>/</≥/≤/区间内/区间外)→阈值（量程校验，联动M04/M07量程）→持续时间（立即/持续1/5/10/30分钟）；持续时间用于抗抖动，默认5分钟并提示原因
定时	时间选择器+重复（每天/工作日/周末/自定义星期/指定日期）；支持日出日落模式（基于家庭经纬度，M02家庭地址）+偏移分钟（-60~+60）；跨时区家庭按家庭时区执行
场景触发	选择其他已存在场景（排除自身与 descendants，防环）→"执行完成后"触发
告警事件	选择M06规则或告警等级（如"当紧急告警触发"）；用于安防联动

动作配置规格：

动作类型	参数与校验
设备控制	选设备→选能力动作（能力模型驱动动态表单：开关/亮度滑杆/色温/目标温度/模式枚举/开度百分比等）→设参数值（量程/枚举校验）；支持"多设备同参数批量添加"
延时	1秒~30分钟；提示"延时期间断电/断网将中止后续动作"
执行场景	选择其他场景（手动/自动均可）；链式深度≤3；防环校验；被选场景停用时提示
发送通知	选择通道（复用M06配置）+文案（1~100字符，支持变量占位符 `{deviceName}`/`{value}`/`{time}`）；通道不可用时引导M06-A02
设置模式	选择家庭模式（在家/离家/睡眠/自定义，M04-R06）→激活；模式不存在时引导创建

逻辑规则：

能力驱动：所有设备/属性/动作选项来自 GET /scenes/capabilities?familyId=（云端按能力模型聚合）；缓存10min；能力变更后（OTA升级）编辑器提示"设备能力已更新，请检查配置"；
权限过滤：动作选择器仅展示当前用户有控制权的设备（M02权限）；无权限设备不出现（非置灰），避免越权配置；
校验时机：字段级实时校验（红色边框+文案）；段落级离开时校验；保存前全量校验+冲突/防环扫描；
保存：POST /scenes（新建）/ PUT /scenes/{id}（编辑）；请求体为结构化 DSL（见6.3）；返回场景ID+版本；保存并启用 status=enabled；
版本管理：每次保存 version+1；正在执行的事务使用触发时快照版本，不受后续编辑影响；旧版本保留5个支持回滚（P2）；
编辑锁定：同场景同时仅允许一人编辑（云端乐观锁 If-Match version）；冲突时提示"该场景正在被其他成员编辑，请稍后"；
自动命名：未填名称时按 DSL 生成默认句（"当门窗打开就开灯"），多语言按句式模板生成；
场景配额：保存前校验家庭配额；超限阻断+提示；
埋点：各段落添加率、触发器类型分布、动作类型分布、冲突面板处理选择、保存成功率、编辑时长、草稿恢复率。

异常与边界：编辑中设备被移除→该段落标红"设备已移除"+[替换设备]/[删除该项]，未处理不可保存；触发器全部删除→保存阻断"至少需要一个触发条件（手动场景请选手动触发）"；动作全部删除→阻断"至少需要一个执行动作"；延时+断电→日志记录中止；跨时区家庭定时→按家庭时区（M02）而非手机时区。

验收要点：三段式编排闭环；能力驱动动态表单正确（新品类无需发版）；权限过滤生效；阈值/量程/枚举校验；防环与冲突扫描准确；乐观锁编辑冲突提示；草稿保存与恢复；默认命名多语言自然。

S03 场景执行反馈与部分失败处理（FR-1703）

页面目标：让每一次执行结果可感知、可解释、可补救。

页面元素：

元素	规格与规则
执行中反馈	手动执行：卡片loading环+全屏轻量Toast"正在执行…"；自动执行：静默（除配置通知）
结果 Toast/横幅	成功：轻震动+绿色Toast"已执行 N 个动作"；部分失败：橙色横幅"N个动作中M个失败"+[查看详情]→S04详情；失败：红色Toast+错误摘要+[重试]
结果详情浮层（手动执行后）	上滑半屏浮层：动作清单逐项状态（✓/✘/跳过）+失败原因+[重试失败动作]+[全部重试]；3s无操作自动收起
重试入口	失败/部分失败后24h内可在S04或浮层重试；重试使用事务快照参数（设备已变更时提示）
离线设备处理提示	执行前检测：若含离线设备→弹窗"以下设备离线：X、Y。继续执行将跳过/中止（按场景配置）"+[继续]/[取消]（手动执行时；自动执行按配置直接处理）

逻辑规则：

回执驱动：MQTT scene/exec/{txId} 推送逐动作进度（index/status/latency/errorCode）→浮层实时刷新；断连走 GET /scenes/exec/{txId} 轮询（1s×10次）；
单动作超时15s判定失败；错误码映射用户可读文案（设备离线/指令超时/设备拒绝/参数越界/网关不可达）；
失败策略执行：场景配置"继续"→跳过失败项执行后续；"中止"→立即终止并标记失败；
重试幂等：重试仅针对失败动作，携带原 txId + retryIndex，云端幂等去重；重复点击合并；
部分失败通知：安防类模板默认开启失败通知（经M06）；用户自建场景默认关闭，可在S02高级设置开启；
抑制透明：被限流/防环/免打扰抑制时，手动执行仍返回结果（手动不受限流抑制，除3s节流）；自动执行抑制仅记录日志，不打扰用户；
埋点：执行成功率、部分失败率、失败错误码分布、重试成功率、浮层查看率。

验收要点：三态反馈准确；逐动作回执实时；错误码文案映射完整；离线预检弹窗；重试幂等与24h窗口；失败通知按配置生效。

S04 自动化日志与调试页（FR-1704）

页面目标：让自动化"为什么执行/为什么没执行"完全可解释，支撑用户自助排障。

页面元素：

元素	规格与规则
顶部Tab	执行历史 / 模拟运行
筛选栏	场景多选+结果状态（成功/部分失败/失败/跳过/抑制）+时间范围（今天/7天/30天/自定义）+搜索
执行历史时间线	每条：时间+场景名+触发原因摘要句（"门窗传感器打开"）+结果徽标+耗时；按日分组粘性表头
详情展开（点击条目）	①触发快照：设备+属性+触发值+上报时间；②生效条件判定明细：逐条件通过/未通过（含实际值）；③动作清单：序号+设备+指令+参数+状态+耗时+错误码；④抑制原因（若被抑制）：限流/防环/免打扰/设备锁；⑤[重试失败动作][查看设备][复制日志ID]
模拟运行 Tab	选择场景（下拉）→[开始干跑]→输出：当前条件下是否会触发、生效条件逐项判定、将执行的动作清单（标注"不会真实操作设备"）；支持"假设时间"选择器（模拟未来某时刻，验证定时/时间范围逻辑）
日志统计条	顶部小卡：近7天执行N次/成功率X%/失败Top场景
空态	"暂无执行记录"；筛选无结果独立空态
导出/客服	[联系客服]携带最近日志ID与场景配置上下文→M10工单

逻辑规则：

数据来源：GET /scenes/logs?familyId=&sceneIds=&status=&start=&end=&cursor=；游标分页每页30条；云端保留30天，超期自动清理（页面说明"仅保留最近30天日志"）；
跳过与抑制也记录：条件不满足的跳过默认记录（可在设置中关闭以节省存储）；抑制必须记录（排障关键）；
模拟运行：POST /scenes/{id}/dry-run（body可含 assumeTime）；云端用当前设备状态快照+规则引擎求值，不下发任何指令；返回判定明细；接口P99≤1s；
高频触发标记：同一场景1分钟内触发>10次→日志标记"抖动风险"+建议增加持续时间条件（联动S02冲突面板提示）；
日志脱敏：不含用户PII；设备名/值原样保留；
权限：管理员查看全部日志；普通成员仅查看自己执行的与授权场景日志；
埋点：日志页访问率、详情展开率、干跑使用率、客服跳转率、重试点击率。

异常与边界：日志量大（>1万条）虚拟滚动+分页；干跑时设备全部离线→返回"设备状态未知，判定结果可能不准确"警告；场景已删除→日志仍保留（标记"场景已删除"）但不可重试。

验收要点：五类结果（成功/部分失败/失败/跳过/抑制）均有记录且原因可读；详情四段结构完整；干跑不产生真实指令（真机验证设备状态无变化）；假设时间模拟定时逻辑正确；30天清理；权限隔离。

S05 场景模板市场（FR-1705）

页面目标：降低场景创建门槛，用官方最佳实践驱动功能渗透与设备交叉销售。

页面元素：

元素	规格与规则
顶部分类导航	横向滚动芯片：推荐/回家/离家/睡眠/起床/影音/安防/节能/节气/我的模板
搜索栏	关键词+品类筛选（支持"温湿度""门锁""灯带"等设备词）
模板卡片网格	封面插画+名称+一句话价值主张+适用品类图标+应用次数+评分；"需N台设备"角标
模板详情页	头图+简介+功能说明列表+所需设备能力清单（每项：能力名+已有✓/缺少✘）+参数预览（触发器/条件/动作只读展示）+用户评价（P1）+[应用模板]
能力匹配检测	进入详情即检测；全匹配→[应用模板]高亮；部分缺失→按钮变为[应用并适配]，缺失项展示[去添加设备]→M03配网（携带品类上下文）或[用现有设备替代]
参数适配页	应用后进入S02预填态：逐段引导用户将模板中的"抽象设备角色"（如"主灯"）映射到家庭实际设备；阈值/时间参数可调（预设默认值）；未完成映射的段落标红不可保存
我的模板	列表：名称+来源（自建/官方复制）+应用次数；[应用][重命名][删除]；自建模板上限20个/家庭；P2支持模板分享码
运营位	顶部Banner（云端可配，跳转模板详情/H5活动）；新用户首屏推荐3个入门模板

逻辑规则：

数据来源：GET /scenes/templates?category=&keyword=&page=；模板元数据云端CMS管理（M12运营后台），支持上下架/排序/多语言；APP缓存1h；
应用流程：GET /scenes/templates/{id} → 本地能力匹配（对比家庭设备能力）→ 用户映射设备 → 生成场景DSL → POST /scenes（携带 templateId 用于统计）→ 默认状态=已启用（用户在适配页可改为仅保存）；
角色映射：模板使用抽象角色（role: main_light / ac / door_sensor），适配页强制映射到真实设备；一个角色可映射多设备（批量动作）；
模板更新：官方模板更新不影响已应用场景（快照式复制）；模板下架不影响已应用；
我的模板：S02[另存为我的模板]→抽象化设备为角色（自动按品类生成角色，用户可改名）→POST /scenes/templates/custom；
多语言：模板名称/简介/说明/参数默认文案由CMS按7语种维护；缺失语种回退英文并标记待翻译（运营看板）；
配额与权限：应用模板占用家庭场景配额；仅管理员可应用模板与创建自建模板；普通成员可浏览不可应用（按钮置灰+提示）；
埋点：模板曝光/点击/应用漏斗、缺失设备引导转化率（交叉销售指标）、分类偏好、我的模板使用率；数据回流M12运营看板。

异常与边界：家庭无任何匹配设备→详情页明示"当前家庭缺少必需设备"+仅展示[去添加设备]；模板所需能力设备已有但固件过旧→提示[升级固件]→M09；映射过程中设备被移除→该角色标红需重新映射；网络失败→模板列表展示缓存+重试。

验收要点：分类/搜索/详情闭环；能力匹配检测准确（✓/✘与真实设备一致）；角色映射强制校验；应用后场景可正常执行；缺失设备引导M03转化链路；我的模板抽象化与再应用；模板更新不影响已应用场景。

4. 通用交互与视觉规范（UI设计输入，FR-1706）

双主题：浅色/深色两套；场景卡片图标底色支持12色选择在两主题下均满足对比度；执行结果徽标四色（绿/橙/红/灰）深色模式调亮；触发器/条件/动作三段用不同色相区分（IF蓝/AND紫/THEN绿）帮助认知。
组件清单：分段控件、场景卡片（手动网格款/自动列表款）、启停开关、最近执行徽标、长按操作菜单、三段式编排容器（可折叠段落+段落头摘要句）、触发器/条件/动作条目卡（图标+参数化摘要句+编辑删除）、类型选择器（网格图标+搜索）、能力驱动动态参数表单（滑杆/枚举芯片/时间选择器/数值输入）、拖拽排序手柄、冲突与防环告警面板、结果浮层（逐动作状态清单）、日志时间线条目（分组粘性表头）、干跑结果卡、模板卡片（封面+角标）、能力匹配清单（✓/✘）、角色映射选择器、模板分类芯片、空态插画（无场景/无结果/无设备/无模板四款）。
动效规范：场景执行loading环（1s周期）；成功卡片绿色闪烁1次（300ms）+轻震动；段落展开/收起 250ms；条目拖拽浮起阴影+位置让位动画；结果浮层上滑 300ms 弹性；模板应用成功打勾动画；动效均提供"减弱动效"降级。
参数化摘要句：所有触发器/条件/动作以自然语言句呈现（"当客厅门窗传感器打开"、"并且时间在 18:00-23:00"、"就打开客厅主灯并调至60%"）；句式模板按7语种分别人工撰写，占位符 {device}/{value}/{time} 按语种语序可调整位置，禁止字符串硬拼接。
多语言：德/法/俄等长文本预留1.4倍空间；摘要句超长时中间省略并保留设备名；单位（℃/℉/%/lux）跟随M04设置；时间格式跟随locale（12/24小时制）；日出日落文案按地区可用。
无障碍：三段式段落支持读屏播报段落名+条目数；摘要句完整可读（不依赖颜色/图标）；结果徽标含文字标签；拖拽排序提供"上移/下移"按钮替代手势；开关有明确状态播报；焦点顺序按视觉流；动态表单控件均有label。
响应式：平板/折叠屏宽屏下 S01 手动场景3列网格+自动化右侧列表分栏；S02 编辑器采用左段落导航+右内容区；S04 日志左列表+右详情分栏；S05 模板4列网格。
品牌一致性：场景图标库与M02房间图标、M04设备图标同源（统一图标系统）；模板封面插画风格与运营Banner一致（M12提供）。

5. 客户端技术要求（Flutter）

状态管理：Riverpod/BLoC；场景列表 FutureProvider+缓存（TTL 5min）；编辑器用 StateNotifier 管理 DSL 草稿树（三段+条目增删改排序），支持撤销（最近10步，P1）；执行事务 StreamProvider(MQTT)+轮询兜底；日志游标分页 Provider。
DSL 模型：定义 SceneDsl 数据类（meta/triggers[]/conditions[]/actions[]/options），与云端 JSON Schema 一致；序列化/反序列化 + 版本号；本地校验器 SceneValidator（字段级/段落级/防环预检）与云端校验规则共享配置（云端下发规则元数据，减少双端不一致）。
能力驱动表单：封装 DynamicParamForm 组件，按能力模型 schema（type: bool/enum/number/slider/time/text）动态渲染控件；校验规则（min/max/step/enum/required）由 schema 驱动；新增品类零代码适配。
MQTT：复用 M02/M04 连接层；订阅 scene/exec/{txId}（执行进度）、scene/status/{familyId}（场景状态变更，如其他成员编辑/启停）、device/capability/{deviceId}（能力变更通知，触发编辑器刷新）；QoS1。
本地缓存：Hive 存储场景列表、能力数据（TTL 10min）、编辑器草稿（TTL 7天，键=familyId+sceneId+userId）、模板列表（TTL 1h）；草稿含完整DSL；账号注销联动清除。
拖拽排序：使用 reorderable list；长按触发；排序结果防抖500ms批量提交；失败回滚。
深链路由：注册 ehome://scene/{sceneId}（编辑）、ehome://scene/{sceneId}/execute（执行）、ehome://scene/log/{txId}（日志详情）、ehome://scene/template/{templateId}（模板详情）；M06告警/推送点击携带深链直达。
性能：场景列表>100项虚拟滚动；日志>1000条虚拟列表+分页；编辑器复杂DSL（>30条目）渲染优化（const/局部rebuild）；能力数据预加载；模板封面图 CDN+缓存+占位图。
安全：DSL 提交 HTTPS；执行请求带家庭权限校验；本地缓存无PII；Sentry 上报脱敏（不含家庭设备明细）；防越权：客户端权限过滤仅为体验，云端强制校验。
埋点：见各页；统一 SceneAnalytics 封装，事件命名 scene_*；关键漏斗（模板曝光→应用→执行）完整串联；性能埋点（执行端到端延迟、编辑器保存耗时、列表首屏渲染）。

6. 云端需求（场景规则引擎服务）

6.1 接口清单

接口	方法	说明
/scenes	GET	场景列表；参数 familyId/type/rooms/tags/status/keyword/page；返回摘要+最近执行状态
/scenes	POST	创建场景；body=SceneDsl；校验+防环+配额→返回 sceneId/version
/scenes/`{id}`	GET/PUT/DELETE	详情/编辑（乐观锁 If-Match version）/软删除（30天回收站）
/scenes/`{id}`/toggle	POST	启停
/scenes/`{id}`/duplicate	POST	复制（自动化默认停用）
/scenes/order	PUT	批量排序
/scenes/`{id}`/execute	POST	手动一键执行；返回 txId；3s节流+幂等键
/scenes/exec/`{txId}`	GET	执行事务状态与逐动作结果（轮询兜底）
/scenes/exec/`{txId}`/retry	POST	重试失败动作（24h窗口，幂等）
/scenes/capabilities	GET	家庭可用触发器/条件/动作能力聚合（能力驱动表单数据源）
/scenes/logs	GET	执行日志；参数 sceneIds/status/start/end/cursor；保留30天
/scenes/`{id}`/dry-run	POST	模拟运行（可带 assumeTime）；不下发指令；返回判定明细
/scenes/validate	POST	DSL 校验（编辑器实时调用，含冲突/防环扫描）
/scenes/templates	GET	模板市场列表（分类/搜索/分页）
/scenes/templates/`{id}`	GET	模板详情（含抽象角色与能力需求清单）
/scenes/templates/custom	POST/GET/DELETE	自建模板管理（上限20/家庭）
/scenes/trash	GET/POST	回收站列表/恢复（30天）
（MQTT下行）scene/exec	—	场景动作指令下发（网关/设备）；QoS1
（MQTT上行）scene/exec/`{txId}`	—	逐动作回执与事务结果→转发APP
（MQTT下行）scene/rule/sync	—	本地场景规则下沉网关（本地联动）；含版本与校验和
（内部）规则引擎	—	事件总线消费设备上报/定时器/告警事件→匹配触发器→求值生效条件→抑制检查→创建事务→按序执行
（内部）调度器	—	定时触发（家庭时区）、日出日落计算（经纬度+天文算法）、延时动作定时器
（内部）限流与防环	—	令牌桶（单场景/单家庭）、环路检测（有向图 DFS）、抖动抑制、链式深度≤3

6.2 关键策略

规则引擎：事件驱动（Kafka/Pulsar 消费设备上报事件）+ 内存索引（triggerKey→sceneIds）；匹配 P99 ≤50ms；支持 AND/OR 触发器组合、生效条件求值、动作有序编排；规则热加载（编辑保存后 ≤2s 生效，无需重启）。
执行事务：以 txId 为主键记录动作序列快照（版本冻结）、逐项回执、耗时、错误码；单动作超时15s；全事务超时=Σ动作超时+延时（上限35min）；失败策略（继续/中止）可配；重试基于快照幂等。
本地联动：全部设备同网关且网关支持本地规则时，规则下沉网关（scene/rule/sync），断网可执行，执行结果网关缓存待联网后回传日志；混合场景走云端；编辑器明示可用性。
限流与防环：①单场景最短触发间隔3s（手动）/10s（自动）；②单家庭1分钟最多执行60次；③令牌桶超限→抑制并记日志；④保存时构建场景依赖有向图，DFS 检测环路，发现即阻断并给出环路路径；⑤链式执行深度≤3；⑥抖动抑制：高频触发源强制要求持续时间条件（未设置时保存告警）。
冲突检测：同设备同属性被多个场景以不同值设置→保存时提示（不阻断，用户可确认）；提供"冲突优先级"按场景执行顺序与最后写入生效原则说明。
时区与定时：定时按家庭时区（M02）执行；夏令时切换日处理（跳过/顺延规则明示）；日出日落按家庭经纬度每日计算+偏移；跨时区旅行不影响家庭自动化。
数据一致性：设备移除/家庭解散→关联场景标记失效并通知；设备替换提供重映射接口；场景软删除30天可恢复；日志独立保留30天。
性能SLA：场景列表 P99 ≤300ms；保存校验 ≤800ms；手动执行端到端（云）P90 ≤3s、本地 P90 ≤1s；干跑 P99 ≤1s；日志查询 P99 ≤500ms；引擎可用性 99.9%（多实例+故障转移）。
运营与监控看板：场景创建数/活跃场景数、手动执行量与成功率、自动触发量与成功率、部分失败率与Top错误码、抑制率（限流/防环/免打扰分布）、模板应用漏斗与交叉销售转化、抖动风险场景清单；异常（成功率<95%/引擎延迟超标）自动告警SRE。

6.3 场景 DSL 结构（双端契约，M1 冻结）

{
  "version": 3,
  "meta": { "name": "夜间开门亮灯", "icon": "door", "color": "#1976D2", "roomId": "r_01", "tags": ["安防"], "acl": "members" },
  "triggers": {
    "logic": "OR",
    "items": [
      { "type": "device.state", "deviceId": "d_123", "prop": "contact", "from": "close", "to": "open" },
      { "type": "sensor.threshold", "deviceId": "d_456", "metric": "illuminance", "op": "<", "value": 20, "duration": 300 }
    ]
  },
  "conditions": [
    { "type": "time.range", "start": "18:00", "end": "23:59", "tz": "family" },
    { "type": "device.state", "deviceId": "d_789", "prop": "power", "is": "on" }
  ],
  "actions": [
    { "type": "device.control", "deviceId": "d_789", "cmd": "setBrightness", "params": { "value": 60 } },
    { "type": "delay", "seconds": 30 },
    { "type": "notify", "channels": ["app"], "text": "`{deviceName}` 已开启" },
    { "type": "scene.run", "sceneId": "s_002" }
  ],
  "options": { "failPolicy": "continue", "notifyOnFail": false, "localExecutable": true }
}

7. 验收标准核对表

需求	验收标准	本设计落点
FR-1701	双分段列表/筛选/排序/批量/长按六操作闭环；权限隔离；配额与失效提示；首页与语音同步	S01；/scenes 接口族
FR-1702	三段式编排；能力驱动动态表单；五类触发器+五类动作；防环与冲突扫描；乐观锁；草稿	S02；/scenes/validate；capabilities
FR-1703	执行三态反馈；逐动作回执；离线预检；失败策略；重试幂等	S03；/scenes/`{id}`/execute；MQTT回执
FR-1704	五类结果日志可解释；详情四段；干跑不产生真实指令；假设时间；30天清理	S04；/scenes/logs；/dry-run
FR-1705	模板分类/搜索/详情；能力匹配✓✘；角色映射强制；应用可执行；我的模板；交叉销售引导	S05；/scenes/templates 族
FR-1706	双主题/7语种参数化摘要句/无障碍/响应式全达标	第4章；组件清单；句式模板

QA测试要点（专项）：

执行链路真机验证：手动/自动触发→云端与本地两种执行模式→逐动作回执→结果三态；本地联动断网执行验证（拔网线后网关场景仍生效，联网后日志回传）；
触发器矩阵：五类触发器逐一验证（设备状态 from→to 语义、阈值持续时间抗抖、定时重复/日出日落偏移/夏令时切换日、场景链式、告警事件联动M06）；
防环与限流：构造 A→B→A 环路保存被阻断并展示路径；链式深度4层阻断；1分钟60次限流触发抑制并记录；高频抖动源未加持续时间告警；
部分失败注入：单设备离线/指令超时/参数越界/网关不可达四类错误码注入→失败策略（继续/中止）行为正确→重试幂等（重复点击不重复执行）；
干跑安全性：dry-run 全程真机验证设备状态无任何变化（关键安全项）；假设时间模拟定时/时间范围判定正确；
日志完整性：成功/部分失败/失败/跳过/抑制五类均有记录；详情四段（触发快照/条件判定/动作清单/抑制原因）准确；30天清理任务生效；
模板应用：能力匹配✓✘与真实设备一致；角色映射未完成阻断保存；映射多设备批量动作正确；模板更新不影响已应用场景；缺失设备引导M03链路可达；
权限与安全：普通成员无新建/编辑/删除入口且服务端越权请求返回403；动作选择器不出现无权限设备；编辑乐观锁冲突提示；场景不绕过M02设备权限；
并发与一致性：两成员同时编辑同场景→后者冲突提示；执行中编辑场景→事务使用快照版本不受影响；设备移除→场景部分失效徽标+修复入口；
多语言与无障碍：7语种摘要句语法自然（人工评审，重点德/法/俄长文本不截断）；读屏播报三段与日志详情；拖拽提供上移/下移替代；减弱动效生效；深色模式徽标对比度；
性能压测：1000场景家庭规则匹配P99≤50ms；手动执行端到端云端P90≤3s、本地P90≤1s；列表100+项渲染流畅；日志1万条虚拟滚动；
兼容性：iOS 13+/Android 7.0+真机；折叠屏/平板分栏；语音生态（M11）场景名同步与可触发验证。

8. 依赖与风险

项	说明	责任/时点
设备能力模型	scene_trigger/condition/action 能力声明与动态表单 schema——能力驱动编排的基石，缺失将退化为硬编码品类分支	云端+固件 M1 冻结 schema；M2 联调
场景 DSL 契约	三段式 DSL JSON Schema、版本号、校验规则双端共享	M1 技术评审冻结（本文6.3为初稿）
M04 设备控制	动作下发复用设备控制通道与状态回执	M1 已交付；M2 联调
M02 家庭/房间/权限	权限过滤、房间分组、家庭时区与经纬度（日出日落）	M1 已交付
M06 告警通知	"发送通知"动作、失败提醒、告警事件作为触发源	M2 并行联调
M09 OTA	固件能力升级后触发能力变更通知；固件过旧引导升级	M2 联调
M07 传感器校准	阈值触发依赖校准后数据精度；校准变更可能需重核阈值	M2 联调
M11 语音生态	场景注册为语音实体；场景重命名同步	M2/M3 联调
M12 运营后台	模板市场 CMS（上下架/排序/多语言/Banner）	M2 前交付 CMS 最小可用
网关本地联动能力	本地规则下沉协议、缓存容量、断网日志回传——影响"断网可用"承诺	固件团队 M1 评估；不支持则一期全走云端并调整文案
规则引擎选型	自研轻量引擎 vs Drools/Flink CEP；性能、热加载、运维成本权衡	M0 技术评审确定
防环与抖动治理	复杂家庭多场景互相触发风险高；需持续运营监控抑制率与抖动清单	M2 上线后持续调优
定时精度与夏令时	天文算法+时区库准确性；夏令时切换日行为需产品明确定义	M1 产品确认；M2 实现+专项测试
日志存储成本	跳过事件全量记录将放大存储；需采样/关闭策略与成本评估	M1 架构评审

以上为 M08 智能场景联动（FR-1701~1706）完整详细需求设计：三段式编排（IF/AND/THEN）、能力驱动动态表单、五类触发器与五类动作、执行事务与部分失败重试、可解释日志与干跑调试、模板市场与角色映射、防环限流与本地联动降级均已落点；与 M01/M02/M03/M04/M06/M07/M09/M10/M11/M12 文档格式及衔接协议一致（能力模型同源、MQTT复用、权限联动、通知复用），可直接交付 UI 与开发。如确认无误，可按同样格式继续输出后续模块（如 M09 OTA升级、M10 帮助中心与工单、M11 语音生态接入、M12 运营后台等）。

M08 智能场景联动（对应需求：FR-1701~1706）​

1. 模块概述与设计原则​

1.1 模块范围​

1.2 设计原则​

1.3 用户与前置条件​

2. 页面结构与流程图​

2.1 页面导航结构​

2.2 核心状态机一：场景（自动化）生命周期​

2.3 核心状态机二：场景执行事务（云端/网关-设备）​

3. 页面级详细需求​

S01 场景管理中心（FR-1701）​

S02 场景编辑器（FR-1702）​

S03 场景执行反馈与部分失败处理（FR-1703）​

S04 自动化日志与调试页（FR-1704）​

S05 场景模板市场（FR-1705）​

4. 通用交互与视觉规范（UI设计输入，FR-1706）​

5. 客户端技术要求（Flutter）​

6. 云端需求（场景规则引擎服务）​

6.1 接口清单​

6.2 关键策略​

6.3 场景 DSL 结构（双端契约，M1 冻结）​

7. 验收标准核对表​

8. 依赖与风险​

M08 智能场景联动（对应需求：FR-1701~1706）

1. 模块概述与设计原则

1.1 模块范围

1.2 设计原则

1.3 用户与前置条件

2. 页面结构与流程图

2.1 页面导航结构

2.2 核心状态机一：场景（自动化）生命周期

2.3 核心状态机二：场景执行事务（云端/网关-设备）

3. 页面级详细需求

S01 场景管理中心（FR-1701）

S02 场景编辑器（FR-1702）

S03 场景执行反馈与部分失败处理（FR-1703）

S04 自动化日志与调试页（FR-1704）

S05 场景模板市场（FR-1705）

4. 通用交互与视觉规范（UI设计输入，FR-1706）

5. 客户端技术要求（Flutter）

6. 云端需求（场景规则引擎服务）

6.1 接口清单

6.2 关键策略

6.3 场景 DSL 结构（双端契约，M1 冻结）

7. 验收标准核对表

8. 依赖与风险