24 KiB
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Product-Requirements wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Product-Requirements.- wiki_revision: a2aada9db75909dc5fc85cc5d91c8c8bcab82c45 synchronized_at: 2026-09-01T04:09:23Z
产品需求
本页用途
本页同时承担 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 和幂等收据继续。
Sense 批量开通长期规则
SEN-004 已在工单 #72 实现、合入 dev 并通过用户验收。Sense 可独立导入 CSV/XLSX 摄像头清单，服务端预校验地址、重复项和剩余配额，再按条目执行接入。批次保留创建时的配额与占用快照，但新的批次与设备写入必须读取 SEN-011 的统一配额事实源；16 不是数据库、循环、分页或单机容量硬上限。
导入清单禁止账号和密码字段。ONVIF/RTSP 凭据只在受控表单与单次执行请求中短暂存在，随后进入既有加密 Vault；批次、条目、响应、日志和结果导出都不得包含凭据。批次允许部分成功，成功设备不因其他条目失败而回滚；批量重试与单项重试只领取失败条目，并通过批次幂等键、持久化设备引用和条件状态更新避免重复创建设备。
Sense 本地事件候选
SEN-008 在 Sense 内提供只读的本地事件候选查询。网管或非技术人员可按发生时间、候选状态、证据状态、规则引用和关键词筛选，查看候选详情、证据处理结果与逐条保留到期时间。
候选状态只表示 Sense 内部的 candidate（候选）或 confirmed（已确认事件）；证据状态独立表示 pending（处理中）、success（成功）或 failed（失败）。本能力在 Brain、Bell 均未启动时仍可使用。本地候选不是跨项目事件契约，不等同于 Bell Alert，也不表示已经向 Bell 送达。
Sense 运维中心
SEN-009 由 Sense 独立提供设备、媒体和可选本地推理的运维概览。页面以“期望态—实际态—未收敛差异—下一步动作”展示认证失败、退避等待、时间漂移、孤儿安全闸和能力未安装，面向网管或非技术运维人员，不暴露凭据或内部数据库结构。
运维中心在 Brain、Bell 均未启动时可用。本地推理适配器尚未建立协调契约时显示 unavailable；该状态不导致页面失败。所有问题均为 Sense 运维事实，不等同于 Bell 业务 Alert，也不会从本页面发送给 Bell。
读取默认只读。受控重试仅对明确可重试的设备/媒体问题开放，必须通过 RBAC、对象版本和在途状态校验并写入脱敏审计。孤儿媒体资源只隔离和提示，不提供自动删除。
Sense 容量与配额长期规则
SEN-011 将默认 16 路实现为可配置的 Sense 本地交付配额。统一配置保存在 PostgreSQL；新增设备、重新启用和批量开通在写事务内原子校验。配额不可读时拒绝这些写入，但已有设备、视频流和读取保持可用。降低配额不会自动停用现有设备。
容量页面只展示 16/32/64/128 的当前配置和性能测试状态。除已经验证的 16 路学校试点基线外，其余档位在完成目标硬件压测前都不得解释为单机承载承诺。
Sense 边缘节点资产与离线状态
Sense 为网管和非技术运维人员提供只读的“边缘节点”页面，集中查看节点名称、位置、运行版本、模型版本、运行时长、承载路数、控制隧道、视频数据面和回填队列。节点最近心跳超过 90 秒即在读取时显示为离线；离线不会清空最后一次采集到的通道和队列状态，页面必须同时标明陈旧时长。心跳恢复后，连接状态与控制、视频、回填通道分别收敛，未全部收敛时显示“恢复中”。列表、详情及状态变化均可审计。
本能力只管理 Sense 自有投影，不建立 Brain/Bell 共享身份、控制协议或跨项目回填执行；Brain、Bell 未运行时仍可独立查看。合成节点仅供显式开发和测试，不由生产启动或迁移自动写入。
BRN-001 独立输入适配交付边界
BRN-001 的首个独立实现已通过工单 #11 验收。Brain 可在 Sense、Bell 均未启动时使用固定种子和时间基准生成可重复的 RGB 合成帧，也可从显式本地路径读取容器字节供后续解码层消费；两种输入都携带 Brain 内部逻辑设备、Profile 和分辨率信息，并支持 EOF、协作取消及安全可定位错误。
项目内配置版本为 brain.internal.input/v1，可承载测试用区域和方向线，但它不是 Sense→Brain 共享契约。正式 RTSP、Sense 源/区域配置和跨项目机器身份仍须由协调工单在版本化 contracts/ 中冻结；不得让 Sense 或 Bell 直接依赖此内部模型。配置和测试不得包含摄像头凭据、客户视频、个人数据或机器绝对路径。
BRN-002 独立解码交付边界
BRN-002 的首个解码阶段已通过工单 #13 验收。Brain 通过可替换 DecoderBackend 把内部输入转换为顺序、纳秒时间戳、逻辑设备、Profile、分辨率和像素格式明确的帧；当前独立路径支持确定性 RGB24 与匿名本地 YUV4MPEG2 C444。正常 EOF、主动取消、损坏或不支持格式、尺寸变化/不匹配均有明确结果。
该验收不包括生产 RTSP、FFmpeg/PyAV、NVIDIA 硬件解码、多路性能或客户视频，不得据此声明 GPU/生产编解码能力。
BRN-002 匿名检测与跟踪交付边界
工单 #14 已验收匿名目标检测和会话内单路跟踪。输出只包含匿名类别、置信度、边界框、帧时间和当前进程内轨迹 ID；不包含姓名、人脸模板、生物特征、摄像头凭据或跨摄像头身份。
当前版本化基线是无外部权重的 first-party 亮度目标算法及 PyTorch 2.12.1 张量后端，只证明匿名检测/跟踪接口与链路可运行。真实人员检测效果、GPU、召回率、误报率和 ReID 均未验证或启用。
BRN-003/BRN-004 区域与方向规则交付边界
工单 #15 已验收 Brain 内部危险区域与方向越线判定。轨迹框底边中心为归一化锚点；多边形边界视为区域内，状态区分 outside、entered、inside；有向线按起点→终点区分左右方向，并使用 deadband 抑制贴线抖动。
每个结果绑定规则配置版本、Profile、分辨率和解释原因。结果仍是 Brain 内部候选，不是 Bell Alert 或正式共享事件；聚集、完整时段/持续/冷却和正式 Sense 配置契约仍是后续范围。
BRN-005 独立内部事件候选交付边界
工单 #16 已验收 Brain 首个独立纵切：合成/本地输入经过解码、匿名检测/单路跟踪和区域/方向规则后，可输出 brain.internal.event-candidate/v1 JSON Lines 候选。事件 ID 基于规范化输入事实与版本生成稳定 SHA-256；相同输入、配置和版本重复运行不制造不同 ID。
内部候选只含逻辑输入引用、规则/模型版本、发生时间、匿名观测和解释原因，不含摄像头凭据、客户隐私、人脸、生物特征、机器绝对路径或伪造证据。该格式不是正式 Brain→Bell 契约；证据、机器身份、Outbox/可靠投递和跨项目 E2E 仍须协调工单实现。
Sense↔Brain 配置与状态 connector
工单 #148、#149 冻结的唯一共享事实源仍为 contracts/source-config/v1/（yovision.source-config/v1）和 contracts/runtime-status/v1/（yovision.runtime-status/v1）。工单 #152 已于 2026-08-31 通过用户验收并合入 dev。
Sense 现在可从 Device/Profile/Area 内部事实生成无凭据完整快照并持久分配 revision；Brain 严格校验版本、JCS/SHA-256、Profile/几何/状态，幂等应用并保留 last-known-good。Brain 以持久单调 sequence 发布实际应用 revision、运行/模型、健康和输入状态；Sense 保存只读投影并区分在线、陈旧、离线、恢复和 revision mismatch。双端持久 replay store 在各自数据库内防止机器令牌重放，重启不清空安全状态。
connector 可停用，断线或对端未安装不阻断 Sense/Brain 核心能力。#152 交付产品 adapter、持久状态和恢复原语；部署级 HTTP 托管、进程编排、真实双机 TLS 与最终 E2E 仍属于 #154/#155。
标准事件、证据与可靠 connector
工单 #150 冻结的唯一共享事实源仍为 contracts/events/v1/（yovision.event/v1）和 contracts/evidence/v1/（yovision.evidence-reference/v1）。工单 #153 已于 2026-08-31 通过用户验收并合入 dev。
Brain 将内部匿名候选映射为标准事件；默认拓扑由 Sense 以机器身份接收并在同一事务中写入 InboundEvent、证据元数据和 Bell Outbox，再由后台 Worker 可靠投递到 Bell。Bell 以持久机器令牌 replay、永久 (producer_id, source_event_id) Receipt、JCS/SHA-256 摘要和冲突审计写入不可变 Event；Alert/ack/close 仍只由 Bell 私有规则与处置流程产生。
证据继续使用逻辑引用，状态为 pending/processing/success/failed；失败、超时或过期只形成明确降级，不暴露内部路径、长期签名 URL 或凭据，也不改写 Event/Alert 生命周期。三端 connector 均可停用并保持独立运行；停用或故障时保留 Outbox、Receipt、Event、replay 与审计事实。
Sense 的 local_event.CreateWithOutbox 是本地候选与标准事件 Outbox 的正式原子写入口；当前仓库尚无生产本地候选创建调用链，不把不存在的上游路径声明为已接通。真实客户 PKI、生产 PostgreSQL、现场网络与最终故障隔离由 #154/#155 验证。
Bell 联系人和值班排班
Bell 的告警接收对象和值班安排由工单 #183 建立，目标是让管理员维护可审计、可验证且不泄露通道地址的通知基础数据。
- 联系人与通知通道分离管理；通道地址只以密文保存，API、操作日志和页面均不得返回或记录明文，只展示脱敏摘要。
- 通道“已启用”和“已验证”是两个独立状态；验证结果以只追加事实记录保存，不能用启用状态替代验证。
- 值班组成员必须是已启用联系人，发布前主值班与备值班必须是不同联系人，且均具有已启用、已验证的通知通道。
- 周排班使用 IANA 时区，必须覆盖完整一周且不允许时间空档或重叠；排班以版本发布，已发布版本不可修改。
- 临时替班作为只追加事实记录保存，不能覆盖或改写已发布历史，且同一排班版本内不得时间重叠。
- 普通操作员只读，管理员可维护与发布。
- 本范围只提供联系人、通道验证事实和值班排班基础能力，不执行真实外部通知；实际发送属于后续工单 #185。