36 lines
2.3 KiB
Markdown
36 lines
2.3 KiB
Markdown
# Sense → Brain 媒体源与区域规则配置契约 v1
|
||
|
||
`yovision.source-config/v1` 是 Sense 发布、Brain 消费的完整配置快照。它只携带稳定逻辑标识、无凭据媒体引用、Profile 规格、归一化规则及完整性摘要，不暴露 Sense 数据库模型或 Brain 内部配置模型。
|
||
|
||
本版本选择 JSON Schema，而不是 OpenAPI：快照可经文件、消息或后续 connector 传输，工单 #148 不定义 HTTP 端点。后续 connector 若提供 HTTP API，应引用本 Schema，不复制字段定义。
|
||
|
||
## 文件
|
||
|
||
- `source-config.schema.json`：Draft 2020-12 JSON Schema。
|
||
- `examples/valid/`：可接受的 active 与待重校准快照。
|
||
- `examples/invalid/`：必须安全拒绝的版本、秘密、路径、坐标和绑定错误。
|
||
- `compatibility.md`：版本、兼容周期、迁移和回退规则。
|
||
- `mapper-fields.md`：Sense 生产者与 Brain 消费者字段映射和测试责任。
|
||
|
||
## 消费规则
|
||
|
||
1. 先按 JSON Schema 校验，再执行跨字段语义校验。
|
||
2. `schema_version` 必须精确等于 `yovision.source-config/v1`；未知主版本不得降级猜测。
|
||
3. `rule_set.profile_binding` 必须与 `profile.id/width/height` 完全一致。
|
||
4. `rule_set.state != active` 时不得运行任何规则；`recalibration_required` 表示 Profile 规格变化后需重新标定。
|
||
5. `areas` 与 `directional_lines` 的 `id` 在同一快照内必须全局唯一；多边形必须非退化，线段起终点不得相同。
|
||
6. `effective_at` 不得早于 `published_at`。
|
||
7. `integrity.value` 是移除顶层 `integrity` 后，对 RFC 8785 JCS 规范化 JSON 字节计算的 SHA-256 小写十六进制摘要。生产消费者应使用合规 JCS 实现；仓库样例只使用 JCS 简单类型子集。
|
||
|
||
`media.ref` 是 connector 解析的无凭据不透明引用，固定以 `media:` 开头。它不能包含 URI authority、用户名、密码、查询参数、fragment、Windows 盘符或文件系统路径。RTSP 凭据交换与机器身份不属于本契约。
|
||
|
||
## 可复制验证
|
||
|
||
从仓库根目录运行：
|
||
|
||
```powershell
|
||
& contracts\tests\source-config-v1\run.ps1
|
||
```
|
||
|
||
脚本在系统临时目录创建隔离虚拟环境、安装固定版本的 Schema 校验器并运行测试，不修改产品目录。测试结束后会清理临时环境。
|