架构设计

详细设计与决策依据见 raw/03-通用场景应用方案.md 和 raw/08-三系统职责划分.md。

1. 总体分层

YoVision 使用“通用底座 + 场景包”，按变化频率分为：

L0 基础设施 → L1 接入 → L2 流水线 → L3 能力 → L4 业务编排 → L5 场景包

L1–L4 是可复用平台能力。
L5 只包含规则模板、升级策略、话术和报表口径，必须能通过配置交付。
规则位于推理之后、告警之前；不可编进模型或 MediaMTX 配置。

2. 三系统

系统	语言/状态	职责	不负责
Sense	Go，有状态	设备台账（`modality + capabilities`）、ONVIF、MediaMTX 控制、对账、探活、隧道、设备型触发、流分片、隐私区域设备准入	AI 判定、事件业务、预警
Brain	Python/CUDA，业务无状态	解码/推理、检测/姿态/跟踪/ReID、时间窗判定、事件 mapper、像素级触发	设备真相源、告警升级、租户权限
Bell	Go + Web，有状态	事件校验/存储、规则、预警状态机、投递、反馈、租户/RBAC、审计、配额真相源和管理端	媒体转发、模型执行

MediaMTX、PostgreSQL、MinIO、Prometheus 等作为独立基础设施部署。

3. 部署与系统边界

首期每个客户部署一套私有实例，数据和事件证据留在客户环境；数据库实体、RBAC、配置与 API 从第一版携带 tenant_id 并保持 SaaS-ready 边界。
Bell 自研且是事件、Alert、ack、升级链、租户和审计的唯一业务真相源；客户平台通过版本化 OpenAPI/Webhook 集成，不反向接管核心状态机。
M1–M3 的视频入口只有 ONVIF/RTSP。现有 NVR 在售前盘点；仅支持 GB/T 28181 的项目必须建立独立适配器任务，不把国标信令混入 Sense 最小骨架。
M3 客户端为值班室 Web + 响应式移动 H5，可嵌入客户系统；是否开发原生 App 在 M4 后另行决定。

4. 核心数据流

摄像头/传感器
    │
    ▼
Sense ── 视频流/触发信号 ──> Brain
  │                            │
  │ 设备与切片 API             │ 事件契约 v0.1
  │                            ▼
  └────────────────────────── Bell ──> Web/H5/短信/语音/Webhook/本地声光
                                  └──> outcome/误报反馈回 Brain

主流程：

Bell 持有站点配额；Sense 在新增/启用设备时通过版本化内部 API 或只读投影校验。
Sense 维护设备期望态，通过 MediaMTX API 和对账器收敛实际态。
Brain 消费视频与触发信号，产生符合 v0.1 的事件。
Bell 做 schema 与代码级断言，生成平台 ULID，保存不可变事件。
规则命中后创建独立 Alert，先落库再投递，等待 ack 并按策略升级。
Bell 发起 pre-roll 证据回捞，Sense 提供切片接口。
用户标记 outcome，反馈进入 Brain 的数据闭环。

首个 M3 数据流部署在 S2 民办寄宿学校的 16 路高风险点位，只运行越线、危险区域和聚集等匿名规则，不加载人脸底库。

5. 十条不可越界的决定

MediaMTX 独立运行，Sense 管配置与生命周期。
设备型触发源归 Sense；需要解码的像素级触发归 Brain。
pre-roll 由 Bell 发起、Sense 切片；Brain 不直接管理录像。
平台事件 ULID 由 Bell 生成；Brain 只填 source_event_id。
一个 PostgreSQL 实例，sense/bell schema 分离；Brain 无业务 schema。
16/128 都不是单机保证；媒体与推理按独立分片横向扩展。
Bell 拥有 site.max_video_channels，Sense 在设备写路径执行；不跨 schema 直接写。
事件片段写入客户侧 MinIO/S3，常态录像留在客户 NVR；元数据/审计、人脸和训练样本使用独立生命周期。
投递状态机只依赖 Bell provider 接口，不直接依赖某家短信或语音 SDK；生产前至少两条独立路径并能故障切换。
设备领域模型使用 modality + capabilities，页面不以摄像头作为唯一根实体；隐私策略属于 Area，Sense 在新增/启用写路径按成像能力执行，策略不可用时只阻断新变更，不静默切断已有链路。

6. 容量架构

site.max_video_channels 默认 16、最大 128。
media_shard.max_streams 初始建议 32，可按故障域降为 16，最终由压测确定。
inference_profile.max_sources 由模型、FPS、分辨率、batch 和硬件基准决定。
流绑定必须记录 mtx_instance/分片归属；路由变化不改判定与业务代码。
单分片故障不能扩散到其他分片。
管理端默认查看 16 路，但按 128 路设计分页、虚拟列表、筛选和批量操作。

7. 一致性与失败处理

PostgreSQL 是期望态真相源；MediaMTX、推理 worker 和对象存储是可对账的实际态。
对账器水平触发、幂等、指数退避、限制并发；部分失败不做跨系统回滚，只持续收敛。
孤儿删除必须有 10% 安全闸和人工可观察指标。
配额读取失败只阻止新增/启用，不中断已有流。
Brain 投递失败落本地队列重试，不阻塞实时推理主链路。
Alert 先落库再投递，进程重启恢复未完成升级链。
事件证据技术默认保留 30 天并按生命周期删除；客户/法务在 M3 生产上线前确认法规适用性和最终期限，技术默认值不能覆盖其结论。

8. 数据与契约

核心实体：Tenant → Site → Area（含 capture_policy）/Device（含 modality + capabilities）→ StreamBinding/Zone；Rule → Event → Alert → DeliveryAttempt/Ack。
Event 与 Alert 不合并：一个事件可触发多次预警与投递，一次预警也可聚合多个事件。
事件 v0.1 以 raw/contracts/event-v0.1.schema.json 与 raw/contracts/README.md 为准；未知顶层字段拒绝，只允许通过 ext 扩展。
v0.1 还需代码校验时间自洽、confidence 当前为 null、证据文件名隐私、唯一 primary sensor 等跨字段约束。
S2 MVP 不处理人脸。首个人脸试点最早 M5，只允许经法务/客户门禁确认的 S4 成人访客/承包商白名单（≤10,000 人），并提供非人脸替代方式。

9. 目录目标

Sense/cmd + Sense/internal/{device,onvif,mtx,reconcile,probe,trigger,tunnel,authcb,store}
Brain/{pipeline,models,judge,emit,trigger,contracts}
Bell/cmd + Bell/internal/{ingest,event,rule,alert,deliver,feedback,tenant,audit,store}
Bell/{web,packs,contracts}

当前只有空目录占位；真实脚手架必须由对应任务创建。

10. 开发顺序

M0 不写生产代码。
M1 只动 Sense，5 路视频接入骨架与 MediaMTX；设备模型从此时起保持模态/能力可扩展，但不提前实现非视频适配器。
M2 仍以 Sense 为主，完成 16 路开通/停用、对账、多租户投影与隧道。
M3 Brain 与 Bell 同时起步，事件契约首次被真实使用。
M4/M5 再做 64/128 路分片、完整管理端和多个场景包；M6 接入雷达、门磁、按钮和可穿戴等非视频适配器。

M3 先执行不少于 2 周的 dry-run，冻结现场标注集，按规则报告召回率和每路每天误报数；现场基线评审后才把数值阈值写入站点验收附件。算法效果指标与系统 SLA 分开验收。

任何任务若违反顺序或跨越系统边界，必须先修改架构决策并经评审，不得“先写再说”。

7.5 KiB Raw Blame History Unescape Escape