World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-model
//! 审核队列 API:消解疑似重复对 + 低置信事实 + 合并日志/回滚。
use axum::extract::{Path, Query, State};
use axum::Json;
use serde::Deserialize;
use serde_json::json;
use utopia_core::models::Role;
use uuid::Uuid;
use super::graph_routes::require_kb;
use crate::auth::{AuthUser, SessionOrToken};
use crate::error::ApiResult;
use crate::state::AppState;
#[cfg(test)]
#[path = "review_routes_phrase_tests.rs"]
mod phrase_tests;
/// 一页多少条。**服务端的默认,不是上限**——前端可以要更少,多则被 clamp 挡住
const REVIEW_PAGE: i64 = 10;
/// 冲突双方的三元组快照:(旧主语, 旧宾语, 新主语, 新宾语, 谓词标签)。
type ConflictSnapshot = (String, Option<String>, String, Option<String>, String);
/// 事实快照(决策台账用):reject 后事实从图里消失,台账必须自包含展示文本。
/// 一律在动作执行前取。
pub(crate) async fn fact_snapshot(
state: &AppState,
kb_id: Uuid,
fact_id: Uuid,
) -> Option<serde_json::Value> {
// 宾语可能是实体或字面值;结构化字面值优先取 summary(与队列卡片同一显示口径)
let row: Option<(String, Option<String>, Option<String>, f32)> = sqlx::query_as(
"SELECT s.canonical_name, COALESCE(r.label, fact_surface_predicate(f.id)),
COALESCE(o.canonical_name, f.object_value ->> 'summary',
f.object_value #>> '{}'), f.confidence
FROM facts f
JOIN entities s ON s.id = f.subject_id
LEFT JOIN relation_types r ON r.id = f.predicate_id
LEFT JOIN entities o ON o.id = f.object_id
WHERE f.id = $1 AND f.kb_id = $2",
)
.bind(fact_id)
.bind(kb_id)
.fetch_optional(&state.pool)
.await
.ok()
.flatten();
row.map(|(s, p, o, c)| json!({ "subject": s, "predicate": p, "object": o, "confidence": c }))
}
#[derive(Deserialize)]
pub struct ReviewQuery {
/// 要看哪一档。缺省 duplicates
#[serde(default)]
pub queue: Option<String>,
/// 只对 duplicates 有意义:any(缺省)/ same(两边同类)/ conflict(两边类型冲突)
#[serde(default)]
pub types: Option<String>,
#[serde(default)]
pub limit: Option<i64>,
#[serde(default)]
pub offset: Option<i64>,
}
/// 审核队列:**计数与内容分开取**。
///
/// 从前一次把八个队列全端回来,每个固定 100 条,前端再客户端分页——于是左栏
/// 的徽标是截断后的数字(库里 164 条低置信事实,界面写 100),而第十一页之后
/// 的东西界面上不存在。
///
/// 现在:计数每次都回(八个 COUNT 一条查询,走的是与列表同一套 WHERE),
/// 内容只回当前那一档的一页。切换分档或翻页各发一次请求,代价是多几次往返,
/// 换来的是**数字不再骗人**,而且一个有十万条待办的库也翻得到底。
pub async fn list(
State(state): State<AppState>,
AuthUser(user): AuthUser,
Path(kb_id): Path<Uuid>,
Query(q): Query<ReviewQuery>,
) -> ApiResult<Json<serde_json::Value>> {
require_kb(&state, &user, kb_id, Role::Viewer).await?;
let counts = utopia_store::review::counts(&state.pool, kb_id).await?;
let queue = q.queue.as_deref().unwrap_or("duplicates");
// 上限挡住「limit=1000000 把库拖垮」,同时留出足够一页的余量
let limit = q.limit.unwrap_or(REVIEW_PAGE).clamp(1, 200);
let offset = q.offset.unwrap_or(0).max(0);
let items = match queue {
// 记忆抽出、等人点头的事实(0015)。排第一:它是人自己说的话
"pending" => json!(utopia_store::pending::list(&state.pool, kb_id, limit, offset).await?),
"duplicates" => json!(
utopia_store::resolution::list_reviews(
&state.pool,
kb_id,
utopia_store::resolution::TypeFilter::parse(q.types.as_deref())?,
limit,
offset,
)
.await?
),
"conflicts" => {
json!(utopia_store::temporal::list_conflicts(&state.pool, kb_id, limit, offset).await?)
}
"unconfirmed" => {
json!(utopia_store::graph::stale_facts(&state.pool, kb_id, limit, offset).await?)
}
"lowconf" => json!(
utopia_store::graph::low_confidence_facts(
&state.pool,
kb_id,
utopia_store::review::LOW_CONFIDENCE_BELOW,
limit,
offset,
)
.await?
),
"mappings" => {
json!(utopia_store::mappings::proposed(&state.pool, kb_id, limit, offset).await?)
}
// 对齐器两票不一致的签名与类别词(#725 对齐队列,0044 决定 3)
"alignment" => {
json!(utopia_store::alignment_queue::list(&state.pool, kb_id, limit, offset).await?)
}
// 勘误 agent 留给人的动作(0044 决定 7):闸门拦下的撤、改、加
"errata" => json!(utopia_store::errata::held(&state.pool, kb_id, limit, offset).await?),
"violations" => {
json!(
utopia_store::reasoning::open_violations(&state.pool, kb_id, limit, offset).await?
)
}
"defects" => {
json!(utopia_store::reasoning::open_defects(&state.pool, kb_id, limit, offset).await?)
}
"merges" => {
json!(utopia_store::resolution::list_merges(&state.pool, kb_id, limit, offset).await?)
}
// agent 的每一笔(0025):建议、自动裁决与人的回答,最新的在前
"agent" => json!(utopia_store::governance::list(&state.pool, kb_id, limit, offset).await?),
// 认不出的档名当成契约错误报出来,而不是悄悄回空——悄悄回空会让前端
// 拼错一个字母之后看到「这一档清空了」
other => {
return Err(utopia_core::AppError::invalid(
"unknown_queue",
format!("no review queue named {other}"),
)
.into())
}
};
Ok(Json(json!({
"counts": counts,
"queue": queue,
"items": items,
})))
}
#[derive(Deserialize)]
pub struct CloseFactBody {
pub valid_to: chrono::DateTime<chrono::Utc>,
/// year | month | day。**写多少位就是多少精度**(与图谱页的区间编辑同一约定);
/// 不给按日——只发日期的老客户端就是这个意思
#[serde(default)]
pub valid_to_precision: Option<String>,
}
/// 人给的世界轴精度。从前这里一律写 "day"(「人在界面上选的是一个日期」),于是
/// 「2023 年 6 月结束」只能编成 6 月 1 日——在无知的地方填一个确定的值,正是
/// `facts.valid_to_precision` 那条注释说的病
fn world_precision(p: Option<&str>) -> Result<&'static str, utopia_core::AppError> {
let Some(p) = p else { return Ok("day") };
utopia_store::graph::WORLD_PRECISIONS
.iter()
.copied()
.find(|w| *w == p)
.ok_or_else(|| {
utopia_core::AppError::invalid(
"bad_precision",
"A closing date's precision is year, month, day, hour, minute or second.",
)
})
}
/// 人工闭合一条事实的有效区间("这事在某时结束了")——走作废+改写,
/// 与自动闭合同一机制,账本可回放。
pub async fn close_fact(
State(state): State<AppState>,
AuthUser(user): AuthUser,
Path((kb_id, fact_id)): Path<(Uuid, Uuid)>,
Json(body): Json<CloseFactBody>,
) -> ApiResult<Json<serde_json::Value>> {
require_kb(&state, &user, kb_id, Role::Editor).await?;
// 归属与状态校验:本 KB 的、未作废、开放区间的事实才可闭合
let ok: Option<(Uuid,)> = sqlx::query_as(
"SELECT id FROM facts
WHERE id = $1 AND kb_id = $2 AND invalidated_at IS NULL AND valid_to IS NULL",
)
.bind(fact_id)
.bind(kb_id)
.fetch_optional(&state.pool)
.await
.map_err(utopia_core::AppError::Db)?;
if ok.is_none() {
return Err(utopia_core::AppError::NotFound.into());
}
let precision = world_precision(body.valid_to_precision.as_deref())?;
let snap = fact_snapshot(&state, kb_id, fact_id).await;
utopia_store::temporal::close_superseded(&state.pool, fact_id, body.valid_to, precision)
.await?;
if let Some(mut d) = snap {
d["valid_to"] = json!(body.valid_to.to_rfc3339());
d["valid_to_precision"] = json!(precision);
let _ = utopia_store::audit::record(
&state.pool,
Some(kb_id),
user.id,
"fact.close",
"fact",
Some(fact_id),
d,
)
.await;
}
state.emit_review(kb_id);
Ok(Json(json!({ "ok": true })))
}
#[derive(Deserialize)]
pub struct ConflictBody {
/// close | keep | reject_new
pub action: String,
/// close 且新事实无起点时必填
#[serde(default)]
pub close_at: Option<chrono::DateTime<chrono::Utc>>,
/// `close_at` 的精度(year | month | day),不给按日
#[serde(default)]
pub close_at_precision: Option<String>,
}
/// 时态冲突裁决(S3:自动闭合拿不准的那些)。
pub async fn resolve_conflict(
State(state): State<AppState>,
AuthUser(user): AuthUser,
Path((kb_id, conflict_id)): Path<(Uuid, Uuid)>,
Json(body): Json<ConflictBody>,
) -> ApiResult<Json<serde_json::Value>> {
require_kb(&state, &user, kb_id, Role::Editor).await?;
// 快照双方三元组:裁决会作废/改写事实,先抄后动
let snap: Option<ConflictSnapshot> = sqlx::query_as(
"SELECT os.canonical_name, oo.canonical_name, ns.canonical_name, no_.canonical_name,
r.label
FROM fact_conflicts c
JOIN facts fo ON fo.id = c.old_fact_id
JOIN facts fn_ ON fn_.id = c.new_fact_id
JOIN entities os ON os.id = fo.subject_id
LEFT JOIN entities oo ON oo.id = fo.object_id
JOIN entities ns ON ns.id = fn_.subject_id
LEFT JOIN entities no_ ON no_.id = fn_.object_id
JOIN relation_types r ON r.id = fo.predicate_id
WHERE c.id = $1 AND c.kb_id = $2",
)
.bind(conflict_id)
.bind(kb_id)
.fetch_optional(&state.pool)
.await
.ok()
.flatten();
let close_precision = world_precision(body.close_at_precision.as_deref())?;
utopia_store::temporal::resolve_conflict(
&state.pool,
kb_id,
conflict_id,
&body.action,
body.close_at,
close_precision,
)
.await?;
if let Some((os, oo, ns, no, pred)) = snap {
let action = match body.action.as_str() {
"close" => "conflict.close_old",
"keep" => "conflict.keep_both",
_ => "conflict.reject_new",
};
let _ = utopia_store::audit::record(
&state.pool,
Some(kb_id),
user.id,
action,
"conflict",
Some(conflict_id),
json!({
"predicate": pred,
"old_subject": os, "old_object": oo,
"new_subject": ns, "new_object": no,
"close_at": body.close_at.map(|t| t.to_rfc3339()),
"close_at_precision": body.close_at.map(|_| close_precision),
}),
)
.await;
}
state.emit_review(kb_id);
Ok(Json(json!({ "ok": true })))
}
#[derive(Deserialize)]
pub struct DecideBody {
/// merge | keep
pub action: String,
/// 人拍板时写的那一句(0026):什么让你这么定。可空
#[serde(default)]
pub rationale: Option<String>,
}
pub async fn decide(
State(state): State<AppState>,
AuthUser(user): AuthUser,
Path((kb_id, review_id)): Path<(Uuid, Uuid)>,
Json(body): Json<DecideBody>,
) -> ApiResult<Json<serde_json::Value>> {
require_kb(&state, &user, kb_id, Role::Editor).await?;
let snap: Option<(String, String, f32)> = sqlx::query_as(
"SELECT a.canonical_name, b.canonical_name, rr.score
FROM resolution_reviews rr
JOIN entities a ON a.id = rr.left_id
JOIN entities b ON b.id = rr.right_id
WHERE rr.id = $1 AND rr.kb_id = $2",
)
.bind(review_id)
.bind(kb_id)
.fetch_optional(&state.pool)
.await
.ok()
.flatten();
utopia_store::resolution::decide_review(
&state.pool,
kb_id,
review_id,
&body.action,
user.id,
body.rationale.as_deref(),
)
.await?;
if let Some((l, r, score)) = snap {
// 理由也进台账:先例是从这里读的,不是从 resolution_reviews
let _ = utopia_store::audit::record(
&state.pool,
Some(kb_id),
user.id,
if body.action == "merge" {
"review.merge"
} else {
"review.keep"
},
"review",
Some(review_id),
json!({ "left": l, "right": r, "score": score, "why": body.rationale }),
)
.await;
}
crate::governance::after_human_decision(
&state,
kb_id,
&[review_id],
Some(&body.action),
user.id,
)
.await;
state.emit_review(kb_id);
Ok(Json(json!({ "ok": true })))
}
#[derive(Deserialize)]
pub struct AgentAnswerBody {
/// merge | keep 答一条建议(与建议相同是接受,不同是改判);
/// revert 撤回一条自动合并;merge 也能推翻一条自动分开
pub action: String,
/// 什么让你这么答(0026)。改判 agent 的时候尤其值得写:那一句就是下次的先例
#[serde(default)]
pub rationale: Option<String>,
}
/// 人回答 agent 的一笔(0025)。回答走的是人的裁决路径:decided_by 是这个人,
/// 台账记的是这个人——它就此成为下一轮的先例
pub async fn agent_answer(
State(state): State<AppState>,
AuthUser(user): AuthUser,
Path((kb_id, decision_id)): Path<(Uuid, Uuid)>,
Json(body): Json<AgentAnswerBody>,
) -> ApiResult<Json<serde_json::Value>> {
require_kb(&state, &user, kb_id, Role::Editor).await?;
let d = utopia_store::governance::get(&state.pool, kb_id, decision_id).await?;
let (l, r) = (
d.left.clone().unwrap_or_default(),
d.right.clone().unwrap_or_default(),
);
match (d.status.as_str(), body.action.as_str()) {
("proposed", act @ ("merge" | "keep")) => {
utopia_store::resolution::decide_review(
&state.pool,
kb_id,
d.target_id,
act,
user.id,
body.rationale.as_deref(),
)
.await?;
let status = if act == d.action {
"accepted"
} else {
"overridden"
};
utopia_store::governance::settle(&state.pool, kb_id, decision_id, status, user.id)
.await?;
let _ = utopia_store::audit::record(
&state.pool,
Some(kb_id),
user.id,
if act == "merge" { "review.merge" } else { "review.keep" },
"review",
Some(d.target_id),
json!({ "left": l, "right": r, "agent_decision": decision_id, "agent_action": d.action,
"why": body.rationale }),
)
.await;
}
("applied", "revert") => {
let merge_id = d.merge_id.ok_or_else(|| {
utopia_core::AppError::invalid(
"not_a_merge",
"Only an applied merge can be reverted; a pair kept apart can be merged instead.",
)
})?;
utopia_store::resolution::revert_merge(&state.pool, kb_id, merge_id).await?;
utopia_store::governance::settle(&state.pool, kb_id, decision_id, "reverted", user.id)
.await?;
let _ = utopia_store::audit::record(
&state.pool,
Some(kb_id),
user.id,
"merge.revert",
"merge",
Some(merge_id),
json!({ "source": l, "target": r, "agent_decision": decision_id }),
)
.await;
// 撤回 agent 的合并到了两次:保险丝
crate::governance::fuse(&state, kb_id).await;
}
("applied", "merge") if d.action == "keep" => {
let (left_id, right_id): (Uuid, Uuid) = sqlx::query_as(
"SELECT left_id, right_id FROM resolution_reviews WHERE id = $1 AND kb_id = $2",
)
.bind(d.target_id)
.bind(kb_id)
.fetch_optional(&state.pool)
.await
.map_err(utopia_core::AppError::from)?
.ok_or(utopia_core::AppError::NotFound)?;
let (target, source) =
utopia_store::resolution::merge_direction(&state.pool, left_id, right_id).await?;
let merge_id = utopia_store::resolution::merge_entities(
&state.pool,
kb_id,
source,
target,
Some(user.id),
"overrode agent keep",
)
.await?;
utopia_store::governance::settle(
&state.pool,
kb_id,
decision_id,
"overridden",
user.id,
)
.await?;
let _ = utopia_store::audit::record(
&state.pool,
Some(kb_id),
user.id,
"merge.manual",
"merge",
Some(merge_id),
json!({ "source": l, "target": r, "agent_decision": decision_id }),
)
.await;
}
(status, action) => {
return Err(utopia_core::AppError::invalid(
"agent_answer",
format!("cannot {action} an agent decision that is {status}"),
)
.into())
}
}
crate::governance::after_human_decision(&state, kb_id, &[d.target_id], None, user.id).await;
state.emit_review(kb_id);
Ok(Json(json!({ "ok": true })))
}
#[derive(Deserialize)]
pub struct BatchBody {
pub ids: Vec<Uuid>,
/// merge | keep,整批一个动作
pub action: String,
/// 整批一句理由(0026):一批同一个动作,多半也是同一个依据
#[serde(default)]
pub rationale: Option<String>,
}
/// 一批 id 最多多少条:够一屏「全选」,又挡住一次请求把库锁上几分钟
const BATCH_MAX: usize = 500;
/// 批量裁决(#428):与单条 `decide` 同一条路——每条各自合并/分开、各自记
/// 台账,回来的是逐条结果。一次只推一遍前端刷新。
pub async fn batch(
State(state): State<AppState>,
AuthUser(user): AuthUser,
Path(kb_id): Path<Uuid>,
Json(body): Json<BatchBody>,
) -> ApiResult<Json<serde_json::Value>> {
require_kb(&state, &user, kb_id, Role::Editor).await?;
if body.ids.is_empty() || body.ids.len() > BATCH_MAX {
return Err(utopia_core::AppError::invalid(
"batch_size",
format!("between 1 and {BATCH_MAX} ids per batch"),
)
.into());
}
// 台账要的名字与分数在裁决前取——合并之后 source 一侧的名字已经不在原处了
let snaps: Vec<(Uuid, String, String, f32)> = sqlx::query_as(
"SELECT rr.id, a.canonical_name, b.canonical_name, rr.score
FROM resolution_reviews rr
JOIN entities a ON a.id = rr.left_id
JOIN entities b ON b.id = rr.right_id
WHERE rr.kb_id = $1 AND rr.id = ANY($2)",
)
.bind(kb_id)
.bind(&body.ids)
.fetch_all(&state.pool)
.await
.unwrap_or_default();
let outcomes = utopia_store::resolution::decide_reviews(
&state.pool,
kb_id,
&body.ids,
&body.action,
user.id,
body.rationale.as_deref(),
)
.await?;
let action = if body.action == "merge" {
"review.merge"
} else {
"review.keep"
};
for o in outcomes.iter().filter(|o| o.error.is_none()) {
if let Some((_, l, r, score)) = snaps.iter().find(|s| s.0 == o.id) {
let _ = utopia_store::audit::record(
&state.pool,
Some(kb_id),
user.id,
action,
"review",
Some(o.id),
json!({ "left": l, "right": r, "score": score, "batch": body.ids.len(),
"why": body.rationale }),
)
.await;
}
}
let decided_ids: Vec<Uuid> = outcomes
.iter()
.filter(|o| o.error.is_none())
.map(|o| o.id)
.collect();
crate::governance::after_human_decision(
&state,
kb_id,
&decided_ids,
Some(&body.action),
user.id,
)
.await;
state.emit_review(kb_id);
let decided = decided_ids.len();
Ok(Json(json!({ "decided": decided, "outcomes": outcomes })))
}
pub async fn confirm_fact(
State(state): State<AppState>,
AuthUser(user): AuthUser,
Path((kb_id, fact_id)): Path<(Uuid, Uuid)>,
) -> ApiResult<Json<serde_json::Value>> {
require_kb(&state, &user, kb_id, Role::Editor).await?;
let snap = fact_snapshot(&state, kb_id, fact_id).await;
utopia_store::graph::confirm_fact(&state.pool, kb_id, fact_id).await?;
if let Some(d) = snap {
let _ = utopia_store::audit::record(
&state.pool,
Some(kb_id),
user.id,
"fact.confirm",
"fact",
Some(fact_id),
d,
)
.await;
}
state.emit_review(kb_id);
Ok(Json(json!({ "ok": true })))
}
pub async fn reject_fact(
State(state): State<AppState>,
AuthUser(user): AuthUser,
Path((kb_id, fact_id)): Path<(Uuid, Uuid)>,
) -> ApiResult<Json<serde_json::Value>> {
require_kb(&state, &user, kb_id, Role::Editor).await?;
let snap = fact_snapshot(&state, kb_id, fact_id).await;
utopia_store::graph::reject_fact(&state.pool, kb_id, fact_id).await?;
if let Some(d) = snap {
let _ = utopia_store::audit::record(
&state.pool,
Some(kb_id),
user.id,
"fact.reject",
"fact",
Some(fact_id),
d,
)
.await;
}
state.emit_review(kb_id);
Ok(Json(json!({ "ok": true })))
}
pub async fn revert_merge(
State(state): State<AppState>,
AuthUser(user): AuthUser,
Path((kb_id, merge_id)): Path<(Uuid, Uuid)>,
) -> ApiResult<Json<serde_json::Value>> {
require_kb(&state, &user, kb_id, Role::Editor).await?;
let snap: Option<(String, String)> = sqlx::query_as(
"SELECT s.canonical_name, t.canonical_name
FROM entity_merges m
JOIN entities s ON s.id = m.source_id
JOIN entities t ON t.id = m.target_id
WHERE m.id = $1 AND m.kb_id = $2",
)
.bind(merge_id)
.bind(kb_id)
.fetch_optional(&state.pool)
.await
.ok()
.flatten();
utopia_store::resolution::revert_merge(&state.pool, kb_id, merge_id).await?;
if let Some((s, t)) = snap {
let _ = utopia_store::audit::record(
&state.pool,
Some(kb_id),
user.id,
"merge.revert",
"merge",
Some(merge_id),
json!({ "source": s, "target": t }),
)
.await;
}
// 撤的是 agent 自己裁的合并:那一行记成 reverted,并看保险丝(0025)
crate::governance::after_revert(&state, kb_id, merge_id, user.id).await;
state.emit_review(kb_id);
Ok(Json(json!({ "ok": true })))
}
#[derive(Deserialize)]
pub struct ManualMergeBody {
pub source: Uuid,
pub target: Uuid,
/// 什么让你把它们并起来(0026)。可空
#[serde(default)]
pub rationale: Option<String>,
}
/// 手动合并(实体面板"Merge into…"入口)。
pub async fn manual_merge(
State(state): State<AppState>,
AuthUser(user): AuthUser,
Path(kb_id): Path<Uuid>,
Json(body): Json<ManualMergeBody>,
) -> ApiResult<Json<serde_json::Value>> {
require_kb(&state, &user, kb_id, Role::Editor).await?;
let snap: Option<(String,)> = sqlx::query_as(
"SELECT s.canonical_name || ' → ' || t.canonical_name
FROM entities s, entities t WHERE s.id = $1 AND t.id = $2",
)
.bind(body.source)
.bind(body.target)
.fetch_optional(&state.pool)
.await
.ok()
.flatten();
let why = body
.rationale
.as_deref()
.map(str::trim)
.filter(|s| !s.is_empty());
let merge_id = utopia_store::resolution::merge_entities(
&state.pool,
kb_id,
body.source,
body.target,
Some(user.id),
why.unwrap_or("manual merge"),
)
.await?;
if let Some((pair,)) = snap {
let (s, t) = pair.split_once(" → ").unwrap_or((pair.as_str(), ""));
let _ = utopia_store::audit::record(
&state.pool,
Some(kb_id),
user.id,
"merge.manual",
"merge",
Some(merge_id),
json!({ "source": s, "target": t, "why": why }),
)
.await;
}
state.emit_review(kb_id);
Ok(Json(json!({ "merge_id": merge_id })))
}
#[derive(Deserialize)]
pub struct HistoryQuery {
#[serde(default)]
pub page: i64,
#[serde(default = "default_history_per")]
pub per: i64,
}
fn default_history_per() -> i64 {
20
}
/// 决策台账:review 域的审计事件,服务端分页。
pub async fn history(
State(state): State<AppState>,
AuthUser(user): AuthUser,
Path(kb_id): Path<Uuid>,
Query(q): Query<HistoryQuery>,
) -> ApiResult<Json<serde_json::Value>> {
require_kb(&state, &user, kb_id, Role::Viewer).await?;
let per = q.per.clamp(1, 100);
let page = q.page.max(0);
let (events, total) =
utopia_store::audit::review_history(&state.pool, kb_id, per, page * per).await?;
Ok(Json(json!({ "events": events, "total": total })))
}
/// 审核台的总览(#377):等着办的、办过的、库的成色。三段聚合,一次返回。
pub async fn summary(
State(state): State<AppState>,
AuthUser(user): AuthUser,
Path(kb_id): Path<Uuid>,
) -> ApiResult<Json<utopia_core::models::ReviewSummary>> {
require_kb(&state, &user, kb_id, Role::Viewer).await?;
Ok(Json(
utopia_store::review_summary::summary(&state.pool, kb_id).await?,
))
}
#[derive(Deserialize)]
pub struct DecideMappingReq {
/// confirmed | rejected
pub status: String,
}
/// 对一条语义层映射表态(0011)。
///
/// **改状态不删行**:确认发生过、拒绝也发生过。而拒绝留痕当下就有用——
/// 下一轮探索会再次算出被拒绝过的那条,`propose` 的 `WHERE status = 'proposed'`
/// 据此不把它刷回待看。
pub async fn decide_mapping(
State(state): State<AppState>,
AuthUser(user): AuthUser,
Path((kb_id, mapping_id)): Path<(Uuid, Uuid)>,
Json(req): Json<DecideMappingReq>,
) -> ApiResult<Json<serde_json::Value>> {
require_kb(&state, &user, kb_id, Role::Editor).await?;
if !matches!(req.status.as_str(), "confirmed" | "rejected") {
return Err(utopia_core::AppError::invalid(
"bad_status",
"status must be confirmed or rejected",
)
.into());
}
utopia_store::mappings::decide(&state.pool, kb_id, mapping_id, &req.status, user.id).await?;
let _ = utopia_store::audit::record(
&state.pool,
Some(kb_id),
user.id,
"mapping.decided",
"concept_mapping",
Some(mapping_id),
json!({ "status": req.status }),
)
.await;
state.emit_review(kb_id);
Ok(Json(json!({ "ok": true })))
}
#[derive(Deserialize)]
pub struct DecideViolationReq {
/// fact_retracted | fact_closed | axiom_relaxed | accepted
pub resolution: String,
/// `fact_closed` 必填:旧断言在哪一天结束
#[serde(default)]
pub close_at: Option<chrono::DateTime<chrono::Utc>>,
/// `close_at` 的精度(year | month | day),不给按日
#[serde(default)]
pub close_at_precision: Option<String>,
/// `fact_retracted` 时撤哪条:双事实与环上的违规必填,单事实的可省(#202)
#[serde(default)]
pub fact_id: Option<Uuid>,
}
/// 人裁决一处公理违规。
///
/// **三个出路而不是两个。** `axiom_relaxed` 是这一档独有的:矛盾可能出在定义
/// 而不是数据——用户导的本体把某个属性声明成反对称,而他自己的语料里那关系
/// 其实双向。这时该改的是本体,不是二十条事实。
///
/// **「数据错了」真的撤事实**(#202):此前只记决定,事实照样活在图里,而队列又
/// 不再提它。撤哪条由请求指名(`fact_id`),单事实的种类可省;撤完重算一遍检查,
/// 那条事实牵连的其它违规一并清掉。改公理仍然走本体页——那是另一个页面的事。
pub async fn decide_violation(
State(state): State<AppState>,
AuthUser(user): AuthUser,
Path((kb_id, violation_id)): Path<(Uuid, Uuid)>,
Json(req): Json<DecideViolationReq>,
) -> ApiResult<Json<serde_json::Value>> {
require_kb(&state, &user, kb_id, Role::Editor).await?;
if !matches!(
req.resolution.as_str(),
"fact_retracted" | "fact_closed" | "axiom_relaxed" | "accepted"
) {
return Err(utopia_core::AppError::invalid(
"bad_resolution",
"resolution 只能是 fact_retracted、fact_closed、axiom_relaxed 或 accepted",
)
.into());
}
let row: Option<(String, Uuid, Uuid, Vec<Uuid>)> = sqlx::query_as(
"SELECT kind, left_fact, right_fact, path FROM axiom_violations
WHERE id = $1 AND kb_id = $2 AND status = 'open'",
)
.bind(violation_id)
.bind(kb_id)
.fetch_optional(&state.pool)
.await
.map_err(utopia_core::AppError::Db)?;
let Some((kind, left, right, path)) = row else {
return Err(utopia_core::AppError::NotFound.into());
};
let repaired = kind == "derived_contradiction";
// 撤事实的那条路自己会把违规标成 resolved;其余出路在下面统一记
let mut decided = false;
match (repaired, req.resolution.as_str()) {
(_, "fact_retracted") => {
let Some(target) =
utopia_store::reasoning::pick_retraction(left, right, &path, req.fact_id)
else {
return Err(utopia_core::AppError::invalid(
"fact_required",
"这处违规涉及多条事实,要说撤哪一条,且只能是它列出的那几条",
)
.into());
};
let snap = fact_snapshot(&state, kb_id, target).await;
utopia_store::reasoning::retract_from_violation(
&state.pool,
kb_id,
violation_id,
Some(target),
user.id,
)
.await?;
decided = true;
if let Some(d) = snap {
let _ = utopia_store::audit::record(
&state.pool,
Some(kb_id),
user.id,
"fact.reject",
"fact",
Some(target),
d,
)
.await;
}
}
(true, "fact_closed") => {
let Some(at) = req.close_at else {
return Err(utopia_core::AppError::invalid(
"close_at_required",
"fact_closed 要给出结束日期",
)
.into());
};
let open: Option<(Uuid,)> = sqlx::query_as(
"SELECT id FROM facts
WHERE id = $1 AND invalidated_at IS NULL AND valid_to IS NULL",
)
.bind(left)
.fetch_optional(&state.pool)
.await
.map_err(utopia_core::AppError::Db)?;
if open.is_none() {
return Err(utopia_core::AppError::invalid(
"not_open",
"这条断言已有结束日期,或已被撤",
)
.into());
}
let precision = world_precision(req.close_at_precision.as_deref())?;
let snap = fact_snapshot(&state, kb_id, left).await;
utopia_store::temporal::close_superseded(&state.pool, left, at, precision).await?;
if let Some(mut d) = snap {
d["valid_to"] = json!(at.to_rfc3339());
d["valid_to_precision"] = json!(precision);
let _ = utopia_store::audit::record(
&state.pool,
Some(kb_id),
user.id,
"fact.close",
"fact",
Some(left),
d,
)
.await;
}
}
(false, "fact_closed") => {
return Err(utopia_core::AppError::invalid(
"bad_resolution",
"fact_closed 只用于 derived_contradiction",
)
.into());
}
_ => {}
}
if !decided {
utopia_store::reasoning::decide(&state.pool, kb_id, violation_id, &req.resolution, user.id)
.await?;
}
// 路清了就让派生落地,人不必再去点一次「推一遍」。撤与闭合把断言挪开了,
// 认可则在 materialize 里放行
if repaired {
utopia_store::reasoning::materialize(&state.pool, kb_id).await?;
}
// 撤掉的事实可能还挂在别的违规里:重算一遍,那些行随之清掉,队列不留死账
if req.resolution == "fact_retracted" {
utopia_store::reasoning::run(&state.pool, kb_id).await?;
}
let _ = utopia_store::audit::record(
&state.pool,
Some(kb_id),
user.id,
"violation.decided",
"axiom_violation",
Some(violation_id),
json!({ "resolution": req.resolution }),
)
.await;
state.emit_review(kb_id);
Ok(Json(json!({ "ok": true })))
}
/// 手动跑一遍一致性检查。
///
/// **同步跑而不是排任务**:这是纯计算,没有模型调用也没有网络——一个几万条
/// 事实的库跑下来是毫秒级。排进任务队列只会让人点完按钮盯着一个"排队中",
/// 而队列真正要解决的是"这活儿要跑几分钟"。
///
/// `predicates_with_axioms` 一并回给前端:**零和零的含义不同**。没有公理时
/// 结论是"没有判据",界面该说"先导一份带公理的本体",而不是"未发现矛盾"。
pub async fn run_consistency_check(
State(state): State<AppState>,
AuthUser(user): AuthUser,
Path(kb_id): Path<Uuid>,
) -> ApiResult<Json<serde_json::Value>> {
require_kb(&state, &user, kb_id, Role::Editor).await?;
let report = utopia_store::reasoning::run(&state.pool, kb_id).await?;
// 本体自洽性一并算。两者判据同源(都是本体声明的公理),分两个按钮
// 只会让人点两次
let onto = utopia_store::reasoning::check_ontology(&state.pool, kb_id).await?;
let _ = utopia_store::audit::record(
&state.pool,
Some(kb_id),
user.id,
"consistency.checked",
"knowledge_base",
Some(kb_id),
json!({
"edges": report.edges,
"predicates_with_axioms": report.predicates_with_axioms,
"found": report.found,
"inserted": report.inserted,
"cleared": report.cleared,
"cycles_capped": report.cycles_capped,
"defects_found": onto.found,
}),
)
.await;
state.emit_review(kb_id);
Ok(Json(json!({
"edges": report.edges,
"predicates_with_axioms": report.predicates_with_axioms,
"found": report.found,
"inserted": report.inserted,
"cleared": report.cleared,
// 环没搜完的谓词数(#642):不为零时环只报了一部分,界面该说「这个谓词的环
// 太多,先看公理」,而不是让人以为那就是全部
"cycles_capped": report.cycles_capped,
// 本体自己那一档单独回。**不加进 found**:两个数不是一类东西,
// 加起来之后「3 处矛盾」既可能是三条事实抵触,也可能是本体自己写反了三处
"classes": onto.classes,
"defects_found": onto.found,
"defects_new": onto.inserted,
})))
}
#[derive(Deserialize)]
pub struct DecideDefectReq {
/// fixed | accepted
pub resolution: String,
}
/// 人对一处本体缺陷表态。
///
/// **两个出路而不是三个**:本体缺陷压根没看数据,所以没有「数据错了」这一条。
pub async fn decide_defect(
State(state): State<AppState>,
AuthUser(user): AuthUser,
Path((kb_id, defect_id)): Path<(Uuid, Uuid)>,
Json(req): Json<DecideDefectReq>,
) -> ApiResult<Json<serde_json::Value>> {
require_kb(&state, &user, kb_id, Role::Editor).await?;
if !matches!(req.resolution.as_str(), "fixed" | "accepted") {
return Err(utopia_core::AppError::invalid(
"bad_resolution",
"resolution 只能是 fixed 或 accepted",
)
.into());
}
utopia_store::reasoning::decide_defect(&state.pool, kb_id, defect_id, &req.resolution, user.id)
.await?;
let _ = utopia_store::audit::record(
&state.pool,
Some(kb_id),
user.id,
"defect.decided",
"ontology_defect",
Some(defect_id),
json!({ "resolution": req.resolution }),
)
.await;
state.emit_review(kb_id);
Ok(Json(json!({ "ok": true })))
}
/// 跑一遍推理(R1)。
///
/// **受 `materialize_inferences` 开关约束。** 默认关,因为这一步往图里加东西,
/// 而 0001 判据 2 说「本体是引导不是执法」——声明可能是错的,不该在用户没表态时
/// 就按它改图。开关关着时不静默跳过:回一个明确的错,界面才说得出为什么没动。
///
/// 同步跑,与一致性检查同一个理由:纯计算,没有模型调用也没有网络。
#[derive(Deserialize)]
pub struct PendingQuery {
pub chunk_id: Uuid,
}
/// 一句记忆抽出的全部待确认项——对话里那张确认卡按这个取(0015)。
/// Viewer 也能看:看得见提议、看不见按钮,与 Review 页同一口径
pub async fn pending_for_chunk(
State(state): State<AppState>,
AuthUser(user): AuthUser,
Path(kb_id): Path<Uuid>,
Query(q): Query<PendingQuery>,
) -> ApiResult<Json<serde_json::Value>> {
require_kb(&state, &user, kb_id, Role::Viewer).await?;
let items = utopia_store::pending::for_chunk(&state.pool, kb_id, q.chunk_id).await?;
Ok(Json(json!({ "items": items })))
}
#[derive(Deserialize)]
pub struct DecidePendingBody {
/// `confirm` 进账本;`reject` 记进 `rejected_facts`,下一轮重抽不再提
pub action: String,
}
/// 人对一条待确认事实点头或摇头。
///
/// 两个动作都进决策台账,快照自包含——行删了之后台账上还读得出当时确认的是什么。
/// 确认走与抽取相同的那条路(事实 + 证据 + 时态对账),所以一句「Mira 交给 Devin 了」
/// 点头之后,Mira 那条会像从文档里抽出来时一样被闭合
pub async fn decide_pending(
State(state): State<AppState>,
AuthUser(user): AuthUser,
Path((kb_id, pending_id)): Path<(Uuid, Uuid)>,
Json(body): Json<DecidePendingBody>,
) -> ApiResult<Json<serde_json::Value>> {
require_kb(&state, &user, kb_id, Role::Editor).await?;
match body.action.as_str() {
"confirm" => {
let done = utopia_store::pending::confirm(&state.pool, kb_id, pending_id).await?;
let _ = utopia_store::audit::record(
&state.pool,
Some(kb_id),
user.id,
"fact.nod_confirmed",
"fact",
Some(done.fact_id),
done.snapshot,
)
.await;
// 点头落下的开放陈述带着时间词:按文档重排一次时间解析(0045),
// 幂等,同一篇排着就不重复
let _ = utopia_store::jobs::enqueue_unless_queued(
&state.pool,
"resolve_time",
json!({ "document_id": done.document_id }),
)
.await;
state.emit_pending(kb_id);
state.emit_review(kb_id);
state.emit_graph(kb_id);
Ok(Json(json!({
"ok": true,
"fact_id": done.fact_id,
"created": done.created,
"conflicts": done.conflicts,
})))
}
"reject" => {
let snap = utopia_store::pending::reject(&state.pool, kb_id, pending_id, Some(user.id))
.await?;
let _ = utopia_store::audit::record(
&state.pool,
Some(kb_id),
user.id,
"fact.nod_rejected",
"pending_fact",
Some(pending_id),
snap,
)
.await;
state.emit_pending(kb_id);
state.emit_review(kb_id);
Ok(Json(json!({ "ok": true })))
}
other => Err(utopia_core::AppError::invalid(
"unknown_action",
format!("action must be confirm or reject, got {other}"),
)
.into()),
}
}
pub async fn run_inference(
State(state): State<AppState>,
AuthUser(user): AuthUser,
Path(kb_id): Path<Uuid>,
) -> ApiResult<Json<serde_json::Value>> {
require_kb(&state, &user, kb_id, Role::Editor).await?;
let on: bool =
sqlx::query_scalar("SELECT materialize_inferences FROM knowledge_bases WHERE id = $1")
.bind(kb_id)
.fetch_one(&state.pool)
.await
.map_err(utopia_core::AppError::Db)?;
if !on {
return Err(utopia_core::AppError::invalid(
"inference_off",
"materialized inference is off for this knowledge base",
)
.into());
}
let report = utopia_store::reasoning::materialize(&state.pool, kb_id).await?;
let _ = utopia_store::audit::record(
&state.pool,
Some(kb_id),
user.id,
"inference.materialized",
"knowledge_base",
Some(kb_id),
json!({
"rules": report.rules,
"edges": report.edges,
"derived": report.derived,
"inserted": report.inserted,
"invalidated": report.invalidated,
"capped": report.capped,
}),
)
.await;
state.emit_graph(kb_id);
Ok(Json(json!({
"rules": report.rules,
"edges": report.edges,
"derived": report.derived,
"inserted": report.inserted,
"invalidated": report.invalidated,
"capped": report.capped,
})))
}
#[derive(Deserialize)]
pub struct DecideAlignmentPhraseReq {
/// 属性的键;空 = 没有属性对得上,陈述留在开放图谱
#[serde(default)]
pub property: Option<String>,
/// forward | reverse;给了属性就得给
#[serde(default)]
pub direction: Option<String>,
/// start | end | none:状态属性下,带着某一刻的陈述那一刻标的是开始、结束,还是都不是
/// (#966)。不给 = 未知:这样的陈述不算类型化行,签名留在队列里等人补
#[serde(default)]
pub marks: Option<String>,
}
/// 人定一条短语签名绑到哪个属性(#725 对齐队列)。写成人的判定,代理此后不再改它;
/// 类型化图谱立刻按新绑定重算。
#[derive(Deserialize)]
pub struct DecideAlignmentRuleReq {
pub approve: bool,
}
/// 人批或驳一条蕴含规则(0044 决定 3 第五片)。与短语判定同一套:决定和它的后续工作
/// 一次提交,答 202 和 job id。批准且要读数的先排 `read_phrases`(填缓存后自己排物化),
/// 否则直接排物化——驳回也要重算,隐含行得退掉
pub async fn decide_alignment_rule(
State(state): State<AppState>,
AuthUser(user): AuthUser,
Path((kb_id, rule_id)): Path<(Uuid, Uuid)>,
Json(req): Json<DecideAlignmentRuleReq>,
) -> ApiResult<(axum::http::StatusCode, Json<serde_json::Value>)> {
require_kb(&state, &user, kb_id, Role::Editor).await?;
let rule = utopia_store::implication_rules::get(&state.pool, kb_id, rule_id)
.await?
.ok_or(utopia_core::AppError::NotFound)?;
let votes = json!({ "person": if req.approve { "approve" } else { "reject" } });
let job_id = utopia_store::implication_rules::decide_with_delivery(
&state.pool,
kb_id,
rule_id,
req.approve,
&votes,
)
.await?
.ok_or(utopia_core::AppError::NotFound)?;
let _ = utopia_store::audit::record(
&state.pool,
Some(kb_id),
user.id,
"alignment.rule_decided",
"implication_rule",
Some(rule_id),
json!({ "trigger": rule.trigger, "phrase": rule.phrase, "reading": rule.reading,
"approve": req.approve, "job_id": job_id }),
)
.await;
state.emit_review(kb_id);
Ok((
axum::http::StatusCode::ACCEPTED,
Json(json!({ "ok": true, "job_id": job_id, "status": "accepted" })),
))
}
pub async fn decide_alignment_phrase(
State(state): State<AppState>,
AuthUser(user): AuthUser,
Path((kb_id, binding_id)): Path<(Uuid, Uuid)>,
Json(req): Json<DecideAlignmentPhraseReq>,
) -> ApiResult<(axum::http::StatusCode, Json<serde_json::Value>)> {
require_kb(&state, &user, kb_id, Role::Editor).await?;
let sig = utopia_store::phrase_bindings::signature_of(&state.pool, kb_id, binding_id)
.await?
.ok_or(utopia_core::AppError::NotFound)?;
let property = match req
.property
.as_deref()
.map(str::trim)
.filter(|s| !s.is_empty())
{
None => None,
Some(key) => {
let found = utopia_store::ontology::relation_type_views(&state.pool, kb_id)
.await?
.into_iter()
.find(|p| p.key == key)
.map(|p| (p.id, p.temporal == "state"))
.ok_or_else(|| {
utopia_core::AppError::invalid("unknown_property", "no property with that key")
})?;
Some(found)
}
};
let marks = match (
property,
req.marks
.as_deref()
.map(str::trim)
.filter(|s| !s.is_empty()),
) {
(_, None) => None,
(Some((_, true)), Some(m @ ("start" | "end" | "none"))) => Some(m),
(Some((_, true)), Some(_)) => {
return Err(utopia_core::AppError::invalid(
"unknown_marks",
"marks is one of start, end or none",
)
.into())
}
(_, Some(_)) => {
return Err(utopia_core::AppError::invalid(
"marks_needs_state",
"only a state property says which end a moment marks",
)
.into())
}
};
let property = property.map(|(id, _)| id);
let direction = match (property, req.direction.as_deref()) {
(None, _) => None,
(Some(_), Some(d @ ("forward" | "reverse"))) => Some(d),
(Some(_), _) => {
return Err(utopia_core::AppError::invalid(
"direction_required",
"a bound signature needs a direction: forward or reverse",
)
.into())
}
};
let votes = json!({ "person": { "property": req.property, "direction": direction,
"marks": marks } });
// 判定和它的重算任务一次提交(0051)。这里**不再**同步重算:等物化锁占的是池里的
// 连接,而正在跑的那次对齐可能已经读完最后一遍,谁也不替这条判定投影。一个 job
// 只在判定提交后可见,worker 读的是当前绑定;屏幕上等的是 `review` / `graph` 事件
let job_id = utopia_store::phrase_bindings::decide_with_delivery(
&state.pool,
kb_id,
&sig,
utopia_store::phrase_bindings::Decision {
relation_type_id: property,
direction,
status: if property.is_some() { "bound" } else { "none" },
votes: &votes,
decided_by: "person",
basis: None,
marks,
marks_asked: false,
},
)
.await?
.ok_or_else(|| utopia_core::AppError::Conflict("the decision was not written".into()))?;
let _ = utopia_store::audit::record(
&state.pool,
Some(kb_id),
user.id,
"alignment.phrase_decided",
"phrase_binding",
Some(binding_id),
json!({ "phrase": sig.phrase, "property": req.property, "direction": direction,
"marks": marks, "job_id": job_id }),
)
.await;
state.emit_review(kb_id);
// 202:收下了,投影在路上。不编一个 typed: {added: 0} 出来——那不是这次请求知道的事
Ok((
axum::http::StatusCode::ACCEPTED,
Json(json!({ "ok": true, "job_id": job_id, "status": "accepted" })),
))
}
#[derive(Deserialize)]
pub struct DecideAlignmentKindWordReq {
/// 类的键;空 = 没有类对得上
#[serde(default)]
pub class: Option<String>,
}
/// 人定一个类别词绑到哪个类(#725 对齐队列)。绑上的类写到它名下的实体上;两端的类变了,
/// 短语签名跟着变,所以再排一次短语对齐——与判定同一事务排下(`decide_and_apply_human`),
/// 提交之后再排的话,进程在两步之间退出就只剩判定。
///
/// 写令牌也能定(0014 决定 6):判定记在发令牌的人名下,与网页上点的一样
pub async fn decide_alignment_kind_word(
State(state): State<AppState>,
caller: SessionOrToken,
Path((kb_id, kind_word)): Path<(Uuid, String)>,
Json(req): Json<DecideAlignmentKindWordReq>,
) -> ApiResult<Json<serde_json::Value>> {
caller.require_write(Some(kb_id))?;
let token_id = caller.token_id();
let user = caller.user;
require_kb(&state, &user, kb_id, Role::Editor).await?;
let class = match req
.class
.as_deref()
.map(str::trim)
.filter(|s| !s.is_empty())
{
None => None,
Some(key) => Some(
utopia_store::graph::entity_types(&state.pool, kb_id)
.await?
.into_iter()
.find(|c| c.key == key)
.map(|c| c.id)
.ok_or_else(|| {
utopia_core::AppError::invalid("unknown_class", "no class with that key")
})?,
),
};
let votes = json!({ "person": req.class });
let written = utopia_store::type_bindings::decide_and_apply_human(
&state.pool,
kb_id,
&kind_word,
class,
&votes,
)
.await?;
if !written {
return Err(utopia_core::AppError::NotFound.into());
}
let _ = utopia_store::audit::record(
&state.pool,
Some(kb_id),
user.id,
"alignment.kind_word_decided",
"type_binding",
None,
utopia_store::audit::via_token(
json!({ "kind_word": kind_word, "class": req.class }),
token_id,
),
)
.await;
state.emit_review(kb_id);
state.emit_graph(kb_id);
Ok(Json(json!({ "ok": true })))
}
#[derive(Deserialize)]
pub struct DecideErrataReq {
pub approve: bool,
}
/// 人答勘误 agent 留下的一笔(0044 决定 7):批了就执行那个动作,否了只记一笔
pub async fn decide_errata(
State(state): State<AppState>,
AuthUser(user): AuthUser,
Path((kb_id, action_id)): Path<(Uuid, Uuid)>,
Json(req): Json<DecideErrataReq>,
) -> ApiResult<Json<serde_json::Value>> {
require_kb(&state, &user, kb_id, Role::Editor).await?;
let found =
utopia_store::errata::decide_held(&state.pool, kb_id, action_id, req.approve, user.id)
.await?;
if !found {
return Err(utopia_core::AppError::NotFound.into());
}
let _ = utopia_store::audit::record(
&state.pool,
Some(kb_id),
user.id,
"errata.decided",
"errata_action",
Some(action_id),
json!({ "approve": req.approve }),
)
.await;
state.emit_review(kb_id);
state.emit_graph(kb_id);
Ok(Json(json!({ "ok": true })))
}