Skip to content

World's first open-source enterprise world model.

26.7 KB
Raw Blame
use axum::extract::{Path, Query, State};
use axum::Json;
use serde::Deserialize;
use serde_json::json;
use utopia_core::models::Role;
use utopia_core::AppError;
use uuid::Uuid;

use super::documents_routes::require_reader_kb;
use crate::auth::{AuthUser, SessionOrToken};
use crate::error::ApiResult;
use crate::state::AppState;

#[cfg(test)]
#[path = "graph_routes_time_tests.rs"]
mod time_tests;

pub(super) async fn require_kb(
    state: &AppState,
    user: &utopia_core::models::User,
    kb_id: Uuid,
    min: Role,
) -> Result<utopia_core::models::KnowledgeBase, AppError> {
    utopia_store::access::require_kb(&state.pool, user, kb_id, min).await
}

/// 时刻参数(YYYY-MM-DD 或 RFC3339)——服务端时间旅行。
///
/// 两根轴共用这一个解析:`at` 走世界轴(那时世界是什么样),`as_of` 走记录轴
/// (那时我们以为世界是什么样)。**两个参数一路分开**(0019):合成一个控件,
/// 答出来的是另一个问题,而屏幕上看不出来
pub(super) fn parse_instant(
    field: &str,
    raw: Option<&str>,
) -> Result<Option<chrono::DateTime<chrono::Utc>>, AppError> {
    let Some(s) = raw.map(str::trim).filter(|s| !s.is_empty()) else {
        return Ok(None);
    };
    if let Ok(d) = chrono::NaiveDate::parse_from_str(s, "%Y-%m-%d") {
        return Ok(Some(d.and_hms_opt(0, 0, 0).unwrap().and_utc()));
    }
    chrono::DateTime::parse_from_rfc3339(s)
        .map(|t| Some(t.with_timezone(&chrono::Utc)))
        .map_err(|_| {
            AppError::Validation(format!(
                "Invalid `{field}` (expected YYYY-MM-DD or RFC3339)"
            ))
        })
}

/// 总览一次画多少个节点的**默认值**。上限本身是合理的——画一万个点没人看得懂;
/// 骗人的是把它当成规模显示,所以接口同时回总数
const GRAPH_NODE_CAP: i64 = 150;
/// 调得再高也得有个天花板。**这个数不是拍的**:节点按度数降序取,越往后越是
/// 边缘节点,而力导布局是 O(n²) 量级的——超过这个数,先垮的是「拖得动」
/// 而不是「看得清」。要真看上万个点,那是另一种视图,不是把这个调大
const GRAPH_NODE_CAP_MAX: i64 = 1000;

#[derive(Deserialize)]
pub struct OverviewQuery {
    #[serde(default)]
    pub at: Option<String>,
    /// 记录轴:那时**我们持有**的图(0019)。不给就是现在
    #[serde(default)]
    pub as_of: Option<String>,
    /// 画多少个。不给就用默认值;给了也钳在 [10, GRAPH_NODE_CAP_MAX]——
    /// 界面上的按钮只给几档,但接口是公开的,别让一个 `limit=999999` 把库拖垮
    #[serde(default)]
    pub limit: Option<i64>,
}

pub async fn overview(
    State(state): State<AppState>,
    reader: SessionOrToken,
    Path(kb_id): Path<Uuid>,
    Query(q): Query<OverviewQuery>,
) -> ApiResult<Json<serde_json::Value>> {
    require_reader_kb(&state, &reader, kb_id).await?;
    let at = parse_instant("at", q.at.as_deref())?;
    let as_of = parse_instant("as_of", q.as_of.as_deref())?;
    // 画多少个是渲染的事,库里有多少是知识库的事——两个数都回,界面才说得出
    // 「画了 150 个,共 325 个」而不是把上限说成规模
    let limit = q
        .limit
        .unwrap_or(GRAPH_NODE_CAP)
        .clamp(10, GRAPH_NODE_CAP_MAX);
    let (nodes, edges, total_nodes, total_edges) =
        utopia_store::graph::overview(&state.pool, kb_id, limit, at, as_of).await?;
    Ok(Json(json!({
        "nodes": nodes, "edges": edges,
        "total_nodes": total_nodes, "total_edges": total_edges,
    })))
}

