feat(bell): add alert acknowledgement vertical slice
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 单路可视化工程原型、Sense 回环 NVR 管理面纵切和 Brain→Bell 可靠事件 ingress**。后续本地开发统一使用已准入的一台海康样机，多路软件闭环使用独立合成 RTSP 源补足；真实多设备证据延后到客户/借用/租赁条件具备时执行。客户网络尚未提供，T-013 WireGuard 继续后置；下一项建议把 Bell 规则→Alert→ack 最小纵切与证据切片拆成独立任务。
|
||||
当前为 **M0 指定型号实机准入、M1 Sense 五路混合源集成和 M2 本地 16 路软件基线均已完成，M3 已建立 Bell 不可变事件存储、Sense→Bell 全局审计 relay、Brain 单路可视化工程原型、Sense 回环 NVR 管理面纵切、Brain→Bell 可靠事件 ingress 和 Bell 规则→Alert→ack/close 回环工程纵切**。后续本地开发统一使用已准入的一台海康样机，多路软件闭环使用独立合成 RTSP 源补足；真实多设备证据延后到客户/借用/租赁条件具备时执行。客户网络尚未提供，T-013 WireGuard 继续后置；下一项建议独立建立 Bell→Sense 异步证据/pre-roll 切片。
|
||||
|
||||
优先路径：
|
||||
|
||||
@@ -96,6 +96,6 @@ python -m unittest discover -s Brain/tests -p "test_*.py" -v
|
||||
python -m compileall -q Brain
|
||||
```
|
||||
|
||||
日常优先运行根目录 `./init.ps1` 或 `./init.sh`，它会执行上述治理、Brain 单元/编译、生成、测试、静态检查和构建门禁。Sense 本地启动为 `go -C Sense run ./cmd/sense-api`；T-018 控制台必须在完成 PostgreSQL/Control API 外部安全配置后显式设置 `SENSE_CONSOLE_ENABLED=true`，再访问回环 `/sense-console/`。Brain 合成工程原型启动为 `python -m Brain.yovision_brain --source synthetic`。工程页面默认只允许回环，具体配置、版本与校验方法见 [`03-tech-stack.md`](03-tech-stack.md)、[`../Sense/README.md`](../Sense/README.md) 和 [`../Brain/README.md`](../Brain/README.md)。
|
||||
日常优先运行根目录 `./init.ps1` 或 `./init.sh`，它会执行上述治理、Brain 单元/编译、生成、测试、静态检查和构建门禁。Sense 本地启动为 `go -C Sense run ./cmd/sense-api`；T-018 控制台必须在完成 PostgreSQL/Control API 外部安全配置后显式设置 `SENSE_CONSOLE_ENABLED=true`，再访问回环 `/sense-console/`。Brain 合成工程原型启动为 `python -m Brain.yovision_brain --source synthetic`。T-020 在 Bell migration/外部规则与 token 上下文就绪后显式开启 `BELL_ALERTS_ENABLED=true` 与 `BELL_ALERT_CONSOLE_ENABLED=true`，访问 `/bell-console/`；完整变量见 [`../Bell/README.md`](../Bell/README.md)。工程页面默认只允许回环，具体配置、版本与校验方法见 [`03-tech-stack.md`](03-tech-stack.md)、[`../Sense/README.md`](../Sense/README.md)、[`../Brain/README.md`](../Brain/README.md) 和 [`../Bell/README.md`](../Bell/README.md)。
|
||||
|
||||
本机 16 路软件容量基线使用 `./Sense/scripts/t014-capacity.ps1 -PgRoot D:\pgsql17`；正式证据必须使用默认 30 分钟窗口，且只证明固定低码率合成负载。结果与限制见 [`research/sense-16-stream-capacity.md`](research/sense-16-stream-capacity.md)。
|
||||
|
||||
@@ -63,7 +63,7 @@ T-014 没有增加生产依赖。Windows 容量脚本冻结并核对 Sense 模
|
||||
| Go | `1.26.5`（与 Sense 相同） | BSD-3-Clause；复用 §1.1 工具链与校验 | Bell 独立 Go module；升级时同时运行两个 module 的 test/vet/build |
|
||||
| PostgreSQL / pgx | `17.10` / `github.com/jackc/pgx/v5 v5.10.0` | PostgreSQL License / MIT；module sum `h1:VhSvgU2jSli8o3AqIEOTJr7rZwAEUVo4E4XhR94Zfr0=` | 复用 T-009 的 `database/sql` 边界；运行身份改用无 owner 权限的 `bell_runtime` 组 |
|
||||
| JSON Schema | `github.com/santhosh-tekuri/jsonschema/v6 v6.0.2` | Apache-2.0；module sum `h1:KRzFb2m7YtdldCEkzs6KqmJw4nqEVZGK7IN2kJkjTuQ=` | 运行时校验 Draft 2020-12 与 format；退出时可替换 validator，但冻结 schema 和负向契约测试不变 |
|
||||
| ULID | `github.com/oklog/ulid/v2 v2.1.2` | Apache-2.0；module sum `h1:IEclFb9JNvzYA6MW2SCxbLzcHTVsfqm3PrqGQJH5zec=` | 只封装在 Bell ID generator port 后；平台前缀仍为 `evt_`，替换实现不得改变格式或所有权 |
|
||||
| ULID | `github.com/oklog/ulid/v2 v2.1.2` | Apache-2.0；module sum `h1:IEclFb9JNvzYA6MW2SCxbLzcHTVsfqm3PrqGQJH5zec=` | 只封装在 Bell ID generator 边界后；Event 前缀为 `evt_`，T-020 Alert 前缀为 `alt_`，替换实现不得改变格式或所有权 |
|
||||
|
||||
T-015 不冻结 Brain→Bell transport，也不产生可部署 Bell API 二进制。内部 factory 接收不含 `id` 的候选事实，由 Bell 生成 ULID 后才形成最终 v0.1 事件；不得把该 Go 类型当成公共网络协议。
|
||||
|
||||
@@ -93,6 +93,12 @@ T-019 不增加第三方依赖。Brain 继续使用 Python 3.10.11 标准库 `sq
|
||||
|
||||
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 不足，必须发布兼容迁移方案，不能绕过来源幂等键。
|
||||
|
||||
### 1.8 Bell 规则、Alert 与回环值班台（T-020）
|
||||
|
||||
T-020 不增加第三方依赖：规则/Alert 域继续使用 Bell 已冻结的 Go 1.26.5、PostgreSQL 17.10/pgx 和 ULID。规则配置是仓库外 JSON，首版只实现精确事件类型、最小严重度、可选 Site、启用状态和生效时间；canonical SHA-256 相同则幂等复用，变化只追加新版本。规则 worker 是单一可取消循环和有界空闲轮询，不按租户、站点或设备创建 goroutine；数据库 durable sweep、唯一键和事务级 advisory lock 负责多实例收敛。
|
||||
|
||||
回环值班台与 T-018 相同，使用 Go 标准库 `embed`/`net/http` 和自包含 HTML/CSS/原生 JavaScript，无 npm、框架、CDN 或浏览器持久存储。该选择只服务工程验收，不冻结 Bell 正式前端栈。控制台与规则 worker 分别默认关闭；控制台要求规则已启用、整个 Bell 监听地址显式回环、仓库外 token 文件及服务端 tenant/Site/actor 上下文。证据、升级/通知、JWT/OIDC/RBAC 和非回环部署不在本任务内。
|
||||
|
||||
## 2. 外部项目边界
|
||||
|
||||
- MiBeeNvr：只用于 M0 隔离实验室、ONVIF兼容性和交互参考，不作为生产依赖。
|
||||
@@ -136,7 +142,7 @@ go -C Sense build ./...
|
||||
go -C Sense run ./cmd/sense-api
|
||||
```
|
||||
|
||||
Bell 事件域与内部审计 receiver 单独执行：
|
||||
Bell 事件、内部 ingress 与回环 Alert 纵切单独执行：
|
||||
|
||||
```powershell
|
||||
go -C Bell mod download
|
||||
@@ -170,7 +176,7 @@ python scripts/validate_harness_governance.py
|
||||
| Sense Go | `go -C Sense generate ./internal/mtx ./internal/controlapi`、`go -C Sense test ./...`、`go -C Sense vet ./...`、`go -C Sense build ./...` | ONVIF、存储、MediaMTX、对账或公共 API 变化 | T-006 使用 1 路指定实机 + 4 路独立合成源；T-007 才要求客户/借用/租赁的真实多路矩阵 |
|
||||
| PostgreSQL schema/repository | `python -m unittest discover -s tests -p "test_postgres_contract.py"`；Windows 本机再运行 `./scripts/test_postgres.ps1 -PgRoot D:\pgsql17` | migration、权限、配额判定或 PostgreSQL driver 变化 | 不需要摄像头；必须核对临时集群未使用现有 data 目录，现有 5432 listener 前后不变 |
|
||||
| Brain Python | 当前工程原型：`python -m unittest discover -s Brain/tests -p "test_*.py" -v`、`python -m compileall -q Brain` | source、detector port、track、判定状态机、mapper 或模型接口变化 | T-017 合成 fixture 只验工程闭环；命中真实模型任务时另用冻结数据集和目标硬件，不能用 fixture/HOG 结果替代 |
|
||||
| Bell Go/Web | 当前后端：`go -C Bell test ./...`、`go -C Bell vet ./...`、`go -C Bell build ./...`；前端命令待脚手架冻结 | schema、RBAC、预警状态机或公共 UI 变化 | P0 UI 流程由产品/值班角色验收；纯事件存储不需要 UI 人工验收 |
|
||||
| Bell Go/Web | `go -C Bell test ./...`、`go -C Bell vet ./...`、`go -C Bell build ./...`；回环值班台静态门禁：`python -m unittest discover -s tests -p "test_bell_alert_contract.py"`；正式前端命令待脚手架冻结 | schema、RBAC、预警状态机或公共 UI 变化 | P0 正式 UI 流程由产品/值班角色验收；T-020 工程台检查 375px/桌面、键盘、错误态和 reduced-motion，不等于正式 UI 验收 |
|
||||
| 容量/分片 | 任务内基准脚本；本地 16 路入口为 `./Sense/scripts/t014-capacity.ps1 -PgRoot D:\pgsql17` | 默认 16 路软件基线，以及后续 64/128 路分片里程碑 | 本地 16 路控制面可用独立合成源；真实多路、生产 SLA、64/128 路、AI/GPU、网络与存储必须使用目标环境分别验收 |
|
||||
|
||||
代码脚手架落地时必须把真实命令同步到本文、`init.ps1`/`init.sh`、`00-ai-start-here.md` 和 `current-state.md`。
|
||||
|
||||
@@ -49,7 +49,7 @@ Sense ── 视频流/触发信号 ──> Brain
|
||||
2. Sense 维护设备期望态，通过 MediaMTX API 和对账器收敛实际态；PostgreSQL 多实例以数据库时钟短租约和 fencing token 领取 due row，过期 worker 不得提交结果。
|
||||
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 并按策略升级。
|
||||
5. T-020 已实现规则→Alert→ack/close 最小纵切：仓库外规则按 hash 发布不可变版本，worker 对每个 Event 写 durable sweep/evaluation；命中后由 Bell 创建独立 `alt_` ULID、Event 关联和初始 `open` transition。ack 首个竞争者获胜，后到者读取实际 actor/time；当前尚未实现投递或升级。
|
||||
6. Bell 发起 pre-roll 证据回捞，Sense 提供切片接口。
|
||||
7. 用户标记 outcome，反馈进入 Brain 的数据闭环。
|
||||
|
||||
@@ -96,7 +96,7 @@ T-014 已在单台 Windows 主机上用隔离 PostgreSQL、真实 Control API、
|
||||
- Bell 最终事件写入 `bell.events`；同平台 ID/同摘要仅视为幂等重放，同 ID/不同摘要拒绝。`bell_runtime` 只有 `SELECT/INSERT`，事件与 outcome 的 UPDATE/DELETE 另由数据库 trigger 拒绝；后续人工/自动 outcome 追加到独立表，不改写事件 payload。
|
||||
- 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 先落库再投递，进程重启恢复未完成升级链。
|
||||
- Alert 身份、Event 多对多关联与 `open → acknowledged → closed` transition 均只追加；当前状态从最新 transition 推导。规则 evaluation、Alert 创建和初始 transition 在同一事务中提交；无规则/未命中也写 durable sweep。命令永久幂等收据保证重启后同 key 重放原响应。投递和升级链尚未实现，页面不得伪造倒计时或送达事实。
|
||||
- 值班排班发布前必须按 Site 时区校验班次空档、重叠、联系人停用和通道验证；排班以新版本和未来生效时间发布，不原地改写历史。交接班是进行中 Alert 的显式责任转移事件，不替代排班版本变更。
|
||||
- 事件证据技术默认保留 30 天并按生命周期删除；客户/法务在 M3 生产上线前确认法规适用性和最终期限，技术默认值不能覆盖其结论。
|
||||
|
||||
@@ -119,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,...,017_privileges_event_ingress.sql,tests}
|
||||
deploy/postgres/{001_roles.sql,...,019_privileges_bell_alerts.sql,tests}
|
||||
```
|
||||
|
||||
Sense 脚手架和 PostgreSQL `001`～`017` 已实现；Bell 已有事件校验/不可变存储、Sense 审计 relay 与默认关闭的 Brain 事件 ingress，但没有公共管理 API。Brain 已有单路工程原型和仓库外 SQLite 可靠事件 Outbox；尚无生产模型、GPU pipeline、证据切片或规则/Alert 链。
|
||||
Sense 脚手架和 PostgreSQL `001`～`019` 已实现；Bell 已有事件校验/不可变存储、Sense 审计 relay、默认关闭的 Brain 事件 ingress，以及规则/Alert/ack 回环工程纵切，但没有公共管理 API。Brain 已有单路工程原型和仓库外 SQLite 可靠事件 Outbox；尚无生产模型、GPU pipeline、证据切片、升级或通知链。
|
||||
|
||||
## 10. 开发顺序
|
||||
|
||||
- M0 不写生产代码。
|
||||
- M1 只动 Sense，以 1 路 T-001 准入实机 + 至少 4 路独立合成 RTSP 源完成五路接入骨架与 MediaMTX；设备模型从此时起保持模态/能力可扩展，但不提前实现非视频适配器。真实多设备现场门禁移到 T-007，阻塞生产试点但不阻塞本地开发。
|
||||
- M2 仍以 Sense 为主；Control API、对账、多租户投影和本地 16 路开通/停用基线已完成，隧道等待客户网络条件后补验。
|
||||
- M3 Brain 与 Bell 同时起步；T-015～T-019 已打通不可变事件消费者、审计 relay、Brain 单路候选、Sense 回环管理纵切和 Brain→Bell 可靠事件 ingress。下一步仍应在证据切片与规则/Alert 之间按客户可见闭环拆分独立任务。
|
||||
- M3 Brain 与 Bell 同时起步；T-015～T-020 已打通不可变事件消费者、审计 relay、Brain 单路候选、Sense 回环管理纵切、Brain→Bell 可靠事件 ingress 和 Bell 规则→Alert→ack/close 工程纵切。下一步应独立实现 Bell→Sense 异步证据/pre-roll 切片，不与已经冻结的 Alert 状态机混交。
|
||||
- M4/M5 再做 64/128 路分片、完整管理端和多个场景包；M6 接入雷达、门磁、按钮和可穿戴等非视频适配器。
|
||||
|
||||
M3 先执行不少于 2 周的 dry-run，冻结现场标注集，按规则报告召回率和每路每天误报数；现场基线评审后才把数值阈值写入站点验收附件。算法效果指标与系统 SLA 分开验收。
|
||||
|
||||
+3
-1
@@ -41,7 +41,9 @@
|
||||
- T-017：建立 Brain 单路匿名区域事件工程原型；默认合成 fixture、可选 MediaMTX/RTSP，展示 detector port、track、多边形进入判定和不含平台 ID 的候选事实，不把 HOG/fixture 宣称为生产模型或效果证据。
|
||||
- T-018：优先建立 Sense NVR 管理面首个可运行纵切；复用 Control API 和 MediaMTX，以回环工程控制台展示设备、配额、收敛状态和最多 4 路按需 WebRTC 预览，不包含录像/回放或非回环生产认证。
|
||||
- T-019：建立 Brain→Bell 可靠业务事件 ingress；独立冻结数字事件身份到 Bell 逻辑身份的绑定、HMAC 认证、SQLite 持久 Outbox、Bell 永久来源收据和跨重启幂等确认，不得把 T-017 内存事件环当作生产投递。
|
||||
- 规则引擎、场景包加载、预警状态机与双路径投递。
|
||||
- T-020：建立 Bell 规则→Alert→ack/close 最小可见纵切；规则版本、evaluation、Alert/Event 关联、状态迁移和命令收据均 append-only，工程值班台只允许回环且不伪造证据、升级或投递事实。
|
||||
- T-021（建议，尚未创建）：建立 Bell→Sense 异步证据/pre-roll 切片，独立冻结请求、授权、幂等、状态、对象引用和生命周期；不得把常态录像或原始摄像头凭据交给 Bell。
|
||||
- 升级状态机、排班解析与双路径投递。
|
||||
- 最小 Web/App 处置流程、RBAC 与审计。
|
||||
- 现场误报基线和反馈队列。
|
||||
- T-007：客户试点、借用或租赁设备条件具备后完成至少 5 条独立真实上游的现场验收；不阻塞本地开发，但阻塞生产试点启用和真实多路 SLA。
|
||||
|
||||
+19
-8
@@ -1,6 +1,6 @@
|
||||
# API 与契约
|
||||
|
||||
> Brain → Bell 事件契约 v0.1 与内部 ingress v1、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 与 Bell 回环 Alert 控制台 v1 已冻结；其他 API 仍在设计阶段。不得把工程控制台当成 Bell 公共契约，也不得把本文的“待定”自行具体化。
|
||||
|
||||
## 1. 已冻结：Brain → Bell 事件契约
|
||||
|
||||
@@ -32,7 +32,7 @@ T-015 已实现 Bell 消费端的内部组装与存储边界；T-019 在 [`contr
|
||||
| Sense → Brain | 流绑定与设备型触发 | 分片可路由，触发入口与流控制解耦 | 待 M2/M3 设计 |
|
||||
| Worker → 控制面 | 注册、心跳、容量 | `max_sources` 来自 profile/压测，不固定为 16 | 待 M3 设计 |
|
||||
|
||||
冻结签名和失败语义见 [`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 下静默改变一致性或身份语义。
|
||||
冻结签名和失败语义见 [`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/bell-alert-console-v1.openapi.json`](contracts/bell-alert-console-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 拥有投影源数据、视图、事件身份绑定、来源收据、规则版本和 Alert 历史；未来分库必须发布新版本，不能在 v1 下静默改变一致性或身份语义。
|
||||
|
||||
## 3. 已冻结：Sense Control API v1
|
||||
|
||||
@@ -50,7 +50,18 @@ T-015 已实现 Bell 消费端的内部组装与存储边界；T-019 在 [`contr
|
||||
|
||||
T-008 冻结公共控制契约；T-009/T-010 建立 PostgreSQL 投影、准入和本地审计基础；T-011 已实现 7 个 HTTP handler、外部静态摘要认证适配器、tenant/Site scope、幂等收据、ETag/HMAC cursor 和持久化 batch operation。业务路由默认关闭且仅可在 PostgreSQL 上开启；T-016 的审计 relay 是独立内部端点，不替代 Bell 管理服务或 JWT/OIDC。
|
||||
|
||||
## 4. 待冻结的 Bell 公共 API
|
||||
## 4. 已冻结：Bell 回环 Alert 控制台 v1
|
||||
|
||||
- OpenAPI：[`contracts/bell-alert-console-v1.openapi.json`](contracts/bell-alert-console-v1.openapi.json)
|
||||
- 路由前缀：`/bell-console/api/v1`；仅在整个 Bell 服务显式回环监听且两个 Alert feature flag 开启时注册。
|
||||
- 范围：Alert 按状态稳定分页、Alert/Event/规则版本/transition 详情、首次 ack 和确认后 close。列表默认 16、最大 100。
|
||||
- tenant、Site 与 actor 只取启动时的仓库外上下文；Bearer token 只从仓库外文件加载并仅驻留页面内存。写命令要求 8～128 字符 `Idempotency-Key`。
|
||||
- 首次 ack 获胜；后到者返回 `409 already_acknowledged` 和实际 actor/time。同 key/同命令重放原 status/body，同 key/不同命令返回 `409 idempotency_conflict`。
|
||||
- API 不返回 Event 原始 payload、流 URI、凭据、DSN 或 token；当前明确返回证据和投递均 `not_enabled`。
|
||||
|
||||
该 API 用于本地工程/售前联调，不冻结正式客户 URL、JWT/OIDC/RBAC、前端框架或非回环部署。正式公共 API 不得无版本迁移地复用工程 token/上下文模式。
|
||||
|
||||
## 5. 待冻结的 Bell 公共 API
|
||||
|
||||
资源范围预计包括：租户、站点、设备只读投影、规则、事件、预警、ack、处置、误报反馈、审计和报表。设计时必须满足：
|
||||
|
||||
@@ -61,11 +72,11 @@ T-008 冻结公共控制契约；T-009/T-010 建立 PostgreSQL 投影、准入
|
||||
- 错误体包含稳定错误码、可读消息和 trace ID，不返回内部堆栈或凭据。
|
||||
- 人脸功能未授权时表现为能力不存在，而非仅按钮置灰。
|
||||
|
||||
## 5. MediaMTX 接口边界
|
||||
## 6. MediaMTX 接口边界
|
||||
|
||||
Sense 使用 MediaMTX 官方 OpenAPI 生成客户端并加薄封装。业务代码不得散落硬编码 path API；生成代码不可手改。MediaMTX path 不是租户/站点/设备的业务真相源。
|
||||
|
||||
### 5.1 T-003 已实现的内部适配契约
|
||||
### 6.1 T-003 已实现的内部适配契约
|
||||
|
||||
以下是 Sense 内部 Go port，不是 Bell 或第三方可依赖的公共 HTTP API：
|
||||
|
||||
@@ -77,20 +88,20 @@ Sense 使用 MediaMTX 官方 OpenAPI 生成客户端并加薄封装。业务代
|
||||
|
||||
MediaMTX 薄封装调用同版官方 OpenAPI 的 `/v3/config/paths/get|add|patch|delete/{name}`、`/v3/config/paths/list` 与 `/v3/paths/get/{name}`。列表有最大页数和重复页保护，source URI 在薄封装内丢弃。生成源、版本和 SHA-256 见 `docs/03-tech-stack.md`；业务包不得直接 import 生成包。
|
||||
|
||||
### 5.2 设备台账语义
|
||||
### 6.2 设备台账语义
|
||||
|
||||
- 设备类型由 `modality` 表达物理类别，由多值 `capabilities` 表达视频采集、音频、空间规则或遥测能力，避免把“摄像头”固化为唯一设备模型。
|
||||
- 视频配额只统计 `desired_state=enabled` 且具有 `video_capture` capability 的设备；站点默认 16、可配置 1～128。禁用设备和非视频传感器不占视频路数。
|
||||
- SQLite 表使用 `sense_` 前缀且只是 M1 实验室兼容路径；PostgreSQL 使用 `sense.devices`、能力/调和表、两个投影观察表和 `sense.device_operation_outbox`。PostgreSQL 不建立可写 Site/Area 真相副本；后续公共控制 API 只在 PostgreSQL 路径启用，不能把 SQLite 描述为 Area/Outbox 生产等价实现。
|
||||
- 摄像头密码不进入设备普通字段。`credential_ref` 只保存外部密钥引用；ONVIF 返回的 stream URI 只在内存中传给 MediaMTX，不写入设备台账或日志。
|
||||
|
||||
### 5.3 Sense 进程 HTTP 面
|
||||
### 6.3 Sense 进程 HTTP 面
|
||||
|
||||
`GET /healthz` 表示进程存活，`GET /readyz` 表示所选数据库已打开且 schema/权限前置检查完成；两者不要求认证，也不等价于摄像头、MediaMTX path 或里程碑健康。`GET /metrics` 默认输出无租户/设备/Path 标签的 Prometheus 汇总，可通过 `SENSE_METRICS_ENABLED=false` 关闭。T-011 在 `SENSE_CONTROL_API_ENABLED=true`、PostgreSQL v5 schema 和外部安全文件全部有效时注册冻结的 `/api/v1` 路由；默认 SQLite 不注册业务路由。业务路由不提供无 Site 边界的 `/api/v1/devices` 临时接口。
|
||||
|
||||
孤儿报告/处置不是公共 HTTP API。它由 PostgreSQL 专用 `cmd/sense-orphan` 在受控运维主机执行，使用 15 分钟 scan ID、actor、精确确认文本和运行前二次快照；不改变 Sense Control API v1 的 7 个 endpoint。
|
||||
|
||||
## 6. 变更流程
|
||||
## 7. 变更流程
|
||||
|
||||
1. 在对应任务文件写清调用方、提供方、数据所有者、失败语义、幂等与兼容策略。
|
||||
2. 更新本文和 schema/OpenAPI。
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# YoVision 控制面、审计与内部事件传输契约 v1
|
||||
|
||||
> 冻结日期：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 仍未实现。
|
||||
> 冻结日期：2026-08-11。Control API、审计 relay、Brain 事件 ingress 与 Bell 回环 Alert 控制台契约版本：`1.0.0`。Sense 是设备期望态的提供方；Bell 是 Tenant、Site、Area、RBAC、配额、事件、Alert 与全局审计的所有者。T-016 已实现 Sense Outbox 审计 relay，T-019 已实现 Brain 事件 Outbox ingress，T-020 已实现 Bell 规则→Alert→ack/close 工程纵切；Bell 公共管理服务与 JWT/OIDC 仍未实现。
|
||||
|
||||
## 契约文件
|
||||
|
||||
@@ -13,6 +13,7 @@
|
||||
| [`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 与跨重启幂等语义 |
|
||||
| [`bell-alert-console-v1.openapi.json`](bell-alert-console-v1.openapi.json) | Bell | 回环工程值班台 | Alert 分页/详情、首次 ack、确认后关闭与永久幂等收据 |
|
||||
|
||||
OpenAPI 的 `/api/v1` 路径是公共控制面边界；`/healthz`、`/readyz` 仍是非业务运维探针。v1 不提供设备删除：停用设备使用期望态接口，保留设备、操作和审计历史。Site、Area、配额、RBAC 和审计聚合不由 Sense 提供 CRUD。
|
||||
|
||||
@@ -87,6 +88,14 @@ Bell 的永久 `event_ingress_receipts` 以 `(producer_id, source_event_id)` 唯
|
||||
|
||||
数字 `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。
|
||||
|
||||
## Bell 回环规则与 Alert 控制台
|
||||
|
||||
T-020 的 [`bell-alert-console-v1.openapi.json`](bell-alert-console-v1.openapi.json) 只冻结工程 API，不占用未来 Bell 公共 `/api/v1`。整个 `bell-api` 必须显式监听回环，规则、token、tenant/Site 和 actor 上下文均从仓库外启动配置读取；请求不得自报这些上下文。列表按 `created_at DESC,id DESC` 稳定分页，默认 16、最大 100。
|
||||
|
||||
规则文件 v1 只支持精确 `event_kind`、最小严重度、可选 Site、启用状态和生效时间。相同 `(tenant_id,rule_key)` 的配置按 canonical SHA-256 幂等发布；变化生成不可变新版本。Event 无论有无规则/是否命中都会留下 durable sweep；每个被考虑版本写 matched/no_match evaluation，命中时 Bell 创建独立 `alt_` ULID 和 Event 多对多关联。Event、规则版本、evaluation、Alert 身份、关联和 transition 均只追加。
|
||||
|
||||
Alert 状态机为 `open → acknowledged → closed`。ack 由数据库事务与 advisory lock 串行化，只有首个竞争者成功；后到者返回 `409 already_acknowledged` 和实际首位 actor/time，不覆盖历史。close 只允许从 acknowledged 进入。所有命令要求 8～128 字符 `Idempotency-Key`；同租户同 key/同命令永久重放原 status/body，同 key/不同命令返回 `409 idempotency_conflict`。当前详情固定返回 `evidence_status=not_enabled`、`delivery_status=not_enabled`，不得伪造切片、升级或送达事实。
|
||||
|
||||
## 兼容与废弃
|
||||
|
||||
- v1 可增加不改变已有语义的可选响应字段和新错误细节；客户端必须忽略未知响应字段。
|
||||
@@ -103,10 +112,12 @@ 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 json.tool docs/contracts/bell-alert-console-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"
|
||||
python -m unittest discover -s tests -p "test_bell_alert_contract.py"
|
||||
```
|
||||
|
||||
测试同时校验 OpenAPI 结构、生成 server glue、HTTP handler 与 PostgreSQL migration/事务；它不替代 Bell 消费方联合验收或客户现场容量验证。
|
||||
|
||||
@@ -0,0 +1,89 @@
|
||||
{
|
||||
"openapi": "3.1.0",
|
||||
"info": {
|
||||
"title": "YoVision Bell loopback alert console",
|
||||
"version": "1.0.0",
|
||||
"description": "Engineering-only, loopback API for the Event to Rule to Alert to acknowledgement vertical slice. Tenant, site and actor context are server-side configuration, never client input."
|
||||
},
|
||||
"servers": [{"url": "http://127.0.0.1:{port}/bell-console/api/v1", "variables": {"port": {"default": "8081"}}}],
|
||||
"security": [{"consoleBearer": []}],
|
||||
"paths": {
|
||||
"/alerts": {
|
||||
"get": {
|
||||
"operationId": "listAlerts",
|
||||
"parameters": [
|
||||
{"name": "state", "in": "query", "schema": {"$ref": "#/components/schemas/AlertState"}},
|
||||
{"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 16}},
|
||||
{"name": "cursor", "in": "query", "schema": {"$ref": "#/components/schemas/AlertId"}}
|
||||
],
|
||||
"responses": {
|
||||
"200": {"description": "Stable newest-first page", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AlertPage"}}}},
|
||||
"400": {"$ref": "#/components/responses/BadRequest"},
|
||||
"401": {"$ref": "#/components/responses/Unauthorized"}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/alerts/{alert_id}": {
|
||||
"get": {
|
||||
"operationId": "getAlert",
|
||||
"parameters": [{"$ref": "#/components/parameters/AlertId"}],
|
||||
"responses": {
|
||||
"200": {"description": "Alert, related event facts and append-only transitions", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AlertDetail"}}}},
|
||||
"401": {"$ref": "#/components/responses/Unauthorized"},
|
||||
"404": {"$ref": "#/components/responses/NotFound"}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/alerts/{alert_id}:ack": {
|
||||
"post": {
|
||||
"operationId": "acknowledgeAlert",
|
||||
"parameters": [{"$ref": "#/components/parameters/AlertId"}, {"$ref": "#/components/parameters/IdempotencyKey"}],
|
||||
"requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CommandBody"}}}},
|
||||
"responses": {
|
||||
"200": {"description": "First acknowledgement or exact idempotent replay", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CommandResponse"}}}},
|
||||
"409": {"description": "Already acknowledged (including actual first actor/time), or reused key", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CommandResponse"}}}},
|
||||
"401": {"$ref": "#/components/responses/Unauthorized"},
|
||||
"404": {"$ref": "#/components/responses/NotFound"}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/alerts/{alert_id}:close": {
|
||||
"post": {
|
||||
"operationId": "closeAlert",
|
||||
"parameters": [{"$ref": "#/components/parameters/AlertId"}, {"$ref": "#/components/parameters/IdempotencyKey"}],
|
||||
"requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CommandBody"}}}},
|
||||
"responses": {
|
||||
"200": {"description": "Close after acknowledgement or exact idempotent replay", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CommandResponse"}}}},
|
||||
"409": {"description": "Acknowledgement required, already closed, or reused key", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CommandResponse"}}}},
|
||||
"401": {"$ref": "#/components/responses/Unauthorized"},
|
||||
"404": {"$ref": "#/components/responses/NotFound"}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"components": {
|
||||
"securitySchemes": {"consoleBearer": {"type": "http", "scheme": "bearer", "description": "External engineering-console token; never persisted in browser storage."}},
|
||||
"parameters": {
|
||||
"AlertId": {"name": "alert_id", "in": "path", "required": true, "schema": {"$ref": "#/components/schemas/AlertId"}},
|
||||
"IdempotencyKey": {"name": "Idempotency-Key", "in": "header", "required": true, "schema": {"type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"}}
|
||||
},
|
||||
"responses": {
|
||||
"BadRequest": {"description": "Invalid bounded input", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
|
||||
"Unauthorized": {"description": "Missing or invalid console token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
|
||||
"NotFound": {"description": "Alert absent from configured tenant/site", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}
|
||||
},
|
||||
"schemas": {
|
||||
"AlertId": {"type": "string", "pattern": "^alt_[0-9A-HJKMNP-TV-Z]{26}$"},
|
||||
"AlertState": {"type": "string", "enum": ["open", "acknowledged", "closed"]},
|
||||
"Severity": {"type": "string", "enum": ["low", "medium", "high", "critical"]},
|
||||
"AlertSummary": {"type": "object", "additionalProperties": false, "required": ["id", "severity", "title", "state", "rule_key", "rule_version", "created_at"], "properties": {"id": {"$ref": "#/components/schemas/AlertId"}, "severity": {"$ref": "#/components/schemas/Severity"}, "title": {"type": "string", "minLength": 1, "maxLength": 120}, "state": {"$ref": "#/components/schemas/AlertState"}, "rule_key": {"type": "string"}, "rule_version": {"type": "integer", "minimum": 1}, "created_at": {"type": "string", "format": "date-time"}}},
|
||||
"AlertPage": {"type": "object", "additionalProperties": false, "required": ["items", "next_cursor"], "properties": {"items": {"type": "array", "maxItems": 100, "items": {"$ref": "#/components/schemas/AlertSummary"}}, "next_cursor": {"oneOf": [{"$ref": "#/components/schemas/AlertId"}, {"type": "null"}]}}},
|
||||
"EventRef": {"type": "object", "additionalProperties": false, "required": ["id", "device_id", "kind", "severity", "occurred_at"], "properties": {"id": {"type": "string", "pattern": "^evt_[0-9A-HJKMNP-TV-Z]{26}$"}, "device_id": {"type": "integer", "minimum": 1}, "kind": {"type": "string"}, "severity": {"$ref": "#/components/schemas/Severity"}, "occurred_at": {"type": "string", "format": "date-time"}}},
|
||||
"Transition": {"type": "object", "additionalProperties": false, "required": ["sequence", "from_state", "to_state", "actor_ref", "note", "occurred_at"], "properties": {"sequence": {"type": "integer", "minimum": 1}, "from_state": {"oneOf": [{"$ref": "#/components/schemas/AlertState"}, {"type": "null"}]}, "to_state": {"$ref": "#/components/schemas/AlertState"}, "actor_ref": {"type": "string"}, "note": {"oneOf": [{"type": "string", "maxLength": 500}, {"type": "null"}]}, "occurred_at": {"type": "string", "format": "date-time"}}},
|
||||
"AlertDetail": {"allOf": [{"$ref": "#/components/schemas/AlertSummary"}, {"type": "object", "additionalProperties": false, "required": ["events", "transitions", "evidence_status", "delivery_status"], "properties": {"events": {"type": "array", "items": {"$ref": "#/components/schemas/EventRef"}}, "transitions": {"type": "array", "items": {"$ref": "#/components/schemas/Transition"}}, "evidence_status": {"const": "not_enabled"}, "delivery_status": {"const": "not_enabled"}}}]},
|
||||
"CommandBody": {"type": "object", "additionalProperties": false, "properties": {"note": {"oneOf": [{"type": "string", "maxLength": 500}, {"type": "null"}]}}},
|
||||
"CommandResponse": {"type": "object", "additionalProperties": false, "required": ["alert_id", "state", "actor_ref", "occurred_at"], "properties": {"alert_id": {"$ref": "#/components/schemas/AlertId"}, "state": {"$ref": "#/components/schemas/AlertState"}, "actor_ref": {"type": "string"}, "occurred_at": {"type": "string", "format": "date-time"}, "code": {"type": "string", "enum": ["already_acknowledged", "acknowledgement_required", "already_closed", "invalid_state"]}}},
|
||||
"Error": {"type": "object", "additionalProperties": false, "required": ["code", "message"], "properties": {"code": {"type": "string"}, "message": {"type": "string"}}}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -4,29 +4,30 @@
|
||||
|
||||
## 当前阶段
|
||||
|
||||
- 阶段：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。
|
||||
- 阶段：M0 指定摄像头型号准入、M1“一实机 + 四合成源”软件闭环和 M2 本地 16 路批量收敛/稳定基线已通过；M3 已建立 Bell 不可变事件存储、Sense→Bell 全局审计 relay、Brain 单路匿名区域事件工程原型、Brain→Bell 可靠事件 ingress 及 Bell 规则→Alert→ack/close 工程纵切。客户网络尚未提供，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、规则版本/evaluation/Alert 状态机和回环工程值班台。Brain 已包含单路 source/detector/track/zone-entry、回环可视化页与仓库外 SQLite 事件 Outbox，但仍没有生产模型/GPU pipeline、公共管理服务/JWT、证据切片、升级/通知或正式 Web/H5。
|
||||
- 默认容量：16 路；单站点本阶段上限 128 路，必须横向分片。
|
||||
|
||||
## 仓库现实
|
||||
|
||||
- `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/` 已有 Go module 与 `cmd/sense-api`；`Bell/` 已有事件/Alert 域 Go module、最小 `cmd/bell-api` 两条内部 ingress 和嵌入式 `/bell-console/`；`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`～`017` migration 可重放；Sense Outbox fencing、Bell event/global-audit/Brain-ingress repository、nonce/永久来源收据、权限、并发幂等冲突与不可变性测试通过后自动清理，现有 `D:\pgsql17\data` 和 5432 服务未被读取、停止或修改。
|
||||
- Windows 隔离测试使用 `D:\pgsql17\bin` 启动随机回环端口临时集群，`001`～`019` migration 可重放；Sense Outbox fencing、Bell event/global-audit/Brain-ingress/Alert repository、nonce/永久来源与命令收据、8 路并发 evaluation/ack、权限和不可变性测试通过后自动清理，现有 `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 稳定冲突。
|
||||
- T-020 冻结 `bell-alert-console-v1` 回环工程契约：规则配置从仓库外绝对 JSON 加载并按 canonical hash 幂等发布不可变版本；Event durable sweep、evaluation、`alt_` Alert、Event 关联和 `open → acknowledged → closed` transition 只追加。首次 ack 获胜，后到者返回实际 actor/time；8～128 字符命令 key 由永久收据跨重启重放。列表默认 16、最大 100；值班台无 CDN/浏览器持久存储，明确显示证据及升级/投递尚未启用。
|
||||
- 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` 和 `brain-event-ingress-v1.openapi.json` 已分别由 T-016/T-019 实现。两条内部 ingress 使用独立 key；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` 和回环 `bell-alert-console-v1.openapi.json` 已分别由 T-016/T-019/T-020 实现。两条内部 ingress 使用独立 key，Alert 工程台使用独立 token/服务端上下文；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 查询，不在本文复制。
|
||||
@@ -48,7 +49,7 @@ Windows：
|
||||
go -C Sense run ./cmd/sense-api
|
||||
```
|
||||
|
||||
Bell 事件域与两条内部 ingress 验证：
|
||||
Bell 事件、两条内部 ingress 与 Alert 工程纵切验证：
|
||||
|
||||
```powershell
|
||||
go -C Bell test ./...
|
||||
@@ -99,12 +100,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-019 不绕过认证，自动验收使用隔离临时集群。向共享/生产实例安装 migration 前仍需管理员私下提供专用数据库、最小权限登录角色、外部 Control API/两类 ingress key、Brain Outbox 路径、TLS 证书与备份方案。
|
||||
- 本机现有 PostgreSQL 5432 实例使用 SCRAM 且当前开发进程没有管理员密码；T-009～T-020 不绕过认证，自动验收使用隔离临时集群。向共享/生产实例安装 migration 前仍需管理员私下提供专用数据库、最小权限登录角色、外部 Control API/两类 ingress key、Brain Outbox、Bell 规则/token/上下文、TLS 证书与备份方案。
|
||||
- 代码知识图谱在无业务代码阶段可能为空；工具不可用时使用 `rg` 处理文档与配置。
|
||||
|
||||
## 下一步
|
||||
|
||||
客户网络仍未提供，T-013 WireGuard 继续后置。T-019 已完成本地 Brain→Bell 可靠业务事件 ingress；下一项建议独立建立 Bell 规则→Alert→ack 的最小可见纵切，证据/pre-roll 切片另立任务且不与 Alert 状态机混交。客户授权、借用或租赁条件具备后再执行 T-007 五条独立真实上游现场门禁；上述本地任务均不解除 T-007/T-013，也不形成真实多路、模型效果或生产 SLA 承诺。
|
||||
客户网络仍未提供，T-013 WireGuard 继续后置。T-020 已完成本地 Event→Rule→Alert→ack/close 最小可见纵切；下一项建议创建 T-021，独立建立 Bell→Sense 异步证据/pre-roll 切片，冻结请求授权、幂等状态、对象引用和生命周期，不改 Alert 状态机。其后再拆升级计时/排班解析/双路径通知。客户授权、借用或租赁条件具备后再执行 T-007 五条独立真实上游现场门禁；上述本地任务均不解除 T-007/T-013，也不形成真实多路、模型效果或生产 SLA 承诺。
|
||||
|
||||
## 已知风险
|
||||
|
||||
|
||||
+3
-2
@@ -26,8 +26,9 @@
|
||||
| --- | --- | --- |
|
||||
| `/brain-demo` | Brain T-017 回环工程服务 | 只允许显式回环监听；可独立打开 `docs/design/brain/index.html` 使用标识清楚的离线原型数据。不是 Bell 公共业务路由，不展示流 URL/凭据，不产生平台事件 ID、Alert 或处置状态 |
|
||||
| `/sense-console/` | Sense T-018 回环工程服务 | 默认关闭；复用 Control API v1，设备分页默认 16 项，最多 4 路按需 WebRTC 预览。只允许 Sense 与 MediaMTX 播放端均为显式回环地址；不是录像/回放或 Bell 公共业务路由 |
|
||||
| `/bell-console/` | Bell T-020 回环工程服务 | 默认关闭；展示真实 Alert、关联 Event、规则版本和 append-only transition，支持首次 ack 与确认后关闭。整个 Bell 服务必须显式回环监听；token 仅驻留页面内存，tenant/Site/actor 取服务端上下文；证据、升级和投递未启用时必须明确降级 |
|
||||
|
||||
这些路由只为开发、售前和实施联调。正式客户值班端仍由 Bell `/events`、`/alerts` 等受认证路由承载；不得把 Brain 工程页或 T-018 Sense 回环控制台暴露到非可信网络或嵌入客户公共系统。
|
||||
这些路由只为开发、售前和实施联调。正式客户值班端仍由 Bell `/events`、`/alerts` 等受认证路由承载；不得把 Brain 工程页、T-018 Sense 控制台或 T-020 Bell 工程值班台暴露到非可信网络或嵌入客户公共系统。
|
||||
|
||||
## App 候选导航
|
||||
|
||||
@@ -53,6 +54,6 @@ Bell 响应式管理端的底部主导航最多 5 项；Site/Area、RBAC 与审
|
||||
|
||||
## 组件归属
|
||||
|
||||
- 业务组件放 `Bell/web/`，不放进 Sense 或 Brain；T-017 的 `/brain-demo` 是明确隔离的回环工程页，不改变该归属。
|
||||
- 业务组件放 `Bell/web/`，不放进 Sense 或 Brain；T-017 的 `/brain-demo` 是明确隔离的回环工程页。T-020 也使用 `Bell/web/`，但只是自包含工程台，不冻结正式前端框架或公共路由。
|
||||
- 流状态只通过 Bell/Sense 的受控业务 API 展示，不直接把 MediaMTX 管理端暴露给业务用户。
|
||||
- 共用筛选、分页、批量结果和状态时间线组件在前端脚手架确定后再分层，不提前臆造目录。
|
||||
|
||||
+21
-4
@@ -3,12 +3,12 @@ id: T-020
|
||||
title: 建立 Bell 规则到 Alert 与 ack 的最小可见纵切
|
||||
phase: 3
|
||||
deps: [T-015, T-019]
|
||||
status: TODO
|
||||
status: DOING
|
||||
created: 2026-08-11
|
||||
issue: 71
|
||||
context_ref: null
|
||||
claim_branch: null
|
||||
work_branch: null
|
||||
context_ref: 477afa6ba2def34224f2dfeedc5b14421ec27650
|
||||
claim_branch: claims/T-020
|
||||
work_branch: agent/codex/T-020
|
||||
write_paths:
|
||||
- docs/tasks/T-020.md
|
||||
- Bell/
|
||||
@@ -86,3 +86,20 @@ T-019 已把 Brain 候选可靠地写成 Bell 不可变 Event，但 Bell 尚未
|
||||
- 复用已确认 Bell 原型及 US-003/US-005、IX-005～IX-008/IX-013；工程值班台不冻结最终前端框架。
|
||||
- 当前会话未提供 codebase-memory MCP 图工具，按仓库规则降级为定向读取与 `rg`。任务定义前 `./init.ps1` 基线通过：77 项根测试、30 项 Brain 测试，以及 Sense/Bell generate/test/vet/build 全绿。
|
||||
- 任务定义已合入默认分支并创建唯一 Gitea Issue #71；本映射合入默认分支后才允许添加 `status/todo` 并由 dispatcher 分配。
|
||||
|
||||
### 2026-08-11 领取
|
||||
|
||||
- dispatcher `ila` 已在 Issue #71 核对依赖、写路径与活跃任务，并分配给 `codex`。
|
||||
- 基线提交：`477afa6ba2def34224f2dfeedc5b14421ec27650`；claim 分支：`claims/T-020`；工作分支：`agent/codex/T-020`。
|
||||
|
||||
### 2026-08-11 实现与自动化验收
|
||||
|
||||
- PostgreSQL 新增可重放 `018`～`019`，Bell schema 提升到 v6：规则版本、Event sweep、rule evaluation、Alert 身份、Alert/Event 多对多关系、transition 和命令收据全部只追加；`bell_runtime` 仅有 `SELECT/INSERT`，数据库 trigger 同时拒绝 owner 路径的意外 UPDATE/DELETE。Alert 对 `rule_evaluation_id` 唯一，数据库层保证一个 Event/Rule evaluation 最多一个 Alert。
|
||||
- 规则配置从仓库外绝对 JSON 加载，限制 256 KiB/256 条、拒绝未知字段和重复 key；相同 canonical SHA-256 幂等复用版本。单一可取消 worker 使用 durable sweep 与事务级 advisory lock，多实例对同 Event 收敛；无规则和 no-match 同样落 sweep，规则发布不追溯重算已经 sweep 的历史 Event。
|
||||
- Bell 生成 `alt_` ULID，命中 evaluation、Alert、Event 关联和初始 `open` transition 同事务提交。状态只允许 `open → acknowledged → closed`；永久命令收据按 tenant/idempotency key 重放原 status/body，同 key 改命令/actor/note 稳定冲突。并发后到的 ack 返回 `409 already_acknowledged` 和真实首位 actor/time，不覆盖历史。
|
||||
- 冻结并实现 `bell-alert-console-v1` 回环工程 API：列表默认 16/最大 100，tenant/Site/actor 只取启动上下文；Bearer token 来自仓库外文件并用 constant-time 比较。规则 worker 与控制台分别默认关闭；控制台要求整个 Bell 监听地址显式回环，不返回 Event payload、流 URI、凭据、DSN 或 token。
|
||||
- `Bell/web/` 使用 Go embed、自包含 HTML/CSS/原生 JavaScript，无 npm/CDN/浏览器持久存储。页面显示真实规则版本、关联 Event 和 append-only 时间线；证据、升级/投递明确为未启用。按 `ui-ux-pro-max` 检查落实骨架加载、空态/重试、冲突/无权限反馈、颜色+文字、44px target、键盘入口、`aria-live` 和 reduced-motion。
|
||||
- Edge headless + 脱敏回环 fixture 完成 1440×900 与 CDP 375×812 渲染检查：桌面双栏、移动单栏均可操作，375 viewport 的 `innerWidth/scrollWidth/bodyWidth` 均为 `375`。首轮浏览器 QA 发现 `.workspace{display:grid}` 覆盖 `hidden` 导致授权前泄露空壳布局，已增加全局 `[hidden]{display:none!important}` 并复验；临时 fixture、token 和截图均未进入仓库。
|
||||
- `./init.ps1` 最终通过：83 项根测试、30 项 Brain 测试，以及 Sense/Bell generate/test/vet/build 全绿。独立 Bell test/vet/build、OpenAPI JSON、5 项 Alert 静态契约、11 项 PostgreSQL 静态契约和 `node --check Bell/web/assets/app.js` 通过。
|
||||
- `./scripts/test_postgres.ps1 -PgRoot D:\pgsql17` 最终通过：PostgreSQL 17.10 随机回环临时集群将 `001`～`019` 连续重放两遍；真实 repository 验证 rule publish/no-match、8 个 evaluator 只生成 1 个目标 Alert、8 个并发 ack 只有 1 个成功、late ack 观察同一 actor/time、ack 前 close 拒绝、ack 后 close、幂等冲突、重启恢复和不可变权限。临时集群已停止清理，现有 5432 listener 未改变。
|
||||
- 本任务不需要摄像头、GPU、客户网络或通知供应商；结果不等于正式 Bell Web/H5、公共 JWT/RBAC、证据/通知、算法效果、真实多路或生产 SLA 验收。
|
||||
|
||||
Reference in New Issue
Block a user