产品需求文档：故障管理（按用户流程）

UF-001：进入故障管理并查看故障设备清单

描述： 作为运维人员，我希望进入故障管理页面后看到所有当前处于故障状态的设备。

主流程：

1. 用户从侧边栏点击「故障列表」，进入故障管理页。
2. 页面标题展示「故障管理」，副标题「故障设备清单与远程处置」。
3. 清单展示状态为「故障」且当前账号有权限访问的设备。
4. 清单右上角显示「故障设备 N 台」徽章。

验收标准：

• 页面标题为「故障管理」，副标题为「故障设备清单与远程处置」。
• 页头右上角提供「返回设备页」按钮。
• 清单只展示设备状态等于「故障」的条目；非故障设备不进入此清单。
• 清单只展示当前账号有权限访问的故障设备（由 canAccessFaultDevice(deviceId) 判断）。
• 「故障设备 N 台」徽章按当前筛选下的清单数量实时刷新。
• 桌面端表格列序：设备编号 → 设备地址 → 故障内容 → 故障发生时间 → 操作。

参考截图：

UF-002：按设备编号或点位名称筛选故障清单

描述： 作为运维人员，我希望能按设备编号或点位名称筛选清单。

主流程：

1. 用户点击顶部「设备：全部」触发框。
2. 系统展开筛选下拉：搜索框 +「全选设备」开关 + 全部可见故障设备候选项。
3. 用户在搜索框输入关键字。
4. 下拉候选项按关键字过滤；用户勾选目标设备。
5. 清单和右上角徽章按筛选结果刷新。

验收标准：

• 搜索框 placeholder 为「搜索设备编号或点位名称」。
• 搜索同时匹配设备编号、点位名称、显示用的组合标签；大小写不敏感。
• 下拉提供「全选设备」复选框，可一键全选 / 全清。
• 每个候选项的显示文案为「点位名称 · 设备编号」组合。
• 搜索无结果时显示一个禁用的「无匹配设备」占位项。
• 搜索框按下回车时，自动选中当前过滤结果的第一项并关闭下拉。
• 触发框文案随选择状态变化：全选 = 「设备：全部」；未选 = 「设备：未选择」；选 1-2 台 = 「设备：编号1、编号2」；选 3 台及以上 = 「设备：已选 N 台」。

参考截图：

UF-003：在清单中阅读故障描述和首处理建议

描述： 作为运维人员，我希望故障内容列同时给出故障描述和首处理建议，这样我不展开行就能判断是否需要立即处理。

主流程：

1. 用户在清单中扫读故障内容列。
2. 第一行展示故障描述，格式为「部件 · 现象」（例如「咖啡机 · 未检测到 SD 卡」）。
3. 第二行展示首条处理建议，前面带 ⏱ 图标。
4. 若处理建议多于 1 步，右侧出现「查看全部 N 步」可点击文本。
5. 故障发生时间显示在独立列。

验收标准：

• 故障描述优先从故障库 CofeFaultLibrary.getFaultForDevice(deviceId).description 取，使用「部件 · 现象」的形式。
• 故障库无匹配时，回落到 orgStatus 异常部件名 + 「故障 / 失联」，用中文「，」连接（例如「咖啡机失联，机械臂故障」）。
• 仍无匹配时，使用「{设备编号} 设备异常」作为最终兜底文案。
• 故障描述文字使用警示色（深橙）显示。
• 有处理建议时，第二行展示首条建议，前缀带 ⏱ 图标；处理建议为空时显示「暂无处理建议,请联系运维」灰色提示。
• 仅在处理建议多于 1 步时显示「查看全部 N 步」入口；恰好 1 步时不显示。
• 故障发生时间使用「YYYY-MM-DD HH:mm:ss」固定格式。

UF-004：展开一行查看完整处理步骤

描述： 作为运维人员，遇到需要逐步排查的故障，我希望能展开行查看完整的处理步骤列表。

主流程：

1. 用户在桌面表格中点击某行（除「操作」列外的任意位置）或点击「查看全部 N 步」。
2. 系统将该行切换为展开状态，下方出现「如何处理 · 完整步骤」标题和有序步骤列表。
3. 同时「查看全部 N 步」右侧的 ▾ 图标变为 ▴，提示当前已展开。
4. 用户再次点击行 / 「查看全部 N 步」可收起。

