diff --git a/docs/02-requirements.md b/docs/02-requirements.md index 8f035ed..8a199b0 100644 --- a/docs/02-requirements.md +++ b/docs/02-requirements.md @@ -28,10 +28,13 @@ ### 3.1 接入与设备 - 支持标准 ONVIF/RTSP,不绑定摄像头品牌。 +- 台账与管理端以“设备”为根实体,使用 `modality` 表达 video / radar / contact / button / wearable / other,并使用 `capabilities` 决定是否展示画面、媒体、空间配置、遥测等能力;M1~M5 只完整实现 video 适配器,M6 再接入非视频设备,但不得因此把数据模型和一级信息架构写死为摄像头。 - 支持 NAT 后的边缘主动推流;设备身份使用稳定序列号而非 IP。 - 批量开通不依赖逐路手工操作,支持待激活中间态。 - 探活、离线告警、开通校时、断线自动恢复。 - 容量写入时校验站点配额;配额服务不可用时拒绝新增/启用,但不影响已有流。 +- Site、Area 与隐私准入策略由 Bell 统一持有;`capture_policy = video_allowed | non_imaging_only` 通过版本化内部 API 或只读投影提供给 Sense。Sense 在设备新增/启用时依据设备成像能力校验,并显示策略版本/同步状态;策略读取失败时拒绝新的成像设备变更并告警,已有链路不静默停用或伪装为已收敛。 +- ONVIF 能力探测必须持久化厂商、型号、固件、认证方式、Profiles、校时与事件订阅结果以及探测时间;UI 区分探测值和最终生效值。M6 前未实现的非视频协议适配器使用 `adapter_not_ready`,不得伪造在线状态或遥测。 ### 3.2 分析与规则 @@ -51,8 +54,13 @@ - 预警必须有 ack;未 ack 自动升级,进程重启后能续跑。 - 升级链、超时、联系人和时段可按租户/站点配置。 +- 联系人与值班排班必须统一设计并共享人员、值班组和已验证通知通道主数据,但分对象、分版本管理:联系人不承载轮换字段,排班不复制手机号;升级步骤通过类型化目标引用指定人员、值班组或排班计划,不写死号码。 +- 值班排班至少覆盖站点时区、周轮换、生效日期、临时替班、空档/重叠冲突检查、当前与未来值班人预览、版本发布和审计。每次投递创建时解析当时生效的排班版本,并固化实际收件人、通道与解析版本快照;后续修改不得改写历史投递事实。 - 至少两条独立投递路径,其中一条可绕过互联网。 - 区分已发出、已送达、已看到;没有回执不能当成功。 +- Alert 与 Event 保持可导航的多对多关系;被规则抑制且没有创建 Alert 的 Event 不伪装为已投递。 +- 班次交接覆盖未 ack、处置中与升级中的 Alert;接班确认留痕,交接过程不暂停或重置升级链。 +- 交接班只显式转移进行中 Alert 的处置责任,不静默修改未来排班;未来班次替换通过排班临时替班并发布新版本完成。 - 静默必须限时且自动恢复,单次不超过 4 小时,无永久静默。 - 业务预警与运维告警使用不同通道和值班配置。 @@ -61,12 +69,14 @@ - 多租户数据、账号、配置和存储隔离;最小 RBAC 为平台管理员、租户管理员、站点管理员、值班员、只读。 - 全链路审计,预警生命周期可追溯。 - Prometheus/Grafana 至少覆盖设备在线、流状态、推理延迟、事件量、未收敛项和投递 SLA。 +- Sense 提供面向接入运维的运维中心,聚合对账差异、重试退避、孤儿安全闸、媒体/推理分片、边缘隧道/补传和运维告警;它不承担 Bell 的业务预警和全局管理审计。 - 断网时边缘缓存事件,恢复后补传。 - 不在代码、日志、证据文件名和工单中泄露摄像头凭据、客户名或敏感地址。 ### 3.6 管理端与外部集成 - Bell 自研并持有事件、Alert、ack、升级链、租户和审计真相;客户既有平台不得成为这些状态的唯一真相源。 +- Bell 管理端持有 Tenant、Site、Area、RBAC、配额和全局审计真相;Sense 只消费当前租户/站点/角色上下文和带版本的配额/Area 策略投影。Area 策略变更与已有成像设备冲突时必须显式迁移或取消,禁止静默停用。 - 对外使用版本化 OpenAPI/Webhook;M3 客户端为值班室 Web + 响应式移动 H5,可嵌入客户系统。 - 投递层必须使用供应商无关的 provider 接口;试点至少有本地声光/Web 与一条短信或语音,生产前补齐两条独立路径及故障切换。 diff --git a/docs/04-architecture.md b/docs/04-architecture.md index 7bb57ef..48e2946 100644 --- a/docs/04-architecture.md +++ b/docs/04-architecture.md @@ -16,16 +16,16 @@ YoVision 使用“通用底座 + 场景包”,按变化频率分为: | 系统 | 语言/状态 | 职责 | 不负责 | | --- | --- | --- | --- | -| Sense | Go,有状态 | 设备台账、ONVIF、MediaMTX 控制、对账、探活、隧道、设备型触发、流分片 | AI 判定、事件业务、预警 | +| Sense | Go,有状态 | 设备台账(`modality + capabilities`)、ONVIF 能力探测、MediaMTX 控制、对账、探活、隧道、设备型触发、流分片、配额/Area 策略投影与准入执行、接入运维中心 | AI 判定、事件业务、预警、Tenant/Site/Area/RBAC/全局审计真相 | | Brain | Python/CUDA,业务无状态 | 解码/推理、检测/姿态/跟踪/ReID、时间窗判定、事件 mapper、像素级触发 | 设备真相源、告警升级、租户权限 | -| Bell | Go + Web,有状态 | 事件校验/存储、规则、预警状态机、投递、反馈、租户/RBAC、审计、配额真相源和管理端 | 媒体转发、模型执行 | +| Bell | Go + Web,有状态 | 事件校验/存储、规则、预警状态机、投递、反馈、Tenant/Site/Area/RBAC、全局审计、配额与 `capture_policy` 真相源和统一管理端 | 媒体转发、模型执行、设备实际态 | MediaMTX、PostgreSQL、MinIO、Prometheus 等作为独立基础设施部署。 ## 3. 部署与系统边界 - 首期每个客户部署一套私有实例,数据和事件证据留在客户环境;数据库实体、RBAC、配置与 API 从第一版携带 `tenant_id` 并保持 SaaS-ready 边界。 -- Bell 自研且是事件、Alert、ack、升级链、租户和审计的唯一业务真相源;客户平台通过版本化 OpenAPI/Webhook 集成,不反向接管核心状态机。 +- Bell 自研且是事件、Alert、ack、升级链、Tenant/Site/Area/RBAC、配额和全局审计的唯一业务真相源;客户平台通过版本化 OpenAPI/Webhook 集成,不反向接管核心状态机。Sense 只保存执行所需的版本化只读投影,不形成第二份组织/策略真相。 - M1–M3 的视频入口只有 ONVIF/RTSP。现有 NVR 在售前盘点;仅支持 GB/T 28181 的项目必须建立独立适配器任务,不把国标信令混入 Sense 最小骨架。 - M3 客户端为值班室 Web + 响应式移动 H5,可嵌入客户系统;是否开发原生 App 在 M4 后另行决定。 @@ -45,7 +45,7 @@ Sense ── 视频流/触发信号 ──> Brain 主流程: -1. Bell 持有站点配额;Sense 在新增/启用设备时通过版本化内部 API 或只读投影校验。 +1. Bell 持有站点、Area、配额与 `capture_policy`;Sense 在新增/启用设备时通过版本化内部 API 或只读投影校验,并记录所用投影版本。 2. Sense 维护设备期望态,通过 MediaMTX API 和对账器收敛实际态。 3. Brain 消费视频与触发信号,产生符合 v0.1 的事件。 4. Bell 做 schema 与代码级断言,生成平台 ULID,保存不可变事件。 @@ -55,7 +55,7 @@ Sense ── 视频流/触发信号 ──> Brain 首个 M3 数据流部署在 S2 民办寄宿学校的 16 路高风险点位,只运行越线、危险区域和聚集等匿名规则,不加载人脸底库。 -## 5. 九条不可越界的决定 +## 5. 十二条不可越界的决定 1. MediaMTX 独立运行,Sense 管配置与生命周期。 2. 设备型触发源归 Sense;需要解码的像素级触发归 Brain。 @@ -66,6 +66,9 @@ Sense ── 视频流/触发信号 ──> Brain 7. Bell 拥有 `site.max_video_channels`,Sense 在设备写路径执行;不跨 schema 直接写。 8. 事件片段写入客户侧 MinIO/S3,常态录像留在客户 NVR;元数据/审计、人脸和训练样本使用独立生命周期。 9. 投递状态机只依赖 Bell provider 接口,不直接依赖某家短信或语音 SDK;生产前至少两条独立路径并能故障切换。 +10. 设备领域模型使用 `modality + capabilities`,页面不以摄像头作为唯一根实体;未实现协议适配器明确为 `adapter_not_ready`,不得用模拟遥测伪装交付。 +11. Tenant/Site/Area/RBAC、配额、`capture_policy` 与全局审计属于 Bell;Sense 只读消费版本化投影并在设备写路径执行,投影不可用时只阻断相关新变更,不静默切断已有链路。 +12. Sense 的设备操作审计先写本地持久化 outbox,再由幂等 relay 异步送入 Bell 全局审计;不得使用“先执行高风险操作、再尽力入队”的顺序。具体字段、签名、重放与留存契约必须由独立 API/契约任务冻结后实现。 ## 6. 容量架构 @@ -82,14 +85,20 @@ Sense ── 视频流/触发信号 ──> Brain - 对账器水平触发、幂等、指数退避、限制并发;部分失败不做跨系统回滚,只持续收敛。 - 孤儿删除必须有 10% 安全闸和人工可观察指标。 - 配额读取失败只阻止新增/启用,不中断已有流。 +- Area 策略投影读取失败只阻止相关设备新增/启用;已有设备保持原状态并产生运维告警。策略变更与已有成像设备冲突时由 Bell 管理端显式处置。 +- 高风险设备操作在本地事务内同时写期望态与审计 outbox;异步 relay 可重试、幂等投递到 Bell。T-004 只验证交互归属,不定义或实现接口契约。 - Brain 投递失败落本地队列重试,不阻塞实时推理主链路。 - Alert 先落库再投递,进程重启恢复未完成升级链。 +- 值班排班发布前必须按 Site 时区校验班次空档、重叠、联系人停用和通道验证;排班以新版本和未来生效时间发布,不原地改写历史。交接班是进行中 Alert 的显式责任转移事件,不替代排班版本变更。 - 事件证据技术默认保留 30 天并按生命周期删除;客户/法务在 M3 生产上线前确认法规适用性和最终期限,技术默认值不能覆盖其结论。 ## 8. 数据与契约 -- 核心实体:Tenant → Site → Area/Device → StreamBinding/Zone;Rule → Event → Alert → DeliveryAttempt/Ack。 -- Event 与 Alert 不合并:一个事件可触发多次预警与投递,一次预警也可聚合多个事件。 +- Bell 核心实体:Tenant → Site → Area(含 `capture_policy`)以及 Role/Binding/Quota/Audit;Sense 核心实体:Device(含 `modality + capabilities`)→ StreamBinding/Zone,以及带 `source_version`/`synced_at` 的 SiteQuota/AreaPolicyProjection。两个 schema 以稳定逻辑 ID 关联,不跨 schema 写入。 +- 业务实体:Rule → Event → Alert → DeliveryAttempt/Ack;Event 与 Alert 不合并。 +- Bell 通知域分为三个聚合:Contact/Team 保存身份、成员关系和已验证通道;OnCallSchedule/ScheduleVersion/ShiftException 保存时区、轮换与例外;EscalationPolicy/Step 通过 `person / team / on_call_schedule` 类型化 `target_ref` 引用目标。三者共享逻辑 ID,不复制手机号、班次或轮换字段。 +- 每个 DeliveryAttempt 创建时解析当时生效的排班版本,并保存实际收件人、通道、`schedule_version` 和解析时间快照;之后联系人或排班修改不得回写既有投递事实。 +- 一个事件可触发多次预警与投递,一次预警也可聚合多个事件。 - 事件 v0.1 以 `raw/contracts/event-v0.1.schema.json` 与 `raw/contracts/README.md` 为准;未知顶层字段拒绝,只允许通过 `ext` 扩展。 - v0.1 还需代码校验时间自洽、`confidence` 当前为 null、证据文件名隐私、唯一 primary sensor 等跨字段约束。 - S2 MVP 不处理人脸。首个人脸试点最早 M5,只允许经法务/客户门禁确认的 S4 成人访客/承包商白名单(≤10,000 人),并提供非人脸替代方式。 @@ -108,10 +117,10 @@ Bell/{web,packs,contracts} ## 10. 开发顺序 - M0 不写生产代码。 -- M1 只动 Sense,5 路接入骨架与 MediaMTX。 +- M1 只动 Sense,5 路视频接入骨架与 MediaMTX;设备模型从此时起保持模态/能力可扩展,但不提前实现非视频适配器。 - M2 仍以 Sense 为主,完成 16 路开通/停用、对账、多租户投影与隧道。 - M3 Brain 与 Bell 同时起步,事件契约首次被真实使用。 -- M4/M5 再做 64/128 路分片、完整管理端和多个场景包。 +- M4/M5 再做 64/128 路分片、完整管理端和多个场景包;M6 接入雷达、门磁、按钮和可穿戴等非视频适配器。 M3 先执行不少于 2 周的 dry-run,冻结现场标注集,按规则报告召回率和每路每天误报数;现场基线评审后才把数值阈值写入站点验收附件。算法效果指标与系统 SLA 分开验收。 diff --git a/docs/07-user-stories.md b/docs/07-user-stories.md index 7454206..6c21574 100644 --- a/docs/07-user-stories.md +++ b/docs/07-user-stories.md @@ -2,28 +2,28 @@ > 用户故事用于连接需求、页面交互和任务验收。当前 M0/M1 以设备与实施流程为主,最终用户界面在 M3/M4 才实现。 -## US-001 批量开通摄像头 +## US-001 批量开通视频设备 - 角色:实施工程师。 -- 目标:一次导入并验证一个默认 16 路站点,不逐路手工配置。 +- 目标:一次导入并验证一个默认 16 路视频站点,不逐路手工配置;操作入口位于通用设备台账的视频模态筛选下。 - 价值:降低交付时间并为 128 路扩展保留操作效率。 -- 验收:支持待激活、逐设备结果、失败可重试、超配额明确拒绝;128 路规模下仍使用分页/批量流程。 -- 关联:RQ-C-01~RQ-C-08,IX-001~IX-003。 +- 验收:导入后先进入待激活,任务历史可查看逐设备成功/失败原因并仅重试失败项;认证失败时提供不回显旧密码的凭据更新路径;超配额明确拒绝;128 路规模下仍使用分页/批量流程。 +- 关联:RQ-C-01~RQ-C-08,IX-001~IX-004、IX-015。 ## US-002 查看设备与流健康 - 角色:平台运维/站点管理员。 -- 目标:快速知道哪些设备离线、时间漂移、流未收敛或分片异常。 +- 目标:快速知道哪些设备离线、认证失败、时间漂移、流未收敛、隧道异常或分片异常,并能区分期望态与各下游实际态。 - 价值:在业务预警受影响前定位故障。 -- 验收:设备期望态与实际态分开显示;断线重连可观察;业务预警和运维告警不混用。 -- 关联:RQ-C-06~RQ-C-08、RQ-C-29、RQ-C-34,IX-004。 +- 验收:设备期望态与媒体/推理/存储实际态分开显示;对账差异、退避、下次重试和孤儿安全闸可观察;边缘隧道与视频数据面分别显示;业务预警和运维告警不混用。 +- 关联:RQ-C-06~RQ-C-08、RQ-C-29、RQ-C-34,IX-004、IX-019。 ## US-003 处置业务预警 - 角色:家属/值班员。 - 目标:收到异常后查看关联证据、确认接手并记录处置结果。 - 价值:把“发出通知”变成“有人负责”。 -- 验收:首次投递、送达、看到、ack、升级分别可追溯;无 ack 自动升级;进程重启不丢失升级链。 +- 验收:通道的已发出、已送达、已看到,与 Alert 的 ack、升级分别可追溯;无回执、通道不支持、可重试失败和最终失败不伪装成功;Alert 可查看聚合的 Event,Event 可查看触发的 Alert;并发 ack 时后到者看到真实处置人且不能覆盖;无 ack 自动升级,进程重启不丢失升级链。 - 关联:RQ-C-17~RQ-C-30,IX-005~IX-008。 ## US-004 标记误报 @@ -37,9 +37,9 @@ ## US-005 配置规则与升级链 - 角色:租户管理员/站点管理员。 -- 目标:按站点和设备覆盖场景模板,配置区域、时段、持续时间和联系人升级链。 +- 目标:按站点和设备覆盖场景模板,配置区域、时段、持续时间和升级链;升级步骤引用指定人员、值班组或值班排班,不直接写死手机号。 - 价值:同一通用底座适配不同场景。 -- 验收:继承来源清楚、变更可试运行/回滚、静默不超过 4 小时且自动恢复。 +- 验收:继承来源清楚、变更可试运行;升级目标可预览当前解析人和通道,投递后保留解析快照;回滚先展示版本差异与影响,并创建新的不可变版本,不改写历史;静默不超过 4 小时且自动恢复。 - 关联:RQ-C-11~RQ-C-15、RQ-C-23~RQ-C-28,IX-010~IX-012。 ## US-006 事件最小权限查看 @@ -58,6 +58,54 @@ - 验收:3–5 款设备的型号、固件、认证方式、Profiles/StreamUri/校时、主子码流、掉线恢复都有证据;不记录密码和真实客户信息。 - 关联:M0,T-001;无产品 UI,使用版本化测试文档。 +## US-008 管理异构设备与隐私准入 + +- 角色:实施工程师/站点管理员。 +- 目标:在统一设备台账中按模态和能力添加、筛选与查看视频、雷达、门磁、按钮、可穿戴等设备;隐私区域只允许非成像设备。 +- 价值:M2 固化不会因 M6 异构设备接入而推倒重来的信息架构,同时把隐私要求落实为系统准入约束。 +- 验收:一级入口使用“设备”;添加时先选模态,详情按探测能力显示页面并标明来源、时间与生效差异;未实现适配器显示 `adapter_not_ready`,不得伪装在线;`non_imaging_only` Area 不允许新增或启用成像设备,策略读取失败时拒绝新变更并给出恢复路径;M2 完成信息架构与视频准入,M6 完成非视频适配器。 +- 关联:RQ-S1-05、NFR-CMP-05,IX-014、IX-016、IX-019。 + +## US-009 以最小权限运维接入系统 + +- 角色:平台运维/租户管理员/站点管理员/只读用户。 +- 目标:进入 Sense 时明确当前租户、站点、账号和角色,并只看到权限范围内的数据与操作。 +- 价值:让私有化单租户交付也保留 SaaS-ready 隔离边界,避免原型把管理员权限当成默认事实。 +- 验收:切换站点会刷新上下文;只读角色看不到写操作;深链越权安全拒绝且不泄露设备存在性;设备操作日志可带筛选上下文跳到 Bell 全局审计。 +- 关联:RQ-C-31~RQ-C-33,IX-013、IX-020。 + +## US-010 管理站点与区域准入策略 + +- 角色:租户管理员/站点管理员。 +- 目标:在统一管理端维护 Site、Area 层级与 `capture_policy`,并让 Sense 使用同一版本的策略执行设备准入。 +- 价值:避免 Area 在 Sense、Bell 各有一份真相,保证权限、报表和隐私准入口径一致。 +- 验收:Bell 是 Site/Area/配额/策略真相源;策略变更影响已有成像设备时必须显式选择迁移或取消,不自动停用;Sense 展示策略版本与同步状态,投影不可用时仅拒绝相关新写入。 +- 关联:RQ-S1-05、NFR-CMP-05,IX-016、IX-020。 + +## US-011 完成值班交接 + +- 角色:交班值班员/接班值班员。 +- 目标:在班次结束前把所有未 ack、处置中和升级中的 Alert 连同备注交给下一班,并得到明确接手确认。 +- 价值:保证“有人负责”不在班次边界中断。 +- 验收:交接清单显示当前状态、处置人与下一次升级时间;接班人确认后写审计;交接过程不暂停、不重置升级链,未确认交接时原责任关系保持不变。 +- 关联:RQ-C-17~RQ-C-30,IX-021。 + +## US-012 导出规则验收效果 + +- 角色:项目负责人/租户管理员/验收人员。 +- 目标:按规则版本和冻结样本窗口查看可复核的召回率与每路每天误报数。 +- 价值:让站点验收使用场景相关、可追溯的效果口径,避免跨场景“准确率”误导。 +- 验收:报表展示规则版本、样本时间窗、正样本/漏检样本、通道天数、召回率和每路每天误报数;明确不提供跨场景统一准确率;导出保留筛选与口径说明。 +- 关联:RQ-C-22、`02-requirements` §8,IX-022。 + +## US-013 管理联系人和值班排班 + +- 角色:租户管理员/站点管理员。 +- 目标:使用同一套人员、值班组和通知通道主数据配置可发布的值班排班,并让升级策略引用排班目标。 +- 价值:避免先把联系人和号码写死进升级链、后续再迁移到时段轮换;同时避免把联系人、班次和轮换混成一个难维护对象。 +- 验收:联系人维护身份、角色、值班组和已验证通道,不出现排班轮换字段;排班维护时区、班次、周轮换、生效日期、临时替班和版本;发布前发现空档/重叠并阻止发布,可预览当前及未来值班人;投递固化收件人、通道与排班版本快照;交接进行中 Alert 不静默修改未来排班。 +- 关联:RQ-C-24~RQ-C-27、RQ-C-33,IX-012、IX-023。 + ## 追溯规则 新增 P0 UI 任务必须引用至少一个 US 和一个 IX;若没有 UI,任务文件明确写“不适用”。需求变化先更新用户故事和交互清单,再改页面。 diff --git a/docs/08-interaction-checklist.md b/docs/08-interaction-checklist.md index b02ced9..2183b1e 100644 --- a/docs/08-interaction-checklist.md +++ b/docs/08-interaction-checklist.md @@ -4,19 +4,29 @@ | ID | 场景 | 必须覆盖的状态与行为 | 关联 US | 阶段 | | --- | --- | --- | --- | --- | -| IX-001 | 批量导入设备 | 下载模板、上传校验、逐行错误、重复序列号、待激活、确认写入 | US-001 | M2 | -| IX-002 | 配额与批量结果 | 显示已用/上限;超 16 不等于非法,按站点配置校验;部分成功可重试 | US-001 | M2 | +| IX-001 | 批量导入设备 | 下载模板、上传校验、逐行错误、重复序列号、待激活、确认写入;任务历史保留逐项结果、操作者与时间,支持仅重试失败项 | US-001 | M2 | +| IX-002 | 配额与批量结果 | 显示已用/上限;超 16 不等于非法,按站点配置校验;部分成功可重试;配额不可读取时只禁用新增/启用并保留已有列表与流 | US-001 | M2 | | IX-003 | 设备列表 | 分页/筛选/批量选择;128 路不一次加载所有视频和详情 | US-001 | M2/M4 | -| IX-004 | 设备健康 | 期望态、实际态、最后在线、时间漂移、分片、重试进度;运维告警独立 | US-002 | M2/M4 | -| IX-005 | 预警到达 | 明确严重度、站点、时间、证据可用性;重复投递不产生重复处置 | US-003 | M3 | -| IX-006 | ack | 一次点击可确认,显示确认人/时间;并发 ack 有清晰结果 | US-003 | M3 | -| IX-007 | 升级 | 显示当前层级、下一次升级时间、每次投递状态;失败不能伪装成功 | US-003 | M3 | -| IX-008 | 事件详情 | 结构化事实、抓拍、视频、时间线、处置;证据加载失败可重试且不丢元数据 | US-003 | M3/M4 | +| IX-004 | 设备健康 | 期望态、媒体/推理/存储实际态、认证失败、最后在线完整时间与站点时区、时间漂移、分片、重试进度;运维告警独立,凭据更新只允许写入新值且旧值永不回显 | US-002 | M2/M4 | +| IX-005 | 预警到达 | 明确严重度、站点、时间、证据可用性与关联事件数;重复投递不产生重复处置 | US-003 | M3 | +| IX-006 | ack | 一次点击可确认,显示确认人/时间;服务端首个成功者成为处置人,并发后到者看到当前处置人和冲突结果,不静默覆盖或显示双成功 | US-003 | M3 | +| IX-007 | 升级与投递 | 显示当前层级、下一次升级时间;每个通道分别展示已发出、已送达、已看到,Alert ack 单独展示;无回执/不支持/未知、可重试失败及最终失败不得伪装成功 | US-003 | M3 | +| IX-008 | 事件详情 | 结构化事实、抓拍、视频、时间线、处置;证据加载失败可重试且不丢元数据;Alert 展示关联 Event 与聚合原因,Event 展示触发的 Alert 与最终状态,两边可深链;被抑制且未创建 Alert 的事件明确标为未触发 | US-003 | M3/M4 | | IX-009 | 误报反馈 | 确认动作、可选原因、提交成功反馈;只改变 outcome,不改原始事件 | US-004 | M3 | | IX-010 | 规则编辑 | 显示租户/站点/设备继承来源,支持区域/警戒线/时段/持续时间 | US-005 | M3/M4 | -| IX-011 | 规则试运行 | 明确“未正式生效”,展示命中样本与影响范围,支持取消/回滚 | US-005 | M4 | -| IX-012 | 升级链/静默 | 联系人顺序、超时、双通道;静默最长 4h、显示自动恢复时间、无永久选项 | US-005 | M3/M4 | +| IX-011 | 规则试运行与回滚 | 明确“未正式生效”,展示命中样本与影响范围,支持取消;回滚前展示目标版本差异与影响,确认后创建并发布等价的新版本,历史版本保持不可变;版本冲突时阻止覆盖并提供刷新/另存路径 | US-005 | M4 | +| IX-012 | 升级链/静默 | 升级步骤通过类型化目标引用指定人员、值班组或值班排班,不写死号码;显示目标解析预览、联系人顺序、超时与双通道;每次投递固化实际收件人、通道和排班版本快照;静默最长 4h、显示自动恢复时间、无永久选项 | US-005、US-013 | M3/M4 | | IX-013 | 权限与隐私 | 越权统一处理;无授权租户不展示人脸入口;不泄露流 URL/凭据 | US-006 | M3/M4 | +| IX-014 | 设备模态与能力 | 一级入口为“设备”;列表可按 `modality` 筛选,添加时先选模态,详情按 `capabilities` 渐进展示;能力同时显示厂商/型号/固件/认证、探测来源与时间、探测值和生效值差异;视频设备显示画面/媒体/检测区域,未交付的非视频适配器显示 `adapter_not_ready`,不用虚构遥测或禁用的视频页签占位 | US-008 | M2/M6 | +| IX-015 | 停用与收敛 | 明确区分暂停推理订阅、停用设备接入和仅踢当前会话;暂停推理必须说明“解除推理侧订阅”,并在结果中显示推理订阅、其他 reader 数与上游按需拉流状态;操作前展示对观看、录制与证据回捞的影响并二次确认;期望态立即改变、实际态经对账收敛,部分失败可逐项重试;重复请求不产生重复副作用,但每次请求均留审计结果 | US-001、US-002 | M2 | +| IX-016 | 隐私区域设备准入 | Area 与 `capture_policy` 由 Bell 统一管理,Sense 消费带版本的只读投影;`non_imaging_only` 不允许新增/启用具有成像能力的设备;前端就地禁用并解释,后端返回稳定错误码;策略读取失败时拒绝新变更并告警,已有设备遇到策略变化时由 Bell 进入显式迁移/取消流程,不静默留存或停用 | US-008、US-010 | M2/M6 | +| IX-017 | 检测区域几何编辑 | 多边形和方向警戒线支持绘制、显式完成、撤销、清空、顶点编辑;警戒线在草稿/已保存态均显示方向箭头并可反转;鼠标与键盘坐标操作等效;画面参数变化后标记待校准且不自动改坐标;区域版本与规则版本独立 | US-005 | M3 | +| IX-018 | 草稿与跨系统上下文 | 几何草稿自动保存并可恢复;只有持久化失败或切换空间类型等会破坏草稿的动作才拦截确认;Sense↔Bell 双向携带并消费 `camera + zone + return_to` 上下文;返回后恢复草稿,版本已被他人更新时提示冲突且不覆盖 | US-005 | M3 | +| IX-019 | 运维中心与写入降级 | Sense 用一个一级“运维中心”聚合对账差异/退避/下次重试/孤儿安全闸、媒体与推理分片、边缘节点/隧道/补传、运维告警和系统状态;配额或 Area 策略不可读取时页面继续可读且已有链路不受影响,只禁用相关写操作;不得混入 Bell 业务预警 | US-002、US-008 | M2/M4/M6 | +| IX-020 | 管理上下文、RBAC 与审计归属 | 全局头部显示租户、站点、账号和角色;只读角色隐藏写操作,深链越权统一拒绝且不泄露资源是否存在;Tenant/Site/Area/RBAC/配额/全局审计由 Bell 管理,Sense 只呈现消费上下文和设备操作入口,携带 tenant/site/device/return_to 深链到 Bell 审计;Bell 移动端底部导航不超过 5 项,并通过可发现的“管理”入口访问 Site/Area 与审计 | US-006、US-009、US-010 | M2/M4 | +| IX-021 | 值班交接 | 清单覆盖未 ack、处置中和升级中的 Alert,显示交班人、接班人、备注及下一次升级时间;接班确认写审计,交接期间不暂停或重置升级链,未确认时不转移责任 | US-011 | M3 | +| IX-022 | 规则验收报表 | 按规则版本与冻结样本窗口展示召回率、每路每天误报数和计算样本量;支持保留口径的导出;不提供跨场景统一准确率 | US-012 | M4 | +| IX-023 | 联系人与值班排班 | 在“升级链”内部以升级策略、值班与排班、联系人和通道三个二级模块统一设计;联系人与排班共享人员/值班组/已验证通道主数据但分对象维护;排班覆盖站点时区、周轮换、生效日期、临时替班、空档/重叠冲突、当前/未来值班人预览和版本发布审计;交接班只转移进行中 Alert,不暗改未来排班 | US-005、US-011、US-013 | M3/M4 | ## 全局状态 @@ -44,7 +54,10 @@ ## 无障碍与安全 - 键盘可完成主要 Web 流程,焦点清晰,表单错误关联到字段。 -- 文本和关键状态满足可读对比度;严重度同时用文字/图标表达。 +- 正文、按钮文字和关键状态对比度不低于 4.5:1;大字号(不低于 24px,或不低于 18.66px 且粗体)不低于 3:1;非文本控件、状态边界与焦点指示器不低于 3:1。严重度同时用文字/图标表达。 +- 当前导航项显式使用 `aria-current="page"`;响应式隐藏可见文字时,图标按钮仍保留稳定的可访问名。 +- 使用 tab 模式时完整实现 `tablist` / `tab` / `tabpanel`、`aria-controls` / `aria-labelledby`、单一 Tab 停靠点和方向键导航;不能完整实现时不声明 tab 角色。 +- 移动端主要操作目标不小于 44×44px,输入控件正文不小于 16px;绘制画布必须提供无需精确点击的键盘/表单等效路径。 - 删除、停用、踢流、批量覆盖和规则正式发布需要明确影响范围与二次确认。 - UI 不展示摄像头密码、完整连接串、token 或可复用的内部流地址。 diff --git a/docs/design/bell/index.html b/docs/design/bell/index.html new file mode 100644 index 0000000..0fb16cc --- /dev/null +++ b/docs/design/bell/index.html @@ -0,0 +1,999 @@ + + + + + + + + YoVision Bell · 预警处置原型 + + + + + +
PROTOTYPE - 仅供枚举交互,非实现依据
+
+ + +
+
+
青藤教育集团 · 青藤寄宿学校当前账号:林工 · 租户管理员 · Asia/Shanghai
+
+ + + + +
+
+ +
+
+ +
+

