yovision/docs/09-product-requirements.md

generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Product-Requirements wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Product-Requirements.- wiki_revision: e912a1ca1410e01680a0f11f6199ccb42cd8fe8f synchronized_at: 2026-08-27T09:06:08Z

产品需求

本页用途

本页同时承担 YoVision 产品需求正文与需求总览索引，保留已经确认的 Sense、Brain、Bell 和跨项目要求，不因 DevHarness 升级重命名或拆分事实源。

事实来源边界

• 长期产品目标、边界和稳定需求记录在本页。
• 单次任务的范围、变化、实现和验收记录在对应 Gitea 工单。
• 原型用于确认页面、流程与交互，不替代正式需求和验收标准。

当前需求索引

• 产品边界：PR-BND-001～PR-BND-003。
• Sense：SEN-001 起，按 P0、P1/P2 管理。
• Brain：BRN-001 起，按 P0、P1/P2 管理。
• Bell：BEL-001 起，按 P0、P1/P2 管理。
• 跨项目与非功能要求：见本页第 6 节及对应协调工单。

登记规则

新增或变化的长期需求必须有来源、状态、所属产品、优先级和验收边界；会改变已确认结果时先更新工单并重新取得用户确认。

原型与设计资产

原型门禁

新页面、独立用户功能、重大交互或导航变化必须先形成可审阅原型；小范围 UI 使用标注截图、低保真图或明确复用规范；非 UI 任务使用架构、API、数据、状态或流程设计。

线上原型与按需 HTML 快照

默认使用可访问且版本明确的线上原型审核。只有用户明确要求或项目规则要求时，才导出 prototypes/<工单号>/<版本>/index.html；已确认快照不得原位覆盖。

原型确认记录

实现工单记录设计链接或路径、版本/revision、访问检查、确认人、确认时间和覆盖范围。结构、流程、状态、权限或异常处理发生实质变化时必须重新确认。

状态规则

需求使用拟议、已确认、实施中、已交付、已废弃等状态；工单状态仍按待确认、待实施、进行中、阻塞、待验收、已完成管理，两者不得混用。

更新时机

产品边界、长期业务规则、需求优先级或验收边界变化时更新本页；单次实现细节、测试日志和提交哈希只写工单。

最小验收清单

• 需求有稳定编号、所属产品、优先级、来源和验收边界。
• 跨项目需求只有一个契约或协调事实源。
• 需要原型的变更已有可访问、可识别版本并完成确认。
• 不包含密码、令牌、生产数据或完整聊天记录。

1. 产品范围与优先级

YoVision 首个可交付目标是在民办寄宿学校以默认 16 路高风险点位形成完整闭环：

设备接入 → 稳定供流 → 推理/规则 → 事件与证据
→ Bell 预警 → ack/升级/close → 误报反馈

需求优先级：

• P0：独立纵切、首个端到端闭环、安全与可恢复边界。
• P1：形成可交付产品所需的配置、运维和扩展能力。
• P2：后续场景、规模或体验增强。

2. 产品独立性要求

PR-BND-001 Sense 与 Bell 独立销售

• 两者各自拥有登录、用户、角色、菜单、审计、数据库、版本、安装包和备份恢复。
• 同一自然人在两个产品中也视为两个独立账户。
• 不共享用户 ID、密码、JWT、Cookie、Casbin 策略或数据库角色。
• 任一产品不以另一产品为启动依赖。

PR-BND-002 Brain 独立交付

• Brain 可独立构建、测试、版本化和发布，默认随 Sense 产品部署。
• Brain 无交互式账户，不持有 Alert、ack、通知或全局审计真相。
• Brain 与 Sense/Bell 仅通过版本化契约交互。

PR-BND-003 可选产品集成

• 产品间使用独立机器身份，不复用管理员密码或浏览器 token。
• 不允许跨数据库查询、共享文件目录或复制内部表结构临时打通。
• Bell 不读取摄像头密码；事件只携带逻辑设备引用和必要证据引用。

3. Sense 需求

P0

