149 lines
9.5 KiB
Markdown
149 lines
9.5 KiB
Markdown
# Sense 原型评审 → IX 修订稿
|
||
|
||
> 评审对象：`docs/design/sense/index.html`（T-004）
|
||
> 初始输入：Claude 评审草稿，2026-08-04
|
||
> 复核：Codex 从产品、全栈架构与 UI/UX 角度对照《02》《03》《08-三系统职责划分》、US/IX 和当前原型核验
|
||
> 状态：项目负责人已确认按本修订稿继续；最终行为已同步到 `docs/08-interaction-checklist.md`
|
||
> 后续：第二轮缺口复核与最终 IA 见 `11-Sense原型-第二轮缺口.md`、`12-Sense原型-待办清单.md`；若与本文原型范围冲突，以第二轮修订为准
|
||
|
||
---
|
||
|
||
## 1. 评审结论
|
||
|
||
初始评审指出的五类缺口方向成立：设备模态、停用收敛、隐私准入、检测区域几何编辑、草稿与跨系统上下文都需要进入正式交互清单。但原稿不能直接合入，原因有三类：
|
||
|
||
1. 部分证据与当前代码不一致：Sense 页内导航不会清空几何点，Sense→Bell 已携带 `camera + zone`，单媒体分片 32 路已有架构来源。
|
||
2. 部分方案把后端字段直接等同产品能力：非视频设备仍需要连接与健康，隐私准入不能只看显示名称或单一模态。
|
||
3. 部分行为不符合审计和草稿体验：幂等不等于不记审计，避免丢草稿应优先自动保存，而不是每次导航都弹确认。
|
||
|
||
原产品边界保持不变：
|
||
|
||
- Sense 管设备接入、健康、媒体与设备空间配置。
|
||
- 视频设备的检测区域继续位于设备详情，不恢复一级“区域规则”。
|
||
- Bell 管场景、继承、时段、持续时间、试运行、发布和升级链。
|
||
- 两个系统通过稳定深链和可恢复草稿保持连续体验。
|
||
|
||
---
|
||
|
||
## 2. 最终新增 IX
|
||
|
||
| ID | 场景 | 最终约定 | 关联 US | 阶段 |
|
||
| --- | --- | --- | --- | --- |
|
||
| 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 |
|
||
|
||
`IX-003` 已覆盖设备列表分页/筛选/批量选择和 128 路按需加载，因此分页属于原型漏画，不新增 IX。
|
||
|
||
---
|
||
|
||
## 3. 关键设计修订
|
||
|
||
### 3.1 设备使用 `modality + capabilities`
|
||
|
||
`modality` 用于稳定分类：video / radar / contact / button / wearable / other。`capabilities` 决定字段、页签和动作，例如：
|
||
|
||
- `captures_image`
|
||
- `media_stream`
|
||
- `telemetry`
|
||
- `battery`
|
||
- `spatial_config`
|
||
- `directional_line`
|
||
|
||
M2 的一级导航与台账统一使用“设备”，默认筛选视频设备；M1～M5 只完整实现 video 适配器。M6 增加非视频协议适配器，不重新设计根实体与页面层级。
|
||
|
||
非视频设备不展示画面、Profile 和媒体分片，但仍展示“连接与健康”，并根据能力显示最后上报、信号质量、电量、遥测或传感器校准。
|
||
|
||
### 3.2 隐私策略属于 Area
|
||
|
||
隐私是物理位置的准入策略，不是设备已经创建后的标签。统一模型为：
|
||
|
||
```text
|
||
Area.capture_policy = video_allowed | non_imaging_only
|
||
Device.modality
|
||
Device.capabilities.captures_image
|
||
```
|
||
|
||
Sense 在新增/启用写路径执行校验。后端返回稳定错误码，前端负责本地化说明。策略不可读取时对新成像变更 fail closed 并告警；已有链路保持当前状态并进入待处置/未收敛列表，不能因一次依赖失败被静默切断。
|
||
|
||
### 3.3 停用动作不能混为一个开关
|
||
|
||
| 用户动作 | 期望效果 |
|
||
| --- | --- |
|
||
| 暂停推理 | 卸载推理 source；接入和授权观看按策略保留 |
|
||
| 停用设备接入 | 踢当前发布会话、拒绝后续发布、卸载推理；期望态先变，实际态由对账收敛 |
|
||
| 仅踢当前会话 | 运维诊断动作；客户端可能重连，不改变持久期望态 |
|
||
|
||
每种动作展示独立影响范围。重复请求不得生成重复资源变更或状态副作用，但所有操作尝试都应进入审计并标明“已处于目标状态”或实际结果。
|
||
|
||
### 3.4 几何编辑提供显式完成与等效操作
|
||
|
||
- 多边形至少 3 点，方向警戒线恰好 2 点。
|
||
- 双击可作为快捷方式，但必须有可见的“完成绘制”按钮；双击事件不得额外追加顶点。
|
||
- 警戒线草稿和保存态都渲染方向箭头，并提供“反转方向”。
|
||
- 顶点列表支持添加、编辑、删除、撤销，键盘与鼠标结果等效。
|
||
- 画面分辨率或旋转变化后标记待校准，不自动修改坐标，也不自动发布 Bell 规则。
|
||
|
||
### 3.5 草稿优先自动保存
|
||
|
||
页内导航不应反复打断用户。几何草稿在本地/服务端自动保存并显示状态；只有自动保存失败、切换不兼容空间类型或明确放弃草稿时才确认。关闭标签页使用平台允许的离开保护作为兜底，不能把它当主保存机制。
|
||
|
||
深链统一携带并消费：
|
||
|
||
```text
|
||
camera=<stable-device-id>
|
||
zone=<zone-id>
|
||
return_to=<trusted-route-token>
|
||
```
|
||
|
||
`return_to` 只能使用受信路由 token，不能接受任意外部 URL。保存时使用区域版本做乐观并发校验；发现他人已保存新版本时提示重新加载或另存草稿，不覆盖。
|
||
|
||
---
|
||
|
||
## 4. 对初始评审事实的纠正
|
||
|
||
| 初始判断 | 核验结果 | 最终处理 |
|
||
| --- | --- | --- |
|
||
| 128 路列表缺分页需要新 IX | `IX-003` 已覆盖 | 只补原型分页 |
|
||
| 单媒体分片 32 路无出处 | 《03》§4.2 已定义 `media_shard_max_streams: 32`，128 路建议 4 个 32 路分片 | 保留 32；原型标明当前启用数与可扩展上限 |
|
||
| 侧栏/面包屑会清空草稿 | 当前 `switchView()` 不清空 `points` | 不作为现状缺陷；仍要求跨刷新/跨系统恢复 |
|
||
| Sense→Bell 缺少 camera/zone | Sense 已发送两者，但 Bell 未消费 `zone`；Bell→Sense 缺 `zone` | 修复双方生成与消费 |
|
||
| 非视频设备不展示健康页签 | 非视频设备仍有连接、上报、信号、电量与故障状态 | 使用通用“连接与健康”，能力驱动内容 |
|
||
| 幂等操作不生成重复审计 | 不符合审计目标 | 幂等只约束副作用，每次请求保留审计结果 |
|
||
|
||
---
|
||
|
||
## 5. 无障碍与安全收紧
|
||
|
||
- 正文、按钮文字和关键状态对比度不低于 4.5:1；大字号不低于 3:1；非文本控件、状态边界和焦点指示器不低于 3:1。
|
||
- 当前导航显式设置 `aria-current="page"`，不能用空值属性表示当前页。
|
||
- 响应式隐藏可见文字时，按钮仍保留 `aria-label` 等稳定可访问名。
|
||
- Tab 必须完整实现 `tablist` / `tab` / `tabpanel`、关联属性、单一 Tab 停靠点与方向键；否则不声明 tab 角色。
|
||
- 移动端主要操作目标不小于 44×44px，输入正文不小于 16px；几何绘制提供不依赖精确点击的表单等效路径。
|
||
|
||
---
|
||
|
||
## 6. 原型落地范围
|
||
|
||
Sense 原型重新生成并覆盖：
|
||
|
||
1. 一级“设备”入口、模态筛选、分页和视频/雷达示例。
|
||
2. 能力驱动详情：视频显示画面与检测区域，雷达显示遥测，二者都有连接与健康。
|
||
3. 添加设备先选模态，隐私 Area 对成像设备就地拒绝。
|
||
4. 暂停推理、停用接入、踢当前会话的独立影响确认与期望/实际收敛反馈。
|
||
5. 显式完成绘制、方向箭头/反转、顶点编辑、自动草稿与冲突状态。
|
||
6. Sense/Bell 双向 `camera + zone + return_to` 深链。
|
||
7. 对比度、可访问名、完整 Tab 模式、44px 移动触控目标。
|
||
|
||
Bell 原型只调整深链消费和返回上下文，不改变“规则业务归 Bell、空间几何归 Sense”的产品边界。
|
||
|
||
---
|
||
|
||
## 7. 后续兼容债务（不在本原型任务改契约）
|
||
|
||
事件 v0.1 的 schema 描述与契约 README 仍使用 `privacy_flag` 表示区域是否允许视频模态，而本次领域模型已收敛为 Area 的 `capture_policy`。两者当前语义可一一映射：`privacy_flag = true` 等价于 `capture_policy = non_imaging_only`，但不能长期保留两套真相源。
|
||
|
||
M2 开始 schema/API 实现前应单独建立契约任务，选择“保持 v0.1 线格式并在投影层兼容”或“按版本治理规则新增字段/版本”，同步《06》与 `docs/raw/contracts/` 后再写代码。T-004 只更新产品与架构决策，不修改已经声明为既有契约的 event v0.1。
|