实时值班台

先确认高危预警,再查看证据与升级状态;重复投递不会生成重复处置。

值班组在线
+
+
+

待处置预警

6 个未 ack
+
+
+
+ +
+
高危 · S1

危险区域闯入

北围墙 01 · 23:14:08 · EVT-01J8…7A2

+
+
+ + + person · 0.92北围墙 01 · 事件片段事发前 8s · 事发后 12s · 匿名目标 + +
00:11 / 00:20
+
+
+
规则非授权人员进入
置信度0.92
持续时间8.4s
证据状态已校验
+
+

关联事件 · 2

+
仅显示与本事件关联的 20 秒证据。常态录像仍在客户 NVR,本页不暴露流地址或摄像头凭据。
+
+ + +
+
+ +
+

事件中心

事件是不可变事实;预警与处置结果作为关联记录单独展示。

+
+
今日事件47较昨日 -8%
已触发预警18规则命中后独立创建
误报反馈5进入标注队列
证据可用率97.9%1 个片段可重试
+
+
共 47 条
事件编号时间点位规则事实预警结果证据
第 1 / 16 页 · 每页 3 条
+
+ +
+ +

规则策略

Bell 管理场景、范围、时段、持续时间、试运行与发布;检测区域来自对应摄像头的版本化空间配置。

