Skip to content

World's first open-source enterprise world model.

The merge itself joins the entity history (#472)

WaylandYanga169f3df34cc
diff --git a/crates/utopia-store/src/graph.rs b/crates/utopia-store/src/graph.rs
index fcd61b34..ae7c62ae 100644
--- a/crates/utopia-store/src/graph.rs
+++ b/crates/utopia-store/src/graph.rs
@@ -1218,6 +1218,35 @@ pub async fn entity_history(
LEFT JOIN entity_types tf ON tf.id = r.from_type_id
JOIN entity_types tt ON tt.id = r.to_type_id
WHERE r.kb_id = $1 AND r.entity_id = $2 AND r.reverted_at IS NOT NULL
+ ),
+ /* 合并也是这个实体身上的一次认识改变,而且是最大的一次:从此它和另一个
+ 实体算同一个东西。**从前这条轴看不见它**——只看得见合并顺手作废的那些
+ 事实(`merged`),于是界面在说结果,不说发生了什么。#337 之后
+ `entity_merges` 有了自己的时钟(created_at / reverted_at),接进来即可。
+
+ 两个方向分开记:`merged_in` = 别人并进了它(事实搬到它名下),
+ `merged_away` = 它并进了别人(这个 id 从此不再单独存在)。同一句话
+ 说两件事会让「谁吸收了谁」读不出来,而回滚正是按方向做的。 */
+ mg AS (
+ SELECT m.created_at AS at,
+ CASE WHEN m.target_id = $2 THEN 'merged_in' ELSE 'merged_away' END AS kind,
+ m.merged_by AS actor_id,
+ CASE WHEN m.target_id = $2 THEN m.source_id ELSE m.target_id END AS other_id
+ FROM entity_merges m
+ WHERE m.kb_id = $1 AND (m.source_id = $2 OR m.target_id = $2)
+ UNION ALL
+ -- 撤销的归因**不能借合并那一行的 merged_by**:撤的人常常不是当初合的人,
+ -- 而自动合并那一行本来就是 NULL。撤销写审计(`merge.revert`,target 是
+ -- 这次合并),从那儿取才对得上人
+ SELECT m.reverted_at, 'merge_reverted',
+ (SELECT a.actor_id FROM audit_events a
+ WHERE a.kb_id = $1 AND a.action = 'merge.revert'
+ AND a.target_id = m.id
+ ORDER BY a.created_at DESC LIMIT 1),
+ CASE WHEN m.target_id = $2 THEN m.source_id ELSE m.target_id END
+ FROM entity_merges m
+ WHERE m.kb_id = $1 AND (m.source_id = $2 OR m.target_id = $2)
+ AND m.reverted_at IS NOT NULL
)";
let rows: Vec<EntityHistoryEvent> = sqlx::query_as(&format!(
"{EVENTS}
@@ -1283,6 +1312,20 @@ pub async fn entity_history(
NULL::uuid, NULL::text, NULL::text,
rt.from_type_label, rt.to_type_label
FROM rt LEFT JOIN users u ON u.id = rt.actor_id
+ UNION ALL
+ -- 合并事件:没有谓词、没有区间、没有证据行,对方是另一个实体。
+ -- 被合并掉的那一头仍留在 entities 里(revert_merge 要按原路搬回去),
+ -- 所以这里拿得到名字;LEFT JOIN 只是防库被清理过
+ SELECT NULL::uuid, mg.at, mg.kind, NULL::text,
+ NULL::text, o.canonical_name,
+ NULL::jsonb, NULL::timestamptz, NULL::text,
+ NULL::timestamptz, NULL::text,
+ NULL::real, u.display_name, NULL::text,
+ NULL::uuid, NULL::text, NULL::text,
+ NULL::text, NULL::text
+ FROM mg
+ LEFT JOIN entities o ON o.id = mg.other_id
+ LEFT JOIN users u ON u.id = mg.actor_id
) x
ORDER BY x.at DESC, x.fact_id
LIMIT $3 OFFSET $4"
@@ -1293,9 +1336,9 @@ pub async fn entity_history(
.bind(offset)
.fetch_all(pool)
.await?;
- // 总数把改类那一支也算上,否则分页会少一截
+ // 总数把改类、合并那两支也算上,否则分页会少一截
let (total,): (i64,) = sqlx::query_as(&format!(
- "{EVENTS} SELECT (SELECT count(*) FROM ev) + (SELECT count(*) FROM rt)"
+ "{EVENTS} SELECT (SELECT count(*) FROM ev) + (SELECT count(*) FROM rt) + (SELECT count(*) FROM mg)"
))
.bind(kb_id)
.bind(entity_id)
diff --git a/crates/utopia-store/tests/history_shows_the_merge_itself.rs b/crates/utopia-store/tests/history_shows_the_merge_itself.rs
new file mode 100644
index 00000000..1ad96482
--- /dev/null
+++ b/crates/utopia-store/tests/history_shows_the_merge_itself.rs
@@ -0,0 +1,224 @@
+//! 合并本身也进这条认识轴(#337 的时钟接进 `entity_history`),打在真库上。
+//!
+//! 从前 History 只看得见合并**顺手作废的那些事实**(`merged`),看不见合并这件事
+//! 本身:打开一个被并过的实体,界面在说结果,不说发生了什么。而合并是这条轴上
+//! 最大的一次认识改变——从此它和另一个实体算同一个东西。
+//!
+//! 三件事各自会以不同的方式坏掉,所以分开断言:
+//! - **方向**:吸收了谁(`merged_in`)与被谁吸收(`merged_away`)在图上是两件事,
+//! 回滚也是按方向做的;同一句话说两头,读的人分不出谁并进了谁
+//! - **撤销的归因**:撤的人常常不是当初合的人,自动合并那一行的 `merged_by` 还是
+//! NULL——所以撤销那一条要从审计里取人,不能借合并行的
+//! - **总数**:分页的总数漏掉这一支,翻到最后一页会少几条
+
+use sqlx::PgPool;
+use uuid::Uuid;
+
+fn t(s: &str) -> chrono::DateTime<chrono::Utc> {
+ s.parse().unwrap()
+}
+
+struct Fixture {
+ org: Uuid,
+ kb: Uuid,
+ /// 留下的那个
+ keeper: Uuid,
+ /// 四月被并进 keeper,至今仍并着
+ absorbed: Uuid,
+ /// 五月被并进 keeper,六月撤销
+ returned: Uuid,
+ /// 撤销那一下的人
+ reverter: Uuid,
+}
+
+async fn seed(pool: &PgPool) -> anyhow::Result<Fixture> {
+ let (org, ws, kb) = (Uuid::now_v7(), Uuid::now_v7(), Uuid::now_v7());
+ let person = Uuid::now_v7();
+ let (keeper, absorbed, returned) = (Uuid::now_v7(), Uuid::now_v7(), Uuid::now_v7());
+ let reverter = Uuid::now_v7();
+
+ sqlx::query("INSERT INTO organizations (id, name) VALUES ($1, 'history-merge-test')")
+ .bind(org)
+ .execute(pool)
+ .await?;
+ sqlx::query("INSERT INTO workspaces (id, org_id, name) VALUES ($1, $2, 'history-merge-test')")
+ .bind(ws)
+ .bind(org)
+ .execute(pool)
+ .await?;
+ sqlx::query(
+ "INSERT INTO knowledge_bases (id, workspace_id, name) VALUES ($1, $2, 'history-merge-test')",
+ )
+ .bind(kb)
+ .bind(ws)
+ .execute(pool)
+ .await?;
+ sqlx::query(
+ "INSERT INTO users (id, org_id, email, display_name, password_hash)
+ VALUES ($1, $2, $3, 'Reverter', 'x')",
+ )
+ .bind(reverter)
+ .bind(org)
+ .bind(format!("reverter-{}@test.local", reverter.simple()))
+ .execute(pool)
+ .await?;
+ sqlx::query(
+ "INSERT INTO entity_types (id, kb_id, key, label) VALUES ($1, $2, 'person', 'Person')",
+ )
+ .bind(person)
+ .bind(kb)
+ .execute(pool)
+ .await?;
+ for (id, name) in [
+ (keeper, "Zhang Wei"),
+ (absorbed, "Zhang Wei"),
+ (returned, "Zhang Wei"),
+ ] {
+ sqlx::query(
+ "INSERT INTO entities (id, kb_id, type_id, canonical_name, created_at)
+ VALUES ($1, $2, $3, $4, $5)",
+ )
+ .bind(id)
+ .bind(kb)
+ .bind(person)
+ .bind(name)
+ .bind(t("2026-02-01T00:00:00Z"))
+ .execute(pool)
+ .await?;
+ }
+
+ // 四月:absorbed 并进 keeper,自动裁决(merged_by 为空)
+ utopia_store::resolution::merge_entities(pool, kb, absorbed, keeper, None, "test").await?;
+ backdate(pool, absorbed, "2026-04-01T00:00:00Z", None).await?;
+
+ // 五月:returned 并进 keeper;六月由人撤销
+ let merge_id =
+ utopia_store::resolution::merge_entities(pool, kb, returned, keeper, None, "test").await?;
+ utopia_store::resolution::revert_merge(pool, kb, merge_id).await?;
+ backdate(
+ pool,
+ returned,
+ "2026-05-01T00:00:00Z",
+ Some("2026-06-01T00:00:00Z"),
+ )
+ .await?;
+ // 撤销的人记在审计里(`merge.revert`),history 从那儿取归因
+ utopia_store::audit::record(
+ pool,
+ Some(kb),
+ reverter,
+ "merge.revert",
+ "merge",
+ Some(merge_id),
+ serde_json::json!({}),
+ )
+ .await?;
+
+ Ok(Fixture {
+ org,
+ kb,
+ keeper,
+ absorbed,
+ returned,
+ reverter,
+ })
+}
+
+/// 合并的时刻由 `now()` 落库,测试要的是确定的日期。
+async fn backdate(
+ pool: &PgPool,
+ source: Uuid,
+ created: &str,
+ reverted: Option<&str>,
+) -> anyhow::Result<()> {
+ sqlx::query("UPDATE entity_merges SET created_at = $2, reverted_at = $3 WHERE source_id = $1")
+ .bind(source)
+ .bind(t(created))
+ .bind(reverted.map(t))
+ .execute(pool)
+ .await?;
+ Ok(())
+}
+
+#[tokio::test]
+async fn history_carries_the_merge_and_its_direction() -> anyhow::Result<()> {
+ let Some(url) = utopia_store::test_db::url() else {
+ return Ok(());
+ };
+ let pool = PgPool::connect(&url).await?;
+ let f = seed(&pool).await?;
+
+ // 收编的那一头:两次并入 + 一次撤销
+ let (events, total) = utopia_store::graph::entity_history(&pool, f.kb, f.keeper, 50, 0).await?;
+ let kinds: Vec<&str> = events.iter().map(|e| e.kind.as_str()).collect();
+ assert_eq!(
+ kinds.iter().filter(|k| **k == "merged_in").count(),
+ 2,
+ "两次都是别人并进来:{kinds:?}"
+ );
+ assert_eq!(
+ kinds.iter().filter(|k| **k == "merge_reverted").count(),
+ 1,
+ "六月那次撤销要在:{kinds:?}"
+ );
+ assert!(
+ !kinds.contains(&"merged_away"),
+ "keeper 从没被并走过:{kinds:?}"
+ );
+ assert_eq!(total, events.len() as i64, "总数漏了合并这一支");
+
+ // 对方的名字要在,否则界面上只剩一句「有实体并了进来」
+ assert!(
+ events
+ .iter()
+ .filter(|e| e.kind == "merged_in")
+ .all(|e| e.other_name.as_deref() == Some("Zhang Wei")),
+ "并入事件要带对方实体的名字"
+ );
+
+ // 归因:合并是引擎自动裁的(merged_by 为空),撤销是人做的
+ let merged_in = events.iter().find(|e| e.kind == "merged_in").unwrap();
+ assert!(
+ merged_in.actor_name.is_none(),
+ "自动合并没有人,归因该是空(界面显示为引擎)"
+ );
+ let reverted = events.iter().find(|e| e.kind == "merge_reverted").unwrap();
+ assert_eq!(
+ reverted.actor_name.as_deref(),
+ Some("Reverter"),
+ "撤销的人从审计里取,而不是借合并行的 merged_by"
+ );
+
+ // 被并走的那一头:方向相反,而且看得见自己是四月没的
+ let (events, _) = utopia_store::graph::entity_history(&pool, f.kb, f.absorbed, 50, 0).await?;
+ let away: Vec<_> = events.iter().filter(|e| e.kind == "merged_away").collect();
+ assert_eq!(away.len(), 1, "它并进了别人,只有这一次");
+ assert_eq!(away[0].at, t("2026-04-01T00:00:00Z"));
+ assert!(
+ !events.iter().any(|e| e.kind == "merged_in"),
+ "它没吸收过谁"
+ );
+
+ // 撤销过的那一头:并出去、又回来,两条都在
+ let (events, _) = utopia_store::graph::entity_history(&pool, f.kb, f.returned, 50, 0).await?;
+ let kinds: Vec<&str> = events.iter().map(|e| e.kind.as_str()).collect();
+ assert!(
+ kinds.contains(&"merged_away") && kinds.contains(&"merge_reverted"),
+ "并出去与撤销都要在:{kinds:?}"
+ );
+
+ sqlx::query("DELETE FROM knowledge_bases WHERE id = $1")
+ .bind(f.kb)
+ .execute(&pool)
+ .await?;
+ sqlx::query("DELETE FROM users WHERE id = $1")
+ .bind(f.reverter)
+ .execute(&pool)
+ .await?;
+ let gone = sqlx::query("DELETE FROM organizations WHERE id = $1")
+ .bind(f.org)
+ .execute(&pool)
+ .await?;
+ assert_eq!(gone.rows_affected(), 1, "一次性 org 没删掉");
+ Ok(())
+}
diff --git a/web/src/api.ts b/web/src/api.ts
index 01f00a11..2a4fad61 100644
--- a/web/src/api.ts
+++ b/web/src/api.ts
@@ -907,6 +907,11 @@ export interface EntityHistoryEvent {
| "corrected"
| "rejected"
| "merged"
+ /** 别人并进了它:事实搬到它名下 */
+ | "merged_in"
+ /** 它并进了别人:这个 id 从此不再单独存在 */
+ | "merged_away"
+ | "merge_reverted"
| "retyped"
| "retype_reverted";
direction: "out" | "in" | null;
diff --git a/web/src/i18n/en.ts b/web/src/i18n/en.ts
index 6d62d01c..fbc266e5 100644
--- a/web/src/i18n/en.ts
+++ b/web/src/i18n/en.ts
@@ -862,10 +862,17 @@ export const en = {
rejected: "Withdrawn",
/* 并入另一条断言:内容一字未少,不是撤回 */
merged: "Merged into an existing fact",
+ /* 实体合并。**两个方向分开说**——「吸收了谁」和「被谁吸收」在图上
+ 是两件事,回滚也是按方向做的 */
+ merged_in: "Another entity was merged into this one",
+ merged_away: "Merged into another entity",
+ merge_reverted: "Merge undone",
/* 改的是节点上的类,一条事实都没动 */
retyped: "Type changed",
retype_reverted: "Type change undone",
} as Record<string, string>,
+ /* 对方实体已经不在了(库被清理过):合并事件仍然要列出来 */
+ historyGoneEntity: "an entity that is gone",
historyEngine: "engine",
/* 有效区间的变化:修正后区间闭合到某个时点 */
historyClosedAt: (t: string) => `closed at ${t}`,
diff --git a/web/src/i18n/zh.ts b/web/src/i18n/zh.ts
index 71d789b1..14682265 100644
--- a/web/src/i18n/zh.ts
+++ b/web/src/i18n/zh.ts
@@ -778,9 +778,13 @@ export const zh: Strings = {
corrected: "区间被修正",
rejected: "已撤回",
merged: "并入了已有事实",
+ merged_in: "有实体并了进来",
+ merged_away: "并进了另一个实体",
+ merge_reverted: "合并已撤销",
retyped: "改了类",
retype_reverted: "改类被撤销",
},
+ historyGoneEntity: "一个已不存在的实体",
historyEngine: "引擎",
historyClosedAt: (t: string) => `闭合于 ${t}`,
historyFrom: (t: string) => `自 ${t} 起`,
diff --git a/web/src/pages/EntityHistory.tsx b/web/src/pages/EntityHistory.tsx
index f2914975..1685fc79 100644
--- a/web/src/pages/EntityHistory.tsx
+++ b/web/src/pages/EntityHistory.tsx
@@ -20,16 +20,28 @@ const KIND_ICON = {
rejected: Undo2,
// 并入不是撤回:内容一字未少地进了另一条断言
merged: Merge,
+ /* 实体合并:这条轴上最大的一次认识改变——从此它和另一个实体算同一个东西。
+ 两个方向共用一个图标,方向写在正文里("←" 是别人并进来) */
+ merged_in: Merge,
+ merged_away: Merge,
+ merge_reverted: Undo2,
// 改类不是事实变更:图上的节点换了个类,事实一条没动
retyped: Tag,
retype_reverted: Undo2,
} as const;
+/** 实体合并那三种:正文换成对方实体,而不是谓词 + 宾语 */
+const MERGE_KINDS = new Set(["merged_in", "merged_away", "merge_reverted"]);
+
const KIND_TONE: Record<string, string> = {
asserted: "text-ink-2",
corrected: "text-warn",
rejected: "text-danger",
merged: "text-ink-2",
+ merged_in: "text-ink-2",
+ merged_away: "text-ink-2",
+ // 撤销与「改类被撤销」同一档:做过、又收回了
+ merge_reverted: "text-warn",
retyped: "text-ink-2",
retype_reverted: "text-warn",
};
@@ -103,6 +115,15 @@ function EventRow({ e }: { e: EntityHistoryEvent }) {
</span>
<span className="text-ink">{e.to_type_label}</span>
</div>
+ ) : MERGE_KINDS.has(e.kind) ? (
+ /* 合并事件的正文只有对方。**箭头指方向**:并进来是「←」,
+ 并出去是「→」,与上面事实那一行的读法一致 */
+ <div className="mt-1 text-body text-ink-2 truncate">
+ <span className="text-small text-ink-2">
+ {e.kind === "merged_away" ? "→ " : "← "}
+ </span>
+ <span className="text-ink">{e.other_name ?? S.graph.historyGoneEntity}</span>
+ </div>
) : (
<div className="mt-1 text-body text-ink-2 truncate">
<span className="text-small text-ink-2">