• SEN-001 独立登录与权限：Sense 自有用户、角色、菜单、会话和审计；至少覆盖管理员、实施/运维、站点管理员和只读边界。首期采用账号密码直接登录，所有运行模式均不使用验证码；密码保持 6–72 字节且不强制字符复杂度，登录成功与失败必须记录不含秘密的身份审计。默认登录有效期为固定 30 天，后端 JWT 与浏览器持久 Cookie 必须一致；版本更新后已有 Token 不自动延长，不提供滑动续期或服务端单 Token 撤销。
• SEN-002 设备台账：以 Device 为根实体，通过 modality 和 capabilities 表达 video/radar/contact/button/wearable/other；首期只完整实现 video，未实现适配器显示 adapter_not_ready。
• SEN-003 ONVIF/RTSP 接入：支持发现或手工添加、Profiles、StreamUri、主/子码流、校时、认证失败、重新探测和凭据更新。
• SEN-004 批量开通：默认 16 路可导入、预校验、待激活、逐项成功/失败、仅重试失败项；部分成功不做整体回滚。
• SEN-005 MediaMTX 管理：媒体代理保持独立进程；Sense 管理期望配置、生命周期、reader、上游拉流和对账收敛。
• SEN-006 实时监看：支持设备列表、单路实时画面、主/子 Profile、加载/空/失败/重连状态；128 路站点使用分页或虚拟列表，不一次加载全部视频。
• SEN-007 区域配置：支持多边形区域、方向警戒线、设备关联和版本化配置；能力/Profile 变化时显式提示几何重新校准。
• SEN-008 独立本地事件查看：未安装 Bell 时仍可查看本地事件候选和证据状态。
• SEN-009 运维中心：展示设备/媒体/推理期望态与实际态、未收敛差异、退避、下次重试、认证失败、时间漂移、孤儿安全闸和审计。
• SEN-010 安全凭据：摄像头密码只写不读、不回显、不进日志；更新后自动重试并显示脱敏结果。

P1/P2

• SEN-011 容量与配额：默认 16 路；32/64/128 可配置和分片扩展；新增/启用时校验配额，配额不可读时拒绝相关写入但保持已有流与读取。
• SEN-012 边缘节点：展示节点版本、在线时长、承载数、控制隧道、视频数据面和补传队列；断网缓存，恢复补传。
• SEN-013 Media/Brain 分片：容量来自压测而非硬编码；分片故障影响范围可观察，跨分片迁移需独立高风险工单。
• SEN-014 Bell connector：使用持久 Outbox 投递标准事件/审计；Bell 不可用不阻断 Sense，恢复后幂等补投。
• SEN-015 设备运维告警：离线、认证、漂移、收敛、分片和隧道异常不进入 Bell 业务预警队列。

4. Brain 需求

P0

• BRN-001 输入适配：从版本化源契约读取 RTSP/媒体引用、设备逻辑标识和区域配置，不读取 Sense 数据库。
• BRN-002 解码与推理：建立可替换的解码、检测、姿态、跟踪、ReID 和规则判定流水线；模型输出与业务规则分层。
• BRN-003 匿名安全规则：首期支持越线、危险区域、聚集等匿名规则；不启用人脸。
• BRN-004 区域语义：支持多边形、警戒线方向、时段、持续时间和冷却语义；坐标与 Profile/分辨率绑定且版本化。
• BRN-005 标准事件：输出冻结 JSON Schema，包含 producer/source event ID、租户/站点/设备逻辑引用、规则/模型版本、时间、观测、区域和证据引用。
• BRN-006 幂等与重试：同一输入事实重试不得制造语义不同的重复事件；投递失败可恢复并可观测。
• BRN-007 隐私：事件不得包含摄像头密码、内部文件路径、客户隐私明文或未经授权的人脸特征。

P1/P2

• BRN-008 证据：生成抓拍和含 pre-roll 的片段引用；证据失败可形成明确的降级事件，不伪装完整成功。
• BRN-009 容量：按模型、分辨率、FPS、batch 和硬件建立每 16 路逻辑分片基线；不承诺单 GPU 128 路。
• BRN-010 效果评估：按规则版本分别报告召回率、每路每天误报数和样本量，不使用跨场景统一“准确率”。
• BRN-011 人脸后置：默认关闭；仅在单独授权、影响评估、底库合法性、撤回/删除和加密审计完成后进入独立试点。

5. Bell 需求

P0

