yovision/docs/02-requirements.md

需求

本文是 agent 实现入口，完整需求编号、推导和风险见 docs/raw/01-需求收集.md 与 docs/raw/02-需求分析.md。

1. MVP 范围

首个可交付 MVP 覆盖 M0–M3：

1. ONVIF/RTSP 摄像头批量接入、校时、探活、断线重连和设备台账。
2. MediaMTX 媒体路由与可收敛的控制面对账。
3. 默认 16 路的推理、规则、事件证据和预警闭环。
4. 多租户/RBAC 的最小隔离、事件不可变存储、审计。
5. 预警 ack、超时升级、双路径投递、限时静默和重启续跑。
6. 误报标记与样本回流。

交付边界已定为客户侧私有化部署的 S2 民办寄宿学校，默认 16 路高风险点位；代码保留 SaaS-ready 租户边界。M1–M3 只接 ONVIF/RTSP，只验证 NVIDIA x86/Jetson 主路径，不包含 GB/T 28181、信创适配、人脸或独立原生 App。

2. 当前 M0 验收

• 在隔离实验室运行 MiBeeNvr 等现成测试台，不改 _reference/，不接真实客户摄像头。
• 首期统一采购一个指定摄像头型号；至少使用一台真实样机，对冻结的“厂商 + 型号 + 硬件版本 + 固件版本”组合通过 GetProfiles、GetStreamUri、SetSystemDateAndTime。
• 记录认证失败、时间漂移、主/子码流各至少 10 分钟以及至少 3 次断线恢复，形成指定型号准入记录。结论不得外推到其他型号/固件、生产批次或多品牌兼容；基线变化必须重新验证。
• 执行 raw/01-需求收集.md §8 已批准的决策台账；只将明确记录的下游法务、客户、硬件和供应商门禁留到对应里程碑。
• M0 代码与临时配置可丢弃，不作为生产基线；可借鉴范围严格遵循 NVR 白名单。

本地硬件开发基线为现有一台 Hikvision IP Camera，精确型号/硬件/固件由 T-001 冻结；生产代码仍只依赖标准 ONVIF/RTSP adapter，不得写死海康品牌或私有地址。M1 实验室使用该 1 路实机和至少 4 条可独立启停的合成 RTSP 上游完成五路软件闭环。合成源可用于功能、配额和容量测试，但不能证明多台真实设备故障隔离、批次一致性或生产 SLA；这些结论由客户授权、借用或租赁设备的 T-007 现场门禁提供。

3. P0 功能要求

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 分析与规则

• 检测能力与场景解耦；规则位于推理之后、告警之前。
• 支持目标类型、属性/身份、区域、时段、行为和持续时长组合。
• 支持多边形区域、方向性警戒线和租户/站点/设备三级覆盖。
• ReID 是默认同一性手段；人脸识别按租户授权、默认关闭，失败时降级而非漏报。

3.3 事件与证据

• 规则命中生成事件实例：结构化数据、抓拍和含 pre-roll 的视频片段。
• 事件与预警分离；事件不可变，误判只追加/更新处置结果，不改写事实。
• 支持设备冷却、站点聚合、已处置抑制和误报反馈。
• Brain → Bell 必须符合冻结的事件契约 v0.1 和代码级断言。

3.4 预警与处置

• 预警必须有 ack；未 ack 自动升级，进程重启后能续跑。
• 升级链、超时、联系人和时段可按租户/站点配置。
• 联系人与值班排班必须统一设计并共享人员、值班组和已验证通知通道主数据，但分对象、分版本管理：联系人不承载轮换字段，排班不复制手机号；升级步骤通过类型化目标引用指定人员、值班组或排班计划，不写死号码。
• 值班排班至少覆盖站点时区、周轮换、生效日期、临时替班、空档/重叠冲突检查、当前与未来值班人预览、版本发布和审计。每次投递创建时解析当时生效的排班版本，并固化实际收件人、通道与解析版本快照；后续修改不得改写历史投递事实。
• 至少两条独立投递路径，其中一条可绕过互联网。
• 区分已发出、已送达、已看到；没有回执不能当成功。
• Alert 与 Event 保持可导航的多对多关系；被规则抑制且没有创建 Alert 的 Event 不伪装为已投递。
• 班次交接覆盖未 ack、处置中与升级中的 Alert；接班确认留痕，交接过程不暂停或重置升级链。
• 交接班只显式转移进行中 Alert 的处置责任，不静默修改未来排班；未来班次替换通过排班临时替班并发布新版本完成。
• 静默必须限时且自动恢复，单次不超过 4 小时，无永久静默。
• 业务预警与运维告警使用不同通道和值班配置。