+
+
正式生效 · v7

非授权人员进入

危险区域 × 全天 × 持续 3 秒

覆盖范围
4 个点位
检测区域
北围墙危险区域 v7
继承来源
站点模板
今日命中
8
校准检测区域
+
试运行

区域内聚集

人数 ≥ 6 × 持续 20 秒 × 夜间

覆盖范围
3 个点位
检测区域
3 个区域版本
继承来源
设备覆盖
样本命中
14
+
草稿

方向越线

警戒线 A → B × 上学时段

覆盖范围
1 个点位
检测区域
宿舍东通道 · 警戒线 v3
继承来源
设备草稿
最近修改
2h 前
查看警戒线
+
+
+ +
+

升级链

联系人、值班排班和升级策略统一设计、分对象管理;策略引用动态目标,不写死手机号。

当前排班覆盖完整
+
+ +
+

校园高危事件 · 默认链

每一步引用类型化目标,解析后才创建投递
已发布 v4
+
1
值班室 Web + 本地声光立即 · 站点局域网内team:DUTY-ROOM
固定值班组
+
2
当前排班值班员 · 短信立即 · 送达后等待 2 分钟on_call_schedule:SCH-CAMPUS-SECURITY@v12
动态排班
+
3
校级负责人 · 语音未 ack 时升级 · 等待 3 分钟person:USR-SCHOOL-LEAD
指定人员
+
升级策略只保存目标引用和通道偏好,不复制联系人号码或轮换字段。
+

目标解析预览

事件时间 2026-08-04 23:14 · Asia/Shanghai
排班目标校园安保值班表 · v12SCH-CAMPUS-SECURITY
当前解析结果王值班员 · 晚班短信已验证 · 语音已验证
投递快照23:14:13 已固化收件人、通道、排班 v12;后续编辑不改写本次事实
+

解析与版本规则

不可变历史

每次投递创建时按站点时区解析当时生效的排班版本,并保存实际收件人、通道与版本快照。未来排班版本只影响其生效时间后的新投递。

静默规则

无永久选项

静默仅影响选定规则和点位,到时自动恢复;S1 事件不可静默。

+
+ +
+
当前排班v12已发布 · 08-01 生效
站点时区Asia/Shanghai跨午夜班次按站点时间
当前值班王值班员晚班 · 至明日 08:00
未来 14 天覆盖100%0 空档 · 0 重叠
+

校园安保值班表

周轮换 · 白班 08:00–20:00 / 晚班 20:00–08:00
+
今天 · 周二
白班林值班员08:00–20:00
晚班王值班员20:00–08:00
+
周三
白班赵值班员08:00–20:00
晚班周值班员20:00–08:00
+
周四
白班林值班员08:00–20:00
晚班王值班员20:00–08:00
+
周五
白班赵值班员08:00–20:00
晚班周值班员20:00–08:00
+
周六
白班林值班员08:00–20:00
晚班王值班员20:00–08:00
+
周日
白班赵值班员08:00–20:00
晚班周值班员20:00–08:00
+
下周一
白班林值班员08:00–20:00
晚班王值班员20:00–08:00
+
边界:临时替班进入新排班草稿并经发布后影响未来班次;值班交接只转移进行中 Alert 的责任,不会暗改这里的轮换。
+

版本与例外

全量审计
版本生效时间变更状态发布人
v122026-08-01 00:00暑期周轮换当前生效林工
v112026-07-01 00:00赵值班员加入白班组历史周管理员
+
+ +
+
联系人64 名值班员 · 2 名负责人
已验证通道11 / 121 个语音号码待验证
被排班引用4删除前必须解除引用
+

联系人和通知通道

只维护身份、角色、值班组和通道;班次与轮换在排班模块维护
联系人角色值班组通知通道排班引用状态操作
王值班员
USR-DUTY-WANG
值班员校园安保组短信 ✓ · 语音 ✓ · Web ✓SCH-CAMPUS-SECURITY可用
林值班员
USR-DUTY-LIN
值班员校园安保组短信 ✓ · Web ✓SCH-CAMPUS-SECURITY可用
校级负责人
USR-SCHOOL-LEAD
站点负责人校级负责人组短信 ✓ · 语音待验证升级策略 v4部分可用
联系人通道变更只影响后续新投递;已创建投递保留当时的收件人和通道快照。联系人被排班或策略引用时不能直接删除。
+
+
+ +
+

运营报表

算法效果和系统 SLA 分开统计;图表同时提供表格导出。

+

近 7 日预警量

按站点日期汇总;可切换到每路每天误报数。

处置结果

本月已闭环事件。

正常处置 61%误报 22%未闭环 17%
+

规则验收效果

冻结样本窗口:2026-07-01~2026-07-31 · 现场复核集 v3
规则版本样本窗口正样本 / 漏检召回率通道天数误报数每路每天误报数
非授权人员进入 · v707-01~07-31186 / 895.7%496190.038
区域内聚集 · v4 试运行07-15~07-3172 / 691.7%272160.059

口径说明:按规则版本分别报告召回率与每路每天误报数;不提供跨场景统一“准确率”。样本量和冻结窗口随导出保留。

+
+ +
+

站点与 Area

Bell 是 Tenant、Site、Area、配额与隐私准入策略的唯一真相源;Sense 只消费版本化投影。

+
租户1青藤教育集团
站点21 个试点中
视频配额16 / 128默认 16,不是硬上限
策略投影v42Sense 2 分钟前已同步
+

站点

+

青藤寄宿学校 · Area

层级、报表口径和设备准入共用同一逻辑 ID
策略变更不会静默处置已有设备。 若改为“仅非成像”且 Area 内已有摄像头,必须显式迁移设备或取消变更。
Area父级capture_policy设备策略版本投影状态操作
北围墙
area-north-wall
校园允许成像4 视频v42已同步
宿舍卧室
area-dorm-room
宿舍楼仅非成像0 视频 · 1 雷达规划v38已同步
实验楼入口
area-lab-gate
实验楼允许成像2 视频v41待 Sense 拉取
+
+ +
+ +

审计日志

查询、ack、规则发布和证据下载均可追溯;不记录密码与可复用连接串。

+
只读
时间角色动作对象结果来源
第 1 / 28 页 · 每页 3 条
+
+
+
+
+ + + +

配置告警规则

规则草稿 · 尚未正式生效
+
+
+
+
+
空间坐标由摄像头详情维护区域版本变化不会绕过规则试运行或自动正式发布。编辑检测区域
+
+
+
+ +

产品流程:先确认摄像头和检测区域,再配置业务条件;试运行样本达到现场评审要求后,才允许正式发布。

+
+ +

标记为误报

这只会追加事件 outcome,不会修改原始事件事实和证据。

+ +

创建限时静默

到期自动恢复;S1 高危事件与设备离线运维告警不受此静默影响。

+ +

编辑 Area 准入策略

保存生成新策略版本;Sense 投影同步前会显示旧版本,不允许绕过后端准入检查。

+ +

策略与已有设备冲突

北围墙当前有 4 台成像设备。改为“仅非成像”前必须选择显式处置;系统不会自动停用、移动或保留违规设备。

+ +

管理

移动端保留 5 个主入口,低频管理能力从这里进入。
+ +

事件详情

不可变事实
事件编号—
点位—
规则—
证据—

触发的预警

+ +

值班交接

白班 · 林值班员 → 晚班
ALT-1842 · 未 ack下一次升级 01:42
ALT-1841 · 处置中王值班员现场核查
ALT-1839 · 升级中短信重试 2/3

交接期间升级链继续计时,不暂停、不重置;只转移这些进行中 Alert 的处置责任,不修改未来排班。未来班次变化请在“值班与排班”创建替班版本。

+ +

版本历史与回滚