• BEL-001 独立登录与 RBAC：Bell 自有用户、角色、会话、密码策略和审计，不接受 Sense 用户 token。
• BEL-002 外部事件 API：接收 Sense、Brain、其他 NVR、传感器或第三方标准事件；每实例独立 producer identity。
• BEL-003 幂等入站：以 (producer_id, source_event_id) 保证永久稳定收据和跨重启幂等。
• BEL-004 Event 不可变：校验后持久化结构化事件和证据引用；误报或处置不改写原始事件。
• BEL-005 规则与 Alert：规则命中创建 Alert；Event 与 Alert 多对多、双向可导航，抑制的 Event 不伪装成已投递。
• BEL-006 Alert 生命周期：至少支持 open/ack/close；并发 ack 仅首个服务端成功者成为处置人，后到者看到真实结果。
• BEL-007 自动升级：未 ack 按版本化升级链继续；重启后恢复未完成链路，恢复成功/失败可观察。
• BEL-008 投递事实：sent/delivered/seen 与 ack 分离；不支持回执、未知、可重试失败和最终失败均明确展示。
• BEL-009 双路径通知：试点至少本地 Web/声光加短信或语音；生产前两条独立路径，其中一条可绕过互联网，并支持供应商健康和故障切换。
• BEL-010 联系人/排班/升级：人员与已验证通道、值班组、站点时区、周轮换、生效日期、临时替班、空档/重叠检查、版本发布和审计分对象建模。
• BEL-011 投递快照：创建投递时固化实际收件人、通道、排班和升级策略版本；后续修改不改写历史。
• BEL-012 交接与静默：交接覆盖未 ack、处置中和升级中 Alert，升级不中断；静默最多 4 小时并自动恢复。

P1/P2

• BEL-013 事件与审计中心：筛选、分页、批量处置、总数、时间线和安全深链；不一次加载全部记录。
• BEL-014 规则版本：试运行展示命中样本和影响；回滚创建新版本，不改写历史版本。
• BEL-015 去重聚合：支持设备冷却、站点聚合、已处置抑制和静默，并在 Alert 中解释聚合原因。
• BEL-016 保留策略：事件片段、抓拍、元数据、审计和训练样本分别配置并记录到期删除；技术默认 30 天，最终期限由客户/法务确认。
• BEL-017 对外集成：版本化 OpenAPI/Webhook，签名密钥只写不读，重试和失败告警可见；客户平台不接管 Bell 状态机。
• BEL-018 场景包：版本化导入/导出、站点应用差异和升级路径；新场景尽量纯配置交付。

6. 跨项目非功能要求

• NFR-001 可用性：断线重连、先落库后投递、Outbox、对账收敛和重启恢复是基础能力。
• NFR-002 安全：最小权限、全链路审计、秘密仓库外管理、无 query token、无默认密码/JWT secret/演示入口。
• NFR-003 隔离：Sense/Bell 数据库角色只能访问本产品数据；部署在同机也使用不同域名或明确隔离 Cookie Path/策略。
• NFR-004 可观察：设备在线、流状态、推理延迟、事件量、未收敛项、投递 SLA 和恢复失败可监控。
• NFR-005 容量：媒体、解码、推理、证据和 UI 分别压测；16 不硬编码，128 不等于单机承诺。
• NFR-006 可维护：每个交付单元有独立 README、构建/测试/发布命令、版本和子目录规则。
• NFR-007 契约兼容：破坏性变更发新版本；生产者和所有消费者必须有契约测试。
• NFR-008 隐私合规：最少收集、最少展示、目的完成后删除；未成年人、家庭、人脸试点分别经过法务/客户门禁。

7. 首期非目标

• 不直接复制旧仓库整棵目录、go.mod、迁移或任务状态。
• M1-M3 不实现 GB/T 28181、信创适配、原生 App、异构传感器完整适配或人脸。
• 不实现高空抛物专用算法。
• 不承诺未经现场数据验证的召回率、误报率或 128 路单机能力。
• 不在框架初始化工单中同时完成 GoAdmin 升级、TypeScript、Vite 和全部业务重写。

8. 最小产品验收

• Sense 在 Bell 未安装/未启动时可独立登录，完成摄像头接入、实时查看和区域配置。
• Brain 可用合成输入产生符合契约的匿名区域事件，并在 Bell 不可用时明确重试/降级。
• Bell 在 Sense/Brain 未启动时可用合成或第三方事件完成 Alert → ack → close。
• Sense 账号不能登录 Bell，Bell 账号不能登录 Sense。
• 三个项目独立构建、测试和版本化；Sense/Bell 独立迁移、备份、恢复和打包。
• 集成断开不阻断各自核心能力，恢复后按 Outbox 和幂等收据继续。