3.5 平台、安全与运维

• 多租户数据、账号、配置和存储隔离；最小 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 与一条短信或语音，生产前补齐两条独立路径及故障切换。

4. 容量与性能

维度	默认交付	本阶段上限	验收方式
站点视频配额	16 路	128 路	配置项 site.max_video_channels，Bell 持有、Sense 执行
媒体	1 个初始分片	建议 4 个起步	码率、连接、重连和单分片故障隔离实测
推理	1 个逻辑分片起步	最多 8 个 16 路逻辑分片	模型、分辨率、FPS、batch、硬件实测
UI	16 路默认视图	128 路站点	分页/虚拟列表/筛选/批量操作；不一次加载全部视频

硬约束：

• 16 是默认配额，不得写死到数据库约束、数组、循环、规则、分页或批量操作中。
• 128 路不等于单机能力。接入/录像带宽、同时解码、AI 推理、证据存储分别压测和验收。
• 默认由客户已有 NVR 承担常态录像，YoVision 优先保存事件证据，避免重复存储全量视频。

5. 场景优先级

• 首个场景为 S2 民办寄宿学校：客户侧 16 路高风险点位，先做越线、危险区域、聚集等匿名安全规则，不启用人脸。
• S1 居家养老、S3 社区仍是后续目标场景；S1 卧室/卫生间只能使用非成像传感器，该能力在 M6 实现。
• S4 工厂/园区在 M4 前不实现；首个人脸试点最早 M5，仅候选成人访客/承包商白名单且首库不超过 10,000 人。
• 高空抛物不进通用底座。

6. 合规门禁

• 家庭卧室、卫生间不安装摄像头，只能使用非成像传感器。
• 真实 S2 生产试点在 M3 上线前，客户/法务必须确认未成年人影像处理、公共安全视频法规适用性、告示/备案、角色权限和最终留存期限；不阻塞 M1 实验室 Sense 骨架。
• 首个人脸试点在 M5 上线前，必须完成必要性与个人信息保护影响评估、单独同意/替代方式、合法底库来源和撤回/删除流程；方向批准不等于法务批准。
• 人脸特征加密、独立审计、有效期必填、到期失效；原始人脸图不与普通事件证据混存。
• YOLO 商用必须取得 Ultralytics Enterprise License；未获批则走已记录的开源替代路线。

7. MVP 非目标

• 不使用完整 MiBeeNvr 作为生产系统。
• 不在 M1 开发完整管理端、人脸、异构传感器或多场景包。
• M1–M3 不实现 GB/T 28181、国产化信创适配和独立原生 App。
• 不为 128 路提前堆一套分布式平台，但所有边界必须可分片、可配置、可观测。
• 不承诺未经现场数据验证的检出率或误报率；先建立可重复测试集和基线。

8. 验收与证据留存

• M3 先 dry-run 不少于 2 周，冻结站点机位、规则版本、人工标注口径和现场标注集。
• 效果指标按规则分别报告召回率与每路每天误报数；现场基线形成后，在站点验收附件中签署数值阈值，不使用跨场景统一“准确率”。
• 事件片段默认存客户侧 MinIO/S3 兼容对象存储，常态录像留在客户 NVR。技术默认 30 天并在目的完成后删除；客户/法务确认最终期限。元数据、审计、人脸与训练样本使用独立策略。

9. 追溯

• 原始需求编号与优先级：raw/01-需求收集.md。
• 需求分层、状态机、数据模型与风险：raw/02-需求分析.md。
• 技术落地与 NVR 选型：raw/03-通用场景应用方案.md。