#[derive(Deserialize)]
pub struct NeighborhoodQuery {
    pub entity: Uuid,
    #[serde(default)]
    pub hops: Option<u8>,
    #[serde(default)]
    pub at: Option<String>,
    #[serde(default)]
    pub as_of: Option<String>,
}

pub async fn neighborhood(
    State(state): State<AppState>,
    reader: SessionOrToken,
    Path(kb_id): Path<Uuid>,
    Query(q): Query<NeighborhoodQuery>,
) -> ApiResult<Json<serde_json::Value>> {
    require_reader_kb(&state, &reader, kb_id).await?;
    let at = parse_instant("at", q.at.as_deref())?;
    let as_of = parse_instant("as_of", q.as_of.as_deref())?;
    let (nodes, edges) = utopia_store::graph::neighborhood(
        &state.pool,
        kb_id,
        q.entity,
        q.hops.unwrap_or(2),
        at,
        as_of,
    )
    .await?;
    Ok(Json(json!({ "nodes": nodes, "edges": edges })))
}

#[derive(Deserialize)]
pub struct EntitySearchQuery {
    pub q: String,
    #[serde(default)]
    pub limit: Option<i64>,
    #[serde(default)]
    pub offset: Option<i64>,
    /// 记录轴:回放中的图上点搜索框,结果按**当时**的 `degree` 排(0019)。
    /// 不给就是当下
    #[serde(default)]
    pub as_of: Option<String>,
}

pub async fn search_entities(
    State(state): State<AppState>,
    reader: SessionOrToken,
    Path(kb_id): Path<Uuid>,
    Query(query): Query<EntitySearchQuery>,
) -> ApiResult<Json<serde_json::Value>> {
    require_reader_kb(&state, &reader, kb_id).await?;
    // 先校验时刻:一个写错的 `as_of` 配空查询也该回 400,而不是看起来成功
    let as_of = parse_instant("as_of", query.as_of.as_deref())?;
    if query.q.trim().is_empty() {
        return Ok(Json(json!({ "entities": [], "total": 0 })));
    }
    // 一并回总数:「宁分勿合」本来就会造出一堆同名,固定十条时想找的那个
    // 可能根本不在这十条里,而界面上看不出来
    let (entities, total) = utopia_store::graph::search_entities(
        &state.pool,
        kb_id,
        &query.q,
        query.limit.unwrap_or(10).clamp(1, 100),
        query.offset.unwrap_or(0).max(0),
        as_of,
    )
    .await?;
    Ok(Json(json!({ "entities": entities, "total": total })))
}

#[derive(Deserialize)]
pub struct EntityDetailQuery {
    /// 记录轴:回放中的图上点开一个节点,面板该说**当时**的事实(0019)
    #[serde(default)]
    pub as_of: Option<String>,
}

