yovision/Brain/README.md

# YoVision Brain 单路工程原型

T-017 提供可见、可重复的单路工程链路；T-019 为 `zone_entry` 候选增加默认关闭的可靠 Brain→Bell transport。它仍不是生产模型或 NVR：推理演示保持单路，事件先进入仓库外 SQLite Outbox，再由内部 HMAC client 投递给 Bell。

## 环境

- Python `3.10.11`
- NumPy `1.26.4`
- OpenCV `4.9.0.80`

本任务复用本机已验证版本；新环境显式安装：

```powershell
python -m pip install -r Brain/requirements-demo.txt
```

本机冻结的是 `opencv-python`；同一环境只能安装一种提供 `cv2` 命名空间的 OpenCV wheel。不要同时安装标准、headless 和 contrib 变体。后续生产容器若改用 headless，必须在独立任务核对 wheel、许可证与完整回归，不能在本版本号下静默替换包名。

## 启动

无需摄像头的确定性合成回放：

```powershell
python -m Brain.yovision_brain --source synthetic
```

打开 `http://127.0.0.1:8090/brain-demo`。合成人员框由 fixture 提供，页面和事件均显式标识，不得拿它证明模型效果。

使用真实流时，把完整 RTSP URL 写入仓库外绝对路径文件。推荐指向 Sense 管理的 MediaMTX path，而不是绕过 Sense 固化摄像头地址：

```powershell
python -m Brain.yovision_brain --source stream --stream-url-file D:\private\brain-stream.url
```

URL 文件只允许一行、最多 4096 字节，服务不会在状态、页面和错误中返回其内容。演示服务只接受 `127.0.0.1`、`localhost` 或 `::1`；没有暴露到局域网的开关。

真实流使用 OpenCV 内置 HOG/SVM 人员检测和轻量 centroid tracker，只验证可替换端口与区域链路。它不是 M3 生产模型，不能据此承诺召回率、误报率、GPU 容量或 16/128 路能力。

## 可选 Brain → Bell 事件投递

默认不传 `--event-ingress-config`，工程原型行为与 T-017 相同。启用时，配置、key 和 SQLite 文件都必须位于仓库外绝对路径；HTTP 只允许显式回环，非回环必须 HTTPS。key 文件也供 Bell event ingress 读取，但不得与 Sense 审计 key 混用：

```json
{"version":1,"keys":[{"key_id":"brain-a","producer_id":"brain-main","secret_base64url":"<至少32字节随机值的无填充base64url>"}]}
```

Brain 配置示例（占位 ID 必须与 Bell 管理员创建的 `bell.event_ingress_bindings` 一致）：

```json
{
  "version": 1,
  "producer_id": "brain-main",
  "tenant_id": 1,
  "site_id": 1,
  "device_id": 1,
  "modality": "video",
  "severity": "medium",
  "config_version": "brain-demo-v1",
  "bell_url": "http://127.0.0.1:8081/internal/v1/event-candidates",
  "key_id": "brain-a",
  "key_file": "D:\\private\\brain-event-keys.json",
  "outbox_path": "D:\\private\\brain-event-outbox.sqlite3"
}
```

```powershell
python -m Brain.yovision_brain --source synthetic --event-ingress-config D:\private\brain-event-ingress.json
```

Outbox 使用 WAL 和 `synchronous=FULL`，首次打开即绑定 producer/tenant/site/device；更换身份必须使用新的 Outbox 路径，不能让旧队列借新 producer 发送。最多保留 10,000 条待投递；只有 Bell `accepted/duplicate` 才确认 delivered。网络、401 与 5xx 按 1～300 秒退避、最多 100 次；稳定 4xx 进入 dead letter。终态行不会自动删除。状态页只显示计数和稳定错误码，不显示 URL、key、payload 或数据库路径；client 显式忽略环境 HTTP proxy。

## 验证

```powershell
python -m unittest discover -s Brain/tests -p "test_*.py" -v
python -m compileall -q Brain
```

单文件 UI 原型位于 `docs/design/brain/index.html`，可直接打开；此时使用明确标识的离线原型数据。由本地服务打开时，同一文件消费回环 API，并用临时页面 token 保护区域写入。

## 边界

- `source_event_id` 由 Brain 产生，平台 `evt_` ULID 由 Bell 产生。
- 页面仍只保留最多 100 项的内存环；启用 T-019 后，可靠性由独立 SQLite Outbox 承担，不能从页面事件环推断投递状态。
- Bell 平台 ID 只由 Bell 生成；相同 producer/source candidate 重投返回原 ID，Brain 不改写 source ID 规避冲突。
- `D:\OPC\silver_pose` 保持独立，不是本模块的源码目录、运行依赖或模型来源路径。