# 交互清单

> 当前为交互契约草案。P0 页面开工前需在 `docs/design/` 生成单文件 HTML 原型，并由产品确认；原型只负责结构，本文负责行为和状态。

| ID | 场景 | 必须覆盖的状态与行为 | 关联 US | 阶段 |
| --- | --- | --- | --- | --- |
| IX-001 | 批量导入设备 | 下载模板、上传校验、逐行错误、重复序列号、待激活、确认写入 | US-001 | M2 |
| IX-002 | 配额与批量结果 | 显示已用/上限；超 16 不等于非法，按站点配置校验；部分成功可重试 | US-001 | M2 |
| IX-003 | 设备列表 | 分页/筛选/批量选择；128 路不一次加载所有视频和详情 | US-001 | M2/M4 |
| IX-004 | 设备健康 | 期望态、实际态、最后在线、时间漂移、分片、重试进度；运维告警独立 | US-002 | M2/M4 |
| IX-005 | 预警到达 | 明确严重度、站点、时间、证据可用性；重复投递不产生重复处置 | US-003 | M3 |
| IX-006 | ack | 一次点击可确认，显示确认人/时间；并发 ack 有清晰结果 | US-003 | M3 |
| IX-007 | 升级 | 显示当前层级、下一次升级时间、每次投递状态；失败不能伪装成功 | US-003 | M3 |
| IX-008 | 事件详情 | 结构化事实、抓拍、视频、时间线、处置；证据加载失败可重试且不丢元数据 | US-003 | M3/M4 |
| IX-009 | 误报反馈 | 确认动作、可选原因、提交成功反馈；只改变 outcome，不改原始事件 | US-004 | M3 |
| IX-010 | 规则编辑 | 显示租户/站点/设备继承来源，支持区域/警戒线/时段/持续时间 | US-005 | M3/M4 |
| IX-011 | 规则试运行 | 明确“未正式生效”，展示命中样本与影响范围，支持取消/回滚 | US-005 | M4 |
| IX-012 | 升级链/静默 | 联系人顺序、超时、双通道；静默最长 4h、显示自动恢复时间、无永久选项 | US-005 | M3/M4 |
| IX-013 | 权限与隐私 | 越权统一处理；无授权租户不展示人脸入口；不泄露流 URL/凭据 | US-006 | M3/M4 |
| IX-014 | 设备模态与能力 | 一级入口为“设备”；列表可按 `modality` 筛选，添加时先选模态，详情按 `capabilities` 渐进展示；视频设备显示画面/媒体/检测区域，非视频设备保留连接与健康并显示对应遥测，不用禁用的视频页签占位 | US-008 | M2/M6 |
| IX-015 | 停用与收敛 | 明确区分暂停推理、停用设备接入和仅踢当前会话；操作前展示对观看、推理、录制与证据回捞的影响并二次确认；期望态立即改变、实际态经对账收敛，部分失败可逐项重试；重复请求不产生重复副作用，但每次请求均留审计结果 | US-001、US-002 | M2 |
| IX-016 | 隐私区域设备准入 | `capture_policy = non_imaging_only` 的 Area 不允许新增/启用具有成像能力的设备；前端就地禁用并解释，后端返回稳定错误码；策略读取失败时拒绝新变更并告警，已有设备遇到区域策略变化时进入显式处置流程，不静默留存或停用 | US-008 | M2/M6 |
| IX-017 | 检测区域几何编辑 | 多边形和方向警戒线支持绘制、显式完成、撤销、清空、顶点编辑；警戒线在草稿/已保存态均显示方向箭头并可反转；鼠标与键盘坐标操作等效；画面参数变化后标记待校准且不自动改坐标；区域版本与规则版本独立 | US-005 | M3 |
| IX-018 | 草稿与跨系统上下文 | 几何草稿自动保存并可恢复；只有持久化失败或切换空间类型等会破坏草稿的动作才拦截确认；Sense↔Bell 双向携带并消费 `camera + zone + return_to` 上下文；返回后恢复草稿，版本已被他人更新时提示冲突且不覆盖 | US-005 | M3 |

## 全局状态

每个页面/组件至少评估：

- 初始、加载、空数据、成功、部分成功、可重试失败、不可重试失败。
- 无权限、会话过期、网络断开、后端超时、数据已被他人修改。
- 长任务的进度、取消、后台继续和结果通知。
- 批量任务的逐项结果、幂等重试和导出错误清单。

## 桌面与大屏

- 默认 16 路视图不得演变为 16 个同时自动播放的主码流。
- 64/128 路使用分页、虚拟列表、缩略图按需加载和明确并发预览上限。
- 值班台的高优先级预警必须可键盘操作，声音/颜色不能成为唯一提示。
- 地图/平面图与列表能相互定位，但点位缺失时仍可从列表处置。

## App

- push 只作为唤醒入口，最终状态从服务端读取；重复 push 不重复创建处置。
- ack 和一键呼叫必须防误触但不能藏得太深。
- 弱网下先显示结构化事件，再渐进加载抓拍/视频。
- 家属只看到自己的站点和事件证据，不提供常态监控入口。

## 无障碍与安全

- 键盘可完成主要 Web 流程，焦点清晰，表单错误关联到字段。
- 正文、按钮文字和关键状态对比度不低于 4.5:1；大字号（不低于 24px，或不低于 18.66px 且粗体）不低于 3:1；非文本控件、状态边界与焦点指示器不低于 3:1。严重度同时用文字/图标表达。
- 当前导航项显式使用 `aria-current="page"`；响应式隐藏可见文字时，图标按钮仍保留稳定的可访问名。
- 使用 tab 模式时完整实现 `tablist` / `tab` / `tabpanel`、`aria-controls` / `aria-labelledby`、单一 Tab 停靠点和方向键导航；不能完整实现时不声明 tab 角色。
- 移动端主要操作目标不小于 44×44px，输入控件正文不小于 16px；绘制画布必须提供无需精确点击的键盘/表单等效路径。
- 删除、停用、踢流、批量覆盖和规则正式发布需要明确影响范围与二次确认。
- UI 不展示摄像头密码、完整连接串、token 或可复用的内部流地址。

## 证据要求

UI 任务完成时在任务文件记录：关联 US/IX、原型路径、自动化测试、关键状态截图/录屏、无障碍检查和人工验收人。未完成的必需人工验收不得标 DONE。