151 lines
10 KiB
Markdown
151 lines
10 KiB
Markdown
# 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. 新增条目（可直接贴入主表）
|
||
|
||
```markdown
|
||
| 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 「无障碍与安全」——把对比度写成可验证的数字
|
||
|
||
现文：「文本和关键状态满足可读对比度」。建议改为：
|
||
|
||
```markdown
|
||
- 正文与关键状态对比度 ≥ 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 「无障碍与安全」——补三条可测项
|
||
|
||
原型实测出的问题，与其修原型不如钉进清单（生产要重写）：
|
||
|
||
```markdown
|
||
- 当前导航项使用 `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. 建议的落地顺序
|
||
|
||
1. IX-014（模态）先定——它影响导航命名与表结构，**建议整页重生成原型而非打补丁**
|
||
2. IX-015 / IX-016 补进原型（停用动作 + 隐私区域拒绝态），二者都只是加控件与一个拒绝态
|
||
3. IX-017 / IX-018 可以只写清单不改原型——都是行为约定，生产实现时按清单做
|
||
4. §3 两处全局收紧直接合入
|
||
5. §4 第 3 条的分片容量需要一个数字决定，然后同步《08》
|