# API 与契约

> 事件契约 v0.1 已冻结；其他 API 仍在设计阶段。不得把本文的“待定”自行具体化为公共契约。

## 1. 已冻结：Brain → Bell 事件契约

- Schema：[`raw/contracts/event-v0.1.schema.json`](raw/contracts/event-v0.1.schema.json)
- 语义、kind 注册表、映射和代码级断言：[`raw/contracts/README.md`](raw/contracts/README.md)
- 示例：`raw/contracts/event-v0.1.example-*.json`

关键规则：

- 顶层未知字段拒绝；扩展只能放 `ext`。
- Brain 提供 `source_event_id`，Bell 生成平台 ULID。
- `confidence` 允许 null，当前判定链路必须为 null。
- `detected_at >= occurred_at`，时间与 `latency_seconds` 自洽。
- 证据文件名只含事件 ID 与日期目录，不含 IP、端口、凭据或客户名。
- `sensors` 中恰有一个 primary，且其 `device_id` 与顶层一致。

## 2. 待冻结的内部接口

| 调用方 → 提供方 | 用途 | 当前约束 | 状态 |
| --- | --- | --- | --- |
| Sense → Bell | 读取站点视频配额 | 版本化；默认 16、最大 128；失败时拒绝新增/启用但不影响已有流 | 待 M2 设计 |
| Bell → Sense | 请求事件证据/pre-roll 切片 | 幂等、按租户授权、异步结果、不得暴露原始凭据 | 待 M3 设计 |
| Bell → Brain | outcome/误报反馈 | 原事件不可变；反馈可重试、去重、审计 | 待 M3 设计 |
| Sense → Brain | 流绑定与设备型触发 | 分片可路由，触发入口与流控制解耦 | 待 M2/M3 设计 |
| Worker → 控制面 | 注册、心跳、容量 | `max_sources` 来自 profile/压测，不固定为 16 | 待 M3 设计 |

## 3. 待冻结的 Bell 公共 API

资源范围预计包括：租户、站点、设备只读投影、规则、事件、预警、ack、处置、误报反馈、审计和报表。设计时必须满足：

- URL 版本化，例如 `/api/v1/...`；具体路径须由对应任务冻结。
- 租户从认证上下文确定，不信任客户端随意传入的 tenant ID。
- 列表强制分页、稳定排序和可组合筛选；批量操作返回逐项结果。
- 写操作支持幂等键或等价机制；并发更新使用版本/ETag 或明确冲突响应。
- 错误体包含稳定错误码、可读消息和 trace ID，不返回内部堆栈或凭据。
- 人脸功能未授权时表现为能力不存在，而非仅按钮置灰。

## 4. MediaMTX 接口边界

Sense 使用 MediaMTX 官方 OpenAPI 生成客户端并加薄封装。业务代码不得散落硬编码 path API；生成代码不可手改。MediaMTX path 不是租户/站点/设备的业务真相源。

## 5. 变更流程

1. 在对应任务文件写清调用方、提供方、数据所有者、失败语义、幂等与兼容策略。
2. 更新本文和 schema/OpenAPI。
3. 同步生产者、消费者、契约测试和示例。
4. 记录迁移、回滚与版本废弃策略。

事件 v0.1 的破坏性变化必须发布新版本，不能原地修改已被 M3 生产者/消费者使用的契约。