pub async fn entity_detail(
    State(state): State<AppState>,
    reader: SessionOrToken,
    Path((kb_id, entity_id)): Path<(Uuid, Uuid)>,
    Query(q): Query<EntityDetailQuery>,
) -> ApiResult<Json<serde_json::Value>> {
    require_reader_kb(&state, &reader, kb_id).await?;
    let as_of = parse_instant("as_of", q.as_of.as_deref())?;
    // 世界轴不过滤(at = None):面板要的是整条时间线,「此刻成立」那一档由前端
    // 按 holds_from / holds_to 分出来(0022)
    let (entity, facts) =
        utopia_store::graph::entity_detail(&state.pool, kb_id, entity_id, None, as_of).await?;
    // 推出来的那些**单独回一个键**,不掺进 `facts`。前端据此给它们自己的一档:
    // 一条派生边跟一条断言边混在同一个列表里,用户看不出「这条是文档里写的」
    // 和「这条是引擎推的」的区别,而那正是推理会污染知识的样子
    // 同一个 as_of(#549):回放中的面板上,派生那一档也是**当时**推出的
    let derived =
        utopia_store::reasoning::derived_for_entity(&state.pool, kb_id, entity_id, None, as_of)
            .await?;
    // 同名的那些**打开面板时就给**,不是等改名之后才回。
    //
    // 从前它只随 `update_entity` 的响应回来,于是「把同名的合并进来」这个动作
    // 只有先改一次名才够得着——而两个张伟并存是「宁分勿合」的正当产物,不是
    // 改名改出来的。合并入口该长在能看见同名的地方。
    let same_name =
        utopia_store::graph::same_name_peers(&state.pool, kb_id, entity_id, as_of).await?;
    // 没落地的派生(0017 §3)也单独一个键:它们连 `derived_facts` 都不在
    let blocked =
        utopia_store::reasoning::blocked_for_entity(&state.pool, kb_id, entity_id, as_of).await?;
    // 名字也单独一个键(0041):本名、简称、曾用名,各带出处与有效期
    let names = utopia_store::names::for_entity(&state.pool, kb_id, entity_id, as_of).await?;
    Ok(Json(json!({
        "entity": entity, "facts": facts, "names": names,
        "derived": derived, "blocked": blocked, "same_name": same_name,
    })))
}

#[derive(Deserialize)]
pub struct EntityPatch {
    #[serde(default)]
    pub type_id: Option<Uuid>,
    #[serde(default)]
    pub canonical_name: Option<String>,
}

/// 人工修正实体的类型或名字。抽取给的是初判,此前判错只能整库重抽。
///
/// 改名撞上同名实体不拦(两个张伟是"宁分勿合"的正当产物),改完把同名的报回去,
/// 由界面提示是否合并——判定它们是否真是同一个,是人的事。
pub async fn update_entity(
    State(state): State<AppState>,
    AuthUser(user): AuthUser,
    Path((kb_id, entity_id)): Path<(Uuid, Uuid)>,
    Json(req): Json<EntityPatch>,
) -> ApiResult<Json<serde_json::Value>> {
    require_kb(&state, &user, kb_id, Role::Editor).await?;
    if req.type_id.is_none() && req.canonical_name.is_none() {
        return Err(AppError::invalid("nothing_to_update", "Nothing to update").into());
    }
    let (before, after) = utopia_store::graph::update_entity(
        &state.pool,
        kb_id,
        entity_id,
        req.type_id,
        req.canonical_name.as_deref(),
    )
    .await?;

    // 台账快照自包含:类型以后被删掉,这条记录仍然读得懂。
    // P4 要按 from/to 聚合"一个月里 37 个实体从 Product 挪到 Concept",所以分开记两个动作。
    if before.type_key != after.type_key {
        let _ = utopia_store::audit::record(
            &state.pool,
            Some(kb_id),
            user.id,
            "entity.retyped",
            "entity",
            Some(entity_id),
            json!({
                "name": after.name,
                "from": { "key": before.type_key, "label": before.type_label },
                "to": { "key": after.type_key, "label": after.type_label },
            }),
        )
        .await;
    }
    if before.name != after.name {
        let _ = utopia_store::audit::record(
            &state.pool,
            Some(kb_id),
            user.id,
            "entity.renamed",
            "entity",
            Some(entity_id),
            json!({ "from": before.name, "to": after.name, "type": after.type_label }),
        )
        .await;
    }

    // 写完之后立刻返回的同名列:这一次问的是当下,不是回放里——传 None 让它
    // 走「今天」那条路,与面板上没在回放时一致
    let peers = utopia_store::graph::same_name_peers(&state.pool, kb_id, entity_id, None).await?;
    state.emit_review(kb_id);
    Ok(Json(json!({ "entity": after, "same_name": peers })))
}