RULE-007 · 历史版本不可变
当前 v7 · 2026-08-01 正式发布持续 3 秒 · 全天 · 4 个点位 · 区域 v7
目标 v6 · 2026-07-18 历史版本持续 5 秒 · 夜间 22:00–06:00 · 3 个点位 · 区域 v6
影响评估将减少 1 个点位并收窄时段;预计每日预警 -18%。确认后创建并发布 v8,使其配置等价于 v6,v6/v7 均保持不变。
+ +

编辑升级步骤

默认链 v5 草稿 · 不直接保存手机号

保存的是类型化目标引用与通道偏好。每次投递创建时按站点时区解析生效排班,再固化收件人、通道和排班版本快照。

+ +

发布值班排班

历史版本不可变

发布前重新检查空档、重叠、联系人停用和通道验证。新版本只影响生效时间后的投递,不回写 v12 或既有投递快照。

+ +

创建临时替班

保存到 v13 草稿,发布后生效

临时替班修改未来排班。若只是把正在处置的 Alert 交给下一班,请使用值班台“交接班”,不要改排班。

+ +

新建联系人

联系人不包含班次和轮换字段

联系人保存身份、角色、值班组与已验证通道。加入哪个班次、何时轮换由“值班与排班”模块引用联系人 ID 完成。

+
+ + + + diff --git a/docs/design/sense/index.html b/docs/design/sense/index.html new file mode 100644 index 0000000..cb299c8 --- /dev/null +++ b/docs/design/sense/index.html @@ -0,0 +1,161 @@ + + + + + + YoVision Sense · 接入运维工作台原型 + + + +
PROTOTYPE - 仅供枚举交互,非实现依据
+ +
+ + +
+
+
+
租户青藤教育集团
+
+ 管理站点 / Area ↗ +
+
+ + + 林工 +
+
+
+ + +
+

运行总览

先看影响范围,再进入设备或运维中心处理。

+
+ + + + +
+
+

需要关注

北门 02 · 认证失败旧凭据不会回显,等待管理员更新
阻断接入
宿舍东侧 03 · 推理未收敛退避第 2 次 · 下次 10:49:10
待重试
edge-east · 隧道断开视频数据面仍正常 · 补传队列 86 MB
控制面异常
+

容量

视频 16 / 128

默认交付 16,不是硬编码上限。当前媒体分片承载 16 / 初始配置建议 32,启用 1 / 最多 4。

+
+
+ +
+

实时监控

默认仅 4 路低码率预览;128 路不同时加载。

+
低码率预览
北围墙 01

在线 · reader 2

低码率预览
北围墙 02

在线 · reader 1

认证失败
北门 02

无画面

待激活
食堂后门 04

尚未接入

+
+ +
+

设备

青藤寄宿学校 · 统一台账按模态与能力展示。

+
设备模态 / 能力状态期望 / 实际Area最后变化操作
第 1 / 2 页
+
+ +
+ +
视频设备

北围墙 01

在线SN-HK-001
+
+

生命周期

+ + + +
+
+ +
+

接入任务

CSV 导入、发现与逐项激活均保留可重试结果。

+
运行中1发现与探测
待激活2写入台账但尚未接入
部分成功1可仅重试失败项
过去 24h16成功激活
+
任务方式进度逐项结果操作者 / 时间操作
宿舍楼补点
task-20260804-17
CSV部分成功成功 3 · 失败 1 · 待激活 1林工
北区自动发现
task-20260804-18
ONVIF 发现
探测 7 / 11系统
+
+ +
+

运维中心

接入控制面的差异与基础设施告警;不包含 Bell 业务预警。

+
待收敛2最高优先级 90
媒体分片1 / 4当前承载 16 / 配置建议 32
边缘节点2 / 31 个控制面隧道断开
运维告警4P1 1 · P2 3
+
+
对象 / 优先级期望态实际态差异与退避下次重试操作
宿舍东侧 03
P90
Brain subscribedworker not_found第 2 次 · 20s
北围墙 02
P60
Media runningpath idle第 1 次 · 10s
+ + + + +
+
+
+
+
+ + + + + + +

添加设备

保存后进入“待激活”,探测成功且配额/Area 策略通过后才接入。

+ +

更新设备凭据

+ +

切换 ONVIF Profile

切换会重新建立媒体 path,短时影响观看、推理与录制;检测区域进入待校准,不自动修改坐标。

+ +

能力探测差异

新探测 probe-8429 ·

字段上次探测本次探测生效值
主 ProfileProfile_1Profile_1Profile_1
事件订阅PullPointPullPoint + motion待确认
设备时间+0.2s+1.8s等待校时
+ +

设备接入控制

+ +

宿舍楼补点 · 逐项结果

行设备结果原因 / 下一步操作
2食堂后门 04待激活探测完成,等待确认
3宿舍东侧 03成功已接入 media-01—
4北门 02失败AUTH_REJECTED · 更新凭据

部分成功不会整体回滚:成功项已生效,失败项保持可重试。

+ +

孤儿 path 人工恢复

安全闸已阻止本批删除,原型不提供绕过入口。先导出 5 个对象及 publisher、reader、录像索引与待回捞证据,再由独立维护任务分批处置。

