27 KiB
27 KiB
generated: true (请先修改 Gitea Wiki,禁止直接编辑本文件) wiki_page: Business-Rules-and-Glossary wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Business-Rules-and-Glossary.- wiki_revision: 9be486cd2d3fe424cf389f65c2c868eacab6a020 synchronized_at: 2026-09-01T04:08:16Z
业务规则与术语
核心术语
| 术语 | 定义 |
|---|---|
| Sense | 独立销售的视频接入、媒体、区域配置和运维产品 |
| Brain | 无界面的推理交付单元,输出观测和标准事件 |
| Bell | 独立销售的事件预警与处置产品 |
| Device | 设备根实体;通过 modality/capabilities 表达视频、雷达、门磁等能力 |
| Site | 一个客户部署中的站点边界 |
| Area | 多边形区域、警戒线及其隐私/准入策略 |
| Event | 已发生的不可变结构化事实及证据引用 |
| Alert | Bell 根据一个或多个 Event 和规则创建的处置对象 |
| ack | 明确由某人接手 Alert,不等同于消息已送达或已看到 |
| Outbox | 与本地状态同事务持久化、可重试投递的消息队列记录 |
| producer identity | Bell 为每个外部产品实例分配的机器身份 |
| 场景包 | 规则模板、升级策略、话术和报表口径的版本化配置包 |
工单状态
- 待确认:需求或方案等待负责人确认。
- 待实施:方案已确认,但依赖或排期尚未满足。
- 进行中:主 agent 正在工单声明的写路径内实施。
- 阻塞:出现计划外且当前无法解除的问题。
- 待验收:实现、测试和文档证据完成,等待负责人验收。
- 已完成:负责人明确验收并完成归档、关闭。
旧仓库任务的 DONE 不继承到新仓库。所有迁移项初始均为“待迁移”,必须用新代码、新测试和新验收重新证明。
稳定业务规则
- Sense 与 Bell 完全独立认证;同一自然人在两个产品中是两个账户。
- 任一产品可独立部署、升级、备份、恢复和验收,另一产品不作为启动依赖。
- Brain 不拥有用户、Alert、通知或业务审计真相。
- 产品集成使用机器身份和版本化契约,不共享数据库、用户会话或内部模型。
- Bell 以
(producer_id, source_event_id)保持跨重启幂等。 - Event 不可变;误报只追加 outcome/反馈,不改写原始事实。
sent、delivered、seen、ack是不同事实;无回执不能当成功。- 未 ack 自动升级且进程重启后续跑;并发 ack 只有首个成功者成为处置人。
- 联系人、排班和升级策略共享主数据但分对象、分版本;投递创建时固化实际收件人、通道和解析版本。
- 静默必须限时并自动恢复,单次不超过 4 小时。
- 默认 16 路,按 32/64/128 横向扩展;128 路不等于单机或单 GPU 承诺。
- 首期 S2 民办寄宿学校只做匿名规则,不启用人脸。
- 家庭卧室、卫生间禁止摄像头,只能使用非成像传感器。
- 摄像头凭据、客户数据、真实视频、JWT secret 和生产配置不得进入仓库、工单或 Wiki。
- 业务预警与设备/媒体/推理运维告警使用不同通道和责任人。
新项目需要补充什么
以下事实必须由后续工单和负责人确认后补充:
- GoAdmin/go-admin-ui 的固定上游 commit、许可证记录和裁剪模块;
- Go、Node、Python、CUDA、PostgreSQL、MediaMTX 的精确版本;
- Bell 数据库 schema、Sense/Bell 部署域名和备份命令;Sense 浏览器 Cookie 与后端会话名称已由工单 #64 固定;
- Brain 模型、推理 FPS、硬件容量和商用许可;
- 试点最终留存期、通知供应商和验收阈值;
- 三个交付单元的正式版本与发布流程。
未确认项不得从旧代码或模板默认值推断为当前事实。
Sense 身份与权限规则
- Sense 仅使用自己的用户库、JWT 密钥和会话;浏览器 Cookie 为
Sense-Admin-Token,后端可接受的独立会话 Cookie 为sense_session,不得与 Bell 共享。 - 当前身份管理固定四个角色:
admin(系统管理员)、implementation_operator(实施/运维)、site_admin(站点管理员)、viewer(只读用户)。业务设备权限由后续设备工单在这些角色上扩展,不复制新的身份事实源。 - 仓库和迁移不创建默认账户或默认密码。首位管理员只能通过仓库外的
SENSE_BOOTSTRAP_TOKEN一次性创建;令牌至少 32 个字符,初始化完成后必须从进程环境移除,已有任一用户时接口拒绝再次初始化。 - Sense 密码至少 6 个字符、最多 72 字节,不要求大小写、数字或符号组合,允许全小写;交付时仍应使用难猜且不复用的密码。
- 登录成功/失败、登出、密码变更和鉴权拒绝必须留下身份审计;密码、令牌、Cookie、验证码、数据库连接和摄像头凭据不得进入审计正文。
site_admin可在账户维护流程中读取角色、部门、岗位和字典等必要支撑数据,但不能修改角色、菜单或系统配置;implementation_operator与viewer不具备账户管理权限。未注册的配置和接口管理路由对所有角色返回 404。
Sense 视频服务规则
- MediaMTX 始终是独立二进制;Sense 管理配置、进程生命周期、路径期望态和状态对账,不把媒体内核放入 GoAdmin handler 或 GORM model。
- Control API 只能绑定回环地址。Sense 可启动配置的 MediaMTX,也可连接已由外部启动的实例;外部实例标记为非本实例所有,孤儿安全闸禁止 Sense 停止它。
- 已验证 Profile 幂等形成媒体路径;数据库不保存带凭据 Stream URI。摄像头凭据只在 loopback Control API 请求边界临时使用,不进入基础配置、日志或 Sense API。
- 路径状态区分 pending、waiting、ready、process_unavailable、apply_failed、status_unavailable、path_missing、stopped,并保存失败次数和有上限的下次重试时间。
- 冷启动恢复 desired=running 路径;用户明确停止的路径保持 stopped,不因启动扫描自动重新启用。稳定路径只刷新状态,不重复下发配置或无意义增加版本。
- MediaMTX 失败不得删除或降级设备台账与最后一次已验证 Profile。
Sense 实时监看规则
- 设备/Profile 列表必须分页和搜索;16/128 路不能导致页面同时创建全部播放器。用户选择一路并打开 Dialog 后才建立 reader,关闭或切换时销毁当前播放器。
- 页面和 JSON API 不返回 RTSP URI、摄像头凭据或 MediaMTX 内部路径。播放器只使用同源短期能力地址;能力令牌必须高熵、绑定用户、每用户单会话,并在停止认证轮询后最多 2 分钟失效。
- 播放状态必须区分 loading、waiting、ready、authentication_failed、stream_not_found、service_unavailable、timeout、expired、offline 和 stopped,并同时显示文字与可行动处理建议,不能只用颜色表达。
- waiting 表示媒体路径存在且播放器正在建立 reader,不等于摄像头接入失败;20 秒仍未就绪才显示连接超时并允许显式重连。
- 默认从浏览器访问 Sense 的主机名推导 MediaMTX WebRTC 端口 8889;经过反向代理、HTTPS 或端口映射时,部署方必须显式配置安全的
SENSE_MEDIAMTX_WEBRTC_PUBLIC_BASE,不得回退到只对服务器自身有效的地址。
Sense 旧 MVP 规则状态
2026-08-14 前的 Sense 账户、设备、发现、Profile、MediaMTX、播放会话和区域版本实现规则仅适用于 explore 快照,不是新 main / dev 的运行事实。迁移工单应从这些记录提取已确认业务与安全约束,但认证、RBAC、管理端外壳和通用 CRUD 必须基于冻结 GoAdmin 源码重新实现并重新验收。
Bell 旧 MVP 规则状态
2026-08-14 前的 Bell 独立身份、Event/Receipt、规则、Alert、ack/close 和审计实现仅保存在 explore。不可变、幂等、并发处置和产品独立边界仍是待迁移业务要求,但新实现必须从冻结 GoAdmin/go-admin-ui 源码派生并重新验收。
旧实现迁移边界
旧 Sense 中已验证的中文设备字段、请求白名单、凭据隔离和媒体链路行为可作为迁移验收用例;不得把旧自研基础框架直接复制到新 dev。
Sense 设备台账与凭据规则
- Device 是 Sense 内的设备根实体,类型包括视频、雷达、门磁、按钮、穿戴和其他;16 路仍只是默认交付配额,分页和台账容量不得硬编码为 16。
- 当前仅视频设备具备可用接入适配器;其余类型必须显示“适配器未就绪”,不允许通过虚假成功状态掩盖能力缺口。
- 设备台账支持列表、新建、编辑和停用;停用保留审计与后续关联,不提供物理删除。编辑、停用和凭据更新均使用版本号检测并发冲突。
- 摄像头 ONVIF 与 RTSP 凭据按设备和用途分离,以 AES-256-GCM 密文保存;加密密钥只从外部环境
SENSE_CREDENTIAL_KEY注入,不写入数据库、仓库、工单、Wiki 或日志。 - 凭据只写不可读:HTTP 和页面仅显示“已配置/未配置”,不得回填用户名、密码或密文;更新凭据后只记录状态并请求后续接入流程重试。
admin、implementation_operator、site_admin可维护设备与凭据,viewer仅可查看设备台账。
Sense 视频接入规则
- “获准网卡”和“获准目标网段”都是部署人员显式配置的授权边界;私网地址不自动代表已授权。未配置发现网卡时不发送 WS-Discovery,手工地址也必须通过目标 CIDR 检查。
- ONVIF 设备地址、Media XAddr 和 RTSP Stream URI 禁止 URL 用户信息、敏感认证查询参数、HTTP 重定向和超出授权网段的目标。摄像机返回不可用主机名时,只能归一化为已验证设备主机并重新执行授权检查。
- ONVIF 支持 Basic、MD5 Digest 和 SHA-256 Digest 的 auth;不支持的算法或 qop 必须拒绝,不静默降级。
- Profile 保存 token、名称、分辨率、编码、用途、无凭据 Stream URI 和逐 Profile 验证状态;主码流默认取分辨率最高项,子码流取最低项。
- 认证失败、超时、时间异常、目标未授权和重定向拒绝必须给出不同状态。失败重探不得删除最后一次已验证 Profile;凭据更新后可重新探测。
Sense 区域与方向警戒线规则
- 区域配置必须绑定已验证的 Device、Profile Token、分辨率和编码;客户端只提交媒体路由引用,最终绑定规格由后端重新查询确认。
- 多边形使用 3–64 个画面内坐标点,必须有非零面积,边线不得自交或重叠;方向警戒线恰好两个不同点,并明确“起点到终点”或“终点到起点”。
- 坐标以 0–1 归一化值保存,同时固化当时分辨率和编码。Profile 删除、Token 替换、分辨率或编码变化必须设置
needs_recalibration,不得静默缩放或重投影旧几何。 - 新建为 v1;编辑、启停和重新校准都追加不可变版本。请求使用
expectedVersion乐观并发,过期版本返回 409,旧版本保留用于审计。 admin、implementation_operator、site_admin可创建和保存新版本;viewer只读。页面状态必须同时使用文字和 Tag,不能只靠颜色表达。- 鼠标可点击/拖动顶点;键盘必须能添加、移动和删除顶点。错误在绘制区域附近以可被辅助技术感知的文字给出,并提供撤销、清空和未保存关闭确认。
- 区域配置是 Sense 内部事实;#69 不发布 Brain 契约。后续 Sense→Brain 配置协议必须由独立协调工单从当前版本投影生成,不能共享数据库模型。
DevHarness 任务证据边界
- Gitea 工单正文与评论是单次任务的需求、变化、实现、测试、提交和验收事实来源。
- Gitea Wiki 只保存长期有效的项目事实;核心页面由
wiki-docs.json显式映射。 docs/task/是按人工明确要求形成的专项或历史兼容快照,可能不完整或不是最新状态,不得替代工单。- 默认不创建、导出或更新任务快照;导出过程不自动删除本地历史文件。
Sense 本地事件候选规则
- “本地事件候选”是 Sense 内部匿名记录,不是 Bell Event 或 Alert;任何跨项目输出必须等待版本化协调契约。
- 候选状态与证据状态是两组独立状态,不能用证据成功推断事件已确认,也不能用事件已确认推断证据成功。
- 列表和详情只读;新增、确认、删除、重试或送达不属于本页面。
- 每条记录保存明确的
retain_until,页面展示实际到期时间;保留时长由服务端生产者/策略决定,页面不虚构全局固定天数。 - 合成夹具只由测试显式装载,生产启动和迁移都不会自动写入假事件。
- GET 列表和详情继续经过 Sense JWT、Casbin RBAC、数据权限中间件及系统操作审计。
Sense 运维状态规则
- 运维问题是设备、媒体或本地推理适配器的本地状态,不是 Event 或 Bell Alert;不得进入 Bell 业务预警队列。
- 问题必须同时保留期望态、实际态、差异、建议动作、对象版本和安全闸;退避问题还要展示下次重试时间。
- 设备认证失败和时间漂移复用既有视频接入探测;媒体失败复用既有 MediaMTX 对账循环。
- 受控重试必须校验对象版本并防止同一对象并发执行;实施/运维和站点管理员可执行,viewer 只读。
- 孤儿媒体路由只能显示“隔离待确认”,不得从运维中心自动删除。
- Brain 未配置或未安装时显示本地推理 unavailable,不读取 Brain 数据库,也不阻断设备/媒体运维。
Sense 容量与配额规则
- 配额是 Sense 单产品的交付配置,不是单机性能承诺;默认初始化为 16 路,数据库、循环、分页和列表容量不得以 16 为硬上限。
- 配额占用按非停用设备计算:已接入和待接入各占用一路,停用设备不占用;重新启用必须重新经过配额安全闸并回到待接入状态。
- 设备新增、重新启用及批量开通写入必须使用同一 PostgreSQL 配额事实源。写事务锁定单行配额配置、读取当前占用、检查剩余量后再写设备,防止并发超配。
- 配额缺失、非法或读取失败时,新增、启用和批量相关写入必须拒绝;已有设备、视频流和只读查询继续可用。
- 降低配额到当前占用以下不会自动停用设备或中断视频;剩余量按 0 显示,后续新增/启用持续拒绝,直到占用回到配额内。
- 32/64/128 只展示当前配置和目标硬件性能测试状态。未验证不得解释为支持或稳定承载承诺。
- 配额调整必须记录旧值、新值、操作人、时间和原因;viewer 与实施/运维角色只读,只有站点管理员可调整配额和重新启用设备。
Sense 边缘节点状态规则
- 边缘节点投影:Sense 保存的节点最后已知运行状态,不是 Brain/Bell 的共享机器身份或跨产品事实源。
- 在线:最近心跳距读取时刻不超过 90 秒,且没有未完成的恢复阶段。
- 离线:最近心跳距读取时刻超过 90 秒。离线是读取时推导状态,不得用“未知”覆盖最后已知的控制隧道、视频数据面、负载和回填队列;所有这些值必须同时标明陈旧。
- 恢复中:心跳已经恢复,但控制隧道、视频数据面或回填通道仍在独立收敛。只有恢复阶段明确收敛后才显示在线。
- 状态转换写入不可变事件;列表和详情读取写入脱敏操作审计,不记录凭据或原始心跳载荷。
- 合成夹具必须显式调用,生产迁移和启动不得自动写入节点。
Sense MediaMTX 分片规则
- 媒体分片是一个独立 MediaMTX Control API 及其配置容量的 Sense 本地投影,不是 Brain 分片,也不是跨产品共享节点身份。
- 主分片容量优先读取显式
SENSE_MEDIAMTX_CAPACITY;未设置时读取 Sense PostgreSQL 的当前统一配额。额外分片容量逐项来自仓库外 JSON 配置。16 和 128 均不得作为分配算法硬上限。 - 新媒体路径只在状态为运行正常或等待首次探测、且仍有配置容量的分片中确定性分配;同一路径重复处理必须保持原归属。
- 分片异常、停用或状态陈旧都不得自动改写已有路径归属。详情必须能定位受影响的设备、位置、Profile 和媒体路径,同时不返回 Control API、RTSP URI 或凭据。
- 跨分片迁移预检是只读操作,只检查源状态、全部受影响路径和候选目标容量;即使预检通过也不授予执行权限。实际迁移必须另建高风险工单并取得人工确认。
- 额外分片只能配置为 external,Control API 必须使用无用户信息、无查询参数、无路径的本机回环 HTTP 地址。Sense 不停止外部实例。
Sense 内部 Outbox 业务规则
- 领域记录与 outbox 必须在同一 PostgreSQL 事务中提交;任一写入失败时两者一起回滚。
- 幂等键在消息表唯一,成功后还保留永久投递收据;重试和人工恢复沿用原业务记录与幂等键。
- worker 只能领取到期的 pending/retry 或租约已过期的 processing 记录;同一记录不能被两个 worker 同时成功领取。
- 失败保留脱敏错误与尝试历史,按退避等待;达到最大次数进入 dead。人工重新排队必须填写原因并记录操作者,不删除历史。
- implementation_operator、site_admin、viewer 可查看;只有 implementation_operator、site_admin 可重新排队。
- 未配置外部 connector 时保留内部记录且不阻断 Sense 核心功能。测试 sink 在 prod/production 模式禁止启用。
- 管理 API 不返回内部 payload、外部凭据或机器身份;Brain/Bell 正式协议属于后续协调工单。
Sense 运维告警规则
- 六类运维告警固定为:设备/边缘节点离线、设备认证失败、设备时间漂移、媒体状态对账失败、媒体分片异常、控制隧道异常。
- 每个“告警类型 + 对象类型 + 对象 ID”只有一条记录;同一源版本重复刷新不增加发现次数,也不产生第二条活动告警。恢复后再次异常复用原记录、递增处理周期并保留全部历史。
- 状态为
unacknowledged(待确认)、acknowledged(已确认)、recovering(恢复观察)、recovered(已恢复)。人工确认只表示已接手,不表示故障恢复。 - 健康事实恢复后先进入固定 5 分钟观察窗口;只有
recovering且观察窗口结束后才能人工确认恢复。观察期再次异常返回原处理状态并追加恢复失败历史。 - 确认和恢复都要求 6–256 字符原因、当前版本和允许的状态;旧版本或错误状态返回冲突。所有动作写入独立流转历史和 GoAdmin 操作审计。
- 运维告警永远设置为 Sense 内部运维记录,不创建本地安全事件或 Bell Alert,不进入跨项目 Outbox,也不实现通知升级。
Sense↔Brain 配置与状态规则
- 配置流:由稳定
config_id和严格递增的正整数revision标识;revision 不得复用或倒退。 - 无凭据媒体引用:
media.ref是由后续 connector 解析的不透明逻辑引用,不是 RTSP URL、本机路径或数据库主键。 - Profile 绑定:规则集必须与 Profile ID、宽高一致;Profile 变化必须形成新 revision,并在需要时标记
recalibration_required,旧几何不得静默重投影。 - 规则坐标:区域与方向线使用 0–1 归一化坐标,规则 ID 在同一规则集内唯一;退化多边形和重合线端点无效。
- 完整性:源配置对移除
integrity后的 JCS 表示计算 SHA-256;校验失败保留上一有效 revision。 - 配置应用状态:Brain 在
configurations[]中按config_id报告not_configured/applying/applied/rejected与实际applied_revision;同一消息重复 ID 整条拒绝。 - 状态时序:Brain 实例 sequence 单调递增;Sense 拒绝倒序消息。观测时间超过约定 90 秒时由 Sense 标记陈旧,不用未知值覆盖最后已知投影。
- 状态边界:运行/健康错误只形成 Sense 运维投影,不是业务 Event 或 Bell Alert;不得包含用户会话、凭据、内部路径或客户视频。
- 版本兼容:v1 只接受已冻结语义;破坏性字段或语义变化发布新主版本。未知主版本停止摄取并保留上一有效事实。
标准事件、证据和幂等规则
- 标准 Event:匿名、不可变的跨产品安全事实,不是 Bell Alert,也不携带处置或通知状态。
- 原始生产者:
producer_id始终标识最初产生事件的 Brain 或 Sense 实例;relay 使用独立传输身份,但不得替换业务生产者。 - 永久幂等键:精确 UTF-8 对
(producer_id, source_event_id)。重试沿用同一键,不生成新事件。 - 规范摘要:完整 Event 使用 RFC 8785 JCS 规范化后计算 SHA-256。同键同摘要为重复成功;同键异摘要为终止性冲突,并追加脱敏审计。
- 时间格式:Event v1 使用 UTC RFC 3339、三位毫秒和
Z;可选字段缺失时省略,不发送 null。 - 证据引用:
evidence_id与owner_id是不透明逻辑引用,不是 URL、文件路径或访问凭据。 - 证据状态:
pending → processing → success|failed。success 要求内容类型和摘要/大小;failed 要求稳定错误码和是否可重试。 - 降级原则:证据失败、未知或过期不删除 Event,不自动关闭 Alert,也不伪装成完整成功。
- Bell 所有权:Bell 独占内部 Event/Receipt、规则、Alert、ack、close、通知与用户审计;上游不得写入这些状态。
- 兼容与回退:未知主版本终止接收但保留已有事实;破坏性变化发布新主版本。回退停用新生产者版本,不删除 Outbox、Receipt、Event 或审计。
机器身份、权限和重放规则
- 机器 principal 格式为
yv:<sense|brain|bell>:<instance>,每个产品实例独立;不得替代、携带或映射 Sense/Bell 用户身份。 - v1 audience 只允许
yovision-sense、yovision-brain、yovision-bell;scope 只允许source-config:write、runtime-status:write、events:ingest、evidence:read,没有通配符。 - 机器令牌只能从 Authorization Bearer 读取,不接受管理员密码、浏览器 JWT/Cookie、query token、共享 secret 或其他产品用户身份。
- 相同
(principal,jti)只能成功一次;传输重试必须签发新令牌和 jti,但业务幂等键与载荷保持不变。 - 私钥只存在于仓库外受操作系统保护的文件或秘密存储;运行配置只引用路径。公钥注册表属于各消费者本地配置,不是共享数据库。
- 轮换先登记新
kid,最多并存 24 小时,切换后移除旧 key;禁用 principal 或吊销kid对每次请求即时生效。 - 回退只能关闭 connector 并恢复三端独立运行,不得降级为明文、共享管理员身份、共享 JWT 或跳过签名/TLS 验证。
Connector 持久性与故障隔离规则
- 配置事实与运行投影分离:Sense 的期望 revision 不等于 Brain 已应用 revision;只以 Brain runtime-status 的实际值更新只读投影。
- 最后有效配置:Brain 对过期、未知版本、摘要错误或不安全配置拒绝应用,并保留 last-known-good;不得用失败输入覆盖当前配置。
- 机器重放与业务幂等分离:每次网络重试必须使用新 jti;事件仍沿用原
producer_id/source_event_id与规范载荷。 - Sense 同事务网关:Brain 事件只有在 Sense 的 InboundEvent、EvidenceRecord 与 Bell Outbox 同一事务成功后才算被 Sense 接受。
- Bell 永久收据:同键同摘要只形成一个 Receipt/Event;同键异摘要是终止冲突并追加脱敏审计,不能覆盖或删除原事实。
- 证据降级独立:pending、failed、timeout、expired 不改变 Event 不可变性,也不自动 ack/close Alert。
- 停用规则:关闭 connector 只停止新接入或投递;不得清空未投递 Outbox、持久 replay、Receipt、Event、证据元数据或审计。
- 独立运行:Sense、Brain、Bell 不因对端未安装、离线或 connector 关闭而停止各自核心能力;不得以共享数据库/JWT/Cookie 规避故障隔离。
Bell 联系人与排班术语
- 联系人(Contact):可参与 Bell 告警接收和值班安排的人员记录。
- 通知通道(Channel):联系人使用的消息到达方式;通道地址密文保存,对外只提供脱敏摘要。
- 通道验证事实(Channel Validation):一次独立、只追加的验证结果;“已验证”不等于“已启用”。
- 值班组(Duty Group):参与同一排班规则的一组联系人。
- 排班版本(Schedule Version):值班组在指定 IANA 时区下的一套完整周排班;发布后冻结,不原位修改。
- 轮值时段(Rotation Slot):排班版本内的连续时间段,包含不同的主值班与备值班联系人。
- 临时替班(Override):在已发布排班上的只追加例外事实,不改写原排班历史。
规则:
- 发布前必须验证整周无空档、无重叠,并验证主备不同、成员有效及通知通道已启用且已验证。
- 已发布排班、通道验证事实、审计事实和临时替班记录保持不可变;更正通过新版本或新事实完成。
- 同一排班版本中的临时替班不能重叠。
- 普通操作员只读;创建、修改、启停、验证、发布和替班由管理员执行。