10 KiB
Sense 原型评审 → IX 条目草稿
来源：
yovision-T-004/docs/design/sense/index.html（codex，2026-08-04） 用途：补齐原型枚举缺口对应的交互清单条目，供并入docs/08-interaction-checklist.md写入约束：T-004 的write_paths只含docs/tasks/T-004.md、docs/design/sense/index.html、docs/design/bell/index.html，且唯一写入者为 codex。本文件是草稿输入，由 08 文件的所有者合入，不要由本会话直接改那个 worktree。 状态：全部条目标【待确认】，按docs/design/README.md工作流第 5 步逐条人工确认。
0. 先纠正一条
原评审列的「128 路列表缺分页」不需要新条目——IX-003 已覆盖「分页/筛选/批量选择；128 路不一次加载所有视频和详情」。那是原型漏画，回原型补即可，清单无需改动。
因此新增 5 条（IX-014 ~ IX-018），另有 2 处全局章节需要收紧。
1. 新增条目（可直接贴入主表）
| IX-014 | 设备模态与准入 | 设备台账按 modality（video/radar/contact/button/wearable）建模；列表、筛选、添加流程不得以"摄像头"为唯一形态；非成像设备无画面、无 Profile、无分片，其详情页不展示视频相关页签 | US-001 | M2/M6 |
| IX-015 | 停用与踢流 | 停用需展示影响范围（是否中断在途会话、是否影响推理）并二次确认；停用后期望态与实际态分别收敛，实际态不得立即伪装为"已停止"；重新启用为幂等操作 | US-001、US-002 | M2 |
| IX-016 | 隐私区域设备准入 | 标记为隐私区域的位置只接受非成像模态；选择该位置时成像类设备不可选并说明原因；越过前端的写请求由后端拒绝并回显同一措辞 | US-006 | M2 |
| IX-017 | 检测区域几何编辑 | 多边形与方向警戒线的绘制、撤销、清空、闭合；警戒线必须渲染方向箭头；键盘坐标输入与鼠标绘制等效；画面参数变化后既有区域标记为待校准且不静默失效 | US-005 | M3 |
| IX-018 | 草稿与跨系统上下文 | 存在未保存几何草稿时，离开页面（导航、面包屑、切换绘制工具、跳转 Bell）必须拦截并确认；Sense↔Bell 深链双向携带摄像头与区域上下文，返回后草稿不丢失 | US-005 | M3 |
2. P0 条目详情展开
IX-014 设备模态与准入
为什么是 P0：原型把「摄像头」写进了导航名、表名、添加对话框标题和协议下拉（只有 ONVIF/RTSP）。《08-三系统职责划分》§1.1 已定 devices 含 modality，且隐私区域约束现在按模态判定。信息架构一旦以摄像头为唯一形态定稿，接入雷达时是整页重做而非加字段——这与事件契约 v0.1 在 2026-08-03 因同一假设被迫原地修订是同构问题。
| 项 | 约定 |
|---|---|
| 取值 | video / radar / contact / button / wearable / other |
| 列表 | 模态是可筛选维度；设备图标按模态区分，不复用摄像头图标 |
| 添加流程 | 先选模态，再按模态渲染字段。radar/contact 无 Profile、无码流、无分片绑定 |
| 详情页 | 非成像模态不展示「画面与检测区域」「流与健康」页签，而非展示为禁用 |
| 命名 | 一级导航不叫「摄像头」。建议「设备」，摄像头作为模态筛选项 |
| 阶段 | 建模与命名在 M2 落地；雷达等真实接入在 M6。建模不能等到 M6 |
状态覆盖：模态不支持该操作 / 模态与站点策略冲突 / 老数据无 modality 的迁移默认值。
IX-015 停用与踢流
为什么是 P0：原型的「期望态」列有"停用"这个值，但没有停用动作，也没有任何关于"停用会不会踢掉正在观看的流"的表达。这是 Sense 最有运维后果的行为，且《03》§2.1 定义了四种粒度（卸载推理源 / 踢会话 / 鉴权回调 401 + 踢流 / DELETE path），标准组合是先踢再拒。原型不画，IX 就不会生成，实现时会退化成一个静默的布尔开关。
| 项 | 约定 |
|---|---|
| 确认前必须说明 | 是否中断当前在途会话、是否影响正在运行的推理、是否影响录制与证据回捞 |
| 期望态与实际态 | 点击停用后期望态立即变更，实际态由对账器收敛；实际态不得立即显示"已停止" |
| 收敛可见 | 停用中的设备计入「待收敛项」，收敛超时有明确提示 |
| 幂等 | 重复停用/启用不产生副作用，不生成重复审计条目 |
| 批量 | 批量停用逐项结果可见，部分失败可重试 |
状态覆盖：正在被其他人观看时停用 / 对账器不可达时停用 / 停用后又被上游策略重新启用。
IX-016 隐私区域设备准入
为什么是 P0：这是代码级硬约束（《01》RQ-S1-05、《02》NFR-CMP-05、《03》§3.2）。原型的「区域」下拉只是普通选项，没有任何拒绝路径。合规约束在 UI 上不可见时，实现者不会知道它存在。
| 项 | 约定 |
|---|---|
| 判定依据 | 按 modality 判定，不按设备类型名判定。privacy_flag = true 的位置允许 radar/contact/button/wearable，拒绝 video |
| 前端 | 成像模态在隐私位置不可选，并就地说明原因，而非提交后报错 |
| 后端 | 绕过前端的写请求必须拒绝，措辞与前端一致 |
| 位置属性变更 | 已有成像设备的位置被改标为隐私区域时，必须走显式处置流程，不允许静默留存 |
状态覆盖：位置属性读取失败时默认按最严处理（拒绝成像）。
IX-017 检测区域几何编辑
为什么是 P0：原型的草稿层（drawDraft）把警戒线画成无向线段，但方向是警戒线唯一的语义——越线方向决定是否触发。静态示例 SVG 里画了箭头，草稿里没有，说明这是实现遗漏而非设计取舍。
| 项 | 约定 |
|---|---|
| 方向 | 警戒线草稿与已保存态都必须渲染方向箭头；提供反转方向的操作 |
| 最小点数 | 多边形 ≥3，警戒线 =2；不足时保存被拒并说明 |
| 闭合交互 | 双击闭合不得先追加顶点（原型 534–535 行：dblclick 前两次 click 会多加 2 个点） |
| 键盘等效 | 坐标输入（0–100%）与鼠标绘制完全等效，含撤销与删除单点 |
| 待校准 | 画面分辨率/旋转变化后既有区域标记为待校准，不静默失效也不自动改坐标 |
| 版本 | 区域版本与告警规则版本是不同对象；保存区域不发布规则 |
IX-018 草稿与跨系统上下文
为什么是 P0：T-004 任务书自己写明"后端系统边界不得迫使用户丢失当前摄像头或规则草稿上下文"。实测原型有三条路径会静默丢弃草稿：面包屑返回（502 行）、侧栏导航（493 行）、切换绘制工具（536 行 points.length = 0）。而 clearPoints 与 discardDraft 都有 confirm——同一类破坏性操作，三处有确认、三处没有。
| 项 | 约定 |
|---|---|
| 拦截范围 | 页内导航、面包屑、切换绘制工具、跳转 Bell、关闭标签页 |
| 一致性 | 所有丢弃草稿的路径使用同一个确认组件与措辞 |
| 深链 | Sense→Bell 与 Bell→Sense 双向携带 camera + zone；原型目前只有 Bell→Sense 带 return 参数，反向缺失 |
| 返回 | 从 Bell 返回后草稿仍在；若期间区域被他人保存，提示冲突而非覆盖 |
3. 全局章节需要收紧的两处
3.1 「无障碍与安全」——把对比度写成可验证的数字
现文：「文本和关键状态满足可读对比度」。建议改为：
- 正文与关键状态对比度 ≥ 4.5:1，大字号（≥18.66px 粗体或 ≥24px）≥ 3:1；**主操作按钮同样受此约束**。
实测依据（对原型配色计算，非估计）：
| 用途 | 前景/背景 | 实测 | 判定 |
|---|---|---|---|
.btn-primary 主 CTA |
#ffffff / #0ea5e9 |
2.77:1 | ❌ 深浅两个主题都不过（浅色主题未覆盖 --primary-strong） |
浅色主题 --subtle |
#718096 / #ffffff |
4.02:1 | ❌ 用于 .nav-label、搜索图标 |
| 其余抽查 6 项 | — | 4.6–16.3:1 | ✅ |
主按钮那条影响最大：「添加摄像头」「保存区域版本」「保存为待激活」全是它。修法是把 --primary-strong 压到 #0369a1 一带（≈5.9:1），或主按钮改深底浅字。
3.2 「无障碍与安全」——补三条可测项
原型实测出的问题，与其修原型不如钉进清单（生产要重写）：
- 当前导航项使用 `aria-current="page"`；不得用空值属性表达（空串等于 false）。
- 图标按钮在任何断点下都必须保留可访问名；隐藏文字标签时须提供 aria-label。
- 采用 tab 模式时必须完整：`role="tabpanel"` + `aria-controls` 关联 + 方向键导航，不做半套。
对应原型位置：aria-current 见 489 行 toggleAttribute；图标按钮见 236 行 ≤1180px 隐藏 .nav span；tab 半套见 372–377 与 503–507 行。
4. 不进清单、但要回原型补的
| # | 内容 | 处理 |
|---|---|---|
| 1 | 设备列表分页控件 | IX-003 已覆盖，仅原型漏画 |
| 2 | 「推理绑定 16/16」画成 100% 满格紫条 | 正常态显示成满载，易误读为告警。换表现，不进清单 |
| 3 | 分片容量 8/32 的 32 无出处 |
《08》只定义站点 16 默认 / 128 上限，未定义单分片容量。要么把 media_shard.max_streams 补进《08》§3，要么原型改用文档里的数——两个分片 ×32 = 64，与站点上限 128 也对不齐 |
5. 建议的落地顺序
- IX-014（模态）先定——它影响导航命名与表结构，建议整页重生成原型而非打补丁
- IX-015 / IX-016 补进原型（停用动作 + 隐私区域拒绝态），二者都只是加控件与一个拒绝态
- IX-017 / IX-018 可以只写清单不改原型——都是行为约定，生产实现时按清单做
- §3 两处全局收紧直接合入
- §4 第 3 条的分片容量需要一个数字决定，然后同步《08》