+ + + + diff --git a/docs/raw/02-需求分析.md b/docs/raw/02-需求分析.md index 0209d0b..aa22e25 100644 --- a/docs/raw/02-需求分析.md +++ b/docs/raw/02-需求分析.md @@ -125,8 +125,8 @@ erDiagram | --- | --- | --- | | **Tenant 租户** | 计费与数据隔离的最小单位 | 所有查询必须带 tenant_id,无例外 | | **Site 站点** | 一个物理场所(一户 / 一所学校 / 一个小区) | 升级链、时段策略挂在这一层 | -| **Area 区域** | 站点内的逻辑分区(教学楼 / 单元 / 客厅) | 用于权限范围与报表口径 | -| **Device 设备** | **不叫 Camera**,`device_type` 取 camera/radar/door/button | 为异构传感器预留(继承参考项目 §4.5) | +| **Area 区域** | 站点内的逻辑分区(教学楼 / 单元 / 客厅),由 Bell 统一管理 | 用于权限范围、报表口径与设备准入;`capture_policy` 表达是否仅允许非成像设备,Sense 只消费带版本的策略投影 | +| **Device 设备** | **不叫 Camera**;`modality` 表达 video/radar/contact/button/wearable/other,`capabilities` 表达成像、媒体、遥测等具体能力 | 模态负责稳定分类,能力负责决定字段与操作,避免接入新设备时重做台账和页面 | | **Zone 画面区域** | 画在某路画面上的多边形或警戒线 | 与 Area 是两回事:Area 是物理概念,Zone 是像素坐标 | | **Rule 规则** | 「主体 × 条件 × 时空 × 动作」的可配置组合 | 三级覆盖:租户默认 → 站点 → 设备 | | **Event 事件** | 一次被判定成立的客观发生 | **不可变**。误判只能被标记,不能被删改 | @@ -608,21 +608,27 @@ GPU 型号和数量不在需求阶段写死。M1 用 5 路打通,M3 以 16 路 在参考项目基础上扩展多租户与规则/事件。**字段级设计见《03》,此处只给结构与关键约束。** ```sql --- ── 组织(Bell 为真相源;Sense 只读配额投影)──────── +-- ── 组织(Bell 为真相源;Sense 不直接写这些表)──────── tenants(id, code, name, status, plan, created_at) sites(id, tenant_id, code, name, scene_pack, subnet CIDR, timezone, status, max_video_channels INT NOT NULL DEFAULT 16 CHECK (max_video_channels BETWEEN 1 AND 128)) -areas(id, site_id, name, parent_id) +areas(id, site_id, name, parent_id, + capture_policy) -- video_allowed | non_imaging_only --- ── 设备(不叫 cameras,为异构传感器预留)──── +-- ── Sense 只读投影(来源版本与同步时间必须可追溯)──── +site_quota_projections(site_id, max_video_channels, source_version, synced_at) +area_policy_projections(area_id, site_id, capture_policy, source_version, synced_at) + +-- ── Sense 设备(不叫 cameras,为异构传感器预留)──── devices( id, tenant_id, site_id, area_id, - device_type, -- camera | radar | door | button + modality, -- video | radar | contact | button | wearable | other + device_kind, -- camera | mmwave_radar | door_contact | panic_button | ... + capabilities JSONB, -- captures_image / media_stream / telemetry / battery / spatial_config / ... serial UNIQUE, -- ⚠️ 身份用序列号,不用 IP vendor, model, onvif_addr, onvif_user, onvif_secret, -- secret 加密存储 state, -- pending_activation | active | offline | disabled - privacy_flag, -- 隐私区域标记,为 true 时拒绝 camera 类型 last_seen_at ) stream_bindings(id, device_id, mtx_instance, inference_shard, path_name, rtsp_url, profile_token, enabled, @@ -701,6 +707,8 @@ CREATE INDEX ON alerts(state) WHERE state NOT IN ('closed','suppressed'); 7. 人脸相关表独立 schema、独立加密、独立审计;`persons.valid_until` 必填,无"永久有效"选项 8. `sites.max_video_channels` 默认 16、最大 128;配额在写入设备时校验,分片容量由运行时配置与压测决定 9. `sites.max_video_channels` 由 Bell 持有,Sense 通过版本化内部 API 或只读投影校验设备新增/启用;不得跨 schema 直接写入 +10. Tenant/Site/Area/RBAC、配额与全局审计属于 Bell;Sense 仅使用稳定逻辑 ID 关联并保存带 `source_version` / `synced_at` 的执行投影 +11. 高风险设备写操作与本地审计 outbox 在 Sense 同一事务提交,再由幂等 relay 异步汇入 Bell;审计接口字段、签名和重放规则另立契约任务冻结 --- diff --git a/docs/raw/03-通用场景应用方案.md b/docs/raw/03-通用场景应用方案.md index d6ca725..283a924 100644 --- a/docs/raw/03-通用场景应用方案.md +++ b/docs/raw/03-通用场景应用方案.md @@ -921,7 +921,7 @@ scene_packs/campus@1.2/ | 约束 | 实现 | | --- | --- | -| 卧室、卫生间**禁装摄像头** | `devices.privacy_flag = true` 时系统拒绝创建 `device_type = camera`(代码级硬约束) | +| 卧室、卫生间**禁装摄像头** | `areas.capture_policy = non_imaging_only` 时,Sense 在设备新增/启用写路径拒绝具有 `captures_image` 能力的设备(代码级硬约束);策略读取失败时拒绝新变更并告警,不静默切断已有链路 | | 平时不解码不上传 | 触发式推理 + `record: no` + 边缘环形缓冲 | | 家属只能看自己家的告警关联片段 | RBAC:`family` 角色的证据访问范围 = `site_id` ∩ `alert_events` | | 3 分钟内必有真人接手 | 4 级升级链(30s/60s/90s → 呼叫中心) | @@ -1067,7 +1067,7 @@ capacity: `stream_bindings` 同时记录 `mtx_instance` 与 `inference_shard`。默认按 `site_id + device_id` 稳定分配;扩容时允许迁移,但同一设备任一时刻只能归属一个有效媒体分片和一个推理分片。 -`sites.max_video_channels` 的唯一真相源在 Bell;Sense 在设备新增/启用写路径通过版本化内部 API 或只读投影执行配额校验,不跨 schema 直接写入。配额依赖暂时不可用时只拒绝新的容量变更,已有视频链路继续运行。 +`sites.max_video_channels`、Site/Area 层级和 `areas.capture_policy` 的唯一真相源在 Bell;Sense 在设备新增/启用写路径通过版本化内部 API 或带 `source_version` / `synced_at` 的只读投影执行校验,不跨 schema 直接写入。配额或 Area 策略依赖暂时不可用时只拒绝相关新变更,已有视频链路继续运行并产生运维告警。 > **不要单实例硬扛 128 路**:扩容必须通过增加分片与 Worker 完成。单分片故障只允许影响该分片,不能拖垮整个站点。GPU 型号与数量不在架构文档写死,M1 用 5 路打通,M3 建立 16 路基线,M4/M5 再验证 64/128 路。 @@ -1115,7 +1115,8 @@ OpenTelemetry → Jaeger,排查单帧处理延迟与端到端事件链路。 | 端 | 核心功能 | | --- | --- | -| **管理系统(Web)** | 租户/站点/设备管理、批量开通、规则配置(含试运行)、Zone 画图、升级链配置、事件看板与筛选、事件详情(视频+观测回放)、处置与工单、误报标记、统计报表、审计查询、RBAC | +| **Sense 接入工作台(Web)** | 当前租户/站点上下文、设备台账与批量开通、能力探测、Zone 画图、对账/分片/边缘隧道/补传/运维告警;不管理 Tenant/Site/Area/RBAC 或全局审计 | +| **Bell 统一管理端(Web)** | Tenant/Site/Area/配额/`capture_policy`、RBAC、规则配置(含试运行)、升级链、事件看板与筛选、事件详情(视频+观测回放)、处置与工单、误报标记、统计报表、全局审计;设备操作日志从 Sense 汇入并可深链返回 | | **App(家属/值班员)** | 预警接收与 ack、事件详情与视频回看、一键呼叫、误报反馈、限时静默、设备状态、(家属)多老人切换 | | **大屏/值班台** | 实时事件流、地图/平面图点位、声光联动、当班交接 | | **Webhook/开放 API** | 对接客户既有平台、门禁、消防、工单系统 | @@ -1144,7 +1145,9 @@ OpenTelemetry → Jaeger,排查单帧处理延迟与端到端事件链路。 | --- | --- | --- | --- | --- | --- | | **Sense** | 感知系统 | L1 接入 | Go | 有(设备台账) | M1 | | **Brain** | 推理系统 | L2 流水线 + L3 算法 | Python / CUDA | **无状态** | M3 | -| **Bell** | 管理系统 | L4 业务 + L0 基座 | Go + 前端 | 有(事件、告警) | M3 → M4 | +| **Bell** | 管理系统 | L4 业务 + L0 基座 | Go + 前端 | 有(事件、告警、组织与策略真相) | M3 → M4 | + +Sense 的高风险设备操作不能采用“先执行、再尽力记录审计”。实现时应在本地事务内同时写期望态与持久化 outbox,再由幂等 relay 异步汇入 Bell 全局审计。该跨系统接口的字段、签名、重放和留存必须另立 API/契约任务,不在 UI 原型任务中顺带冻结。 三者之间只有一条契约——**事件实例 JSON**(§2.6,规范本体见 `contracts/event-v0.1.schema.json`)。Sense 向 Brain 供流与信号,Brain 产出事件,Bell 消费事件。这条边界让推理侧换模型、换框架(Savant → Pipeless、YOLO → YOLOX)时,另两个系统一行不改。 @@ -1228,7 +1231,7 @@ redis 消息总线 - [ ] 终止服务时的底库彻底删除义务与证明方式已约定 ## 架构 -- [ ] `devices` 表而非 `cameras`,含 `device_type` +- [ ] `devices` 表而非 `cameras`,含 `modality + capabilities`;Bell 持有 Area 与 `capture_policy`,Sense 只存带版本的准入投影 - [ ] 设备身份用序列号 - [ ] 触发入口独立成 handler - [ ] `sync_state` 每系统一行 diff --git a/docs/raw/08-三系统职责划分.md b/docs/raw/08-三系统职责划分.md index 31b7170..fbd9877 100644 --- a/docs/raw/08-三系统职责划分.md +++ b/docs/raw/08-三系统职责划分.md @@ -23,7 +23,7 @@ **Sense —— 把现场的流和信号稳定地拿进来并管住** -- 设备台账(`devices`,含 `modality`:video / radar / contact / button / wearable) +- 设备台账(`devices`,含 `modality`:video / radar / contact / button / wearable / other,以及决定成像、媒体、遥测、空间配置等页面与操作的 `capabilities`) - ONVIF 客户端:连接、GetProfiles、GetStreamUri、SetSystemDateAndTime - mediamtx API 客户端(**自行用 oapi-codegen 从其 OpenAPI 生成**,不依赖第三方 SDK) - **对账器**:水平触发、`sync_state`、独立信号量、10% 孤儿删除安全闸、只收敛不回滚 @@ -31,6 +31,7 @@ - WireGuard 控制面隧道 - mediamtx 鉴权回调(401 + 踢流是四种停用粒度之一) - 容量配额执行:设备新增/启用时读取 Bell 的站点配额,只拒绝超额变更;配额服务暂时不可用时不影响已有流 +- Area 准入执行:消费 Bell 的版本化 `capture_policy` 投影;策略不可用时只拒绝相关新写入,不静默中断已有设备 - 流绑定与媒体分片调度:维护 `mtx_instance`,默认 16 路交付;扩到 128 路时按 `media_shard.max_streams` 横向分片 - 边缘节点 agent:推流、本地环形缓冲、断网续传 - **设备型触发源**:雷达、门磁、按钮、ONVIF 事件订阅 @@ -54,8 +55,8 @@ - 告警状态机:升级链、ack、抑制、静默(**≤4h,无永久选项**) - 投递:push / 短信 / 语音,**双供应商** - 误报反馈闭环:`outcome` 回写 Brain -- 多租户 RBAC、`tenant_features`(人脸授权开关:未授权时能力在 API 与 UI 中**不可见**,不是禁用) -- 审计日志 +- Tenant/Site/Area、`capture_policy`、多租户 RBAC、`tenant_features`(人脸授权开关:未授权时能力在 API 与 UI 中**不可见**,不是禁用) +- 全局审计日志;接收 Sense 设备操作审计并保留来源上下文 - 站点容量配额的唯一真相源:`site.max_video_channels` 默认 16、上限 128;提供版本化内部读取接口/投影给 Sense 执行 - 管理后台前端 + 大屏:按 128 路设计分页/虚拟列表、筛选与批量操作,不一次性加载全部视频 @@ -80,7 +81,7 @@ Sense/ │ ├── sense-api/ 控制面服务:设备台账、鉴权回调、对账器 │ └── sense-agent/ 边缘节点:推流、环形缓冲、隧道 ├── internal/ -│ ├── device/ 设备台账(devices,含 modality) +│ ├── device/ 设备台账(devices,含 modality + capabilities) │ ├── onvif/ 连接、GetProfiles、GetStreamUri、SetSystemDateAndTime │ ├── mtx/ oapi-codegen 生成的 mediamtx 客户端 + 薄封装 │ ├── reconcile/ 对账循环(幂等 + 退避 + 安全闸) @@ -138,7 +139,7 @@ Bell/ --- -## 3. 七条边界(不写死就会漂) +## 3. 八条边界(不写死就会漂) | # | 边界 | 定论 | | --- | --- | --- | @@ -149,8 +150,10 @@ Bell/ | 5 | 一个 PostgreSQL 还是三个 | **一个实例,schema 分离**(`sense` / `bell`),Brain 无 schema。"DB 是唯一真相源"是对账器成立的前提,拆库即失效 | | 6 | 16 路与 128 路分别指什么 | **16 路是默认交付规格,128 路是本阶段单逻辑站点上限**,都不是“单进程/单服务器保证值”。媒体与推理必须横向分片;单机承载量由分辨率、码率、帧率、模型和硬件基准测试决定 | | 7 | 站点配额谁拥有、谁执行 | **Bell 拥有 `sites.max_video_channels`,Sense 在设备新增/启用写路径执行**。通过版本化内部 API 或只读投影同步,不允许 Sense 直接写 Bell schema;依赖暂时不可用时拒绝新变更,但已有视频链路继续运行 | +| 8 | 设备模态与隐私准入怎么建模 | 台账使用 `modality + capabilities`,不以摄像头作为唯一根实体;**Bell 拥有 Area 与 `capture_policy`,Sense 消费带版本投影并按设备 `captures_image` 能力在新增/启用写路径执行**。策略不可用时拒绝相关新变更并告警,已有链路不静默停用;M1 固化模型,M6 再增加非视频适配器 | +| 9 | 接入操作审计怎么进入 Bell | Sense 在同一事务写设备期望态和持久化 outbox,再由幂等 relay 异步汇入 Bell 全局审计;不得先执行高风险操作再尽力入队。字段、签名、重放和留存由独立 API/契约任务冻结 | -第 2、3、6、7 条是本文档新定的,若实施中发现更合适的切法,改这里并同步《02》《03》。 +第 2、3、6、7、8、9 条是本文档新定的,若实施中发现更合适的切法,改这里并同步《02》《03》。 --- @@ -179,6 +182,6 @@ DB schema sense — bell | **M3** 默认 16 路推理 + 规则引擎 + 事件预警 | **Brain + Bell 同时起步**,契约在此首次被真实使用 | | **M4** 64 路分片 + 灰度 + 管理系统 | Sense 与 Brain 完成横向分片,Bell 完成 128 路规模下的列表与批量交互;验证单分片故障隔离 | | **M5** 128 路容量验收 + 第二三场景包 + 触发式推理 + 人脸 | Sense/Brain 验证扩容不改业务代码;Bell 的 `packs/`(**纯配置**)+ Brain 的模型与触发 | -| **M6** 异构传感器 + 两级判定 | Sense 的 `trigger/` 与 `device/`(modality 扩展)+ Brain 两级判定 | +| **M6** 异构传感器 + 两级判定 | Sense 的 `trigger/` 与 `device/` 增加非视频协议适配器与能力实现(`modality + capabilities` 模型已从 M1 保留)+ Brain 两级判定 | > M3 是契约第一次被真实使用的时刻。**在此之前契约允许原地修订,之后版本递增规则绝对生效**(契约 README §1)。 diff --git a/docs/raw/09-Sense原型评审-IX草稿.md b/docs/raw/09-Sense原型评审-IX草稿.md new file mode 100644 index 0000000..1500656 --- /dev/null +++ b/docs/raw/09-Sense原型评审-IX草稿.md @@ -0,0 +1,148 @@ +# 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= +zone= +return_to= +``` + +`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。 diff --git a/docs/raw/11-Sense原型-第二轮缺口.md b/docs/raw/11-Sense原型-第二轮缺口.md new file mode 100644 index 0000000..6c5981e --- /dev/null +++ b/docs/raw/11-Sense原型-第二轮缺口.md @@ -0,0 +1,139 @@ +# Sense 原型第二轮评审复核版 + +> 原始输入:Claude《Sense 原型第二轮评审》,2026-08-04 +> 复核基准:`docs/design/sense/index.html`,提交 `e18a1ea` +> 复核视角:产品边界、全栈架构、M2 用户流程与 UI/UX +> 状态:项目负责人已确认按本复核结论继续修改 + +--- + +## 1. 总结 + +Claude 指出的对账运维、设备能力来源、非视频适配器阶段、待激活、凭据恢复、写入降级和边缘隧道等缺口方向成立;但原稿不能直接作为执行清单,主要有三类问题: + +1. **基准落后**:设备分页和推理收敛成功态已经实现,分片数据也不再是原稿引用的 `8 / 32`。 +2. **范围扩大**:T-004 当前关联 US-001、US-002、US-008 和部分 US-005,并未承诺一次画完完整 M2/M4 管理端。新增 P0 页面必须先同步 US/IX 与任务范围。 +3. **系统归属混淆**:`routes.md` 的 `/sites`、`/operations`、`/audit` 是统一管理 Web 的候选页面职责,不等于都应成为 Sense 一级导航。Bell 拥有租户/RBAC、审计、配额真相源和管理端;Sense 负责设备接入与运行态运维。 + +因此,本轮采纳“补核心流程、收敛导航、冻结归属”的方案,不采用“Sense 导航机械扩为 8 项”。 + +--- + +## 2. 对原评审事实的纠正 + +| 原判断 | 当前事实 | 处理 | +| --- | --- | --- | +| 设备列表分页未实现 | 已有 5 条/页、上一页/下一页、页数和总数 | 标记完成;批量选择未来新增时再定义跨页语义 | +| “推理绑定 16/16”仍是紫色满格 | 已改为“推理配置收敛 16/16”绿色成功态 | 标记完成 | +| 分片仍显示 `8 / 32` | 当前为 `16 / 32`,并显示“当前 1 / 最多 4” | 只补“32 是可配置建议值、最终由压测确定” | +| T-004 `write_paths` 只有三个文件 | 已扩展到需求、架构、US/IX、评审稿和两个原型 | 更新清单基准 | +| modality 筛选包含 ONVIF/MQTT | modality 是 video/radar;ONVIF/RTSP/MQTT 属于 protocol | 文档严格区分模态、设备种类、协议和能力 | + +--- + +## 3. 最终产品信息架构 + +### 3.1 Sense Edge Console + +Sense 保持最多五个一级入口,移动端底部导航不超过五项: + +```text +运行总览 +实时监控 +设备 +接入任务 +运维 + ├─ 对账与孤儿资源 + ├─ 媒体分片 + ├─ 边缘节点与隧道 + ├─ 运维告警 + └─ 系统状态 +``` + +原“系统状态”并入“运维”。总览的待收敛项、设备告警和分片状态均可下钻到运维的对应子页。Sense 顶栏显示当前租户、站点、用户和角色,并消费 Bell 下发的授权上下文,但不自建租户/RBAC 真相源。 + +### 3.2 Bell / 统一管理端 + +以下能力归 Bell/统一管理端,而不是在 Sense 重复建设一级页面: + +- Tenant、Site、Area 管理和 RBAC。 +- Area 的 `capture_policy` 编辑与已有成像设备的显式处置流程。 +- 全局审计查询;Sense 设备操作记录只提供带设备筛选的深链。 +- `site.max_video_channels` 的配置与真相源。 + +Area 与策略由 Bell 持有,Sense 使用带版本的只读投影执行新增/启用准入;投影未知或过期时 fail closed,只阻止新的成像变更,不中断已有链路。 + +--- + +## 4. 采纳的真实缺口 + +### 4.1 对账与运维中心(P0) + +- 未收敛项展示期望态/实际态具体差异、重试次数、退避间隔和下次重试时间。 +- 手动动作语义为“提高优先级并重新触发收敛”,不能绕过对账器直接修改实际资源。 +- 展示孤儿资源、占比、10% 安全闸及人工处置提示;不提供绕过安全闸的一键删除。 +- 展示媒体分片、边缘节点、控制隧道、数据面、补传队列和独立运维告警。 +- 明确“控制隧道断开但已有视频数据面仍正常”的组合态。 + +### 4.2 设备能力来源(P0) + +`capabilities` 必须来自探测/适配器结果并保存来源、探测时间与版本,不能由前端名称猜测。详情展示“已探测能力”和“当前生效能力”;重新探测显示新增/消失差异,能力降级时列出受影响的触发、Profile 或空间配置。 + +US-007 的采购白名单当前仍是版本化测试文档,无产品 UI;运行设备可只读显示“白名单型号/未验证型号”,不把白名单管理升级成 M2 P0 页面。 + +### 4.3 非视频适配器阶段态(P0) + +M1~M5 可登记 radar 等模态以验证信息架构和隐私准入,但实际态必须是 `adapter_not_ready`(用户文案“适配器未就绪 · M6”),不得显示在线/离线或模拟 MQTT 遥测连接,也不计入视频配额。 + +### 4.4 设备生命周期(P0) + +- 待激活作为可筛选状态,支持重新探测、校时、配额/策略复核、激活和逐项失败原因。 +- 认证失败与离线分开;更新凭据只写不读、不回显旧值,更新后显示重试结果。 +- 批量凭据仅允许安全导入逐设备凭据,不提供把同一密码覆盖到多台设备的一键操作。 +- Profile 切换展示对当前观看、推理、区域校准与短暂中断的影响。 + +### 4.5 写入降级与权限(P0) + +- 配额不可读:列表与已有视频可用,新增/启用被阻止。 +- Area 策略投影不可读/过期:只阻止新的成像变更,已有链路保持现状并告警。 +- 只读角色隐藏写操作;越权或资源不存在的深链使用统一安全拒绝态。 +- 原型角色切换器只用于枚举状态,不代表 Sense 拥有账号或权限数据。 + +### 4.6 措辞与可观察结果(P0) + +“暂停推理”统一为: + +> 解除推理侧对该路的订阅;有其他观看者时上游继续拉流,无其他 reader 时上游按需停止。 + +执行结果同时显示推理订阅、reader 数和上游拉流状态,避免实现成推理插件内部直接 `return` 而持续浪费带宽。 + +--- + +## 5. 降级或后置的建议 + +| 原建议 | 最终处理 | +| --- | --- | +| Sense 新增“站点与区域”一级导航 | 不采纳;Bell/统一管理端持有管理页,Sense 顶栏只做站点上下文切换 | +| Sense 新增“审计”一级导航 | 不采纳;保留设备操作记录并深链 Bell 全局审计 | +| 直接批量覆盖同一设备密码 | 不采纳;仅做逐设备写入或安全文件导入 | +| M2 提供跨媒体分片迁移 | 后置 M4;本轮只展示分片详情与影响范围 | +| M2 提供节点升级/重启 | 后置独立高风险运维任务;本轮只展示状态 | +| 提前为推理绑定、pre-roll、设备型触发创建空页面 | 不采纳;能力模型与运维子导航已保留扩展,不创建无操作价值的占位页 | + +--- + +## 6. 审计接口的独立架构任务 + +Bell 是全局审计真相源,但 T-004 不修改 `docs/api.md`。后续任务需要冻结 Sense → Bell 审计投递或等价投影契约,至少包含: + +- Sense 在执行高风险写操作前,把操作意图与审计 outbox 在本地持久化;不能“先执行后尝试记录”。 +- Bell 不可达时,只要本地 outbox 已持久化,业务操作可继续;恢复后幂等补投。 +- 明确租户/站点范围、事件 ID、操作者、目标、请求结果、重试与保留策略。 + +此项属于 API/一致性设计,不用原型中的 toast 代替契约。 + +--- + +## 7. 本轮实施边界 + +T-004 重新生成 Sense 原型并补 Bell 管理端入口,同时更新正式 US/IX 和本复核稿。`docs/api.md`、生产代码、事件 v0.1 与真实认证实现不在本任务修改;人工确认前 T-004 继续保持 `DOING`。 diff --git a/docs/raw/12-Sense原型-待办清单.md b/docs/raw/12-Sense原型-待办清单.md new file mode 100644 index 0000000..2129600 --- /dev/null +++ b/docs/raw/12-Sense原型-待办清单.md @@ -0,0 +1,189 @@ +# Sense 原型待办清单(第二轮复核后执行版) + +> 来源:《09-Sense原型评审-IX草稿》《10-Sense原型-功能模块缺口》《11-Sense原型-第二轮缺口》 +> 基准:Sense 提交 `e18a1ea` +> 适用任务:T-004 +> 原则:按产品边界执行,不把 Sense 一级导航扩成 8 项 + +--- + +## 1. 状态说明 + +- `本轮`:T-004 第三轮原型必须完成。 +- `后置`:已确认方向,但不在本轮画完整动作。 +- `独立任务`:写路径或契约不同,不在 T-004 顺带修改。 +- `完成`:当前原型已有,不重复实现。 + +--- + +## 2. 最终导航与系统归属 + +### Sense(五个一级入口) + +```text +运行总览 · 实时监控 · 设备 · 接入任务 · 运维 +``` + +“运维”内部使用二级 Tab:对账、分片、边缘节点、运维告警、系统状态。移动端底部导航保持五项。 + +### Bell / 统一管理端 + +- Tenant / Site / Area 与 `capture_policy` 管理。 +- RBAC 与当前用户授权上下文。 +- 全局审计查询和设备筛选深链。 +- 站点视频配额真相源。 + +Sense 只消费上述上下文和带版本投影,不复制真相源。 + +--- + +## 3. 本轮执行项 + +### S-01 运维中心与对账队列 · P0 · 本轮 + +- 总览“待收敛项”可下钻。 +- 展示期望态/实际态差异、重试次数、退避间隔、下次重试时间。 +- “重新触发收敛”只提高任务优先级,不直接绕过对账器修改资源。 +- 展示孤儿资源与 10% 安全闸;安全闸触发时禁止删除并说明人工恢复路径。 +- 分片、边缘节点、运维告警和系统状态作为运维二级页。 + +验收:能打开某个未收敛项并查看差异;能看到安全闸和下一次重试时间。 + +### S-02 角色与安全拒绝态 · P0 · 本轮 + +- 顶栏显示当前用户和角色,提供“站点管理员/只读”原型切换。 +- 只读模式隐藏新增、激活、停用、更新凭据、保存区域等写操作。 +- 越权深链显示统一拒绝态,不泄露资源是否存在。 +- 角色切换只是原型演示,授权真相源仍在 Bell。 + +### S-03 租户/站点上下文与 Area 归属 · P0 · 本轮 + +- Sense 顶栏显示当前租户并支持站点切换;切换后示例列表与计数同步更新。 +- Bell 增加站点/Area 管理入口,展示配额来源与 `capture_policy`。 +- 把已有视频设备的 Area 改为 `non_imaging_only` 时,要求先迁移设备、取消修改或进入显式处置流程,不静默停用。 + +### S-04 全局审计深链 · P1 · 本轮 + +- Sense 不新增一级审计页。 +- 设备详情“操作记录”增加“在 Bell 查看全部审计”,携带 tenant/site/device 筛选上下文。 +- Bell 审计页消费这些参数并显示来源为 Sense。 + +### S-05 capabilities 探测与差异 · P0 · 本轮 + +- 详情显示厂商、型号、固件、认证方式、Profile、校时与 ONVIF 事件订阅能力。 +- 区分已探测能力与当前生效能力,记录上次探测时间。 +- “重新探测”显示新增/消失能力及受影响配置,不自动覆盖。 +- 只读显示采购白名单结果;白名单维护继续使用 M0 文档,不新增管理页。 + +### S-06 适配器未就绪 · P0 · 本轮 + +- radar 可登记并进入台账,但实际态为“适配器未就绪 · M6”。 +- 不显示在线/离线、MQTT 实时遥测或测试连接成功。 +- 不计入视频配额,仍参与 `non_imaging_only` 准入判断。 + +### S-07 待激活闭环 · P0 · 本轮 + +- 状态筛选包含待激活,列表至少有一条示例。 +- 详情提供重新探测、校时、配额/区域策略复核和激活。 +- 批量激活展示逐项成功/失败及可重试原因。 + +### S-08 认证失败与凭据更新 · P0 · 本轮 + +- 认证失败作为独立实际态。 +- 凭据更新只写不读,不回显旧值;更新后自动重试并显示结果。 +- 批量场景仅演示安全文件逐设备导入,不提供同一密码批量覆盖。 + +### S-09 写入降级态 · P0 · 本轮 + +- 状态演示新增“配额不可读”和“区域策略不可读”。 +- 两态下实时监控和设备读取保持可用;新增/启用等相关写操作禁用并就地解释。 +- 已有设备不被伪装为停用或已收敛。 + +### S-10 边缘节点与隧道 · P1 · 本轮 + +- 展示节点版本、在线时长、承载数、控制隧道、视频数据面和补传队列。 +- 至少演示“隧道断开 / 视频数据面正常”和“恢复后补传”组合态。 +- 节点升级/重启只显示为后置能力,不提供可执行按钮。 + +### S-11 Profile 切换 · P1 · 本轮 + +- 展示主/子 Profile 和当前用途。 +- 切换前说明短暂中断、reader、推理和区域待校准影响。 +- 原型不执行真实媒体操作。 + +### S-12 分片详情 · P1 · 本轮(迁移后置) + +- 展示承载设备、实际码率、重连历史与单分片故障影响范围。 +- 标注 32 为可配置建议容量,最终由压测确定。 +- 跨分片迁移动作后置 M4,本轮不提供按钮。 + +### S-13 批量任务与逐项结果 · P0 · 本轮 + +- 任务列表、预校验结果、逐行失败原因、单行/失败项重试、错误清单导出。 +- 明确部分成功语义:成功项已经生效,失败项可重试,不做整体回滚。 + +### S-14 运维告警 · P1 · 本轮 + +- 展示离线、认证失败、时间漂移、收敛失败、分片异常和隧道断开。 +- 明确运维告警不会进入 Bell 业务预警队列或通知家属。 +- 运维静默/通知配置后置,原型只显示入口归属。 + +### S-16 时间显示口径 · P1 · 本轮 + +- 默认显示服务器时间与时区。 +- 相对时间同时提供完整时间戳;设备时间只在漂移语义中出现。 +- 审计和对账示例使用同一口径。 + +### S-17 当前租户 · P1 · 本轮 + +- 顶栏显示当前租户;首期私有部署不提供租户切换器。 +- 原型文案说明列表已经按认证上下文的 tenant/site 过滤。 + +### S-18 暂停推理措辞与结果 · P0 · 本轮 + +- 文案改为“解除推理侧订阅;无其他 reader 时上游按需停止”。 +- 结果展示推理订阅、reader 数和上游拉流状态。 + +### S-19 分片容量标注 · P2 · 本轮 + +- `32` 标注为“当前配置/建议容量”,不是产品硬上限。 + +--- + +## 4. 已完成,不重复执行 + +| 编号 | 状态 | 证据 | +| --- | --- | --- | +| S-15 设备分页 | 完成 | 5 条/页、上一页/下一页、页数和总数已实现 | +| S-20 推理收敛视觉 | 完成 | 已改为绿色“推理配置收敛 16/16” | +| 第一轮 IX-014~IX-018 | 完成 | 模态/能力、三种停用、隐私准入、几何方向、草稿和深链均已落地 | + +--- + +## 5. 后置与独立任务 + +| 编号 | 处理 | +| --- | --- | +| S-21 Sense → Bell 审计契约 | 独立任务修改 `docs/api.md`;采用本地持久化 transactional outbox + 幂等补投 | +| S-22 推理绑定运维 | M3 在“运维”内新增二级能力,不预建空页面 | +| S-23 pre-roll 运维 | M3 需求稳定后新增,不预建空页面 | +| S-24 设备型触发配置 | M6 随非视频适配器实现,不预建空页面 | +| 跨媒体分片迁移 | M4 容量/分片任务 | +| 节点升级/重启 | 独立高风险运维任务,需要权限、回滚和维护窗口 | + +--- + +## 6. 总验收 + +- [x] Sense 一级导航保持 5 项,移动端不出现第 6 个底部入口。 +- [x] 运维中心可查看未收敛差异、退避、孤儿与安全闸。 +- [x] 只读角色下所有写操作消失,越权深链显示安全拒绝态。 +- [x] radar 显示“适配器未就绪 · M6”,不显示在线或模拟遥测成功。 +- [x] 能力重新探测显示差异,能力降级不自动覆盖依赖配置。 +- [x] 待激活、认证失败、凭据更新和逐项激活结果可演示。 +- [x] 配额/策略不可读时只阻止相关写操作,已有流与读取可用。 +- [x] “暂停推理”展示订阅、reader 和上游拉流结果。 +- [x] Bell 可管理 Site/Area 策略并显式处理已有成像设备。 +- [x] Sense 设备审计深链到 Bell,并保留 tenant/site/device 筛选。 +- [x] 1440×900、375×812、812×375 无页面级横向溢出;主要移动控件不小于 44px。 +- [x] 运行时无异常,`git diff --check` 与 `./init.ps1` 通过。 diff --git a/docs/raw/14-Bell原型评审.md b/docs/raw/14-Bell原型评审.md new file mode 100644 index 0000000..b0c9fa3 --- /dev/null +++ b/docs/raw/14-Bell原型评审.md @@ -0,0 +1,57 @@ +# Bell 原型评审(复核定稿) + +> 评审对象:`docs/design/bell/index.html` +> 输入:Claude 首轮评审草稿;YoVision 需求、架构、US、IX 与路由文档 +> 复核日期:2026-08-04 + +## 1. 结论 + +Claude 指出的投递状态、Event↔Alert 关系、交接班、分页、规则回滚和验收报表缺口成立,应在 T-004 内修复。Area 归属、并发 ack、失败态和重启可观测性的部分结论需要校正;另外原评审遗漏了移动端管理入口与审计深链注入风险。 + +## 2. 本轮采纳 + +| 优先级 | 项目 | 最终要求 | +| --- | --- | --- | +| P0 | 投递事实 | `sent`、`delivered`、`seen`、`ack` 分开;不支持回执、状态未知、可重试失败和最终失败不得伪装为成功。ack 属于 Alert 处置事实,不是通道投递状态。 | +| P0 | Event↔Alert | Alert 详情展示关联 Event 与聚合原因;Event 详情展示触发的 Alert 与最终状态;两边可导航。抑制可能不创建 Alert,不能把“已处置抑制”误写成聚合原因。 | +| P1 | 并发 ack | 首个服务端成功者成为处置人;后到者看到当前处置人与确认时间,不能覆盖,也不能显示双成功。 | +| P1 | 交接班 | 展示未 ack、处置中和升级中的 Alert;明确交出人、接手人、备注和确认审计;交接期间升级链不中断。 | +| P1 | 局部失败 | 保留弱网证据降级;新增会话过期、ack 竞争结果、规则版本冲突,以及投递的可重试/最终失败。失败应靠近对应操作,不扩展成无意义的全页状态集合。 | +| P1 | 分页 | 事件中心和审计日志均提供总数、页码、上一页与下一页,不一次加载全部记录。 | +| P2 | 规则回滚 | 查看版本差异与影响范围;回滚通过创建并发布新版本完成,历史版本不可变。 | +| P2 | 验收报表 | 按规则版本和冻结样本窗口报告召回率、每路每天误报数及样本量;明确不提供跨场景统一“准确率”。 | + +## 3. 校正与不采纳 + +1. Area 已在 `raw/12`、US-010、IX-016 和架构文档中冻结为 Bell 管理,Sense 只消费版本化投影;“重写 S-03”属于过期建议,本轮不重复修改。 +2. 《13》A-2 的同库只读视图是独立架构裁决,不因原型评审直接采用。本轮继续保持 Bell 真相源与受控 API/投影边界,不修改 schema、API 或跨库访问方式。 +3. 原型已有并发 ack 文案,但没有可演示的竞争结果,因此补交互而不是从零新增概念。 +4. `weak` 已覆盖结构化事件成功、视频证据失败的部分成功态;“一个失败态都没有”不准确。本轮补操作级失败和会话过期,不机械增加三个全局错误页。 +5. 进程重启续跑是后端恢复、指标和测试要求。正常值班时间线不展示内部服务重启;只有确实影响用户的异常恢复才进入业务时间线,本轮不添加常态重启节点。 + +## 4. 原评审遗漏 + +- 移动端底部主导航继续限制为 5 项,但通过顶部“管理”入口访问站点与 Area、审计日志,避免管理能力在窄屏不可发现。 +- 桌面侧栏分成“值班与业务”和“管理”两组,避免权限与运营入口混在同一层级。 +- Sense→Bell 审计深链的 `device` 参数不得通过 `innerHTML`/`insertAdjacentHTML` 拼接;必须按文本节点写入并对返回链接编码,防止原型把不可信查询参数变成 DOM 注入。 + +## 5. 实施顺序 + +1. 修复审计深链注入。 +2. 补投递状态模型和 Event↔Alert 双向关系。 +3. 补并发 ack、交接班与操作级失败。 +4. 补事件/审计分页和移动端管理入口。 +5. 补规则回滚与按规则版本的验收报表。 +6. 用桌面、竖屏手机和横屏手机验证可访问性、无横向溢出及运行时安全;人工确认前 T-004 继续保持 `DOING`。 + +## 6. 产品裁决补充:联系人、排班与升级策略 + +采纳“联系人管理和排班一次设计到位”的方向,但将“同源”修正为“共享主数据、分对象建模”: + +- 联系人/成员保存身份、角色、值班组和已验证通知通道,不承载班次与轮换字段。 +- 值班排班引用联系人或值班组,保存站点时区、班次、周轮换、生效日期、临时替班、版本和冲突校验,不复制手机号。 +- 升级策略的每一步使用 `person / team / on_call_schedule` 类型化目标,不直接写号码;界面提供当前解析人与通道预览。 +- 每次投递创建时固化实际收件人、通道与排班版本快照,后续联系人或排班变更不改写历史事实。 +- 交接班只转移进行中 Alert 的处置责任;未来班次变化必须走临时替班并发布新排班版本。 + +信息架构继续保留一级“升级链”,内部以“升级策略 / 值班与排班 / 联系人与通道”三个二级模块渐进披露。M3 原型覆盖周轮换、时区、生效日期、替班、空档/重叠冲突、值班人预览、版本发布和审计;自动排班优化、外部日历同步、工时合规与自助换班后置,不在 T-004 扩展。 diff --git a/docs/routes.md b/docs/routes.md index 2df3a14..40e41f4 100644 --- a/docs/routes.md +++ b/docs/routes.md @@ -9,13 +9,14 @@ | `/overview` | 站点、设备、事件和预警摘要 | 业务预警与运维告警分区 | | `/sites` | 站点列表、配额与状态 | 显示 16 默认/128 上限,不暗示单机能力 | | `/sites/:siteId/devices` | 设备列表、批量导入/启停、健康 | 分页/虚拟列表、逐项结果、不泄露凭据 | -| `/events` | 事件筛选与批量处置入口 | 事件与预警状态分开显示 | -| `/events/:eventId` | 事实、证据、时间线、outcome | 权限最小化;弱网渐进加载 | -| `/alerts` | 待 ack、升级中、已结束预警 | 清楚区分投递/送达/看到/ack | -| `/rules` | 场景包、规则继承、区域/时段配置 | 显示继承来源与试运行状态 | -| `/escalations` | 联系人、通道、超时与静默 | 双路径;静默 ≤4h,无永久项 | +| `/events` | 事件筛选与批量处置入口 | 事件与预警状态分开显示;服务端分页,不一次加载全量 | +| `/events/:eventId` | 事实、证据、时间线、outcome 与触发的 Alert | 权限最小化;弱网渐进加载;与 Alert 双向导航 | +| `/alerts` | 待 ack、升级中、已结束预警 | 清楚区分已发出/已送达/已看到/ack;支持值班交接 | +| `/alerts/:alertId` | Alert 处置、投递/升级事实与关联 Event | 展示聚合原因;ack 竞争不覆盖;与 Event 双向导航 | +| `/rules` | 场景包、规则继承、区域/时段配置 | 显示继承来源、试运行、不可变版本和回滚状态 | +| `/escalations` | 升级策略、值班排班、联系人和通道 | 一个一级入口下渐进展示三个二级模块;共享人员/值班组/已验证通道主数据但分对象建模;策略使用人员/组/排班类型化目标,支持解析预览、排班版本/替班/冲突与投递快照;双路径,静默 ≤4h,无永久项 | | `/operations` | 设备/流/分片/对账运维 | 不与业务预警混在同一队列 | -| `/audit` | 审计查询 | 只读、分页、按权限脱敏 | +| `/audit` | 审计查询 | 只读、服务端分页、按权限脱敏;深链筛选参数仅按文本渲染 | 这些是页面职责占位,不等于已冻结 URL;实现任务须更新本文件后再编码。 @@ -26,6 +27,8 @@ - 设备:最小健康状态,不提供未经授权的常态监控。 - 我的:联系人、通知偏好和限时静默。 +Bell 响应式管理端的底部主导航最多 5 项;Site/Area、RBAC 与审计通过顶部“管理”菜单进入,不能因为窄屏隐藏侧栏而失去入口。桌面侧栏把值班/事件/规则/升级/报表与 Site/Area/审计分组显示。 + ## 值班台/大屏 - 实时事件流与高优先级预警。 diff --git a/docs/tasks/T-004.md b/docs/tasks/T-004.md index 2fddcd5..843932c 100644 --- a/docs/tasks/T-004.md +++ b/docs/tasks/T-004.md @@ -3,47 +3,67 @@ id: T-004 title: 设计 Sense 与 Bell 交互原型 phase: 0 deps: [T-002] -status: TODO +status: DONE created: 2026-08-03 issue: 6 -context_ref: null -claim_branch: null -work_branch: null +context_ref: 32b9859a405a4d64c03b6d3ae765340bc37fdfa0 +claim_branch: claims/T-004 +work_branch: agent/codex/T-004 write_paths: - docs/tasks/T-004.md - 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/raw/14-Bell原型评审.md + - docs/routes.md + - docs/08-interaction-checklist.md + - docs/07-user-stories.md + - docs/02-requirements.md + - docs/04-architecture.md + - docs/raw/02-需求分析.md + - docs/raw/03-通用场景应用方案.md + - docs/raw/08-三系统职责划分.md --- ## 问题 / 背景 Sense 与 Bell 尚无可供产品确认的页面结构。生产 UI 开工前,需要用两个零构建依赖的单文件 HTML 原型枚举导航、控件、主要状态与高频工作流,避免直接从实现代码猜交互。Sense 可参考 MiBeeNvr 的监控、摄像头与仪表盘信息架构,但必须补齐 YoVision 的设备健康、分片/期望态、批量开通和区域/警戒线编辑;Bell 必须体现事件与 Alert 分离、ack、升级链、证据、误报和权限边界。 +产品评审进一步区分“检测区域”和“告警规则”:前者依附具体摄像头画面、分辨率与坐标系,应在摄像头详情中编辑;后者包含场景、继承、时段、持续时间、试运行、发布与升级链,应由 Bell 管理。后端系统边界不得迫使用户丢失当前摄像头或规则草稿上下文。 + ## 关联需求与交互(如适用) -- 用户故事:Sense 关联 US-001、US-002、US-005;Bell 关联 US-003~US-006。 -- 交互清单:Sense 关联 IX-001~IX-004、IX-010~IX-011;Bell 关联 IX-005~IX-013。 -- 相关页面 / 路由:原型阶段为 `docs/design/sense/index.html` 与 `docs/design/bell/index.html`,不定义生产路由。 +- 用户故事:Sense 关联 US-001、US-002、US-008、US-009,并为 US-005 提供视频设备空间配置;Bell 关联 US-003~US-006、US-010~US-013,并拥有 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~IX-023,负责规则继承/试运行/发布/回滚、联系人/排班/升级策略、站点与 Area 策略、值班交接、验收报表和全局审计。 +- 相关页面 / 路由:原型阶段为 `docs/design/sense/index.html` 与 `docs/design/bell/index.html`;同步补充 `docs/routes.md` 的候选页面职责,但不冻结或实现生产 URL。 ## 方案 1. 使用统一的 YoVision 深色安防控制台设计系统,Sense 与 Bell 保持品牌、状态色、控件和导航规律一致。 -2. Sense 制作为单页可交互工作台:总览、监控墙、设备、区域规则、接入任务和系统状态;区域编辑器支持多边形、警戒线、撤销、清空、键盘替代和保存反馈。 -3. Bell 制作为单页可交互值班台:预警队列、事件证据、ack/处置、升级时间线、误报反馈、规则和升级链概览。 -4. 两个原型均内联 CSS/JS,使用假数据,不加载真实视频、客户信息、生产地址或外部依赖;顶部固定标注原型用途。 -5. 完成桌面、窄屏、键盘焦点、加载/空态/错误切换和 `prefers-reduced-motion` 检查,提交人工评审;产品确认前不把任务标为 `DONE`。 +2. Sense 制作为单页可交互工作台:总览、监控墙、设备、接入任务和运维中心,移动端也固定为这 5 个入口;不设置一级“区域规则”或全局管理页。运维中心聚合对账、分片、边缘/隧道、运维告警和系统状态。统一设备台账使用 `modality + capabilities` 决定详情页和操作,M1~M5 完整展示视频设备,非视频设备在 M6 前明确显示 `adapter_not_ready`,不得虚构遥测。 +3. 视频设备在“画面与检测区域”页签完成多边形、方向警戒线、显式完成、方向反转、逐点编辑、会话草稿恢复、乐观并发冲突和待校准反馈;Sense 只保存空间几何并只读显示关联规则,不提供业务规则绑定、时段、持续时间、试运行或正式发布。 +4. Bell 制作为单页可交互值班台和统一管理端:通道的已发出/已送达/已看到与 Alert ack 分开,Event↔Alert 可双向导航;并发 ack 显示真实处置人,班次交接不暂停升级链;规则编辑必须选择摄像头与检测区域版本,并负责继承、时段、持续时间、试运行、发布和以新版本完成回滚;Bell 同时管理 Site/Area/配额/`capture_policy`,策略与已有成像设备冲突时必须显式迁移或取消。 +5. Sense 摄像头详情与 Bell 规则草稿通过可演示的相对深链互相进入,携带摄像头/区域上下文;原型可以跨文件,但生产产品不得要求用户重新查找同一摄像头或丢失未完成草稿。 +6. 两个原型均内联 CSS/JS,使用假数据,不加载真实视频、客户信息、生产地址或外部依赖;顶部固定标注原型用途。 +7. 添加设备时先选择类型,依据能力渐进展示字段;区域的 `capture_policy` 负责隐私准入,视频设备在“仅非成像设备”区域中的新增或启用必须被阻止,策略不可用时对新写入失败关闭。 +8. 全局头部展示租户、站点、账号和角色;只读角色隐藏写操作,深链越权不泄露资源是否存在。Sense 设备日志带租户/站点/设备条件跳到 Bell 全局审计并可返回。 +9. 完成桌面、窄屏、横屏、键盘焦点、加载/空态/错误/依赖降级切换和 `prefers-reduced-motion` 检查,提交人工评审;产品确认前不把任务标为 `DONE`。 +10. Bell 事件与审计列表必须分页;规则验收报表按规则版本和冻结样本窗显示召回率与每路每天误报数,不提供跨场景统一准确率;移动端底部主导航保持 5 项,通过顶部“管理”入口访问 Site/Area 与审计。 +11. Bell 一级“升级链”内部统一设计升级策略、值班与排班、联系人和通道三个二级模块:共享人员/值班组/已验证通道主数据但分对象维护;升级步骤引用人员/组/排班类型化目标,排班支持时区、周轮换、生效日期、临时替班、冲突检查、解析预览、版本发布和审计,投递保留解析快照。 ## 不可变约束 -- 阈值 / 数值边界:默认 16 路、单站点上限 128 路;静默最长 4 小时;原型不得暗示 128 路同时播放主码流。 -- 判定式 / 状态转换:事件事实不可被处置改写;Alert 的首次投递、送达、看到、ack 和升级必须分开展示;区域规则正式发布与试运行必须可区分。 +- 阈值 / 数值边界:默认 16 路视频、单站点视频上限 128 路;非视频设备不占视频路数;单媒体分片初始配置建议 `max_streams=32`、当前示例承载 16、最多 4 个分片,最终以压测为准;静默最长 4 小时;原型不得暗示 128 路同时播放主码流。 +- 判定式 / 状态转换:事件事实不可被处置改写;Alert 的首次投递、送达、看到、ack 和升级必须分开展示;检测区域版本与告警规则版本是不同对象;规则正式发布与试运行必须可区分,保存区域不得自动发布规则。 - 安全边界:不得展示摄像头密码、完整 RTSP/ONVIF 地址、token、真实客户/未成年人数据或人脸入口;破坏性动作须确认。 -- 既有契约:原型不修改事件 v0.1、API、路由和生产技术栈,不作为生产实现代码。 +- 既有契约:原型不修改事件 v0.1、API、schema、生产路由实现和生产技术栈;仅补充候选路由职责,不作为生产实现代码。 ## 验收要点 -- 任务相关验证:两个 HTML 可本地打开、无外部依赖;关键按钮和状态切换可用;运行 HTML 结构检查、`git diff --check` 与 `./init.ps1`。 -- 完整门禁:本任务不修改 schema/API/路由,因此不触发契约与导航实现门禁;若范围变化则先更新任务。 +- 任务相关验证:两个 HTML 可本地打开、无外部依赖;关键按钮和状态切换可用;Sense 一级导航固定 5 项且无“区域规则”,设备列表可按类型/生命周期筛选与分页,视频详情可编辑检测区域,非视频适配器未交付时不伪装在线;运维中心覆盖对账/分片/边缘/运维告警/系统状态;Bell 可演示投递事实、Event↔Alert、并发 ack、交接班、事件/审计分页、试运行、正式发布、新版本回滚、验收报表、移动端管理入口、Site/Area 策略冲突,以及升级策略/排班/联系人二级模块、动态目标解析、排班发布/替班/冲突和投递快照;Sense↔Bell 规则深链保留 `camera + zone + return_to`,审计深链保留 `tenant + site + device + return_to` 且只按文本渲染参数;运行 HTML 结构检查、`git diff --check` 与 `./init.ps1`。 +- 完整门禁:本任务不修改 schema/API 或生产路由实现,因此不触发契约实现门禁;候选路由职责已随 IX 更新。若实现范围变化则另立任务。 - 人工 / 设备验收:必需。项目负责人分别打开 Sense 与 Bell 原型,确认页面结构、控件集合和主要工作流;未确认前不得标记 `DONE` 或合并为最终设计。 - 构建产物:`docs/design/sense/index.html`、`docs/design/bell/index.html`;双击浏览器打开,零构建依赖。 @@ -56,13 +76,92 @@ Sense 与 Bell 尚无可供产品确认的页面结构。生产 UI 开工前, - 责任 Agent:codex。 - 唯一写入者:codex。 - 委派:不启用。 -- Gitea:主 Issue 为 #6;领取必须从精确 `context_ref` 建立 claim 与工作分支。 +- Gitea:主 Issue 为 #6;`context_ref` 为 `32b9859a405a4d64c03b6d3ae765340bc37fdfa0`,claim 为 `claims/T-004`,工作分支为 `agent/codex/T-004`。 任何新增写路径先检查与其他活跃任务是否重叠;同一时刻只有一个 Agent 修改本任务的 `write_paths`。 ## 执行记录 +### 2026-08-04 人工验收通过与任务完成 + +- 项目负责人确认 Sense 与 Bell 原型均可接受,人工验收门禁通过;确认范围包括最终页面信息架构、控件集合、主要工作流,以及 Bell 最新的“升级策略 / 值班与排班 / 联系人和通道”分对象设计。 +- 两份原型的任务相关自动化验证已在前述执行记录中完成:HTML/脚本静态检查、桌面与窄屏浏览器交互、无横向溢出、运行时无异常、`git diff --check` 与 `./init.ps1` 均通过。 +- T-004 状态更新为 `DONE`。本次确认冻结原型阶段的产品方向;后续生产实现、API/schema 契约和高级排班能力仍须另立任务,不由本任务隐含扩展。 + +### 2026-08-04 联系人、排班与升级策略产品裁决 + +- 采纳“一次设计到位”的方向,并将“同源”修正为“共享主数据、分对象建模”:Contact/Team 管身份和已验证通道,OnCallSchedule/Version/Exception 管时区、轮换和替班,EscalationStep 使用人员/组/排班类型化目标;DeliveryAttempt 固化实际收件人、通道与排班版本快照。 +- 正式需求、架构、US-005/US-013、IX-012/IX-023、候选路由和 `raw/14` 已同步。交接班继续只转移进行中 Alert,未来替班必须形成排班草稿并发布新版本;高级自动排班、外部日历、工时合规和自助换班后置。 +- Bell 保留一级“升级链”,内部新增“升级策略 / 值班与排班 / 联系人和通道”三个二级模块。策略可切换 `person / team / on_call_schedule` 并预览解析结果;排班覆盖 Site 时区、周轮换、覆盖率、空档/重叠阻断、临时替班、v13 发布与版本审计;联系人表单不含班次/轮换字段,通道需要验证且被引用时不可直接删除。 +- Node.js 内联脚本、167 个唯一 ID、114 个按钮可访问名、全部表单标签、外部依赖和危险 DOM API 检查通过。Edge/CDP 在 1440×900、375×812、812×375 验证动态目标、解析快照、排班冲突、替班草稿、版本发布、联系人边界、交接边界和二级模块深链:页面级无横向溢出,移动端二级按钮不小于 44px,运行时 0 exception;临时 QA 脚本未写入仓库。 +- 自动化验收完成后 T-004 仍保持 `DOING`;需项目负责人打开 Bell 原型人工确认升级链信息架构和排班边界,确认前不合并 PR、不标记 `DONE`。 + +### 2026-08-04 Bell 原型评审复核与修复 + +- 将 Claude 评审复核为最终裁决并保存到 `raw/14`:采纳投递状态、Event↔Alert、交接班、分页、回滚和验收报表;纠正 Area 归属、A-2、并发 ack 现状、弱网失败态和重启 UI 建议;额外识别移动端管理入口与审计深链 DOM 注入。 +- Bell 桌面侧栏分为“值班与业务”和“管理”,移动端底部导航继续固定 5 项并增加顶部“管理”菜单。投递时间线分开展示已发出、已送达、已看到、无回执、通道不支持、可重试与最终失败,Alert ack 继续独立。 +- Alert 详情与 Event 详情支持双向打开并展示聚合/未触发原因;补齐服务端首个成功者语义的并发 ack 演示、值班交接、事件/审计分页、会话过期、规则版本冲突、不可变新版本回滚和按规则版本的验收效果表。 +- 审计深链不再把 `device` 查询参数拼入 HTML,改为 `textContent` 与 DOM 节点构造;恶意 `` 参数专项验证未创建节点、未执行脚本且保持安全文本显示。本轮不采纳 A-2 数据库视图,不修改 API/schema,也不在正常值班时间线展示内部服务重启。 +- Node.js 内联脚本语法、124 个唯一 ID、按钮可访问名、外部依赖和危险 DOM API 静态检查通过。Edge/CDP 在 1440×900、375×812、812×375 验证投递事实、双向关系、并发 ack、交接、分页、规则冲突/回滚、验收报表、会话过期、移动管理与深链注入:页面级无横向溢出,移动导航与管理入口不小于 44px,运行时 0 exception;桌面值班台和窄屏管理页已目检,临时 QA 脚本未写入仓库。 +- 自动化验收完成后任务仍保持 `DOING`;项目负责人必须打开 Bell 原型确认信息架构、投递语义和交接/回滚流程,确认前不合并 PR、不标记 `DONE`。 + +### 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` 并确认按复核后的最终建议继续修改。复核结论为:设备模态、停用收敛、隐私准入、几何编辑、草稿恢复与无障碍问题方向成立,但分片容量来源、页内草稿丢失和双向深链现状等证据需纠正。 +- T-004 继续保持唯一活跃任务;dispatcher 已在 Issue #6 发布 `CLAIM RENEWAL`,将本轮涉及的评审稿、US/IX、需求/架构与 Sense/Bell 原型加入 `write_paths`。当前没有其他活跃任务占用这些路径。 +- 本轮按 `docs/design/README.md` 的显著改版规则重新生成 Sense 页面结构,不恢复一级“区域规则”;一级入口改为“设备”,详情按 `modality + capabilities` 渐进展示,视频设备仍在详情中维护画面检测区域,Bell 继续独占业务规则与发布。 + +### 2026-08-04 Claude 评审续修实现与自测 + +- 将评审结论回写到需求、架构、用户故事和 IX:设备以 `modality + capabilities` 建模,隐私策略归属 Area;M2 冻结通用信息架构与视频准入,M6 再实现非视频适配器。明确幂等只消除重复副作用,每次请求仍写审计;暂停推理、停用接入和断开会话为三个不同动作。 +- Sense 已重构为通用设备台账:17 台示例设备、5 条/页、类型/状态/搜索筛选,视频配额单独显示为 16 / 128;雷达详情展示遥测能力和通用健康且隐藏视频区域页签。添加设备对话框按能力切换字段,并验证视频设备会被“仅非成像设备”区域阻止、雷达仍可接入。 +- 区域编辑补齐显式完成、警戒线箭头与方向反转、逐点键盘编辑/删除、双击防重复顶点、`sessionStorage` 会话草稿恢复、版本冲突阻止覆盖;工具切换会先确认,页内导航不清除草稿。Sense 与 Bell 双向链接统一携带 `camera + zone + return_to`,Bell 会读入并保留区域上下文。 +- Node.js 内联脚本编译、唯一 ID/标签目标/外部资源静态审计均通过;关键前景/背景组合对比度为 5.93~16.43:1。Edge Headless/CDP 在 1440×900、375×812 与 812×375 实测设备筛选、雷达详情、隐私准入、区域方向与冲突、Tab 方向键、停止操作收敛和双向深链;页面级无横向溢出、移动端无低于 44px 的可见主要控件、运行时 0 exception。截图已人工检查且未写入仓库。 +- 任务仍保持 `DOING`:需项目负责人打开两份原型确认最终信息架构与主要工作流,确认前不合并 PR、不标记 `DONE`。 + ### 2026-08-03 任务定义 - 依据用户请求、US-001~US-006、IX-001~IX-013 和 MiBeeNvr 本地只读截图定义两个单文件原型范围。 - 人工验收为必需门禁;原型完成后先进入评审,不自动视为最终设计。 + +### 2026-08-03 领取与基线 + +- dispatcher `ila` 已将 Issue #6 分配给 `codex`,claim 与工作分支均从精确 `context_ref` 创建并读回一致。 +- 在独立 worktree `D:\OPC\yovision-T-004` 开始工作;写入范围仅限本任务声明的三个路径。 + +### 2026-08-04 原型实现 + +- 使用 `ui-ux-pro-max` 生成并复核统一设计系统:深色专业安防控制台、高信息密度、系统字体、语义状态色、150–300ms 微交互、明确焦点和 reduced-motion;Sense 使用青蓝强调接入/画面,Bell 使用紫色强调处置/状态机。 +- 首版 `docs/design/sense/index.html` 覆盖运行总览、4 路按需监控、摄像头期望态/实际态、批量接入、系统健康,以及多边形/方向警戒线的鼠标绘制、坐标键盘替代、撤销、草稿、试运行和发布确认;后续产品评审修订见下文。 +- `docs/design/bell/index.html` 已覆盖预警队列、事件事实与证据、一次点击 ack、升级倒计时和投递事实、处置结果、误报反馈、规则、升级链、报表和审计;弱网时先显示结构化事实并允许证据后台重试。 +- 两个文件均为单文件内联 CSS/JS,无外部依赖、真实视频、客户数据、连接串或人脸入口;顶部均固定显示原型用途提示。 + +### 2026-08-04 自测结果 + +- 标准库 HTML 结构审计通过:两文件均有 viewport、原型横幅、reduced-motion,无重复 `id`、无未命名按钮、无不可识别表单控件和外部 HTTP 资源;Sense 统计 40 个按钮/21 个控件,Bell 统计 42 个按钮/14 个控件。 +- Playwright 在 1440×900 与 375×812 视口实测:两页页面级 `scrollWidth == clientWidth`,桌面三栏和移动底部导航正常,浏览器控制台 0 error / 0 warning;桌面与移动关键状态截图已人工检查,临时 QA 图片未写入仓库。 +- Sense 实测坐标点添加、草稿状态、保存反馈、设备导航、添加摄像头对话框和 Esc 退出;Bell 实测一键 ack、升级计时停止、弱网状态、误报必填校验、错误焦点和 Esc 退出。 +- 尚待项目负责人分别打开两个 HTML,确认页面结构、控件集合和主要工作流;在收到确认前任务保持 `DOING`。 + +### 2026-08-04 产品评审修订 + +- 项目负责人指出 Sense 的区域规则没有融合到摄像头模块。复核 US-001/US-002 与 US-005 的角色和任务后,确认原型把“摄像头空间几何”和“业务告警规则”混为同一一级模块,且让微服务边界影响了用户操作路径。 +- 采纳“领域分离、体验连续”的产品方案:Sense 摄像头详情维护检测区域与校准状态;Bell 维护业务规则、试运行和正式发布;通过携带摄像头/区域上下文的深链连接两个原型。 +- `ui-ux-pro-max` 的导航层级、渐进披露、深链与状态保持原则用于本轮修订;默认 16 路从摄像头详情进入,128 路仍通过设备列表的筛选、分页与区域状态列治理,不恢复独立的一级区域编辑入口。 + +### 2026-08-04 修订后自测 + +- 标准库 HTML 审计通过:Sense 69 个唯一 `id`、40 个有名称按钮、16 个有标签控件;Bell 67 个唯一 `id`、50 个有名称按钮、21 个有标签控件;两页均无外部 HTTP 资源。专项断言确认 Sense 不再存在一级 `zones` 页面、规则发布按钮或试运行开关。 +- Node.js 对两个内联脚本执行语法编译检查通过。Edge Headless/CDP 在 1440×900 与 375×812 验证摄像头详情、坐标绘制、区域保存、画面参数变化后待校准、Sense→Bell 深链、Bell 规则草稿、Bell→Sense 返回链和正式发布确认;页面无横向溢出,控制台 0 error,运行时 0 exception。 +- 浏览器测试首次发现 Sense 移动端区域画布受 `min-height + aspect-ratio` 影响发生横向溢出,并发现条件上下文条的 `hidden` 被组件 `display` 覆盖;两项均已修复并重新通过桌面/移动截图人工检查。临时 QA 截图未写入仓库。 +- `./init.ps1` 通过:上下文校验、16 个治理单测与完整治理检查均成功;`git diff --check` 通过。任务继续保持 `DOING`,等待项目负责人确认修订后的信息架构与工作流。 +