feat: implement T-019 reliable event ingress
Harness governance / validate (pull_request) Has been cancelled
Harness governance / validate (pull_request) Has been cancelled
This commit is contained in:
QiuSW
@@ -40,7 +40,7 @@ MVP 以默认 16 路跑通一个场景的端到端闭环；架构、数据和 UI
|
||||
|
||||
## 当前阶段
|
||||
|
||||
当前为 **M0 指定型号实机准入、M1 Sense 五路混合源集成和 M2 本地 16 路软件基线均已完成，M3 已建立 Bell 不可变事件存储、Sense→Bell 全局审计 relay、Brain 单路可视化工程原型，并完成 T-018 Sense 回环 NVR 管理面纵切**。后续本地开发统一使用已准入的一台海康样机，多路软件闭环使用独立合成 RTSP 源补足；真实多设备证据延后到客户/借用/租赁条件具备时执行。客户网络尚未提供，T-013 WireGuard 继续后置；当前执行 T-019，建立 Brain→Bell 可靠业务事件 ingress。
|
||||
当前为 **M0 指定型号实机准入、M1 Sense 五路混合源集成和 M2 本地 16 路软件基线均已完成，M3 已建立 Bell 不可变事件存储、Sense→Bell 全局审计 relay、Brain 单路可视化工程原型、Sense 回环 NVR 管理面纵切和 Brain→Bell 可靠事件 ingress**。后续本地开发统一使用已准入的一台海康样机，多路软件闭环使用独立合成 RTSP 源补足；真实多设备证据延后到客户/借用/租赁条件具备时执行。客户网络尚未提供，T-013 WireGuard 继续后置；下一项建议把 Bell 规则→Alert→ack 最小纵切与证据切片拆成独立任务。
|
||||
|
||||
优先路径：
|
||||
|
||||
|
||||
@@ -87,6 +87,12 @@ T-018 不增加生产或前端依赖：Go 使用标准库 `embed`/`net/http` 提
|
||||
|
||||
该选择只适用于默认关闭的回环工程控制台，不冻结 Bell 最终前端框架。页面默认 16 项 cursor 分页、最多 4 路按需预览且不自动加载视频；Sense HTTP 与 WebRTC 基地址必须同时是显式回环地址。非回环 HTTPS/JWT/OIDC、MediaMTX 外部认证、录像/回放和正式客户会话均保持待冻结，不能从 T-018 的本地演示外推为生产安全或 NVR 存储能力。
|
||||
|
||||
### 1.7 Brain → Bell 事件 ingress（T-019）
|
||||
|
||||
T-019 不增加第三方依赖。Brain 继续使用 Python 3.10.11 标准库 `sqlite3`、`urllib`、HMAC/SHA-256 和线程；SQLite Outbox 开启 WAL 与 `synchronous=FULL`，文件、配置和 key 都必须是仓库外绝对路径。内部 HTTP client 显式禁用环境代理，避免业务事件被 `HTTP(S)_PROXY` 意外转发；回环可用 HTTP，非回环只接受 HTTPS。队列最多 10,000 条待投递、单 payload 1 MiB、1～300 秒退避、最多 100 次，终态记录保留供运维核查。
|
||||
|
||||
Bell 复用已冻结 Go 1.26.5、PostgreSQL 17.10/pgx、JSON Schema 和 ULID，不新增消息总线或 SDK。`brain-event-ingress-v1` 是单事件、producer-bound HMAC 内部适配器；Bell 用永久来源收据和事务级 advisory lock 保证同 `(producer_id, source_event_id)` 只生成一个平台事件。该选择不冻结 Bell 公共认证、生产 Brain GPU/runtime 或未来高吞吐 transport；若容量基准证明单条 HTTP 不足，必须发布兼容迁移方案，不能绕过来源幂等键。
|
||||
|
||||
## 2. 外部项目边界
|
||||
|
||||
- MiBeeNvr：只用于 M0 隔离实验室、ONVIF兼容性和交互参考，不作为生产依赖。
|
||||
@@ -98,7 +104,7 @@ T-018 不增加生产或前端依赖：Go 使用标准库 `embed`/`net/http` 提
|
||||
|
||||
- Python、Savant/DeepStream 的精确版本；Go、MediaMTX 与 PostgreSQL 已分别为 Sense M1/M2 冻结，后续阶段可按升级流程调整。
|
||||
- Bell 前端框架和组件库。
|
||||
- Brain→Bell 业务事件投递 transport；Sense→Bell 审计 relay 已独立冻结为内部 HTTP，不能据此默认 Brain transport。
|
||||
- Brain 生产推理 runtime 与更高吞吐 transport；T-019 已冻结首版 Brain→Bell 单事件内部 HTTP ingress，但不据此承诺 64/128 路吞吐或消息总线选型。
|
||||
- 目标 GPU/边缘硬件、解码能力和每 worker 的 `max_sources`。
|
||||
- MinIO/S3 的精确版本、加密实现，以及客户/法务确认后的最终生命周期策略。
|
||||
- 短信/语音供应商及生产双路径组合；是否开发原生 App 最早在 M4 根据试点反馈决定。
|
||||
|
||||
+10
-9
@@ -47,15 +47,15 @@ Sense ── 视频流/触发信号 ──> Brain
|
||||
|
||||
1. Bell 持有站点、Area、配额与 `capture_policy`；首期在同一 PostgreSQL 实例内发布 `bell.site_quota_v1` 和 `bell.area_policy_v1` 两个版本化只读视图。T-009/T-010 已实现 Bell 源表/视图、最小权限和 Sense PostgreSQL repository；Sense 按 Area→Site 的固定 advisory-lock 顺序执行策略与配额准入并记录所用版本。未来分库必须发布新版本契约，不能静默改变 v1 语义。
|
||||
2. Sense 维护设备期望态，通过 MediaMTX API 和对账器收敛实际态；PostgreSQL 多实例以数据库时钟短租约和 fencing token 领取 due row，过期 worker 不得提交结果。
|
||||
3. Brain 消费视频与触发信号，产生符合冻结契约的事件候选。T-017 已先建立单路 frame source、可替换 detector、轻量 track、多边形进入判定和回环可视化工程原型；合成 fixture 与 OpenCV HOG 均明确不是生产模型，候选只含 `source_event_id`，不自报平台 `id`。T-018 的 Sense 回环控制台只读取设备事实并按需嵌入 MediaMTX WebRTC 页面，不代理媒体、不参与推理或事件生成。
|
||||
4. Bell 做 schema 与代码级断言，生成平台 ULID，保存不可变事件。T-015 已实现内部 candidate→final event factory、append-only PostgreSQL repository 和独立 outcome 事实；Brain→Bell transport、认证和公共 API 仍未冻结。
|
||||
3. Brain 消费视频与触发信号，产生符合冻结契约的事件候选。T-017 已建立单路 frame source、可替换 detector、轻量 track、多边形进入判定和回环可视化工程原型；T-019 把候选先写入仓库外 SQLite Outbox，再经 producer-bound HMAC 内部 HTTP 投递。合成 fixture 与 OpenCV HOG 均不是生产模型，Brain 只生成 `source_event_id`，不自报平台 `id`。T-018 的 Sense 回环控制台不参与推理或事件生成。
|
||||
4. Bell 做身份/Area 隐私、schema 与代码级断言，生成平台 ULID，保存不可变事件。T-015 已实现内部 candidate→final event factory、append-only PostgreSQL repository 和独立 outcome 事实；T-019 增加数字事件身份到 Bell/Sense 逻辑身份的受控绑定、永久来源收据和短期 nonce 收据。该 ingress 是内部适配器，Bell 公共 API/JWT/OIDC 仍未冻结。
|
||||
5. 规则命中后创建独立 Alert，先落库再投递，等待 ack 并按策略升级。
|
||||
6. Bell 发起 pre-roll 证据回捞，Sense 提供切片接口。
|
||||
7. 用户标记 outcome，反馈进入 Brain 的数据闭环。
|
||||
|
||||
首个 M3 数据流部署在 S2 民办寄宿学校的 16 路高风险点位，只运行越线、危险区域和聚集等匿名规则，不加载人脸底库。
|
||||
|
||||
## 5. 十二条不可越界的决定
|
||||
## 5. 十三条不可越界的决定
|
||||
|
||||
1. MediaMTX 独立运行，Sense 管配置与生命周期。
|
||||
2. 设备型触发源归 Sense；需要解码的像素级触发归 Brain。
|
||||
@@ -69,6 +69,7 @@ Sense ── 视频流/触发信号 ──> Brain
|
||||
10. 设备领域模型使用 `modality + capabilities`，页面不以摄像头作为唯一根实体；未实现协议适配器明确为 `adapter_not_ready`，不得用模拟遥测伪装交付。
|
||||
11. Tenant/Site/Area/RBAC、配额、`capture_policy` 与全局审计属于 Bell；Sense Control API v1 只管理 Device 期望态与收敛查询，Sense 只读消费版本化投影并在设备写路径执行，投影不可用时只阻断相关新变更，不静默切断已有链路。
|
||||
12. Sense 的设备操作审计先写本地持久化 Outbox，再由幂等 relay 异步送入 Bell 全局审计；不得使用“先执行高风险操作、再尽力入队”的顺序。T-016 已实现 HMAC/nonce 内部 HTTP relay、数据库时钟 lease/fencing、逐项确认与 Bell 不可变全局事实；Sense 不获得 Bell schema 权限，Bell 不读取 Sense Outbox。
|
||||
13. Brain 的业务事件同样先写仓库外持久 Outbox，再异步投递；Bell 以 `(producer_id, source_event_id)` 永久收据而非短期 nonce 保证跨重启幂等。只有 `accepted/duplicate` 可确认本地 delivered；事件 ID 始终由 Bell 生成，稳定冲突不得自动改写来源 ID 或 payload。
|
||||
|
||||
## 6. 容量架构
|
||||
|
||||
@@ -93,8 +94,8 @@ T-014 已在单台 Windows 主机上用隔离 PostgreSQL、真实 Control API、
|
||||
- 设备创建和期望态受理在本地事务内同时写脱敏 `sense.device_operation_outbox`；Outbox 失败回滚业务写入，相同期望态不增加 generation 但仍审计。relay 最多领取 100 行，以 30 秒数据库 lease 和单调 fencing token 防止过期 worker 确认；成功和 dead letter 都保留本地事实。
|
||||
- Bell 先验证时间窗、nonce 和 constant-time HMAC，再逐项校验 v1/v2 事件；同 nonce/同摘要重放原结果，同 nonce/不同摘要拒绝。`bell.audit_events` 只追加且不自动清理，只有 10 分钟幂等收据允许 Bell runtime 删除过期行。
|
||||
- Bell 最终事件写入 `bell.events`；同平台 ID/同摘要仅视为幂等重放，同 ID/不同摘要拒绝。`bell_runtime` 只有 `SELECT/INSERT`，事件与 outcome 的 UPDATE/DELETE 另由数据库 trigger 拒绝；后续人工/自动 outcome 追加到独立表，不改写事件 payload。
|
||||
- Brain 投递失败落本地队列重试，不阻塞实时推理主链路。
|
||||
- T-017 的 100 项内存事件环只服务单路工程演示，重启可丢失且不等同于上述投递队列；Brain→Bell 后续建议 T-019 必须另行实现有界持久 Outbox、身份映射、认证和幂等确认，不能把 demo 内存状态升级为生产 transport。T-018 先实现 Sense 回环 NVR 管理面纵切，不改变该事件链边界。
|
||||
- T-019 的 Brain SQLite Outbox 与推理内存环分离：最多 10,000 条待投递，网络/5xx/认证故障按 1～300 秒重试，最多 100 次；稳定 4xx 进入 dead letter。Outbox 写入失败时不得在演示状态中伪装为已排队或已投递。
|
||||
- Bell 先按 HMAC key 绑定 producer，再解析候选；永久来源收据、最终 event 和成功 nonce 响应同事务提交。同来源/同 canonical hash 返回原 Bell ID，同来源/不同 hash 返回冲突。T-017 的 100 项内存环仍只服务页面显示，不承担可靠投递。
|
||||
- Alert 先落库再投递，进程重启恢复未完成升级链。
|
||||
- 值班排班发布前必须按 Site 时区校验班次空档、重叠、联系人停用和通道验证；排班以新版本和未来生效时间发布，不原地改写历史。交接班是进行中 Alert 的显式责任转移事件，不替代排班版本变更。
|
||||
- 事件证据技术默认保留 30 天并按生命周期删除；客户/法务在 M3 生产上线前确认法规适用性和最终期限，技术默认值不能覆盖其结论。
|
||||
@@ -102,7 +103,7 @@ T-014 已在单台 Windows 主机上用隔离 PostgreSQL、真实 Control API、
|
||||
## 8. 数据与契约
|
||||
|
||||
- Bell 核心实体：Tenant → Site → Area（含 `capture_policy`）以及 Role/Binding/Quota/Audit；Sense 核心实体：Device（含 `modality + capabilities`）→ StreamBinding/Zone，以及只记录已观察版本的 SiteQuota/AreaPolicyProjection。两个 schema 以稳定逻辑 ID 关联，不跨 schema 写入；配额 v1 为五列，Area v1 固定为 `tenant_id/site_id/area_id/capture_policy/source_version/source_updated_at` 六列。
|
||||
- Sense Control API v1 使用站点作用域路径、认证上下文 tenant、HMAC cursor 分页、PostgreSQL 幂等收据与资源 ETag；敏感连接引用只写不读。T-011 已实现 7 个 handler，并以 feature flag 限定到 PostgreSQL 路径；首版外部静态 SHA-256 注册表只实现认证 port 的私有部署适配器。T-016 审计 relay 采用独立外部 HMAC key 文件和内部端点，不等同于 Bell 公共管理认证。正式签名和兼容规则以 [`contracts/`](contracts/) 为准。
|
||||
- Sense Control API v1 使用站点作用域路径、认证上下文 tenant、HMAC cursor 分页、PostgreSQL 幂等收据与资源 ETag；敏感连接引用只写不读。T-011 已实现 7 个 handler，并以 feature flag 限定到 PostgreSQL 路径。T-016 审计 relay 与 T-019 Brain 事件 ingress 各用独立外部 HMAC key/端点，均不等同于 Bell 公共管理认证。正式签名和兼容规则以 [`contracts/`](contracts/) 为准。
|
||||
- 业务实体：Rule → Event → Alert → DeliveryAttempt/Ack；Event 与 Alert 不合并。
|
||||
- Bell 通知域分为三个聚合：Contact/Team 保存身份、成员关系和已验证通道；OnCallSchedule/ScheduleVersion/ShiftException 保存时区、轮换与例外；EscalationPolicy/Step 通过 `person / team / on_call_schedule` 类型化 `target_ref` 引用目标。三者共享逻辑 ID，不复制手机号、班次或轮换字段。
|
||||
- 每个 DeliveryAttempt 创建时解析当时生效的排班版本，并保存实际收件人、通道、`schedule_version` 和解析时间快照；之后联系人或排班修改不得回写既有投递事实。
|
||||
@@ -118,17 +119,17 @@ Sense/cmd + Sense/internal/{device,onvif,mtx,reconcile,orphan,metrics,probe,trig
|
||||
Brain/{pipeline,models,judge,emit,trigger,contracts}
|
||||
Bell/cmd + Bell/internal/{ingest,event,rule,alert,deliver,feedback,tenant,audit,store}
|
||||
Bell/{web,packs,contracts}
|
||||
deploy/postgres/{001_roles.sql,...,015_privileges_audit_relay.sql,tests}
|
||||
deploy/postgres/{001_roles.sql,...,017_privileges_event_ingress.sql,tests}
|
||||
```
|
||||
|
||||
Sense 脚手架和 PostgreSQL `001`～`015` 已实现；Bell 已有事件校验/不可变存储 Go 基础和只面向 Sense 审计 relay 的最小 `bell-api`，但没有公共管理 API。Brain 已有 T-017 单路工程原型，包括合成/RTSP source、HOG 演示 detector、track、zone entry、回环服务与自包含 UI；尚无生产模型、GPU pipeline、持久 Outbox 或 Bell ingress。
|
||||
Sense 脚手架和 PostgreSQL `001`～`017` 已实现；Bell 已有事件校验/不可变存储、Sense 审计 relay 与默认关闭的 Brain 事件 ingress，但没有公共管理 API。Brain 已有单路工程原型和仓库外 SQLite 可靠事件 Outbox；尚无生产模型、GPU pipeline、证据切片或规则/Alert 链。
|
||||
|
||||
## 10. 开发顺序
|
||||
|
||||
- M0 不写生产代码。
|
||||
- M1 只动 Sense，以 1 路 T-001 准入实机 + 至少 4 路独立合成 RTSP 源完成五路接入骨架与 MediaMTX；设备模型从此时起保持模态/能力可扩展，但不提前实现非视频适配器。真实多设备现场门禁移到 T-007，阻塞生产试点但不阻塞本地开发。
|
||||
- M2 仍以 Sense 为主；Control API、对账、多租户投影和本地 16 路开通/停用基线已完成，隧道等待客户网络条件后补验。
|
||||
- M3 Brain 与 Bell 同时起步，事件契约首次被真实使用；按项目负责人调整，T-017 后先补 Sense 回环 NVR 管理面纵切，再继续 Brain→Bell 事件 ingress。
|
||||
- M3 Brain 与 Bell 同时起步；T-015～T-019 已打通不可变事件消费者、审计 relay、Brain 单路候选、Sense 回环管理纵切和 Brain→Bell 可靠事件 ingress。下一步仍应在证据切片与规则/Alert 之间按客户可见闭环拆分独立任务。
|
||||
- M4/M5 再做 64/128 路分片、完整管理端和多个场景包；M6 接入雷达、门磁、按钮和可穿戴等非视频适配器。
|
||||
|
||||
M3 先执行不少于 2 周的 dry-run，冻结现场标注集，按规则报告召回率和每路每天误报数；现场基线评审后才把数值阈值写入站点验收附件。算法效果指标与系统 SLA 分开验收。
|
||||
|
||||
+4
-3
@@ -1,6 +1,6 @@
|
||||
# API 与契约
|
||||
|
||||
> Brain → Bell 事件契约 v0.1、Sense Control API v1、Bell 配额/Area 只读投影 v1、Sense 本地设备审计事件 v1/v2 与 Sense→Bell 审计 relay v1 已冻结；其他 API 仍在设计阶段。不得把本文的“待定”自行具体化为公共契约。
|
||||
> Brain → Bell 事件契约 v0.1 与内部 ingress v1、Sense Control API v1、Bell 配额/Area 只读投影 v1、Sense 本地设备审计事件 v1/v2 与 Sense→Bell 审计 relay v1 已冻结；其他 API 仍在设计阶段。不得把本文的“待定”自行具体化为公共契约。
|
||||
|
||||
## 1. 已冻结：Brain → Bell 事件契约
|
||||
|
||||
@@ -17,7 +17,7 @@
|
||||
- 证据文件名只含事件 ID 与日期目录，不含 IP、端口、凭据或客户名。
|
||||
- `sensors` 中恰有一个 primary，且其 `device_id` 与顶层一致。
|
||||
|
||||
T-015 已实现 Bell 消费端的内部组装与存储边界：可信 ingress 先接收“不含平台 `id`”的候选事实，Bell 生成 `evt_` ULID 后形成最终 v0.1 对象，再执行 schema 与六项代码断言并不可变落库。该候选类型是 Bell 内部 port，不是 Brain 可依赖的 HTTP/消息总线协议；transport、认证和重放语义仍由后续任务冻结。
|
||||
T-015 已实现 Bell 消费端的内部组装与存储边界；T-019 在 [`contracts/brain-event-ingress-v1.openapi.json`](contracts/brain-event-ingress-v1.openapi.json) 冻结并实现网络适配器。Brain 发送“不含平台 `id`”的完整候选，Bell 生成 `evt_` ULID 后执行 schema、六项代码断言与不可变落库。内部 endpoint 使用独立 producer-bound HMAC key，不是 Bell 公共 API 或 JWT/OIDC 的替代品。
|
||||
|
||||
## 2. 跨系统接口状态
|
||||
|
||||
@@ -26,12 +26,13 @@ T-015 已实现 Bell 消费端的内部组装与存储边界：可信 ingress
|
||||
| Sense → Bell | 读取站点视频配额 | 同一 PostgreSQL 实例内只读 `bell.site_quota_v1`；默认 16、最大 128；失败时拒绝新增/启用但不影响已有流 | T-008 冻结，T-009 已实现数据路径 |
|
||||
| Sense → Bell | 读取 Area 成像准入 | 只读 `bell.area_policy_v1`；`video_allowed | non_imaging_only`；缺失/非法/回退失败关闭但不影响已有设备 | T-010 已冻结并实现数据路径 |
|
||||
| Sense → Bell | 汇入设备操作审计 | `POST /internal/v1/audit-events:batch`；1～100 项、1 MiB、10 秒 deadline、HMAC/nonce、逐项确认；非回环必须 HTTPS | T-016 已冻结并实现 |
|
||||
| Brain → Bell | 汇入业务事件候选 | `POST /internal/v1/event-candidates`；单条完整 v0.1-minus-id candidate、1 MiB、10 秒 deadline、producer-bound HMAC、永久来源收据；非回环必须 HTTPS | T-019 已冻结并实现 |
|
||||
| Bell → Sense | 请求事件证据/pre-roll 切片 | 幂等、按租户授权、异步结果、不得暴露原始凭据 | 待 M3 设计 |
|
||||
| Bell → Brain | outcome/误报反馈 | 原事件不可变；反馈可重试、去重、审计 | 待 M3 设计 |
|
||||
| Sense → Brain | 流绑定与设备型触发 | 分片可路由，触发入口与流控制解耦 | 待 M2/M3 设计 |
|
||||
| Worker → 控制面 | 注册、心跳、容量 | `max_sources` 来自 profile/压测，不固定为 16 | 待 M3 设计 |
|
||||
|
||||
冻结签名和失败语义见 [`contracts/README.md`](contracts/README.md)、[`contracts/sense-audit-relay-v1.openapi.json`](contracts/sense-audit-relay-v1.openapi.json)、[`contracts/site-quota-v1.sql`](contracts/site-quota-v1.sql)、[`contracts/area-policy-v1.sql`](contracts/area-policy-v1.sql) 与 [`contracts/sense-device-audit-v1.schema.json`](contracts/sense-device-audit-v1.schema.json)。Bell 拥有投影源数据和视图，Sense 数据库角色只有 `SELECT`；未来分库必须发布新版本，不能在 v1 下把本地视图静默替换为网络调用。
|
||||
冻结签名和失败语义见 [`contracts/README.md`](contracts/README.md)、[`contracts/brain-event-ingress-v1.openapi.json`](contracts/brain-event-ingress-v1.openapi.json)、[`contracts/sense-audit-relay-v1.openapi.json`](contracts/sense-audit-relay-v1.openapi.json)、[`contracts/site-quota-v1.sql`](contracts/site-quota-v1.sql)、[`contracts/area-policy-v1.sql`](contracts/area-policy-v1.sql) 与 [`contracts/sense-device-audit-v1.schema.json`](contracts/sense-device-audit-v1.schema.json)。Bell 拥有投影源数据、视图、事件身份绑定与来源收据；未来分库必须发布新版本，不能在 v1 下静默改变一致性或身份语义。
|
||||
|
||||
## 3. 已冻结：Sense Control API v1
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Sense 控制面、准入投影与本地审计契约 v1
|
||||
# YoVision 控制面、审计与内部事件传输契约 v1
|
||||
|
||||
> 冻结日期：2026-08-11。Control API 与审计 relay 契约版本：`1.0.0`。Sense 是设备期望态的提供方；Bell 是 Tenant、Site、Area、RBAC、配额与全局审计的所有者。T-016 已实现 Sense Outbox 到 Bell 的内部 relay；Bell 公共管理服务与 JWT/OIDC 仍未实现。
|
||||
> 冻结日期：2026-08-11。Control API、审计 relay 与 Brain 事件 ingress 契约版本：`1.0.0`。Sense 是设备期望态的提供方；Bell 是 Tenant、Site、Area、RBAC、配额、事件与全局审计的所有者。T-016 已实现 Sense Outbox 审计 relay，T-019 已实现 Brain 事件 Outbox ingress；Bell 公共管理服务与 JWT/OIDC 仍未实现。
|
||||
|
||||
## 契约文件
|
||||
|
||||
@@ -12,6 +12,7 @@
|
||||
| [`sense-device-audit-v1.schema.json`](sense-device-audit-v1.schema.json) | Sense | 本地 Outbox；Bell relay | 脱敏设备操作审计事实，不包含传输协议 |
|
||||
| [`sense-device-audit-v2.schema.json`](sense-device-audit-v2.schema.json) | Sense | 本地 Outbox；Bell relay | v1 后继，增加脱敏配置修改受理事实；v1 文件保持不变 |
|
||||
| [`sense-audit-relay-v1.openapi.json`](sense-audit-relay-v1.openapi.json) | Bell | Sense | 内部批量端点、HMAC、逐项确认、nonce 防重与重试边界 |
|
||||
| [`brain-event-ingress-v1.openapi.json`](brain-event-ingress-v1.openapi.json) | Bell | Brain | 单业务事件入站、producer/key 绑定、Bell ID 与跨重启幂等语义 |
|
||||
|
||||
OpenAPI 的 `/api/v1` 路径是公共控制面边界；`/healthz`、`/readyz` 仍是非业务运维探针。v1 不提供设备删除：停用设备使用期望态接口，保留设备、操作和审计历史。Site、Area、配额、RBAC 和审计聚合不由 Sense 提供 CRUD。
|
||||
|
||||
@@ -72,6 +73,20 @@ Outbox 用 30 秒数据库时钟 lease、单调 fencing token 和 `FOR UPDATE SK
|
||||
{"version":1,"keys":[{"key_id":"sense-a","secret_base64url":"<external-secret>"}]}
|
||||
```
|
||||
|
||||
## Brain → Bell 业务事件 ingress
|
||||
|
||||
Brain 向 `POST /internal/v1/event-candidates` 单条投递完整 event v0.1 candidate；candidate 与冻结最终事件的顶层字段完全一致，只省略 Bell 所有的 `id`。envelope 额外携带 `schema_version=1` 和 `producer_id`。Bell 校验 HMAC、key 与 producer 的绑定、当前逻辑设备/Area 映射、event schema 和六项语义断言后生成 `evt_` ULID；首次接受返回 `201 accepted`，同一来源事实重投返回 `200 duplicate` 和原 Bell ID。
|
||||
|
||||
认证 canonical string 与审计 relay 使用相同五行算法，但 key 文件独立且每项增加 `producer_id`，不得混用审计 key。正文最多 1 MiB、deadline 10 秒、允许 300 秒时钟偏差，nonce 收据至少保留 600 秒；HTTP 只允许回环地址，非回环必须 HTTPS。key 文件形态为：
|
||||
|
||||
```json
|
||||
{"version":1,"keys":[{"key_id":"brain-a","producer_id":"brain-main","secret_base64url":"<external-secret>"}]}
|
||||
```
|
||||
|
||||
Bell 的永久 `event_ingress_receipts` 以 `(producer_id, source_event_id)` 唯一并保存 canonical candidate SHA-256。相同 hash 重投返回原 event ID，不同 hash 返回 `409 source_event_conflict`；事件、来源收据和成功 nonce 响应在一个 PostgreSQL 事务中提交。`event_ingress_nonces` 只是 10 分钟防重表，可清理；来源收据和事件不自动删除、不可更新。Brain 必须先把 candidate 写入仓库外 SQLite Outbox，只有 `accepted/duplicate` 可标记 delivered；401、网络和 5xx 以 1～300 秒退避重试，稳定 4xx 进入 dead letter，最多 100 次、最多 10,000 条待投递。
|
||||
|
||||
数字 `tenant_id/site_id/device_id` 通过 Bell 所有的 `event_ingress_bindings` 映射到当前 Bell Site/Area 和 Sense Device 逻辑 ID。运行时只读取 Sense 设备的 ID、Area 与 modality 列，不获得 endpoint、credential、profile token 或 path；绑定缺失/禁用、设备或 Area 不一致、删除、非视频或 `capture_policy != video_allowed` 均失败关闭。首版绑定只由受控 migration/admin SQL 配置，没有公共 CRUD。
|
||||
|
||||
## 兼容与废弃
|
||||
|
||||
- v1 可增加不改变已有语义的可选响应字段和新错误细节；客户端必须忽略未知响应字段。
|
||||
@@ -87,9 +102,11 @@ Outbox 用 30 秒数据库时钟 lease、单调 fencing token 和 `FOR UPDATE SK
|
||||
python -m json.tool docs/contracts/sense-control-v1.openapi.json | Out-Null
|
||||
python -m json.tool docs/contracts/sense-device-audit-v2.schema.json | Out-Null
|
||||
python -m json.tool docs/contracts/sense-audit-relay-v1.openapi.json | Out-Null
|
||||
python -m json.tool docs/contracts/brain-event-ingress-v1.openapi.json | Out-Null
|
||||
python -m unittest discover -s tests -p "test_sense_control_contract.py"
|
||||
python -m unittest discover -s tests -p "test_sense_control_implementation.py"
|
||||
python -m unittest discover -s tests -p "test_sense_audit_relay_contract.py"
|
||||
python -m unittest discover -s tests -p "test_brain_event_ingress_contract.py"
|
||||
```
|
||||
|
||||
测试同时校验 OpenAPI 结构、生成 server glue、HTTP handler 与 PostgreSQL migration/事务；它不替代 Bell 消费方联合验收或客户现场容量验证。
|
||||
|
||||
@@ -0,0 +1,147 @@
|
||||
{
|
||||
"openapi": "3.1.0",
|
||||
"info": {
|
||||
"title": "YoVision Brain Event Ingress",
|
||||
"version": "1.0.0",
|
||||
"description": "Internal single-event transport. The candidate is the frozen event v0.1 object with only the Bell-owned id omitted."
|
||||
},
|
||||
"paths": {
|
||||
"/internal/v1/event-candidates": {
|
||||
"post": {
|
||||
"operationId": "ingestBrainEventCandidate",
|
||||
"summary": "Validate and persist one Brain event candidate",
|
||||
"parameters": [
|
||||
{"$ref": "#/components/parameters/KeyId"},
|
||||
{"$ref": "#/components/parameters/Timestamp"},
|
||||
{"$ref": "#/components/parameters/Nonce"},
|
||||
{"$ref": "#/components/parameters/Signature"}
|
||||
],
|
||||
"requestBody": {
|
||||
"required": true,
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {"$ref": "#/components/schemas/IngressRequest"}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"200": {"description": "The same producer/source candidate was already stored", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/IngressResponse"}}}},
|
||||
"201": {"description": "Candidate accepted and stored", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/IngressResponse"}}}},
|
||||
"400": {"$ref": "#/components/responses/Error"},
|
||||
"401": {"$ref": "#/components/responses/Error"},
|
||||
"403": {"$ref": "#/components/responses/Error"},
|
||||
"409": {"$ref": "#/components/responses/Error"},
|
||||
"413": {"$ref": "#/components/responses/Error"},
|
||||
"422": {"$ref": "#/components/responses/Error"},
|
||||
"503": {"$ref": "#/components/responses/Error"}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"components": {
|
||||
"parameters": {
|
||||
"KeyId": {"name": "X-YoVision-Key-Id", "in": "header", "required": true, "schema": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$"}},
|
||||
"Timestamp": {"name": "X-YoVision-Timestamp", "in": "header", "required": true, "schema": {"type": "string", "pattern": "^[0-9]{10,}$"}},
|
||||
"Nonce": {"name": "X-YoVision-Nonce", "in": "header", "required": true, "schema": {"type": "string", "minLength": 22, "maxLength": 64}},
|
||||
"Signature": {"name": "X-YoVision-Signature", "in": "header", "required": true, "schema": {"type": "string", "minLength": 43, "maxLength": 43}}
|
||||
},
|
||||
"schemas": {
|
||||
"IngressRequest": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["schema_version", "producer_id", "candidate"],
|
||||
"properties": {
|
||||
"schema_version": {"const": 1},
|
||||
"producer_id": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$"},
|
||||
"candidate": {"$ref": "#/components/schemas/EventV01Candidate"}
|
||||
}
|
||||
},
|
||||
"EventV01Candidate": {
|
||||
"description": "Exact docs/raw/contracts/event-v0.1.schema.json event object with the required Bell-owned id field removed; nested shapes and semantic assertions remain authoritative in that frozen contract.",
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": [
|
||||
"schema_version", "source_event_id", "tenant_id", "site_id", "device_id", "sensors",
|
||||
"kind", "severity", "confidence", "occurred_at", "detected_at", "latency_seconds",
|
||||
"config_version", "rule", "subject", "observation", "evidence", "dedup_key",
|
||||
"aggregated_into", "outcome", "outcome_source", "outcome_reason", "diagnostics", "ext"
|
||||
],
|
||||
"properties": {
|
||||
"schema_version": {"const": "0.1"},
|
||||
"source_event_id": {"type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$"},
|
||||
"tenant_id": {"type": "integer", "minimum": 1},
|
||||
"site_id": {"type": "integer", "minimum": 1},
|
||||
"device_id": {"type": "integer", "minimum": 1},
|
||||
"sensors": {"type": "array", "minItems": 1, "items": {"type": "object"}},
|
||||
"kind": {"type": "string", "pattern": "^[a-z][a-z0-9_]{2,63}$"},
|
||||
"severity": {"type": "string", "enum": ["low", "medium", "high", "critical"]},
|
||||
"confidence": {"type": ["number", "null"], "minimum": 0, "maximum": 1},
|
||||
"occurred_at": {"type": "string", "format": "date-time"},
|
||||
"detected_at": {"type": "string", "format": "date-time"},
|
||||
"latency_seconds": {"type": "number", "minimum": 0},
|
||||
"config_version": {"type": "string", "minLength": 1, "maxLength": 128},
|
||||
"rule": {"type": ["object", "null"]},
|
||||
"subject": {"type": "object"},
|
||||
"observation": {"type": ["object", "null"]},
|
||||
"evidence": {"type": "object"},
|
||||
"dedup_key": {"type": ["string", "null"]},
|
||||
"aggregated_into": {"type": ["string", "null"]},
|
||||
"outcome": {"type": "string"},
|
||||
"outcome_source": {"type": ["string", "null"]},
|
||||
"outcome_reason": {"type": ["string", "null"]},
|
||||
"diagnostics": {"type": ["object", "null"]},
|
||||
"ext": {"type": "object"}
|
||||
}
|
||||
},
|
||||
"IngressResponse": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["schema_version", "producer_id", "source_event_id", "event_id", "status"],
|
||||
"properties": {
|
||||
"schema_version": {"const": 1},
|
||||
"producer_id": {"type": "string"},
|
||||
"source_event_id": {"type": "string"},
|
||||
"event_id": {"type": "string", "pattern": "^evt_[0-9A-HJKMNP-TV-Z]{26}$"},
|
||||
"status": {"type": "string", "enum": ["accepted", "duplicate"]}
|
||||
}
|
||||
},
|
||||
"Error": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["error"],
|
||||
"properties": {
|
||||
"error": {"type": "string"},
|
||||
"detail_code": {"type": "string"}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"Error": {"description": "Stable machine-readable failure", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}
|
||||
}
|
||||
},
|
||||
"x-yovision-final-event-schema": "docs/raw/contracts/event-v0.1.schema.json",
|
||||
"x-yovision-signature": {
|
||||
"algorithm": "HMAC-SHA256",
|
||||
"canonical_lines": ["method", "escaped_path", "unix_timestamp_seconds", "base64url_nonce", "lowercase_hex_sha256_body"],
|
||||
"clock_skew_seconds": 300,
|
||||
"nonce_receipt_ttl_seconds": 600,
|
||||
"minimum_secret_bytes": 32,
|
||||
"key_document_shape": {"version": 1, "keys": [{"key_id": "brain-a", "producer_id": "brain-main", "secret_base64url": "external-secret"}]}
|
||||
},
|
||||
"x-yovision-delivery": {
|
||||
"maximum_body_bytes": 1048576,
|
||||
"deadline_seconds": 10,
|
||||
"initial_retry_seconds": 1,
|
||||
"maximum_retry_seconds": 300,
|
||||
"maximum_attempts": 100,
|
||||
"maximum_queued": 10000,
|
||||
"success_statuses": ["accepted", "duplicate"],
|
||||
"retryable_http": [401, 500, 502, 503, 504]
|
||||
},
|
||||
"x-yovision-idempotency": {
|
||||
"source_scope": ["producer_id", "source_event_id"],
|
||||
"same_candidate": "return duplicate with the original Bell event_id",
|
||||
"different_candidate": "409 source_event_conflict",
|
||||
"bell_owns_event_id": true
|
||||
}
|
||||
}
|
||||
+11
-9
@@ -4,28 +4,29 @@
|
||||
|
||||
## 当前阶段
|
||||
|
||||
- 阶段：M0 指定摄像头型号准入、M1“一实机 + 四合成源”软件闭环和 M2 本地 16 路批量收敛/稳定基线已通过；M3 已建立 Bell 不可变事件存储、Sense→Bell 全局审计 relay 及 Brain 单路匿名区域事件工程原型。客户网络尚未提供，WireGuard T-013 后置，五条独立真实上游和生产 SLA 仍未验收。
|
||||
- 生产代码：Sense 已包含可构建进程、SQLite/PostgreSQL repository、Site/Area 准入、设备操作 Outbox、可选签名 relay、标准 ONVIF SOAP/WS-Security adapter、凭据引用、MediaMTX 生成客户端、Control API v1、对账/探活、数据库租约、孤儿只读扫描/受控命令、低基数指标和可重复 16 路容量脚本；Bell 已包含事件 v0.1 校验/不可变存储、append-only outcome，以及只服务 Sense 审计的最小 `bell-api` 和全局审计 repository。Brain 已包含单路 source/detector/track/zone-entry 流水线和回环可视化页，但仍没有生产模型/GPU pipeline、Brain 事件 ingress、公共管理服务/JWT、规则/Alert 或正式 Web/H5。
|
||||
- 阶段：M0 指定摄像头型号准入、M1“一实机 + 四合成源”软件闭环和 M2 本地 16 路批量收敛/稳定基线已通过；M3 已建立 Bell 不可变事件存储、Sense→Bell 全局审计 relay、Brain 单路匿名区域事件工程原型及 Brain→Bell 可靠事件 ingress。客户网络尚未提供，WireGuard T-013 后置，五条独立真实上游和生产 SLA 仍未验收。
|
||||
- 生产代码：Sense 已包含可构建进程、SQLite/PostgreSQL repository、Site/Area 准入、设备操作 Outbox、可选签名 relay、标准 ONVIF SOAP/WS-Security adapter、凭据引用、MediaMTX 生成客户端、Control API v1、对账/探活、数据库租约、孤儿只读扫描/受控命令、低基数指标和可重复 16 路容量脚本；Bell 已包含事件 v0.1 校验/不可变存储、append-only outcome、Sense 审计 relay 和默认关闭的 Brain 事件 ingress。Brain 已包含单路 source/detector/track/zone-entry、回环可视化页与仓库外 SQLite 事件 Outbox，但仍没有生产模型/GPU pipeline、公共管理服务/JWT、规则/Alert、证据切片或正式 Web/H5。
|
||||
- 默认容量：16 路；单站点本阶段上限 128 路，必须横向分片。
|
||||
|
||||
## 仓库现实
|
||||
|
||||
- `Sense/` 已有 Go module 与 `cmd/sense-api`；`Bell/` 已有事件域 Go module 和最小 `cmd/bell-api` 内部审计 receiver；`Brain/` 已有 Python 3.10 单路工程原型、19 项单元/HTTP/UI 契约测试和 `docs/design/brain/index.html` 自包含页面。Bell/Sense migration 统一位于根目录 `deploy/postgres/`。
|
||||
- `Sense/` 已有 Go module 与 `cmd/sense-api`；`Bell/` 已有事件域 Go module 和最小 `cmd/bell-api` 两条内部 ingress；`Brain/` 已有 Python 3.10 单路工程原型、30 项单元/HTTP/UI/Outbox 测试和 `docs/design/brain/index.html` 自包含页面。Bell/Sense migration 统一位于根目录 `deploy/postgres/`。
|
||||
- Sense 设备模型使用 `modality + capabilities`，SQLite 执行 v1 migration；视频配额默认 16、允许 1～128，17/128/129、新增/启用和“降低配额不关闭已有流”均有测试。
|
||||
- T-009 冻结 PostgreSQL `17.10` 和 `pgx/v5 v5.10.0`，实现 `bell`/`sense` schema、NOLOGIN 权限角色、Bell Site 版本 trigger、`bell.site_quota_v1` 和 Sense PostgreSQL repository；同站点并发准入用事务级 advisory lock，配额缺失/越界/版本回退时失败关闭且不改变已有流。
|
||||
- T-010 增量实现 `bell.areas`、`bell.area_policy_v1`、Area 版本观察和 `sense.device_operation_outbox`；`non_imaging_only` 拒绝成像设备创建/启用，失败不改变已有设备。设备创建/期望态受理与脱敏 Outbox 同事务，相同期望态不增加 generation 但仍审计。
|
||||
- Windows 隔离测试使用 `D:\pgsql17\bin` 启动随机回环端口临时集群，`001`～`015` migration 可重放；Sense Outbox fencing、Bell event/global-audit repository、nonce 收据、权限、幂等冲突与不可变性测试通过后自动清理，现有 `D:\pgsql17\data` 和 5432 服务未被读取、停止或修改。
|
||||
- T-015 冻结 Bell Go 1.26.5、JSON Schema v6.0.2 和 ULID v2.1.2；Bell 拒绝上游自报平台 ID，在内部 candidate 组装后执行冻结 v0.1 schema 与六项语义断言。`bell_runtime` 只允许追加/读取 `bell.events`、`bell.event_outcomes`；Brain transport、整数事件 ID 与现有文本逻辑 ID 的跨系统映射、公共 API 和生产隐私 resolver 仍未冻结，不能把内部 factory 当成已上线入口。
|
||||
- Windows 隔离测试使用 `D:\pgsql17\bin` 启动随机回环端口临时集群，`001`～`017` migration 可重放；Sense Outbox fencing、Bell event/global-audit/Brain-ingress repository、nonce/永久来源收据、权限、并发幂等冲突与不可变性测试通过后自动清理，现有 `D:\pgsql17\data` 和 5432 服务未被读取、停止或修改。
|
||||
- T-015 冻结 Bell Go 1.26.5、JSON Schema v6.0.2 和 ULID v2.1.2；Bell 拒绝上游自报平台 ID，在内部 candidate 组装后执行冻结 v0.1 schema 与六项语义断言。T-019 已为该 factory 增加内部网络入口和生产隐私 resolver；公共 API、JWT/OIDC 仍未冻结。
|
||||
- T-016 冻结 `sense-audit-relay-v1`：每批 1～100 项、1 MiB、10 秒 deadline、300 秒时钟窗、600 秒 nonce 收据、30 秒数据库 lease、1～300 秒退避。Sense 使用 `FOR UPDATE SKIP LOCKED` 和 fencing token；Bell constant-time 校验 HMAC，逐项返回 accepted/duplicate/rejected，并把全局事实追加到不可变 `bell.audit_events`。relay 默认关闭，非回环两端必须 HTTPS/TLS，key 只从仓库外文件读取。
|
||||
- T-017 冻结的只是工程原型：Python 3.10.11、NumPy 1.26.4、OpenCV 4.9.0.80；默认 2 FPS 合成 fixture，可选从仓库外文件读取 MediaMTX/RTSP。合成框不是模型输出，HOG/SVM 不是生产 detector，100 项内存事件环不是可靠投递；候选不含 Bell 平台 ID。
|
||||
- T-018 Sense 回环工程控制台已通过项目负责人产品验收：默认关闭并强制 Sense/MediaMTX 播放端显式回环，直接读取 Control API v1 的设备、配额、期望态/实际态/收敛事实；设备 cursor 每页 16 项，只有成像、启用、在线且已收敛的设备可选，最多 4 路按需嵌入 MediaMTX WebRTC 页面。token 只驻留页面内存，刷新即丢失；该验收不包含录像/回放、非回环生产认证、真实 16 机或生产 SLA。
|
||||
- T-019 冻结 `brain-event-ingress-v1`：单事件 1 MiB/10 秒、producer-bound HMAC、300 秒时钟窗、600 秒 nonce、SQLite WAL Outbox、1～300 秒退避、100 次/10,000 条边界。Bell 以受控绑定复查当前 Site/Area/Sense Device，永久 `(producer_id,source_event_id)` 收据与事件同事务提交；同 candidate 跨重启返回原 Bell ID，不同 candidate 稳定冲突。
|
||||
- MediaMTX 固定为独立二进制 `v1.19.3`，官方 OpenAPI 已按 SHA-256 vendoring，并由固定 `oapi-codegen v2.8.0` 生成客户端；手写薄封装有 create/read/delete、幂等 ensure、探活和只返回名称的受限分页枚举测试。
|
||||
- T-003 对账进度与指数退避持久化，覆盖取消和 SQLite 重启恢复；T-006 增加真实 ONVIF adapter、RTSP router、实验室播种/状态工具、故障代理和五路自动验收。T-012 的普通调和不枚举孤儿；独立 PostgreSQL 扫描默认只报告，未知归属永不删除。
|
||||
- T-006 正式使用 1 台准入实机和 4 个独立合成 publisher 连续观察 `1806.6 s` / 180 次采样，四类恢复均通过，最大与最终 `unconverged` 均为 0；详细证据见 `docs/research/sense-5-stream-integration.md`。
|
||||
- T-014 正式使用隔离 PostgreSQL、真实 Control API、两套 MediaMTX 和 16 个独立低码率合成 publisher，完成 17 路配额拒绝、三轮 `16 → 0 → 16` 批量收敛和固定四路故障恢复；稳定观察 `1800.1 s` / 180 次采样，最大与最终 `unconverged` 均为 0、最终在线 Path 16、帧错误 0。证据见 `docs/research/sense-16-stream-capacity.md`；不外推到真实 16 机、网络、录像、AI/GPU、64/128 路或生产 SLA。
|
||||
- `docs/raw/01`～`08` 已记录需求、分析、方案、客户场景、事件比对和三系统职责。
|
||||
- `docs/raw/contracts/event-v0.1.schema.json` 已冻结，并有多份示例与语义说明。
|
||||
- `docs/contracts/sense-control-v1.openapi.json` 的 7 个站点作用域/operation endpoint 已由 T-011 实现；`sense-audit-relay-v1.openapi.json` 已由 T-016 实现。默认 SQLite 只暴露运维探针与低基数 `/metrics`，不注册业务路由或 relay；Bell 管理服务与 JWT/OIDC 尚未实现。
|
||||
- `docs/contracts/sense-control-v1.openapi.json` 的 7 个站点作用域/operation endpoint 已由 T-011 实现；`sense-audit-relay-v1.openapi.json` 和 `brain-event-ingress-v1.openapi.json` 已分别由 T-016/T-019 实现。两条内部 ingress 使用独立 key；Bell 管理服务与 JWT/OIDC 尚未实现。
|
||||
- T-012 把 PostgreSQL schema 提升到 v5：due row 用数据库时钟、`FOR UPDATE SKIP LOCKED`、逐项续租和 fencing token 协调；MediaMTX Path 历史归属、15 分钟孤儿快照、最多 10%/128 项安全闸、无 bypass 的本地处置命令及 `/metrics` 已实现。SQLite 明确保留单实例开发语义。
|
||||
- harness coding 文档、上下文清单、Gitea Issue/PR 模板和治理脚本已接入。
|
||||
- Gitea 已初始化 12 个协作标签；`status/waiting` 用于依赖或外部条件未满足的未领取任务，实时可领取状态必须从 Gitea 查询，不在本文复制。
|
||||
@@ -47,7 +48,7 @@ Windows：
|
||||
go -C Sense run ./cmd/sense-api
|
||||
```
|
||||
|
||||
Bell 事件域和内部审计 receiver 验证：
|
||||
Bell 事件域与两条内部 ingress 验证：
|
||||
|
||||
```powershell
|
||||
go -C Bell test ./...
|
||||
@@ -61,6 +62,7 @@ Brain 单路工程原型验证与启动：
|
||||
python -m unittest discover -s Brain/tests -p "test_*.py" -v
|
||||
python -m compileall -q Brain
|
||||
python -m Brain.yovision_brain --source synthetic
|
||||
# 可选：追加 --event-ingress-config <仓库外绝对路径>
|
||||
```
|
||||
|
||||
跨平台直接验证：
|
||||
@@ -97,12 +99,12 @@ Sense 默认监听 `127.0.0.1:8080`，提供 `/healthz`、`/readyz` 运维探针
|
||||
- 人脸方向已延后至 M5 的 S4 成人园区候选试点；必要性/PIP 影响评估、单独同意与替代方式、合法底库来源和删除流程未完成，阻塞人脸能力上线。
|
||||
- 短信/语音具体供应商未选；生产前必须选定两条独立投递路径并验证故障切换。
|
||||
- 生产 Brain 的 Python/Savant/DeepStream 精确版本、目标硬件和 Bell 前端栈尚未冻结；T-017 的 Python/OpenCV 只适用于工程原型，不能外推为生产选择。Sense M1 的 Go、SQLite driver、MediaMTX、生成器及生成运行时版本已在 T-003 冻结，PostgreSQL/pgx 版本已在 T-009 冻结。
|
||||
- 本机现有 PostgreSQL 5432 实例使用 SCRAM 且当前开发进程没有管理员密码；T-009～T-016 不绕过认证，自动验收使用隔离临时集群。向共享/生产实例安装 migration 前仍需管理员私下提供专用数据库、最小权限登录角色、外部 Control API/relay key 文件、TLS 证书与备份方案。
|
||||
- 本机现有 PostgreSQL 5432 实例使用 SCRAM 且当前开发进程没有管理员密码；T-009～T-019 不绕过认证，自动验收使用隔离临时集群。向共享/生产实例安装 migration 前仍需管理员私下提供专用数据库、最小权限登录角色、外部 Control API/两类 ingress key、Brain Outbox 路径、TLS 证书与备份方案。
|
||||
- 代码知识图谱在无业务代码阶段可能为空；工具不可用时使用 `rg` 处理文档与配置。
|
||||
|
||||
## 下一步
|
||||
|
||||
客户网络仍未提供，T-013 WireGuard 继续后置。T-018 Sense NVR 管理面已通过产品验收；当前执行 T-019，独立冻结并实现 Brain→Bell 业务事件身份、持久重试、认证和幂等 ingress。客户授权、借用或租赁条件具备后再执行 T-007 五条独立真实上游现场门禁；上述本地任务均不解除 T-007/T-013，也不形成真实多路、模型效果或生产 SLA 承诺。
|
||||
客户网络仍未提供，T-013 WireGuard 继续后置。T-019 已完成本地 Brain→Bell 可靠业务事件 ingress；下一项建议独立建立 Bell 规则→Alert→ack 的最小可见纵切，证据/pre-roll 切片另立任务且不与 Alert 状态机混交。客户授权、借用或租赁条件具备后再执行 T-007 五条独立真实上游现场门禁；上述本地任务均不解除 T-007/T-013，也不形成真实多路、模型效果或生产 SLA 承诺。
|
||||
|
||||
## 已知风险
|
||||
|
||||
|
||||
@@ -90,11 +90,23 @@
|
||||
.form-actions { display: grid; grid-template-columns: 1fr 1fr; gap: 8px; }
|
||||
.inline-state { min-height: 42px; padding: 9px 10px; border-left: 3px solid var(--cyan); background: rgba(56, 189, 248, .07); color: var(--muted); font-size: 12px; }
|
||||
.event-list { max-height: 330px; padding: 8px; display: grid; gap: 7px; overflow-y: auto; }
|
||||
.ingress-summary { padding: 11px 12px; display: grid; gap: 8px; border-bottom: 1px solid var(--line); background: rgba(56, 189, 248, .04); }
|
||||
.ingress-head { display: flex; align-items: center; justify-content: space-between; gap: 10px; }
|
||||
.ingress-head h3 { margin: 0; font-size: 13px; }
|
||||
.ingress-state { min-height: 28px; padding: 3px 9px; display: inline-flex; align-items: center; gap: 7px; border: 1px solid var(--line); border-radius: 999px; color: var(--muted); font-size: 12px; font-weight: 750; }
|
||||
.status-dot.error { background: var(--danger); box-shadow: 0 0 0 4px rgba(251, 113, 133, .12); }
|
||||
.ingress-copy { margin: 0; color: var(--muted); font-size: 12px; overflow-wrap: anywhere; }
|
||||
.ingress-counts { margin: 0; display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 6px; }
|
||||
.ingress-counts[hidden] { display: none; }
|
||||
.ingress-counts div { min-width: 0; padding: 7px 8px; border: 1px solid var(--line); border-radius: 8px; background: var(--surface-2); }
|
||||
.ingress-counts dt { color: var(--muted); font-size: 11px; }
|
||||
.ingress-counts dd { margin: 2px 0 0; color: var(--text); font-size: 15px; font-weight: 800; font-variant-numeric: tabular-nums; }
|
||||
.event { padding: 11px; border: 1px solid var(--line); border-radius: 10px; background: var(--surface-2); }
|
||||
.event-head { display: flex; align-items: center; justify-content: space-between; gap: 8px; }
|
||||
.event strong { font-size: 13px; }
|
||||
.event time, .event code { color: var(--muted); font-size: 12px; }
|
||||
.event code { display: block; margin-top: 6px; overflow-wrap: anywhere; }
|
||||
.event-delivery { margin-top: 5px; color: var(--muted); font-size: 12px; }
|
||||
.event-tag { padding: 2px 7px; border: 1px solid rgba(251, 191, 36, .35); border-radius: 999px; background: rgba(251, 191, 36, .08); color: #ffe18a; font-size: 11px; }
|
||||
.empty { min-height: 120px; padding: 26px 16px; display: grid; place-items: center; color: var(--muted); text-align: center; }
|
||||
.architecture-note { margin-top: 14px; padding: 13px 15px; display: grid; grid-template-columns: auto 1fr; gap: 11px; border: 1px solid rgba(139, 124, 246, .30); border-radius: 12px; background: rgba(139, 124, 246, .07); color: var(--muted); }
|
||||
@@ -127,6 +139,8 @@
|
||||
.metrics { grid-template-columns: 1fr 1fr; }
|
||||
.metric strong { font-size: 17px; }
|
||||
.form-actions { grid-template-columns: 1fr; }
|
||||
.ingress-head { align-items: flex-start; flex-direction: column; }
|
||||
.ingress-counts { grid-template-columns: 1fr 1fr; }
|
||||
}
|
||||
@media (prefers-reduced-motion: reduce) {
|
||||
*, *::before, *::after { scroll-behavior: auto !important; transition-duration: .01ms !important; animation-duration: .01ms !important; animation-iteration-count: 1 !important; }
|
||||
@@ -155,7 +169,7 @@
|
||||
<div class="page-head">
|
||||
<div>
|
||||
<h1>单路检测与区域判定</h1>
|
||||
<p>验证从画面、匿名人员框、track 到区域进入候选事实的工程闭环。平台事件 ID、持久投递和 Alert 由后续 Bell 链路负责。</p>
|
||||
<p>验证从画面、匿名人员框、track 到区域进入候选事实的工程闭环。Brain 先持久化到 Outbox，再由 Bell 分配平台事件 ID；Alert 仍由后续 Bell 链路负责。</p>
|
||||
</div>
|
||||
<div id="mode-badge" class="mode-badge">加载运行状态</div>
|
||||
</div>
|
||||
@@ -220,9 +234,22 @@
|
||||
|
||||
<section class="card" aria-labelledby="event-title">
|
||||
<div class="card-head">
|
||||
<div><h2 id="event-title">最近候选事实</h2><p>只产生 source_event_id；Bell 才生成平台 ULID</p></div>
|
||||
<div><h2 id="event-title">最近候选事实</h2><p>内存环仅用于观察；可靠性以 Outbox 状态为准</p></div>
|
||||
<span id="event-count" class="chip"><strong>0</strong> 项</span>
|
||||
</div>
|
||||
<section id="event-ingress" class="ingress-summary" aria-labelledby="event-ingress-title" role="status" aria-live="polite" aria-atomic="true">
|
||||
<div class="ingress-head">
|
||||
<h3 id="event-ingress-title">Bell 可靠投递</h3>
|
||||
<span class="ingress-state"><i id="ingress-dot" class="status-dot" aria-hidden="true"></i><span id="ingress-label">未启用</span></span>
|
||||
</div>
|
||||
<p id="ingress-copy" class="ingress-copy">可靠投递未启用；候选事实不会被标记为 Bell 已接收。</p>
|
||||
<dl id="ingress-counts" class="ingress-counts" aria-label="Outbox 投递计数" hidden>
|
||||
<div><dt>待投递</dt><dd id="ingress-queued">0</dd></div>
|
||||
<div><dt>投递中</dt><dd id="ingress-delivering">0</dd></div>
|
||||
<div><dt>已送达</dt><dd id="ingress-delivered">0</dd></div>
|
||||
<div><dt>死信</dt><dd id="ingress-dead-letter">0</dd></div>
|
||||
</dl>
|
||||
</section>
|
||||
<div id="event-list" class="event-list" aria-live="polite">
|
||||
<div class="empty">人员从区域外进入后，这里会出现一次候选事实。</div>
|
||||
</div>
|
||||
@@ -252,6 +279,7 @@
|
||||
let state = null;
|
||||
let offlineSequence = 0;
|
||||
let offlineTriggered = false;
|
||||
let ingressSignature = "";
|
||||
|
||||
const offlineState = () => {
|
||||
offlineSequence += 1;
|
||||
@@ -275,6 +303,7 @@
|
||||
zone: state && state.zone ? state.zone : {id: "zone-demo-01", name: "楼梯口危险区", version: 1, points: parsePoints(false)},
|
||||
detections: bbox[2] - bbox[0] > .01 ? [{track_id: "P-DEMO-001", class: "person", bbox, detector_score: null, inside_zone: inside}] : [],
|
||||
events,
|
||||
event_ingress: {enabled: false},
|
||||
last_error_code: null
|
||||
};
|
||||
};
|
||||
@@ -376,11 +405,48 @@
|
||||
const tag = document.createElement("span"); tag.className = "event-tag"; tag.textContent = event.fixture ? "夹具候选" : "检测候选";
|
||||
head.append(title, tag);
|
||||
const time = document.createElement("time"); time.dateTime = event.occurred_at; time.textContent = `${formatTime(event.occurred_at)} · ${event.kind}`;
|
||||
const delivery = document.createElement("div"); delivery.className = "event-delivery"; delivery.textContent = event.delivery_status === "outbox_persisted" ? "交接：Outbox 已持久化" : "交接：仅内存观察";
|
||||
const code = document.createElement("code"); code.textContent = event.source_event_id;
|
||||
article.append(head, time, code); return article;
|
||||
article.append(head, time, delivery, code); return article;
|
||||
}));
|
||||
}
|
||||
|
||||
function renderIngress(value = {enabled: false}) {
|
||||
const enabled = value.enabled === true;
|
||||
const queued = Number(value.queued) || 0;
|
||||
const delivering = Number(value.delivering) || 0;
|
||||
const delivered = Number(value.delivered) || 0;
|
||||
const deadLetter = Number(value.dead_letter) || 0;
|
||||
const errorCode = typeof value.last_error_code === "string" ? value.last_error_code : "";
|
||||
const nextSignature = JSON.stringify([enabled, queued, delivering, delivered, deadLetter, errorCode]);
|
||||
if (nextSignature === ingressSignature) return;
|
||||
ingressSignature = nextSignature;
|
||||
const dot = $("ingress-dot");
|
||||
const counts = $("ingress-counts");
|
||||
counts.hidden = !enabled;
|
||||
$("ingress-queued").textContent = String(queued);
|
||||
$("ingress-delivering").textContent = String(delivering);
|
||||
$("ingress-delivered").textContent = String(delivered);
|
||||
$("ingress-dead-letter").textContent = String(deadLetter);
|
||||
if (!enabled) {
|
||||
dot.className = "status-dot";
|
||||
$("ingress-label").textContent = "未启用";
|
||||
$("ingress-copy").textContent = "可靠投递未启用；候选事实不会被标记为 Bell 已接收。";
|
||||
} else if (deadLetter > 0) {
|
||||
dot.className = "status-dot error";
|
||||
$("ingress-label").textContent = "需要处理";
|
||||
$("ingress-copy").textContent = `存在死信${errorCode ? `（${errorCode}）` : ""}；请检查 Bell 绑定、鉴权或候选字段后再处理。`;
|
||||
} else if (errorCode || queued > 0 || delivering > 0) {
|
||||
dot.className = "status-dot warning";
|
||||
$("ingress-label").textContent = errorCode ? "正在重试" : "投递中";
|
||||
$("ingress-copy").textContent = errorCode ? `Outbox 已保留候选并自动重试（${errorCode}）。` : "候选已持久化到本地 Outbox，正在等待 Bell 确认。";
|
||||
} else {
|
||||
dot.className = "status-dot online";
|
||||
$("ingress-label").textContent = "投递正常";
|
||||
$("ingress-copy").textContent = "Outbox 可用；Bell 返回 accepted 或 duplicate 后才计为已送达。";
|
||||
}
|
||||
}
|
||||
|
||||
function render(next) {
|
||||
state = next;
|
||||
$("connection-dot").className = `status-dot ${next.source.connected ? "online" : "warning"}`;
|
||||
@@ -398,6 +464,7 @@
|
||||
if (document.activeElement !== $("zone-name") && document.activeElement !== $("zone-points")) {
|
||||
$("zone-name").value = next.zone.name; setPoints(next.zone.points);
|
||||
}
|
||||
renderIngress(next.event_ingress);
|
||||
renderEvents(next.events);
|
||||
drawOverlay();
|
||||
}
|
||||
|
||||
@@ -47,6 +47,7 @@
|
||||
| kind | 含义 | 默认 severity | 产出方 | 状态 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `fall` | 人员摔倒确认 | `high` | silver_pose FSM 进入 CONFIRMED | ✅ 已上线 |
|
||||
| `zone_entry` | 匿名 track 从区域外进入区域内 | `medium` | Brain 区域进入判定 | ✅ T-019 ingress 已接入 |
|
||||
|
||||
## 4. silver_pose → 契约 映射表
|
||||
|
||||
|
||||
+23
-4
@@ -3,16 +3,18 @@ id: T-019
|
||||
title: 建立 Brain 到 Bell 的可靠事件入站链路
|
||||
phase: 3
|
||||
deps: [T-015, T-017]
|
||||
status: TODO
|
||||
status: DONE
|
||||
created: 2026-08-11
|
||||
issue: 67
|
||||
context_ref: null
|
||||
claim_branch: null
|
||||
work_branch: null
|
||||
context_ref: b7fe44eeb0caf8d41abef365ec2100c74373321f
|
||||
claim_branch: claims/T-019
|
||||
work_branch: agent/codex/T-019
|
||||
write_paths:
|
||||
- docs/tasks/T-019.md
|
||||
- docs/contracts/
|
||||
- docs/raw/contracts/README.md
|
||||
- Brain/
|
||||
- docs/design/brain/index.html
|
||||
- Bell/
|
||||
- deploy/postgres/
|
||||
- scripts/test_postgres.ps1
|
||||
@@ -41,6 +43,7 @@ T-017 已能产生匿名区域事件候选，T-015 已能在 Bell 内部校验
|
||||
## 方案
|
||||
|
||||
1. 在 `docs/contracts/brain-event-ingress-v1.openapi.json` 冻结单事件 envelope、响应、稳定错误码和 HMAC 规则。请求包含 `schema_version=1`、`producer_id` 与不含 Bell `id` 的完整 event v0.1 candidate；Brain 提供 `source_event_id`，Bell 生成并返回平台 `evt_` ULID。正文上限 1 MiB，deadline 10 秒。
|
||||
同步把 T-017 已产生的 `zone_entry` 登记到 event v0.1 kind 注册表；不修改冻结 JSON Schema 或既有 kind 语义。
|
||||
2. 复用 T-016 已验证的 HMAC-SHA256 canonical 形式：method、path、Unix 秒、随机 nonce、body SHA-256 以换行连接；使用独立的仓库外 key 文件，并把每个 key 绑定到一个 `producer_id`。允许 300 秒时钟偏差，nonce 防重收据保留 600 秒。回环可用 HTTP，非回环必须 HTTPS；事件 key 与审计 relay key 不混用。
|
||||
3. 新增 Bell 所有的 `event_ingress_bindings`，把 `(producer_id, tenant_id, site_id, device_id)` 数字事件身份绑定到现有 Bell tenant/site/device/area 逻辑身份和 `video` 模态。入站必须 fail closed：绑定缺失、禁用、站点/Area 已删除、设备或 Area 归属不一致、非视频或 `capture_policy != video_allowed` 均拒绝。首版只提供受控 SQL 配置方式，不新增公共绑定管理 API。
|
||||
4. 新增永久 append-only `event_ingress_receipts`，以 `(producer_id, source_event_id)` 唯一，保存 canonical candidate SHA-256 与 Bell event ID；另用短期 `event_ingress_nonces` 防请求重放。Bell 用单事务和事务级 advisory lock 完成 nonce、来源收据、事件创建与响应：同来源且同 payload 返回原 Bell ID 和 `duplicate`，同来源不同 payload 返回 `source_event_conflict`，不得产生第二条事件。
|
||||
@@ -84,3 +87,19 @@ T-017 已能产生匿名区域事件候选，T-015 已能在 Bell 内部校验
|
||||
- T-019 独立冻结 Brain→Bell 业务事件身份、持久重试、认证和幂等 ingress；不复用 T-017 内存事件环，也不扩张到规则、Alert 或证据链。
|
||||
- 当前会话未暴露 codebase-memory MCP 图工具，代码发现按仓库规则降级为定向读取与 `rg`；任务定义前主分支 `./init.ps1` 基线通过：72 项根测试、19 项 Brain 测试，以及 Sense/Bell generate/test/vet/build 全绿。
|
||||
- 任务定义已合入默认分支并创建唯一 Gitea Issue #67；本映射提交合入后才添加 `status/todo` 并允许 dispatcher 分配。
|
||||
|
||||
### 2026-08-11 领取与基线
|
||||
|
||||
- dispatcher `ila` 检查依赖和开放工单后，从默认分支 `b7fe44eeb0caf8d41abef365ec2100c74373321f` 创建并读回 `claims/T-019` 与 `agent/codex/T-019`；Issue #67 已分配给 `ila`，标签为 `status/doing`，结构化 CLAIM 评论与本文件 `write_paths` 一致。
|
||||
- T-007 保持 `status/waiting`，不构成活跃写路径预留；本任务不启用委派。
|
||||
|
||||
### 2026-08-11 实现与自动化验收
|
||||
|
||||
- 冻结并实现 `brain-event-ingress-v1` 单事件 envelope。Bell event key 独立于审计 key，并把 `key_id` 绑定到唯一 `producer_id`；两端共享 method/path/timestamp/nonce/body-hash 五行 HMAC-SHA256，允许 300 秒时钟偏差，正文上限 1 MiB，非回环必须 HTTPS。Brain client 禁用环境代理和重定向，避免内部事件被旁路转发。
|
||||
- PostgreSQL 新增可重放 `016`～`017`：Bell 所有的数字→逻辑身份绑定引用现有 Site/Area/Sense Device；运行时只能读取设备 ID、Area 与 modality 列，不能读取 endpoint、credential、profile token 或 path。永久来源收据和事件不可更新/删除，只有 10 分钟 nonce 表允许清理。
|
||||
- Bell 在相同事务中提交最终 event、`(producer_id,source_event_id,candidate_hash)` 永久收据和成功 nonce 响应；同来源/同 canonical candidate 返回原 Bell ID，不同 candidate 返回稳定冲突。隔离 PostgreSQL 测试以 8 个并发重投确认只生成 1 条 event/1 条来源收据，并验证 Area 改为 `non_imaging_only` 后新视频事件失败关闭。
|
||||
- Brain 新增完整 v0.1-minus-id mapper、WAL/`synchronous=FULL` SQLite Outbox、HMAC client 和 worker。Outbox 首次打开绑定 producer/tenant/site/device，禁止换身份复用旧队列；候选持久化成功后才进入页面内存环。fixture 显式映射为 `outcome=test/outcome_source=auto`，URI/凭据/`source_ref` 不出 Brain。队列执行 1～300 秒退避、100 次/10,000 条边界，`accepted/duplicate` 才 delivered，稳定 4xx 进入 dead letter；租约崩溃恢复与 Bell 成功后本地未 ack 的重投均有测试。
|
||||
- Brain 工程原型在既有“最近候选事实”卡片内展示脱敏 Outbox 状态与待投递/投递中/已送达/死信计数；以文字和状态点共同区分未启用、正常、重试和死信，且明确单条候选的“仅内存观察”或“Outbox 已持久化”。状态无变化时不重复触发 `aria-live`，页面不暴露 Bell 地址、key 文件或 SQLite 路径。
|
||||
- `zone_entry` 已登记到 event v0.1 kind 注册表；冻结 JSON Schema 未修改。Bell/Brain/部署 README、API、架构、技术栈和当前状态均同步，未扩张到证据、规则、Alert、公共认证或生产模型。
|
||||
- 最终门禁通过：`./init.ps1`（77 项根测试、30 项 Brain 测试及 Sense/Bell generate/test/vet/build）；独立 `go -C Bell test/vet/build ./...`、Brain compileall、4 项跨语言 ingress 契约测试和三项治理校验；`./scripts/test_postgres.ps1` 在 PostgreSQL 17.10 临时集群将 `001`～`017` 重放两次并通过真实 repository、权限、并发幂等、隐私和不可变性验证，随机端口/临时目录已清理且现有 5432 listener 未改变；`git diff --check` 通过。
|
||||
- 本任务不需要真实摄像头或目标 GPU；synthetic fixture mapper、SQLite 崩溃恢复、真实本地 HTTP HMAC client、Bell handler 和真实 PostgreSQL consumer 的联合自动化证据满足本地验收。结果不构成算法效果、真实多路或生产 SLA。
|
||||
|
||||
Reference in New Issue
Block a user