yovision/docs/tasks/T-020.md

id, title, phase, deps, status, created, issue, context_ref, claim_branch, work_branch, write_paths

id	title	phase	deps	status	created	issue	context_ref	claim_branch	work_branch	write_paths
T-020	建立 Bell 规则到 Alert 与 ack 的最小可见纵切	3	T-015 T-019	DONE	2026-08-11	71	477afa6ba2	claims/T-020	agent/codex/T-020	docs/tasks/T-020.md Bell/ deploy/postgres/ scripts/test_postgres.ps1 tests/test_postgres_contract.py tests/test_bell_alert_contract.py docs/contracts/ docs/00-ai-start-here.md docs/03-tech-stack.md docs/04-architecture.md docs/06-tasks.md docs/api.md docs/contracts/README.md docs/current-state.md docs/routes.md

问题 / 背景

T-019 已把 Brain 候选可靠地写成 Bell 不可变 Event，但 Bell 尚未消费 Event、记录规则版本、创建独立 Alert 或接受值班员 ack。现有 Bell 原型能说明目标交互，却没有可运行数据/API；因此客户仍看不到从匿名区域事件到“有人确认处理”的业务闭环。

本任务建立默认关闭、只允许回环联调的最小可见纵切：Bell 从不可变 Event 运行一个受限规则内核，为匹配事件幂等创建 Alert，使用 append-only 状态迁移实现首次 ack 竞争者获胜与确认后关闭，并通过自包含值班台展示真实 PostgreSQL 状态。它为后续升级链、双路径通知、证据切片和正式公共认证提供基础，但不提前伪造这些事实。

关联需求与交互（如适用）

