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: 96fca4d2aa411725282bd3911c133efc75f7146a synchronized_at: 2026-08-27T09:04:59Z # 业务规则与术语 ## 核心术语 | 术语 | 定义 | |---|---| | Sense | 独立销售的视频接入、媒体、区域配置和运维产品 | | Brain | 无界面的推理交付单元，输出观测和标准事件 | | Bell | 独立销售的事件预警与处置产品 | | Device | 设备根实体；通过 modality/capabilities 表达视频、雷达、门磁等能力 | | Site | 一个客户部署中的站点边界 | | Area | 多边形区域、警戒线及其隐私/准入策略 | | Event | 已发生的不可变结构化事实及证据引用 | | Alert | Bell 根据一个或多个 Event 和规则创建的处置对象 | | ack | 明确由某人接手 Alert，不等同于消息已送达或已看到 | | Outbox | 与本地状态同事务持久化、可重试投递的消息队列记录 | | producer identity | Bell 为每个外部产品实例分配的机器身份 | | 场景包 | 规则模板、升级策略、话术和报表口径的版本化配置包 | ## 工单状态 - 待确认：需求或方案等待负责人确认。 - 待实施：方案已确认，但依赖或排期尚未满足。 - 进行中：主 agent 正在工单声明的写路径内实施。 - 阻塞：出现计划外且当前无法解除的问题。 - 待验收：实现、测试和文档证据完成，等待负责人验收。 - 已完成：负责人明确验收并完成归档、关闭。 旧仓库任务的 DONE 不继承到新仓库。所有迁移项初始均为“待迁移”，必须用新代码、新测试和新验收重新证明。 ## 稳定业务规则 1. Sense 与 Bell 完全独立认证；同一自然人在两个产品中是两个账户。 2. 任一产品可独立部署、升级、备份、恢复和验收，另一产品不作为启动依赖。 3. Brain 不拥有用户、Alert、通知或业务审计真相。 4. 产品集成使用机器身份和版本化契约，不共享数据库、用户会话或内部模型。 5. Bell 以 `(producer_id, source_event_id)` 保持跨重启幂等。 6. Event 不可变；误报只追加 outcome/反馈，不改写原始事实。 7. `sent`、`delivered`、`seen`、`ack` 是不同事实；无回执不能当成功。 8. 未 ack 自动升级且进程重启后续跑；并发 ack 只有首个成功者成为处置人。 9. 联系人、排班和升级策略共享主数据但分对象、分版本；投递创建时固化实际收件人、通道和解析版本。 10. 静默必须限时并自动恢复，单次不超过 4 小时。 11. 默认 16 路，按 32/64/128 横向扩展；128 路不等于单机或单 GPU 承诺。 12. 首期 S2 民办寄宿学校只做匿名规则，不启用人脸。 13. 家庭卧室、卫生间禁止摄像头，只能使用非成像传感器。 14. 摄像头凭据、客户数据、真实视频、JWT secret 和生产配置不得进入仓库、工单或 Wiki。 15. 业务预警与设备/媒体/推理运维告警使用不同通道和责任人。 ## 新项目需要补充什么 以下事实必须由后续工单和负责人确认后补充： - 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/` 是按人工明确要求形成的专项或历史兼容快照，可能不完整或不是最新状态，不得替代工单。 - 默认不创建、导出或更新任务快照；导出过程不自动删除本地历史文件。