/// 一条事实的新有效区间。**整体替换,不是部分更新**:区间的两端互相定义,
/// 「把结束端清空」与「这次不动结束端」必须能分辨,而缺字段与 null 在 JSON 里
/// 分不开。界面提交的是表单里的四个值,不是差异。`end_after_period` 是例外:缺省即
/// 保留,见那一格。
#[derive(Deserialize)]
pub struct FactTimePatch {
    #[serde(default)]
    pub valid_from: Option<chrono::DateTime<chrono::Utc>>,
    #[serde(default)]
    pub valid_from_precision: Option<String>,
    #[serde(default)]
    pub valid_to: Option<chrono::DateTime<chrono::Utc>>,
    #[serde(default)]
    pub valid_to_precision: Option<String>,
    /// 为什么改。落进台账,不进图——「之前记错了」与「新证据说是六月」在账本上
    /// 长得一样,硬加一个类型枚举会让入口变重而判据模糊;真需要分辨了,再从
    /// 这里升格成字段
    #[serde(default)]
    pub note: Option<String>,
    /// 终点是不是原文所说时段之后的那一刻(`facts.end_after_period`,#994)。**唯一一个
    /// 缺省即保留的字段**:读出来什么就发回什么的客户端(不认识这个字段的也一样)不该
    /// 改掉它。不给时,终点(截到精度之后的值与精度)没变、起点还在,就留着存的标记;清掉
    /// 起点的保留时刻、丢掉标记(没有起点的行第一刀不标);别的终点照给的收下。路由从不
    /// 换算:存的、收的都是边界本身,按时段显示与换算是界面的事
    #[serde(default)]
    pub end_after_period: Option<bool>,
}

// 梯子只有一张(0024):与数据库的 CHECK、抽取端、显示端同一列
const DATE_PRECISIONS: [&str; 6] = utopia_store::graph::WORLD_PRECISIONS;

/// 修改前的区间,用于「一字未改」的判定与台账里的前后对照。
#[derive(sqlx::FromRow)]
struct FactInterval {
    valid_from: Option<chrono::DateTime<chrono::Utc>>,
    valid_from_precision: Option<String>,
    valid_to: Option<chrono::DateTime<chrono::Utc>>,
    valid_to_precision: Option<String>,
    end_after_period: bool,
    /// 谓词声明成状态:标记只能落在这样的行上
    declared_state: bool,
}

/// 显式要标记,却不是一个能带它的终点
fn bad_end_after_period() -> AppError {
    AppError::invalid(
        "bad_end_after_period",
        "An end that names a period needs a state property, a start and an end date.",
    )
}

/// 复刻 `facts` 表的 CHECK:两端的精度,标记要两端带得了它(`period_mark_fits`,属性是不是
/// 状态读到行之后再查);外加一条数据库没有的:截到各自精度之后,起点不能晚于终点。
///
/// 在这里挡住是为了让错误说人话。交给数据库挡会得到一句约束名,而这三态
/// (仍在持续 / 结束了不知哪天 / 某日结束)本来就是账本里最容易记混的地方。
fn check_interval(p: &FactTimePatch) -> Result<(), AppError> {
    // 起始端:没日期就没精度,且没有 unknown 档——「开始了但不知何时」与
    // 「不知道有没有开始」在这个账本里不可区分(见迁移 0003 的注释)
    match (&p.valid_from, p.valid_from_precision.as_deref()) {
        (Some(_), Some(prec)) if DATE_PRECISIONS.contains(&prec) => {}
        (None, None) => {}
        _ => return Err(AppError::invalid(
            "bad_valid_from",
            "A start date needs a precision of year, month, day, hour, minute or second, and a precision needs a date.",
        )),
    }
    // 结束端:有日期必有精度;没日期只能是仍在持续(都为空)或结束了不知哪天
    match (&p.valid_to, p.valid_to_precision.as_deref()) {
        (Some(_), Some(prec)) if DATE_PRECISIONS.contains(&prec) => {}
        (None, None) => {}
        (None, Some(prec)) if prec == utopia_store::graph::ENDED_UNKNOWN => {}
        _ => {
            return Err(AppError::invalid(
                "bad_valid_to",
                "An end date needs a precision of year, month, day, hour, minute or second. Leave the date empty for still going, or mark it ended with an unknown date.",
            ))
        }
    }
    // 显式要标记:两端得带得了它。属性是不是状态要读到行才知道,这里先当它是,只看两端
    if p.end_after_period == Some(true)
        && !utopia_store::graph::period_mark_fits(true, p.valid_from, p.valid_to, false)
    {
        return Err(bad_end_after_period());
    }
    // 比截到各自精度之后的两端:存下的就是截过的。比原值时,小时精度的 08:30 终点与分钟精度
    // 的 08:10 起点放得过去,截完成了 08:10 → 08:00,存下一段倒着的区间
    let truncate = utopia_store::graph::truncate_to;
    if let (Some(from), Some(to)) = (p.valid_from, p.valid_to) {
        if truncate(from, p.valid_from_precision.as_deref())
            > truncate(to, p.valid_to_precision.as_deref())
        {
            return Err(AppError::invalid(
                "interval_inverted",
                "The start of the interval is after its end.",
            ));
        }
    }
    Ok(())
}

