256 lines
15 KiB
Markdown
256 lines
15 KiB
Markdown
# Sense 原型待办清单（合并 09 / 10 / 11）
|
||
|
||
> 合并来源：《09-Sense原型评审-IX草稿》《10-Sense原型-功能模块缺口》《11-Sense原型-第二轮缺口》
|
||
> 基准：`yovision-T-004/docs/design/sense/index.html`（2026-08-04 09:55）
|
||
> 用途：给 codex 的单一执行清单。理由与推导见来源文档，本文只给**做什么 + 依据 + 验收**。
|
||
> 日期：2026-08-04
|
||
|
||
---
|
||
|
||
## 0. 使用说明
|
||
|
||
- 编号 `S-xx` 稳定，后续讨论只引用编号。
|
||
- **A 组必须一次重生成**，不要逐项打补丁——三项都改信息架构，分次改的返工成本已经累积两轮。
|
||
- **写入范围**：T-004 的 `write_paths` 只含 `docs/tasks/T-004.md`、`docs/design/sense/index.html`、`docs/design/bell/index.html`。标记「⚠️ 超出 write_paths」的条目**需另开任务**，不要在本任务内改。
|
||
- 优先级：**P0** = M2 出口必需；**P1** = M2 内补齐；**P2** = 只留信息架构位，不实现。
|
||
|
||
---
|
||
|
||
## 1. 已完成（核对用，不执行）
|
||
|
||
第一轮《09》的全部条目已落地，实测确认：
|
||
|
||
| 项 | 验证方式 | 结果 |
|
||
| --- | --- | --- |
|
||
| IX-014 modality 建模与「设备」改名 | `modality` 出现 29 次；筛选含「视频 / 雷达」，添加对话框可选「视频设备 / 毫米波雷达」 | ✅ |
|
||
| IX-014 capabilities 驱动页签 | 页签改为「连接与健康」 | ✅ |
|
||
| IX-015 三种停用粒度 | `operationDialog`：暂停推理 / 停用接入 / 断开会话，各带影响说明 + 幂等 + 审计声明 | ✅ |
|
||
| IX-016 隐私准入（新增路径） | `updatePrivacyAdmission()`；区域筛选含 privacy | ✅ |
|
||
| IX-017 警戒线方向 | 检出 marker / 反转相关实现 | ✅ |
|
||
| IX-018 草稿自动保存 | 检出自动保存逻辑 | ✅ |
|
||
| a11y：tab 模式 | `aria-controls` + `aria-selected` + roving `tabindex` | ✅ |
|
||
| **对比度：主按钮** | `--primary-strong` 改为 `#0369a1` / `#075985` | ✅ **5.93:1 / 7.56:1**（原 2.77:1） |
|
||
|
||
---
|
||
|
||
## 2. A 组 · 信息架构级（P0，一次重生成）
|
||
|
||
导航从 5 项扩到 8 项：
|
||
|
||
```
|
||
运行总览 · 实时监控 · 设备 · 接入任务 · 【站点与区域】 · 【运维】 · 系统状态 · 【审计】
|
||
顶栏补：站点切换器 · 当前用户与角色
|
||
```
|
||
|
||
### S-01 运维视图：对账队列 · P0
|
||
|
||
**两轮未动，单点最大缺口。** 总览的「待收敛项」目前不可下钻；对账器是 Sense 区别于普通 NVR 的全部理由，UI 上等于不存在。
|
||
|
||
| 必须包含 | 依据 |
|
||
| --- | --- |
|
||
| 未收敛项列表，逐项显示**期望态 vs 实际态的具体差异** | 架构 §7「PostgreSQL 是期望态真相源」 |
|
||
| 每项的重试次数、当前退避间隔、下次重试时间 | 架构 §7「幂等、指数退避、限制并发」 |
|
||
| **孤儿资源列表 + 10% 安全闸触发告警** | 架构 §7「孤儿删除必须有 10% 安全闸和人工可观察指标」 |
|
||
| 单项手动触发收敛（现有「立即对账」是全局的，粒度过粗） | — |
|
||
| 收敛持续失败的升级路径：多久算异常、通知谁 | 需求 §3.5 运维告警独立 |
|
||
|
||
**验收**：从总览「待收敛项 N」可点击进入；任选一项能看到差异、退避与下次重试时间；孤儿列表与安全闸状态可见。
|
||
|
||
### S-02 权限与角色 · P0
|
||
|
||
**两轮为 0。**「角色」「只读」「权限」在原型中各出现 0 次。权限决定页面上**有没有**按钮，是信息架构问题，不是加一层。
|
||
|
||
| 必须包含 | 依据 |
|
||
| --- | --- |
|
||
| 顶栏显示当前用户与角色 | 需求 §3.5 五角色 RBAC |
|
||
| 只读角色下：添加 / 停用 / 删除 / 更新凭据**不出现**（不是置灰） | `routes.md` 路由守卫 |
|
||
| 越权深链的统一拒绝态 | `routes.md`「深链打开无权限或已删除资源时给出统一、安全的反馈」 |
|
||
| 站点管理员只能看到自己站点 | 需求 §3.5 |
|
||
| 角色切换器（原型演示用，同状态演示下拉的做法） | — |
|
||
|
||
**验收**：切到「只读」角色后，设备页所有写操作控件消失；越权深链显示统一拒绝态。
|
||
|
||
### S-03 站点与区域（Area）管理 · P0
|
||
|
||
实体链 `Tenant → Site → Area/Device` 目前断了两级：Site 是顶栏一行静态字，Area 只是一个下拉选项。
|
||
|
||
| 必须包含 | 依据 |
|
||
| --- | --- |
|
||
| 站点列表：配额已用/上限、在线率、未收敛数、边缘节点状态 | `routes.md` `/sites` |
|
||
| 顶栏站点切换器，切换后所有列表按站点过滤 | 架构 §3 SaaS-ready 边界 |
|
||
| 配额只读展示 + 标注「由 Bell 持有」 | 架构 §5 第 7 条 |
|
||
| **Area 增删改，含 `capture_policy = video_allowed \| non_imaging_only` 的编辑** | 需求 §3.1；架构 §8 |
|
||
| **改 `capture_policy` 时的显式处置流程**（该 Area 已有成像设备怎么办） | IX-016「不静默留存或停用」——规则已写，触发点当前不存在 |
|
||
|
||
**验收**：能新建 Area 并设为 `non_imaging_only`；把一个已有摄像头的 Area 改成该策略时，出现显式处置流程而非静默通过。
|
||
|
||
### S-04 审计入口 · P1
|
||
|
||
原型多处承诺「每次请求均审计」，但没有查询入口。
|
||
|
||
**必须包含**：设备操作审计列表（时间 / 操作 / 对象 / 执行人 / 结果），可按设备、操作类型、时间筛选；标注真相源在 Bell。
|
||
**验收**：从设备详情「操作记录」可跳到全局审计页并保留该设备筛选。
|
||
|
||
---
|
||
|
||
## 3. B 组 · 页内新增（不改 IA）
|
||
|
||
### S-05 capabilities 的产生流程 · P0
|
||
|
||
本轮新引入的 `capabilities` 决定页签显示，但**没有写入它的流程**——「测试连接」仍只是一次性 toast，结果不落地。
|
||
|
||
| 必须包含 |
|
||
| --- |
|
||
| 探测结果落地为设备持久属性，详情页「设备能力」区可见（厂商、型号、固件、认证方式、Profile 列表、是否支持校时、**是否支持 ONVIF 事件订阅**） |
|
||
| **重新探测**动作 + 与既有 `capabilities` 的**差异提示** |
|
||
| 能力降级处置：原本支持事件订阅、重探后不支持了，依赖它的设备型触发怎么办 |
|
||
| 与采购白名单关联（US-007 要求形成白名单，当前白名单与台账无连接） |
|
||
|
||
**验收**：添加设备后「设备能力」区有内容；重新探测能显示"新增/消失了哪些能力"。
|
||
|
||
### S-06 模态适配器未就绪态 · P0
|
||
|
||
需求 §3.1：M1～M5 只完整实现 video 适配器，M6 才接非视频；但信息架构不得写死为摄像头。
|
||
|
||
现在模态下拉已能选 `radar`/`mqtt`——**选了会怎样没有定义**。能一路添加成功就是承诺 M6 能力；直接禁用又违背 IA 要求。
|
||
|
||
**需要第三态**：模态已建模、适配器未就绪——可录入、进台账、占位、参与隐私准入校验，但明确标注「适配器 M6 交付，当前不建立连接」，且不计入视频配额。
|
||
**验收**：选 radar 添加后设备进入台账并显示该标注；实际态不显示为「在线」或「离线」，而是「适配器未就绪」。
|
||
|
||
### S-07 待激活闭环 · P0
|
||
|
||
需求 §3.1 明确的中间态，但设备表无待激活行、筛选无该项、无处置流程。
|
||
|
||
**必须包含**：待激活作为一级筛选项与独立计数；激活流程（重新探测 / 校时 / 配额复核）；批量激活与逐项结果；长期待激活的过期策略。
|
||
**验收**：筛选出待激活设备并完成一次激活，失败时可看到具体原因。
|
||
|
||
### S-08 凭据更新与认证失败恢复 · P0
|
||
|
||
详情页「凭据：已安全保存，页面不可见」——处理正确，但**只有读没有写**。现场改密码是最高频运维事件。
|
||
|
||
**必须包含**：单设备「更新凭据」（只写不读，不回显已存值）；**认证失败作为独立实际态**（区别于「离线」，原因和处置都不同）；批量更新凭据；更新后自动重试接入且结果可见。
|
||
**验收**：认证失败设备在列表中可识别，能就地更新凭据并看到重试结果。
|
||
|
||
### S-09 降级态：配额不可读 / 区域策略不可读 · P0
|
||
|
||
状态演示仍是 `normal / loading / empty / error` 四态。缺的是**写故障**——与「边缘节点不可达」（读故障）表现完全不同：视频照常播、列表照常看，只有写操作被拒。
|
||
|
||
| 必须包含 | 依据 |
|
||
| --- | --- |
|
||
| 配额不可读：横幅说明「当前无法新增或启用设备，已有视频不受影响」，添加/激活按钮禁用并说明原因 | `api.md` §2；架构 §7 |
|
||
| 区域策略不可读：拒绝新的成像设备变更并告警，已有链路不静默停用 | IX-016 |
|
||
|
||
**验收**：状态演示下拉新增这两态，切换后写操作被拒而视频与列表正常。
|
||
|
||
### S-10 边缘节点与隧道 · P1
|
||
|
||
侧栏底部只有一行 `sense-edge-01 · 在线`。但**控制面/数据面分离**是整个 NAT 方案的核心，UI 不体现等于白设计。
|
||
|
||
**必须包含**：边缘节点列表（版本、在线时长、隧道状态、承载设备数）；**隧道断开但视频仍在推**的明确表达；本地缓存水位 + 断网恢复后的补传进度；节点升级/重启动作。
|
||
**依据**：需求 §3.5「断网时边缘缓存事件，恢复后补传」。
|
||
**验收**：能演示「隧道断开 / 视频正常」这个组合态，并显示补传队列长度。
|
||
|
||
### S-11 主 / 子码流切换 · P1
|
||
|
||
详情写死「子码流 704×576 · 5 FPS」，无切换动作。码流是容量的直接变量（架构 §6：`max_streams` 由码率决定），切换还会踢掉当前发布者，需影响范围提示。
|
||
|
||
### S-12 分片详情与设备迁移 · P1
|
||
|
||
分片健康只读。需要：分片详情（承载设备、实际码率、重连历史）、设备跨分片迁移（会中断该路，需确认）、单分片故障的影响范围展示（架构 §6「单分片故障不能扩散」）。
|
||
|
||
### S-13 批量任务列表与逐项结果 · P1
|
||
|
||
「当前任务」是单卡片，「查看逐项结果」是死按钮。IX-001 要求逐行错误、重复序列号、待激活、确认写入。
|
||
|
||
**必须包含**：任务列表（历史可查、可重试、可导出错误清单）；逐项结果页（每行校验结果、失败原因、单行重试）；上传前本地预校验结果页；部分成功语义（8 路里 5 成功 3 失败，成功的已生效）。
|
||
|
||
### S-14 Sense 运维告警列表 · P1
|
||
|
||
总览「今日设备告警 3」与「与业务预警分开」的说明写得对，但点不进去。
|
||
|
||
**必须包含**：运维告警列表（离线、时间漂移超阈、收敛失败、分片异常、隧道断开）；运维侧的静默与通知配置（与 Bell 的业务静默是两套）；明确标注「不会推给家属/值班员」。
|
||
**依据**：需求 §3.4「业务预警与运维告警使用不同通道和值班配置」。
|
||
|
||
### S-15 设备列表分页 · P1
|
||
|
||
「分页」在原型中出现 0 次。IX-003 明确要求，阶段 M2/M4。含批量选择的跨页语义（「全选」到底选了当前页还是全部）。
|
||
|
||
### S-16 时间显示口径 · P1
|
||
|
||
系统内同时存在三个时钟：设备时间（可能漂 +3.8s）、服务器时间（期望态真相源）、浏览器本地时间。而「时间漂移」是原型自己列的一级指标，三者不区分会导致运维误判。
|
||
|
||
**约定**：统一显示服务器时间 + 时区标注；设备时间只出现在漂移列；相对时间悬停显示完整时间戳。
|
||
|
||
### S-17 租户维度 · P1
|
||
|
||
首期一客户一套私有实例，但架构 §3 要求「从第一版携带 `tenant_id` 并保持 SaaS-ready 边界」。不需要租户切换器，但需要当前租户可见、且所有列表按租户过滤这件事在 UI 上成立。
|
||
|
||
---
|
||
|
||
## 4. C 组 · 措辞与文档
|
||
|
||
### S-18 「暂停推理」措辞 · P0（一句话，但防的是重大实现错误）
|
||
|
||
现文：「只停止新推理任务」。这暗示的正是《03》§2.1 明令禁止的实现：
|
||
|
||
> `sourceOnDemand: yes` 的语义是「有 reader 才拉流」，而**推理 source 挂上去就是一个 reader**。因此「暂停分析」必须通过**卸载 source** 实现，不能只在推理插件里 `return`——后者会让 mediamtx 持续拉流、带宽白烧，**而监控上看起来一切正常**。
|
||
|
||
**改为**：「解除推理侧对该路的订阅；无其他观看者时上游自动停止拉流」。
|
||
并把「是否仍在拉流」作为可观察结果显示——这正是那条教训要防的。
|
||
|
||
### S-19 `media_shard.max_streams` 标注 · P2
|
||
|
||
分片显示 `8/32`。架构 §6 写「初始建议 32，可按故障域降为 16，最终由压测确定」——数值有据，但 UI 需标注它是**可配置项**而非固定值，避免被当成硬上限。
|
||
|
||
### S-20 「推理绑定 16/16」的视觉 · P2
|
||
|
||
正常状态画成 100% 满格紫条，易被误读为告警/满载。换表现。
|
||
|
||
### S-21 ⚠️ 超出 write_paths：`api.md` 补审计投递接口 · P1
|
||
|
||
原型承诺「每次请求均审计」，架构 §2 定 Bell 是审计真相源，但 `api.md` §2 的五行内部接口**没有 Sense → Bell 的审计投递**。
|
||
|
||
需补一行并明确失败语义。**建议**：Bell 不可达时操作照常执行、审计落本地队列重传——与 Brain 投递失败的处理保持一致（架构 §7）。
|
||
**处理方式**：另开任务，不在 T-004 内改。
|
||
|
||
---
|
||
|
||
## 5. D 组 · 只留信息架构位（P2，不实现）
|
||
|
||
避免 M3 时整页重做。三项各留一个导航位或详情页签占位即可：
|
||
|
||
| 编号 | 模块 | 依据 |
|
||
| --- | --- | --- |
|
||
| S-22 | 推理绑定视图（设备 ↔ worker 绑定、注册/心跳/容量、绑定失败态） | `api.md` §2「Worker → 控制面」 |
|
||
| S-23 | pre-roll 切片运维（请求量、失败率、耗时） | 架构 §5 第 3 条 |
|
||
| S-24 | 设备型触发源配置（雷达/门磁/按钮/ONVIF 事件订阅） | 《08》§3 边界 2；与 S-06 同源 |
|
||
|
||
---
|
||
|
||
## 6. 执行顺序
|
||
|
||
| 批次 | 条目 | 说明 |
|
||
| --- | --- | --- |
|
||
| **第 1 批** | S-01 · S-02 · S-03 · S-04 | **一次整页重生成**。四项都改信息架构，分次打补丁的返工成本已累积两轮 |
|
||
| **第 2 批** | S-05 · S-06 · S-07 · S-08 · S-09 · S-18 | P0 页内新增 + 措辞。S-18 只是改文案，可随手带上 |
|
||
| **第 3 批** | S-10 ～ S-17 | P1，M2 出口前补齐 |
|
||
| **第 4 批** | S-19 · S-20 · S-22 · S-23 · S-24 | P2，留位与视觉 |
|
||
| **独立任务** | S-21 | 超出 T-004 write_paths |
|
||
|
||
---
|
||
|
||
## 7. 总验收
|
||
|
||
第 1、2 批完成后应满足：
|
||
|
||
- [ ] 导航 8 项；顶栏有站点切换器、当前用户与角色
|
||
- [ ] 「待收敛项」可下钻，能看到期望态/实际态差异、退避与孤儿资源
|
||
- [ ] 切到只读角色，设备页所有写操作控件**消失**（非置灰）
|
||
- [ ] 能新建 `non_imaging_only` 的 Area，并触发既有成像设备的显式处置流程
|
||
- [ ] 「设备能力」区有内容，重新探测能显示能力差异
|
||
- [ ] 选 radar 添加后进入台账，实际态为「适配器未就绪」，不计入视频配额
|
||
- [ ] 待激活可筛选、可激活、失败有原因
|
||
- [ ] 认证失败可识别、可就地更新凭据、可看到重试结果
|
||
- [ ] 状态演示含「配额不可读」「区域策略不可读」，写操作被拒而视频与列表正常
|
||
- [ ] 「暂停推理」措辞已改，且能观察到「是否仍在拉流」
|