验收标准：

• 展开 / 收起逻辑由 toggleFaultRowExpand(deviceId) 统一处理，给目标行切换 is-expanded class。
• 展开后下方区域 .fault-row-detail 显示「如何处理 · 完整步骤」标题和有序列表（1. ... 2. ... 3. ...）。
• 「查看全部 N 步」点击事件需要 event.stopPropagation()，避免和整行点击叠加成"展开再立刻收起"。
• 整行也可触发展开（.fault-row-summary 是 role="button"），但点「操作」列不能触发展开。
• 无处理步骤的故障（暂无建议）不渲染「查看全部」入口。

参考截图：

UF-005：核对故障通知邮箱

描述： 作为运维人员，我希望在清单上直接看到这台设备的故障通知会推给哪个邮箱，这样我能确认告警链路是否生效。

主流程：

1. 用户在清单中扫读设备地址列。
2. 设备地址下方紧贴一个邮箱徽章，反映该设备所属商户配置的通知邮箱。
3. 已配置时徽章显示「✉️ 推送至 邮箱地址」；未配置时显示「✉️ 未配置通知邮箱」并使用更弱的灰色。

验收标准：

• 邮箱来源链路：故障设备 → 所属商户 → customers 列表中匹配 customerId 的 notifyEmail 字段。
• 已配置邮箱：徽章文案「✉️ 推送至 {email}」，title 提示「故障通知将发送至该邮箱」。
• 未配置邮箱：徽章使用 fault-notify-email-empty 样式（灰色），文案「✉️ 未配置通知邮箱」，title 提示「该商户尚未配置故障通知邮箱」。
• 徽章本身不可点击编辑邮箱；要修改通知邮箱需到客户管理模块。

UF-006：唤起远程操作面板并下发指令

描述： 作为运维人员，我希望对某台故障设备发起远程指令时，所有可用动作集中在同一个面板里。

主流程：

1. 用户在故障清单中点击某台设备行末的「远程操作」按钮。
2. 系统弹出「远程操作 · 设备编号」面板，列出四个动作按钮。
3. 用户点击其中一个动作。
4. 系统关闭面板，并通过浏览器 alert 弹窗反馈「已向设备 X 下发指令：Y」。

验收标准：

• 面板标题携带目标设备编号，例如「远程操作 · RCK386」（桌面端居中对话框 fault-desktop-dialog）。
• 面板四个动作按钮固定顺序：机构重启 → 设备开门 → 设备停售 → 音量调节。
• 点击任一动作后，面板关闭并通过 alert 反馈下发指令的设备编号与动作名称。
• 点击面板背景遮罩（fault-sheet-backdrop）可关闭面板。
• 当前账号对该故障设备无访问权限时，openRemoteActions 直接 return，面板不弹出。

参考截图：

UF-007：移动端查看故障清单并发起远程操作

描述： 作为巡店 / 值班人员，我希望在手机上也能完整完成查看故障 → 发起远程指令的闭环。

主流程：

1. 用户在手机打开故障管理页面。
2. 页面以单列卡片展示每台故障设备，含设备编号、设备地址、通知邮箱徽章、故障内容、首处理建议、故障发生时间。
3. 每张卡片底部固定「远程操作」按钮。
4. 用户点击按钮唤起远程操作面板（同 UF-006，移动端使用底部抽屉 fault-sheet-panel，无标题）。
5. 用户选择动作；系统关闭面板并 alert 反馈。

验收标准：

• 移动端使用单列卡片，每张卡片在桌面表格四个字段（编号 / 地址 / 故障内容 / 发生时间）之上再加底部「远程操作」按钮。
• 设备地址下方仍展示通知邮箱徽章。
• 「远程操作」按钮在卡片底部全宽展示。
• 移动端的远程操作面板使用底部抽屉样式（fault-sheet-panel），不显示「远程操作 · 设备编号」标题。
• 桌面端 / 移动端的切换由 isDesktopInteractionMode()（window.innerWidth ≥ 1024）决定。

参考截图：