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 白名单。

## 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/01-需求收集.md)。
- 需求分层、状态机、数据模型与风险：[`raw/02-需求分析.md`](raw/02-需求分析.md)。
- 技术落地与 NVR 选型：[`raw/03-通用场景应用方案.md`](raw/03-通用场景应用方案.md)。