docs(design): close Sense second-review gaps
Harness governance / validate (push) Has been cancelled
Harness governance / validate (pull_request) Has been cancelled

This commit is contained in:
QiuSW
2026-08-04 11:08:41 +08:00
parent e18a1ea83b
commit e0b0bfafeb
13 changed files with 576 additions and 687 deletions
+19 -7
View File
@@ -14,6 +14,8 @@ write_paths:
- docs/design/sense/index.html
- docs/design/bell/index.html
- docs/raw/09-Sense原型评审-IX草稿.md
- docs/raw/11-Sense原型-第二轮缺口.md
- docs/raw/12-Sense原型-待办清单.md
- docs/08-interaction-checklist.md
- docs/07-user-stories.md
- docs/02-requirements.md
@@ -31,31 +33,32 @@ Sense 与 Bell 尚无可供产品确认的页面结构。生产 UI 开工前,
## 关联需求与交互(如适用)
- 用户故事:Sense 关联 US-001、US-002、US-008,并为 US-005 提供视频设备空间配置;Bell 关联 US-003~US-006,并拥有 US-005 的业务规则工作流。
- 交互清单:Sense 关联 IX-001~IX-004、IX-014~IX-018,并提供 IX-010 所需的区域/警戒线几何;Bell 关联 IX-005~IX-013,负责 IX-010~IX-011 的规则继承、试运行和发布。
- 用户故事:Sense 关联 US-001、US-002、US-008、US-009,并为 US-005 提供视频设备空间配置;Bell 关联 US-003~US-006、US-010,并拥有 US-005 的业务规则工作流及 Tenant/Site/Area/RBAC/配额/全局审计真相。
- 交互清单:Sense 关联 IX-001~IX-004、IX-014~IX-020,并提供 IX-010 所需的区域/警戒线几何;Bell 关联 IX-005~IX-013、IX-016、IX-020,负责规则继承/试运行/发布、站点与 Area 策略、全局审计。
- 相关页面 / 路由:原型阶段为 `docs/design/sense/index.html` 与 `docs/design/bell/index.html`,不定义生产路由。
## 方案
1. 使用统一的 YoVision 深色安防控制台设计系统,Sense 与 Bell 保持品牌、状态色、控件和导航规律一致。
2. Sense 制作为单页可交互工作台:总览、监控墙、设备、接入任务和系统状态;不设置一级“区域规则”。统一设备台账使用 `modality + capabilities` 决定详情页和操作,M1~M5 完整展示视频设备,非视频设备以雷达原型验证信息架构,实际适配器留到 M6。
2. Sense 制作为单页可交互工作台:总览、监控墙、设备、接入任务和运维中心,移动端也固定为这 5 个入口;不设置一级“区域规则”或全局管理页。运维中心聚合对账、分片、边缘/隧道、运维告警和系统状态。统一设备台账使用 `modality + capabilities` 决定详情页和操作,M1~M5 完整展示视频设备,非视频设备在 M6 前明确显示 `adapter_not_ready`,不得虚构遥测。
3. 视频设备在“画面与检测区域”页签完成多边形、方向警戒线、显式完成、方向反转、逐点编辑、会话草稿恢复、乐观并发冲突和待校准反馈;Sense 只保存空间几何并只读显示关联规则,不提供业务规则绑定、时段、持续时间、试运行或正式发布。
4. Bell 制作为单页可交互值班台:除预警队列、事件证据、ack/处置、升级时间线、误报反馈和升级链外,规则编辑必须选择摄像头与检测区域版本,并负责继承、时段、持续时间、试运行、发布和回滚。
4. Bell 制作为单页可交互值班台和统一管理端:除预警队列、事件证据、ack/处置、升级时间线、误报反馈和升级链外,规则编辑必须选择摄像头与检测区域版本,并负责继承、时段、持续时间、试运行、发布和回滚;Bell 同时管理 Site/Area/配额/`capture_policy`,策略与已有成像设备冲突时必须显式迁移或取消。
5. Sense 摄像头详情与 Bell 规则草稿通过可演示的相对深链互相进入,携带摄像头/区域上下文;原型可以跨文件,但生产产品不得要求用户重新查找同一摄像头或丢失未完成草稿。
6. 两个原型均内联 CSS/JS,使用假数据,不加载真实视频、客户信息、生产地址或外部依赖;顶部固定标注原型用途。
7. 添加设备时先选择类型,依据能力渐进展示字段;区域的 `capture_policy` 负责隐私准入,视频设备在“仅非成像设备”区域中的新增或启用必须被阻止,策略不可用时对新写入失败关闭。
8. 完成桌面、窄屏、横屏、键盘焦点、加载/空态/错误切换和 `prefers-reduced-motion` 检查,提交人工评审;产品确认前不把任务标为 `DONE`。
8. 全局头部展示租户、站点、账号和角色;只读角色隐藏写操作,深链越权不泄露资源是否存在。Sense 设备日志带租户/站点/设备条件跳到 Bell 全局审计并可返回。
9. 完成桌面、窄屏、横屏、键盘焦点、加载/空态/错误/依赖降级切换和 `prefers-reduced-motion` 检查,提交人工评审;产品确认前不把任务标为 `DONE`。
## 不可变约束
- 阈值 / 数值边界:默认 16 路视频、单站点视频上限 128 路;非视频设备不占视频路数;单媒体分片建议上限 32 路、最多 4 个分片;静默最长 4 小时;原型不得暗示 128 路同时播放主码流。
- 阈值 / 数值边界:默认 16 路视频、单站点视频上限 128 路;非视频设备不占视频路数;单媒体分片初始配置建议 `max_streams=32`、当前示例承载 16、最多 4 个分片,最终以压测为准;静默最长 4 小时;原型不得暗示 128 路同时播放主码流。
- 判定式 / 状态转换:事件事实不可被处置改写;Alert 的首次投递、送达、看到、ack 和升级必须分开展示;检测区域版本与告警规则版本是不同对象;规则正式发布与试运行必须可区分,保存区域不得自动发布规则。
- 安全边界:不得展示摄像头密码、完整 RTSP/ONVIF 地址、token、真实客户/未成年人数据或人脸入口;破坏性动作须确认。
- 既有契约:原型不修改事件 v0.1、API、路由和生产技术栈,不作为生产实现代码。
## 验收要点
- 任务相关验证:两个 HTML 可本地打开、无外部依赖;关键按钮和状态切换可用;Sense 一级导航无“区域规则”,设备列表可按类型筛选/分页,视频详情可编辑检测区域,非视频详情不伪装成媒体流;Bell 可选择摄像头/区域并演示试运行与正式发布;双向深链保留 `camera + zone + return_to`;运行 HTML 结构检查、`git diff --check` 与 `./init.ps1`。
- 任务相关验证:两个 HTML 可本地打开、无外部依赖;关键按钮和状态切换可用;Sense 一级导航固定 5 项且无“区域规则”,设备列表可按类型/生命周期筛选与分页,视频详情可编辑检测区域,非视频适配器未交付时不伪装在线;运维中心覆盖对账/分片/边缘/运维告警/系统状态;Bell 可选择摄像头/区域并演示试运行与正式发布,且可管理 Site/Area 策略冲突;Sense↔Bell 规则深链保留 `camera + zone + return_to`,审计深链保留 `tenant + site + device + return_to`;运行 HTML 结构检查、`git diff --check` 与 `./init.ps1`。
- 完整门禁:本任务不修改 schema/API/路由,因此不触发契约与导航实现门禁;若范围变化则先更新任务。
- 人工 / 设备验收:必需。项目负责人分别打开 Sense 与 Bell 原型,确认页面结构、控件集合和主要工作流;未确认前不得标记 `DONE` 或合并为最终设计。
- 构建产物:`docs/design/sense/index.html`、`docs/design/bell/index.html`;双击浏览器打开,零构建依赖。
@@ -75,6 +78,15 @@ Sense 与 Bell 尚无可供产品确认的页面结构。生产 UI 开工前,
## 执行记录
### 2026-08-04 第二轮缺口复核与最终实现
- 复核 `raw/11`、`raw/12` 后保留对账、能力探测、设备生命周期、RBAC、写入降级、边缘隧道与运维告警等真实缺口;纠正“原型无分页”“分片 8 / 32”“雷达已有真实能力”“T-004 只允许 3 个写路径”等过期事实,并把 M4/M6 能力标为后续阶段而非本轮失败。
- 产品 IA 冻结为 Sense 5 个一级入口:运行总览、实时监控、设备、接入任务、运维中心。Tenant/Site/Area/RBAC/配额/全局审计归 Bell;Sense 仅呈现当前管理上下文并消费版本化配额/Area 策略投影。该决定已同步 US-009/US-010、IX-019/IX-020、正式需求、架构及三份原始分析文档。
- Sense 按显著改版规则整页重新生成:补齐待激活、认证失败、写入型凭据更新、能力探测来源/时间/生效差异、`adapter_not_ready`、逐项任务结果、暂停推理 reader/upstream 结果、对账差异/退避/孤儿安全闸、16/32 分片注释、边缘隧道/补传、独立运维告警、配额/策略不可用时只禁用相关写入,以及只读/越权状态。
- Bell 增加 Site/Area 管理、配额/策略投影状态与策略冲突显式迁移/取消;审计页能消费 Sense 的 `tenant + site + device + return_to` 上下文并返回设备详情。跨系统审计实现约定为 Sense 本地事务 outbox + 幂等 relay,但具体 API/签名/重放/留存仍需独立契约任务,本任务不修改 `docs/api/`。
- Node.js 内联脚本语法、唯一 ID、表单标签、按钮可访问名、Tab 契约和外部资源静态检查通过。Edge Headless/CDP 在 1440×900、375×812、812×375 验证上述关键流程:两页页面级无横向溢出,移动端可见主要控件不小于 44×44px,控制台与运行时均 0 exception;运维中心与 Bell Site/Area 页面截图已人工目检,临时 QA 文件未写入仓库。
- `./init.ps1` 通过:上下文/治理检查、16 个治理单测全部成功;`git diff --check` 通过。自动化验收已完成,任务继续保持 `DOING`,等待项目负责人打开原型进行必需人工确认;确认前不合并 PR。
### 2026-08-04 Claude 评审续修立项
- 项目负责人提供 `docs/raw/09-Sense原型评审-IX草稿.md` 并确认按复核后的最终建议继续修改。复核结论为:设备模态、停用收敛、隐私准入、几何编辑、草稿恢复与无障碍问题方向成立,但分片容量来源、页内草稿丢失和双向深链现状等证据需纠正。