15 KiB
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 添加后进入台账，实际态为「适配器未就绪」，不计入视频配额
- 待激活可筛选、可激活、失败有原因
- 认证失败可识别、可就地更新凭据、可看到重试结果
- 状态演示含「配额不可读」「区域策略不可读」，写操作被拒而视频与列表正常
- 「暂停推理」措辞已改，且能观察到「是否仍在拉流」