/// 人工修正一条事实的有效区间。抽取给的是初判,此前判错只能删掉文档重抽——
/// 名字判错有 Review 可改(见 `update_entity`),时间判错没有入口,而这个
/// 产品卖的正是时间。
///
/// 走账本不走原地改:`correct_interval` 作废旧行、插带 `supersedes` 的修正行。
/// 于是这次修改本身出现在记录轴上(实体面板的 History),世界轴上只留新区间——
/// 旧区间是我们记错了,不是世界曾经的样子,两段并排会被读成换过两次岗。
pub async fn update_fact_time(
    State(state): State<AppState>,
    AuthUser(user): AuthUser,
    Path((kb_id, fact_id)): Path<(Uuid, Uuid)>,
    Json(req): Json<FactTimePatch>,
) -> ApiResult<Json<serde_json::Value>> {
    require_kb(&state, &user, kb_id, Role::Editor).await?;
    check_interval(&req)?;

    // 归属与状态校验:本 KB 的、未作废的事实才可改。派生事实不在此列——
    // 它的区间来自前提,改它等于改一个算出来的值,下一轮推理就会覆盖
    let before: Option<FactInterval> = sqlx::query_as(
        "SELECT f.valid_from, f.valid_from_precision, f.valid_to, f.valid_to_precision,
                f.end_after_period, COALESCE(r.temporal = 'state', false) AS declared_state
         FROM facts f
         LEFT JOIN relation_types r ON r.id = f.predicate_id
         WHERE f.id = $1 AND f.kb_id = $2 AND f.invalidated_at IS NULL
           AND f.derived_by_rule IS NULL",
    )
    .bind(fact_id)
    .bind(kb_id)
    .fetch_optional(&state.pool)
    .await
    .map_err(AppError::Db)?;
    let Some(before) = before else {
        return Err(AppError::NotFound.into());
    };
    // 存下的是截到精度之后的值:比较、判标记都按它
    let truncate = utopia_store::graph::truncate_to;
    let from = req
        .valid_from
        .map(|t| truncate(t, req.valid_from_precision.as_deref()));
    let to = req
        .valid_to
        .map(|t| truncate(t, req.valid_to_precision.as_deref()));
    // 读到了行,属性是不是状态也知道了:显式要的标记按整条规矩再判一遍
    if req.end_after_period == Some(true)
        && !utopia_store::graph::period_mark_fits(before.declared_state, from, to, false)
    {
        return Err(bad_end_after_period().into());
    }
    // 不给标记:发回存的终点(时刻与精度)、这次的两端还带得了它,就是没动它,留着;清掉起点
    // 的带不了,丢掉(时刻照旧)。属性这里不再判:存的标记是按当时的属性写下的,原样发回的
    // 请求不改写这一行
    let end_after_period = match req.end_after_period {
        Some(mark) => mark,
        None => {
            before.end_after_period
                && to == before.valid_to
                && req.valid_to_precision == before.valid_to_precision
                && utopia_store::graph::period_mark_fits(true, from, to, false)
        }
    };
    // 一字未改就不写一条修正进账本:History 上多一行「改过」而区间没动,
    // 读者会去找那个不存在的差异
    if before.valid_from == from
        && before.valid_from_precision == req.valid_from_precision
        && before.valid_to == to
        && before.valid_to_precision == req.valid_to_precision
        && before.end_after_period == end_after_period
    {
        return Ok(Json(json!({ "ok": true, "unchanged": true })));
    }

    let snap = crate::api::review_routes::fact_snapshot(&state, kb_id, fact_id).await;
    let validity = utopia_store::graph::Validity {
        from: req.valid_from,
        from_precision: req.valid_from_precision.as_deref(),
        to: req.valid_to,
        to_precision: req.valid_to_precision.as_deref(),
        // 人改的区间:日期是直接给的,没经过时间解析(0045 第 3 刀按 A 算)
        from_grade: None,
        // 修正行从被替代的行继承锚点(correct_interval 的 SQL 里):改区间是重述
        // 同一份证据,不是更新的证据
        attested_at: None,
        end_after_period,
    };
    let Some(corrected) =
        utopia_store::temporal::correct_interval(&state.pool, fact_id, validity).await?
    else {
        // 并发:另一处已经改写或作废了它。让界面重取,不要把两次修正叠起来
        return Err(AppError::invalid(
            "fact_changed",
            "This fact was changed by someone else. Reload and try again.",
        )
        .into());
    };

    // 改完要重新对账:把起点往前挪可能撞上前任的开放区间,那正是时态引擎
    // 该管的事。复用搬移后的那条路径——换了区间与换了主宾一样,都让唯一性
    // 不变量第一次看到这次相撞
    let report =
        utopia_store::temporal::reconcile_moved_facts(&state.pool, kb_id, &[corrected]).await?;

    if let Some(mut d) = snap {
        d["from"] = json!({
            "valid_from": before.valid_from.map(|t| t.to_rfc3339()),
            "valid_from_precision": before.valid_from_precision,
            "valid_to": before.valid_to.map(|t| t.to_rfc3339()),
            "valid_to_precision": before.valid_to_precision,
            "end_after_period": before.end_after_period,
        });
        d["to"] = json!({
            "valid_from": req.valid_from.map(|t| t.to_rfc3339()),
            "valid_from_precision": req.valid_from_precision,
            "valid_to": req.valid_to.map(|t| t.to_rfc3339()),
            "valid_to_precision": req.valid_to_precision,
            "end_after_period": end_after_period,
        });
        if let Some(note) = req.note.as_deref().map(str::trim).filter(|s| !s.is_empty()) {
            d["note"] = json!(note);
        }
        let _ = utopia_store::audit::record(
            &state.pool,
            Some(kb_id),
            user.id,
            "fact.time_corrected",
            "fact",
            Some(fact_id),
            d,
        )
        .await;
    }

    state.emit_review(kb_id);
    Ok(Json(json!({
        "ok": true,
        "fact_id": corrected,
        "closed": report.corrected.len(),
        "conflicts": report.conflicts,
    })))
}