• 用户故事：US-003（处置业务预警）、US-005（配置规则与升级链中的规则版本边界）。
• 交互清单：IX-005（预警到达）、IX-006（ack 竞争）、IX-007（只展示实际已有的升级/投递事实）、IX-008（Event/Alert 双向关联与证据降级）、IX-013（权限与隐私）。
• 相关页面 / 路由：复用已确认的 docs/design/bell/index.html 值班台信息架构；新增默认关闭的回环工程路由 /bell-console/ 与 /bell-console/api/v1/*。这些路由不是待冻结的 Bell 公共 /api/v1，不冻结最终前端框架。

方案

1. 在 docs/contracts/bell-alert-console-v1.openapi.json 冻结回环工程 API：按状态分页列出 Alert、读取详情、ack 和 close。列表默认 16、最大 100，稳定按 created_at DESC,id DESC；tenant/Site/actor 只来自启动时的仓库外控制台上下文，不接受客户端自报。
2. PostgreSQL 新增 append-only rule_versions、event_rule_sweeps、rule_evaluations、alerts、alert_events、alert_transitions 和 alert_command_receipts。Rule version、evaluation、Alert 身份、Event 关联、状态迁移与幂等收据均禁止 UPDATE/DELETE/TRUNCATE；当前状态由最新 transition 推导，不把 Event 和 Alert 合并。
3. 首版规则内核只支持精确 event_kind、最小严重度、可选 Site 范围和生效时间。每个稳定 rule_key 的最新生效版本决定 enabled/disabled；配置从仓库外绝对 JSON 文件加载并按 canonical hash 幂等发布，不提供公共规则编辑 API，也不实现任意表达式或场景 DSL。
4. 规则 worker 扫描尚无 sweep 的不可变 Event；在单个 PostgreSQL 事务内写 sweep、每条已考虑规则的 evaluation、匹配 Alert、初始 open transition 与 Event 关联。并发 worker 通过唯一键和事务级 advisory lock 收敛；无规则/未命中也写 durable sweep，避免无限重试。崩溃前未提交可重做，提交后不得生成重复 Alert。
5. Alert ID 由 Bell 生成 alt_ ULID。首版每个命中 Rule/Event 生成一个 Alert，但关系表按多对多建模；Alert 保存命中时的 rule version、标题与严重度快照，后续规则变化不改写历史。
6. 状态机固定为 open -> acknowledged -> closed。ack 的首个成功事务固化 actor/时间；并发后到者返回 409 already_acknowledged 并带当前处置人和时间，不覆盖、不双成功。close 只允许从 acknowledged 进入 closed。写请求必须携带 8～128 字符 Idempotency-Key；同 key/同命令重放原响应，同 key/不同命令稳定冲突。
7. bell-api 以 BELL_ALERTS_ENABLED=true 显式启用规则 worker；规则文件必须是仓库外绝对路径。值班台另以 BELL_ALERT_CONSOLE_ENABLED=true 启用，只允许整个 Bell HTTP 监听地址为显式回环，并要求仓库外 token 文件、正整数 tenant/Site 与受限 actor ref。两项默认关闭，控制台 token 只进入页面内存和 no-store 响应，不记录。
8. Bell/web/ 使用 Go embed、HTML/CSS/原生 JavaScript 实现，不增加前端依赖或 CDN。页面显示真实 Alert 队列、关联 Event、规则版本和 append-only 时间线；无证据时明确标注“证据切片尚未启用”，无升级/投递实现时不显示虚构倒计时或成功状态。ack/close 有 loading、成功、并发冲突、可重试错误与无权限反馈，颜色不是唯一状态表达；375px 与桌面均可操作。
9. 增加 Go 域/handler/store 测试、静态 OpenAPI/UI 契约测试，以及隔离 PostgreSQL migration replay、最小权限、规则幂等、并发 evaluation、并发 ack、幂等重放和重启后状态恢复验证。当前会话无 codebase-memory 图工具，代码发现降级为定向读取和 rg 并记录在执行证据。

不可变约束

• 阈值 / 数值边界：Alert 列表默认 16、最大 100；16 不是业务上限，站点仍允许 1～128 路。规则文件和控制台 token 均限制大小；actor/rule/idempotency 字段有显式长度与字符集边界。worker 必须可取消且空闲轮询有界，不按设备或 tenant 创建 goroutine。
• 判定式 / 状态转换：Rule 最新生效版本决定是否启用；严重度顺序固定为 low < medium < high < critical。每个 (event_id, rule_version_id) 最多一个 evaluation/Alert；open -> acknowledged -> closed 之外的迁移拒绝。首次 ack 获胜，后到者不得覆盖。Event、Rule version、Alert 事实和所有 transition 均 append-only。
• 安全边界：功能默认关闭；工程控制台只允许显式回环绑定。token、规则配置、DSN 与客户数据均在仓库外；页面/API/日志不得返回 Event 原始 payload、流 URI、凭据、内部 DSN 或 token。tenant/Site/actor 不来自请求体、查询参数或可修改浏览器存储。
• 既有契约：冻结 Event v0.1、T-019 ingress、Bell 事件 ULID/不可变性和 Sense/Bell schema 所有权保持不变。Alert 是独立实体并通过关系表关联 Event；本任务不修改 docs/raw/contracts/event-v0.1.schema.json。

验收要点

• 任务相关验证：go -C Bell test ./...、go -C Bell vet ./...、go -C Bell build ./...、python -m unittest discover -s tests -p "test_bell_alert_contract.py" -v、python -m unittest discover -s tests -p "test_postgres_contract.py" -v、./scripts/test_postgres.ps1 -PgRoot D:\pgsql17。
• 完整门禁：运行 ./init.ps1、三项治理基线、git diff --check。PostgreSQL migration 必须从空库执行两遍；8 个并发 evaluator 对同 Event/Rule 只创建 1 个 Alert，8 个并发 ack 只有 1 个成功且其余观察同一处置人；同幂等 key 重放稳定，重启后状态/时间线不丢失；运行角色不能改写或删除任一规则/Alert 历史事实。
• 人工 / 设备验收：不需要摄像头、GPU、客户网络或通知供应商。页面沿用已由产品确认的 Bell 原型信息架构；任务责任人在本地以合成 Event 检查 375px/桌面、键盘、加载/空态/成功/冲突/错误和 reduced-motion。该工程验收不等于正式 Web/H5、JWT/RBAC、算法效果或生产 SLA 验收。
• 构建产物：Bell bell-api、嵌入式 /bell-console/、OpenAPI 和 PostgreSQL migration；不提交运行时规则文件、token、数据库或事件样本。

边界（不改什么）

不实现证据/pre-roll 切片、MinIO/S3、升级计时/重启续跑、联系人/排班、通知 provider、短信/语音/Webhook、本地声光、静默、交接班、误报反馈、正式公共 JWT/OIDC/RBAC、正式 Bell 前端框架、规则编辑器/试运行/回滚、生产模型或多路容量压测；不修改 Sense、Brain、MediaMTX、_reference/ 或冻结 Event v0.1。

协作约束

• 责任 Agent：codex。
• 唯一写入者：codex。
• 委派：不启用。
• Gitea：任务定义先合入默认分支；创建唯一 Issue 并完成双向映射后，由 dispatcher 串行领取并回填 context_ref、claim / 工作分支。

任何新增写路径先检查与其他活跃任务是否重叠；同一时刻只有一个 Agent 修改本任务的 write_paths。

执行记录

2026-08-11 任务定义

• T-020 独立冻结规则扫描、Alert 身份/关系和首次 ack 竞争语义；证据、升级/投递和正式公共认证继续拆分，不用占位状态伪装完成。
• 复用已确认 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 验收。

2026-08-11 收尾

• 工作提交 8208118 已推送并创建 PR #73；Issue #71 的实现证据、提交、分支和任务文件一致。
• 自动化、隔离 PostgreSQL 与浏览器工程验收满足本任务门禁，无额外摄像头/客户网络人工门禁；任务标记 DONE，允许合并并关闭 Issue。