Skip to content

World's first open-source enterprise world model.

The alert centre gets written down, as 0005 (#61)

WaylandYanga32561531039
diff --git a/docs/decisions/0005-alert-center.md b/docs/decisions/0005-alert-center.md
new file mode 100644
index 00000000..e3efa5fb
--- /dev/null
+++ b/docs/decisions/0005-alert-center.md
@@ -0,0 +1,174 @@
+# 0005 · 告警中心
+
+- **状态**:规划中 · 未动工
+- **成文**:2026-08-29
+- **相关**:与 Review 队列(0001 P4)职责相邻,本文划边界
+
+---
+
+## 为什么
+
+失败状态目前散在六处,各有各的字段,没有一个地方能一眼看全:
+
+| 位置 | 记的是 |
+|---|---|
+| `jobs.status='failed'` + `jobs.last_error` | 任务失败 —— **没有任何界面** |
+| `documents.status='failed'` | 摄入失败 |
+| `documents.graph_status='failed'` | 抽取失败 |
+| `sources.last_sync_status='failed'` | 源的最近一次同步失败 |
+| `source_sync_runs.status='failed'` | 单次同步失败 |
+| 日志 | 其余一切 |
+
+而且这个问题**已经被局部修过一次**。迁移 `0021_graph_error.sql` 的第一句是:
+
+> 抽取失败的原因此前只进日志与 `jobs.last_error`,文档上什么都不留,界面无从显示。
+
+那次的修法是往 `documents` 上加错误字段。**这是打补丁**:每出现一类新的失败,就往对应的表上加一列。推演层、执行层、OCR 端点、湖仓连接都还没进来,每一个都会带来自己的失败面。照这个路子走下去,会有十几个错误字段散在十几张表上,而用户仍然没有"现在系统哪里不对"的入口。
+
+真正伤人的不是失败本身,是**失败无声**。拖 100 份 PDF 进去、其中 12 份是扫描件,界面上 100 份全绿 —— 用户以为都进去了,直到某天问一个问题、答案里没有那份合同,而他不会想到去怀疑摄入环节。
+
+---
+
+## 边界:与 Review 队列的分工
+
+两者都是"待处理的列表",不划清会互相蚕食。
+
+| | Review 队列 | 告警中心 |
+|---|---|---|
+| 性质 | 需要人**做决定** | 需要人**知道** |
+| 例子 | 这两个实体合不合并、这条低置信事实要不要收 | 这份文档没进去、源连不上、端点挂了 |
+| 不处理的后果 | 知识停在半路 | **你以为进去了,其实没有** |
+| 谁产生 | 抽取与消解在拿不准时主动入队 | 任何执行路径在失败时上报 |
+
+一句话:**Review 管知识的对错,告警管系统的死活。**
+
+---
+
+## 三个决定
+
+### 1. 聚合:同一类未解决的只有一条
+
+拖 100 份 PDF、12 份是扫描件,产生的是**一条**「12 份文档没有文本层」,点开看列表 —— 不是 12 条。同理「Notion 源连续 3 次同步失败」是一条,`last_seen` 往前推。
+
+没有聚合的告警中心,两周后就没人看了。这不是优化,是能不能用的前提。
+
+### 2. 自愈优先于人工关闭
+
+`resolved_at` 由**产生方**清空:配好 OCR 端点、那 12 份重新处理成功,告警自己消失。人工"标记已解决"只是兜底。
+
+做不到自愈的告警,用户很快学会无视它 —— 一旦养成无视的习惯,这个功能就废了,而且是不可逆的。
+
+### 3. 读是各人的,解决是共享的
+
+**这条推翻了一个更省事的方案,理由值得记下来。**
+
+被否决的方案:一条告警被任何一个管理员点开,就对所有人标记已读。看起来省了重复劳动。
+
+失效方式:
+
+> 知识库有三个管理员。A 早上顺手点开看了一眼,没处理。这条告警从 B、C 的未读列表里**永远消失**了 —— 他们不知道曾经发生过这件事,而 A 想着"等会儿再说"。
+
+这是共享已读的经典失效:**所有人都以为别人在处理**,而且发生之后没有任何痕迹能让人发现漏了。
+
+根子在于把两件事合并了:**「已读」是我看没看过,「已解决」是事情完没完**。一个人读过不代表事情解决;而事情解决了,才是所有人都该从列表里移除它的时刻。
+
+所以:
+
+- **未读角标** = 我可见的、未解决的告警中我没读过的条数 —— 每人独立
+- **告警消失** = `resolved_at` 落下,对所有人同时消失 —— 全局共享
+
+代价只有一张两列小表。换来的是**没有人能替别人把一件事读掉**。GitHub 通知、Slack 未读都这么做,不是巧合。
+
+---
+
+## 可见性
+
+`kb_id` 可空,两种语义:
+
+```
+kb_id IS NULL 系统级:LLM 端点不可达、数据库连接池打满、镜像版本不一致
+ → 仅 users.is_admin
+
+kb_id 有值 知识库级:解析失败、抽取失败、源同步失败
+ → 该库中角色 ≥ min_role 的人
+```
+
+**不新写权限逻辑**:`access::kb_role()` 第一句就是 `if user.is_admin { return Ok(Some(Role::Owner)) }`,告警的可见性判定直接复用它,和 KB 路由走同一条鉴权链。系统管理员因此对知识库级告警也全通。
+
+`min_role` 存在 alert 上而不是按 kind 硬编码,因为同一类告警在不同场景下该找的人不同:
+
+- **配置类**(端点、权限、配额)→ admin
+- **内容类**(解析失败、抽取失败、源同步)→ **editor 及以上**
+
+内容类不能只给 admin:拿扫描件举例,admin 需要知道"该配 OCR 了",但**上传那 12 份文件的人**更需要知道"你传的东西没进去"。只给 admin 的话,真正被影响的人反而看不见。
+
+---
+
+## 数据模型草案
+
+```sql
+CREATE TABLE alerts (
+ id UUID PRIMARY KEY,
+ kb_id UUID REFERENCES knowledge_bases(id) ON DELETE CASCADE, -- NULL = 系统级
+ severity TEXT NOT NULL CHECK (severity IN ('info','warning','error')),
+ kind TEXT NOT NULL, -- 'source.sync_failed' / 'llm.unreachable' / ...
+ min_role TEXT NOT NULL, -- 见「可见性」
+ subject_type TEXT, -- document / source / system
+ subject_ids UUID[], -- 聚合:同一 kind 下的所有对象
+ detail JSONB NOT NULL DEFAULT '{}',
+ first_seen TIMESTAMPTZ NOT NULL DEFAULT now(),
+ last_seen TIMESTAMPTZ NOT NULL DEFAULT now(),
+ resolved_at TIMESTAMPTZ
+);
+
+-- 聚合的实现关键:同类未解决的告警在库里只能有一条。
+-- 新实例往 subject_ids 追加、更新 last_seen,而不是插新行。
+CREATE UNIQUE INDEX alerts_open_kind_idx ON alerts (kb_id, kind)
+ WHERE resolved_at IS NULL;
+
+CREATE TABLE alert_reads (
+ alert_id UUID NOT NULL REFERENCES alerts(id) ON DELETE CASCADE,
+ user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+ read_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ PRIMARY KEY (alert_id, user_id)
+);
+```
+
+`kb_id IS NULL` 时那个部分唯一索引不生效(NULL 不参与唯一性判定),系统级告警的去重需要单独处理 —— 实现时用 `COALESCE(kb_id, '00000000-...')` 或一个独立的部分索引。**这是个已知的坑,先记在这里。**
+
+**推送**复用现有的 `AppEvent` broadcast(当前只有 `document` / `review` 两种 kind,加一个 `alert`),SSE 通道是现成的。
+
+---
+
+## 第一刀的范围
+
+**不先建空框架。**
+
+迁移是最难回头的部分。空表建好、发布了,等真接入时发现 schema 不够用(聚合该用数组还是关联表、`min_role` 该在行上还是按 kind 硬编码),改迁移就得走升级路径。而现在还没打 tag,迁移可以推倒重来 —— 这个窗口不该浪费在一张没有数据流过的表上。
+
+更要紧的是:**聚合、自愈、per-user 已读这三件最容易设计错的事,只有真有数据经过才验得出来。** 空框架把它们全留到了以后。
+
+所以第一刀接**两条真实告警源**,各验一条权限路径,且都不需要新的检测逻辑:
+
+| kind | 级别 | 验证什么 |
+|---|---|---|
+| `source.sync_failed` | KB 级 | 聚合(同源连续失败仍是一条)、自愈(下次成功即消失)、`min_role=editor` |
+| `llm.unreachable` | 系统级 | `kb_id IS NULL` 那条去重路径、`is_admin` 可见性 |
+
+两条加起来把 schema 的每个字段都跑过一遍真实数据。**如果设计有错,这一刀就会暴露**,而此时改迁移零成本。
+
+UI 第一版可以粗:顶栏角标 + 一个列表页,能点进出问题的对象即可。
+
+### 留到第二批
+
+**`document.no_text_layer`(扫描件)** —— 它需要先写检测逻辑(判断解析结果为空),而且真正有用是在有了 OCR 端点之后:那时提示语才完整 ——「12 份文档没有文本层,配置 OCR 端点后可重新处理」,同时是错误说明和功能引导。
+
+---
+
+## 被否决的方案
+
+**复用 `audit_events`。** 那张表是"谁做了什么"的台账,性质是不可变记录;告警是"出了什么事",需要状态流转(未读 → 已读 → 已解决)和聚合。塞进同一张表会让台账不再是台账。
+
+**不建表,把六处失败状态 union 起来查询展示。** 零迁移、零新概念,但存不下 per-user 已读,也表达不了自愈语义 —— 而那两件正是这个功能的核心价值。
+
+**共享已读**。见上文「三个决定」第 3 条。
diff --git a/docs/decisions/README.md b/docs/decisions/README.md
index 7122d4b6..e634ed19 100644
--- a/docs/decisions/README.md
+++ b/docs/decisions/README.md
@@ -25,7 +25,8 @@
| 0001 | [本体导入与治理路线](0001-ontology-import-and-governance.md) | 进行中 · P0/P1/P2 已建成,P2c 与 P3–P5 未开工 |
| 0002 | [推理机](0002-reasoning-engine.md) | 规划中 · 取代 0001 P5 的排期 |
| 0003 | [本体从语料里长出来,人站在哪一环](0003-ontology-growth-loop.md) | 已建成 · 含三次判断变化的留痕 |
-| 0004 | [语言:哪些字跟着看的人走,哪些跟着语料走](0004-language-and-localization.md) | 规划中 · L0–L3 |
+| 0004 | [语言:哪些字跟着看的人走,哪些跟着语料走](0004-language-and-localization.md) | 已建成 · L0–L3 全部落地 |
+| 0005 | [告警中心](0005-alert-center.md) | 规划中 · 未动工 |
## 不放这里的东西