pub async fn fact_evidence(
    State(state): State<AppState>,
    reader: SessionOrToken,
    Path((kb_id, fact_id)): Path<(Uuid, Uuid)>,
) -> ApiResult<Json<serde_json::Value>> {
    require_reader_kb(&state, &reader, kb_id).await?;
    let evidence = utopia_store::graph::fact_evidence(&state.pool, kb_id, fact_id).await?;
    Ok(Json(json!({ "evidence": evidence })))
}

/// 一条派生事实的证明(0002 R2):前提按推导顺序,每条带证据,一路到原句。
/// 派生已失效或不存在时 `proof` 为 null——不是错误,界面据此退回文本前提
pub async fn derived_proof(
    State(state): State<AppState>,
    AuthUser(user): AuthUser,
    Path((kb_id, derived_id)): Path<(Uuid, Uuid)>,
) -> ApiResult<Json<serde_json::Value>> {
    require_kb(&state, &user, kb_id, Role::Viewer).await?;
    let proof = utopia_store::reasoning::proof(&state.pool, kb_id, derived_id).await?;
    Ok(Json(json!({ "proof": proof })))
}

/// 没落地的派生的证明链(0017 §3):前提在那条 `derived_contradiction` 违规的
/// `path` 里,展开方式与落了地的一样。违规不存在时 `steps` 为 null
pub async fn blocked_proof(
    State(state): State<AppState>,
    AuthUser(user): AuthUser,
    Path((kb_id, violation_id)): Path<(Uuid, Uuid)>,
) -> ApiResult<Json<serde_json::Value>> {
    require_kb(&state, &user, kb_id, Role::Viewer).await?;
    let steps = utopia_store::reasoning::blocked_proof(&state.pool, kb_id, violation_id).await?;
    Ok(Json(json!({ "steps": steps })))
}

/// 手动触发抽取(failed 重试 / 补配模型后补抽)。
pub async fn extract(
    State(state): State<AppState>,
    AuthUser(user): AuthUser,
    Path(document_id): Path<Uuid>,
) -> ApiResult<Json<serde_json::Value>> {
    let doc = utopia_store::documents::get(&state.pool, document_id).await?;
    require_kb(&state, &user, doc.kb_id, Role::Editor).await?;
    // 来源说了不抽取的(schema 文档,0035 决定 7):说清楚为什么,而不是排一个
    // 流水线到了那一步又跳过的任务
    if let Some(source_id) = doc.source_id {
        if !utopia_store::sources::get(&state.pool, source_id)
            .await?
            .extracts()
        {
            return Err(utopia_core::AppError::invalid(
                "source_not_extracted",
                "Documents under this source are searched, not extracted",
            )
            .into());
        }
    }
    // 手动触发 = 强制全量:清增量标记、解雇在跑的任务、置 queued、建任务,一个事务办完
    let job_id = utopia_store::documents::queue_extraction_one(&state.pool, document_id).await?;
    state.emit_document(doc.kb_id, document_id);
    Ok(Json(json!({ "job_id": job_id })))
}

/// 图谱重建(清算语义,KB admin):清空整个图层后全量重抽。
/// 与来源级重抽的分工——重抽保留既有决策,重建放弃它们,换取
/// "当前语料 × 当前本体"的确定性重演(早期脏抽取、本体大改后的收场手段)。
/// 决策台账与裁决缓存刻意保留(见 store::graph::purge_graph)。
pub async fn rebuild(
    State(state): State<AppState>,
    AuthUser(user): AuthUser,
    Path(kb_id): Path<Uuid>,
) -> ApiResult<Json<serde_json::Value>> {
    require_kb(&state, &user, kb_id, Role::Admin).await?;
    let (entities, facts) = utopia_store::graph::purge_graph(&state.pool, kb_id).await?;
    // 任务由 queue_extraction 与状态同事务建好,这里只负责推送
    let ids = utopia_store::documents::queue_extraction(&state.pool, kb_id, None).await?;
    for id in &ids {
        state.emit_document(kb_id, *id);
    }
    state.emit_review(kb_id);
    let _ = utopia_store::audit::record(
        &state.pool,
        Some(kb_id),
        user.id,
        "graph.rebuild",
        "kb",
        Some(kb_id),
        json!({ "entities_removed": entities, "facts_removed": facts, "documents": ids.len() }),
    )
    .await;
    Ok(Json(json!({
        "entities_removed": entities, "facts_removed": facts, "queued": ids.len()
    })))
}

#[derive(Deserialize)]
pub struct HistoryQuery {
    #[serde(default)]
    pub page: i64,
    #[serde(default = "default_history_per")]
    pub per: i64,
}

fn default_history_per() -> i64 {
    30
}

/// 实体的认知变更历史(记录时间轴):我们何时这么认为、又何时改了主意。
/// 与 entity_detail(有效时间轴,只看现行)互补。
pub async fn entity_history(
    State(state): State<AppState>,
    reader: SessionOrToken,
    Path((kb_id, entity_id)): Path<(Uuid, Uuid)>,
    Query(q): Query<HistoryQuery>,
) -> ApiResult<Json<serde_json::Value>> {
    require_reader_kb(&state, &reader, kb_id).await?;
    let per = q.per.clamp(1, 200);
    let page = q.page.max(0);
    let (events, total) =
        utopia_store::graph::entity_history(&state.pool, kb_id, entity_id, per, page * per).await?;
    Ok(Json(json!({ "events": events, "total": total })))
}