World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-model
//! 时间提及按文档解析(0045 决定 2–5):模型读,代码算。
//!
//! 抽取只记时间**词**(`time_mentions`:原样的字、块、偏移、起/止)。这里是它后面的任务:
//!
//! 1. **文档时间上下文**(决定 3;0064 起由抽取时各块报上来,这里不再问模型)。从前:把开头交给模型,它转写文档自己的日期
//! (落款、备案日、公报的报告年)和文档命名的期间(「fiscal 2027」及其起止);日期词要在
//! 开头里核对得到才算数。结果存在 `documents.time_context`;文档自己的日期写进 `doc_time`
//! (来源 `content`)。上传时间永远不进来(#714)。
//! 2. **解释**(决定 2)。把文档的每个时间词连同它所在的那句话,和上下文一起交给模型;模型
//! 只回形状、引用(写明的数字部分 / 锚点加偏移 / 命名的期间 / 没有)和粒度,**从不算日期**。
//! 解释原样存回提及上,错了看得见、改得了。
//! 3. **算**。日历算术、期间到区间、按粒度截断、形状蕴含的区间,都在这里用结构化字段算,
//! 没有一个时间词写在代码里(决定 8)。写明的日期是 A 级,从文档自己给的锚点算出来的是
//! B 级,锚不到的是 C 级——C 级什么也不写,等锚点(决定 4、6)。
//! 4. 结果落到开放陈述的 `valid_from` / `valid_to`(决定 5 的第一根轴),时间轴上才有它。
//!
//! 例外只长在推送的陈述上(0054 来源):`when` / `ended` 写的是完整日期或带区时刻时,
//! 载荷就已经是结构化的绝对值——结构化的时间戳不是时间词(0045 决定 8,#1089),代码
//! 直接读成解释,不送模型;没有对话模型时,代码读得动的照解,读不动的留 C,任务照常收工。
use crate::extraction::chat_retrying_rate_limits_at;
use crate::llm_util;
use crate::state::AppState;
use chrono::{DateTime, Duration, Months, NaiveDate, NaiveTime, TimeZone, Utc};
use std::collections::{HashMap, HashSet};
use utopia_extract::time::{
build_interpretation_messages, headings_at, now_in_force, parse_interpretation_response,
Anchor, DateParts, Direction, DocumentDating, Granularity, Interpretation, MentionInput,
NamedPeriod, Offset, Reference, Shape, TimeContext, Unit,
};
use utopia_store::graph::{truncate_to, ENDED_UNKNOWN, WORLD_PRECISIONS};
use uuid::Uuid;
/// 一批解释问多少个提及。
const BATCH: usize = 40;
/// 一次解析的结果:世界轴上的位置与等级。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
struct Resolved {
from: Option<DateTime<Utc>>,
from_p: Option<&'static str>,
to: Option<DateTime<Utc>>,
to_p: Option<&'static str>,
/// A:写明的;B:从文档自己的锚点算出来的;C:锚不到
grade: &'static str,
}
const UNRESOLVED: Resolved = Resolved {
from: None,
from_p: None,
to: None,
to_p: None,
grade: "C",
};
/// 数字部分 → 时刻与精度。精度是字写到的那一档:只有年就是年。
fn parts_to_time(p: &DateParts) -> Option<(DateTime<Utc>, &'static str)> {
// 写明的季度从它的头一个月起(日历季度;财年的季度走命名的期间)
let month = p.month.or(p.quarter.map(|q| (q - 1) * 3 + 1));
let p = &DateParts { month, ..p.clone() };
let date = NaiveDate::from_ymd_opt(p.year, p.month.unwrap_or(1), p.day.unwrap_or(1))?;
let time = NaiveTime::from_hms_opt(
p.hour.unwrap_or(0),
p.minute.unwrap_or(0),
p.second.unwrap_or(0),
)?;
let precision = if p.month.is_none() {
"year"
} else if p.day.is_none() {
"month"
} else if p.hour.is_none() {
"day"
} else if p.minute.is_none() {
"hour"
} else if p.second.is_none() {
"minute"
} else {
"second"
};
Some((Utc.from_utc_datetime(&date.and_time(time)), precision))
}
fn granularity_str(g: Granularity) -> &'static str {
match g {
Granularity::Year => "year",
Granularity::Month => "month",
Granularity::Day => "day",
Granularity::Hour => "hour",
Granularity::Minute => "minute",
Granularity::Second => "second",
}
}
/// 两档精度取粗的那一档:字只写到年,模型说是「天」也只能是年——精度不能比字更细
fn coarser(a: &'static str, b: &'static str) -> &'static str {
let rank = |p: &str| WORLD_PRECISIONS.iter().position(|x| *x == p).unwrap_or(0);
if rank(a) <= rank(b) {
a
} else {
b
}
}
/// 锚点加偏移(决定 2 的算术)。月、季、年按月份加减(月末自动收口);周和天以下按时长。
fn shift(t: DateTime<Utc>, offset: &Offset) -> Option<DateTime<Utc>> {
let count = offset.count.unsigned_abs();
let forward = (offset.direction == Direction::After) == (offset.count >= 0);
let months = |n: u64| -> Option<DateTime<Utc>> {
let m = Months::new(u32::try_from(n).ok()?);
if forward {
t.checked_add_months(m)
} else {
t.checked_sub_months(m)
}
};
let span = |d: Duration| -> Option<DateTime<Utc>> {
if forward {
t.checked_add_signed(d)
} else {
t.checked_sub_signed(d)
}
};
match offset.unit {
Unit::Year => months(count.checked_mul(12)?),
Unit::Quarter => months(count.checked_mul(3)?),
Unit::Month => months(count),
Unit::Week => span(Duration::weeks(i64::try_from(count).ok()?)),
Unit::Day => span(Duration::days(i64::try_from(count).ok()?)),
Unit::Hour => span(Duration::hours(i64::try_from(count).ok()?)),
Unit::Minute => span(Duration::minutes(i64::try_from(count).ok()?)),
Unit::Second => span(Duration::seconds(i64::try_from(count).ok()?)),
}
}
/// 一个时刻和它的精度(世界轴的一端)。
type Bound = (DateTime<Utc>, &'static str);
/// 一个季度:包含 `t` 的那三个月(有财年结束日就按财年的季,否则按日历季),
/// 起是季首月,止是季末月(终点精度到月)。「本季度」「上季度」都从这里来
fn quarter_around(t: DateTime<Utc>, fiscal_year_end: Option<(u32, u32)>) -> Option<(Bound, Bound)> {
use chrono::Datelike;
// 财年从结束日的下一个月算起:结束于 1 月 25 日的财年,季首月是 2、5、8、11 月
let first_month = fiscal_year_end.map(|(m, _)| m % 12 + 1).unwrap_or(1);
let month0 = (t.month() as i32 - first_month as i32).rem_euclid(12); // 财年内第几个月(0 起)
let start_month0 = month0 - month0 % 3;
let start = t.checked_sub_months(Months::new(u32::try_from(month0 - start_month0).ok()?))?;
let start = truncate_to(start, Some("month"));
let end = start.checked_add_months(Months::new(2))?;
Some(((start, "month"), (end, "month")))
}
/// 一个期间的起止(写明的数字部分)。
fn period_bounds(from: &DateParts, to: &DateParts) -> Option<(Bound, Bound)> {
Some((parts_to_time(from)?, parts_to_time(to)?))
}
/// 形状决定字在世界轴上占哪一段(决定 7:形状另存,这里只算区间)。
/// 点:一刻,两端同值(0031 事件的写法);自:起点;至:终点;区间:两端;
/// 截至:观察到的起点;时长:没有位置;结束但不知何时:终点精度 unknown
fn place(
shape: Shape,
at: Option<(DateTime<Utc>, &'static str)>,
until: Option<(DateTime<Utc>, &'static str)>,
grade: &'static str,
) -> Resolved {
let trunc = |(t, p): (DateTime<Utc>, &'static str)| (truncate_to(t, Some(p)), p);
let at = at.map(trunc);
let until = until.map(trunc);
let mut r = Resolved {
grade,
..UNRESOLVED
};
match shape {
Shape::Point => {
if let Some((t, p)) = at {
r.from = Some(t);
r.from_p = Some(p);
r.to = Some(t);
r.to_p = Some(p);
}
}
Shape::Since | Shape::AsOf => {
if let Some((t, p)) = at {
r.from = Some(t);
r.from_p = Some(p);
}
}
Shape::Until => {
if let Some((t, p)) = until.or(at) {
r.to = Some(t);
r.to_p = Some(p);
}
}
Shape::Interval => {
if let Some((t, p)) = at {
r.from = Some(t);
r.from_p = Some(p);
}
if let Some((t, p)) = until {
r.to = Some(t);
r.to_p = Some(p);
}
}
Shape::Duration => return UNRESOLVED,
Shape::EndedUnknown => {
r.to_p = Some(ENDED_UNKNOWN);
}
}
if r.from.is_none() && r.to.is_none() && r.to_p.is_none() {
return UNRESOLVED;
}
r
}
/// 一个锚点在世界轴上的位置:文档日期、另一个提及、命名的期间。
fn anchor_time(
anchor: &Anchor,
ctx: &DocumentDating,
earlier: &HashMap<i64, Resolved>,
) -> Option<(Bound, Option<Bound>)> {
match anchor {
Anchor::Document => ctx.date.as_ref().and_then(parts_to_time).map(|t| (t, None)),
Anchor::Mention { id } => {
let r = earlier.get(id)?;
let from = r.from.zip(r.from_p)?;
Some((from, r.to.zip(r.to_p)))
}
Anchor::Period { name } => {
let p = ctx
.periods
.iter()
.find(|p| p.name.eq_ignore_ascii_case(name))?;
let (from, to) = period_bounds(&p.from, &p.to)?;
Some((from, Some(to)))
}
}
}
/// 一条解释 → 世界轴位置。`earlier` 是同一文档里已经算出来的提及(锚点指着它们)。
fn resolve_one(
interp: &Interpretation,
ctx: &DocumentDating,
earlier: &HashMap<i64, Resolved>,
) -> Resolved {
let g = granularity_str(interp.granularity);
// 「结束了,不知哪天」是字明说的(#393 的那一档):没有日期可算,但结束本身是 A 级
if interp.shape == Shape::EndedUnknown {
return place(Shape::EndedUnknown, None, None, "A");
}
match &interp.reference {
Reference::Absolute { from, to } => {
let Some((t, p)) = parts_to_time(from) else {
return UNRESOLVED;
};
let until = to.as_ref().and_then(parts_to_time);
// 一个季度是三个月的区间:到它最后一个月为止
if let (Some(_), None) = (from.quarter, &until) {
let last = t.checked_add_months(Months::new(2)).map(|m| (m, "month"));
let shape = match interp.shape {
Shape::Point | Shape::Duration => Shape::Interval,
s => s,
};
return place(shape, Some((t, "month")), last, "A");
}
place(interp.shape, Some((t, coarser(p, g))), until, "A")
}
Reference::Anchored { anchor, offset } => {
let Some(((t, p), until)) = anchor_time(anchor, ctx, earlier) else {
return UNRESOLVED;
};
// 对着一个期间说「截至」「至」(「年末」对着报告年):说的是期间的末,不是首。
// 这是形状的语义,不是认词
if offset.is_none()
&& matches!(anchor, Anchor::Period { .. })
&& matches!(interp.shape, Shape::AsOf | Shape::Until)
{
if let Some(end) = until {
return place(interp.shape, Some(end), None, "B");
}
}
let (t, until) = match offset {
Some(o) => {
let Some(moved) = shift(t, o) else {
return UNRESOLVED;
};
// 以「年」「月」为单位的偏移(本年、去年、上个月)说的是那一整段:
// 起止同一个桶,精度就是那个单位
if matches!(o.unit, Unit::Year | Unit::Month)
&& matches!(interp.shape, Shape::Point | Shape::Interval)
{
let unit_p = if o.unit == Unit::Year {
"year"
} else {
"month"
};
let start = truncate_to(moved, Some(unit_p));
return place(Shape::Point, Some((start, unit_p)), None, "B");
}
// 以「季」为单位的偏移(本季度、上季度)说的是那一整个季度,不是某一天
if o.unit == Unit::Quarter {
let Some((from, to)) = quarter_around(moved, ctx.fiscal_year_end) else {
return UNRESOLVED;
};
let shape = match interp.shape {
Shape::Point | Shape::Since | Shape::AsOf | Shape::Duration => {
Shape::Interval
}
s => s,
};
return place(shape, Some(from), Some(to), "B");
}
(moved, until.and_then(|(u, _)| shift(u, o).map(|m| (m, g))))
}
None => (t, until),
};
// 锚点算出来的时刻,精度由字说的粒度定,但不能比锚点自己更细
place(interp.shape, Some((t, coarser(p, g))), until, "B")
}
Reference::Period { name, from, to } => {
// 只写了一端的期间(「三个月截至 6 月 30 日」):写明的那一端照写,另一端不猜
match (from, to) {
(None, Some(t)) => {
return place(Shape::Until, None, parts_to_time(t), "A");
}
(Some(f), None) => {
return place(Shape::Since, parts_to_time(f), None, "A");
}
_ => {}
}
let (bounds, grade) = match (from, to) {
(Some(f), Some(t)) => (period_bounds(f, t), "A"),
_ => (
ctx.periods
.iter()
.find(|p| p.name.eq_ignore_ascii_case(name))
.and_then(|p| period_bounds(&p.from, &p.to)),
"B",
),
};
let Some((from, to)) = bounds else {
return UNRESOLVED;
};
// 一个期间本身是区间;「截至期末」这类形状照形状算
let shape = match interp.shape {
Shape::Point | Shape::Since | Shape::Duration => Shape::Interval,
s => s,
};
place(shape, Some(from), Some(to), grade)
}
Reference::None => UNRESOLVED,
}
}
/// 计算已收到的解释;每条解释使用它自己的章节上下文。
fn resolve_interpretations(
interpretations: &[Interpretation],
context_for: impl Fn(i64) -> DocumentDating,
) -> HashMap<i64, Resolved> {
let mut resolved = HashMap::new();
let mut pending: Vec<&Interpretation> = interpretations.iter().collect();
while !pending.is_empty() {
let before = pending.len();
pending.retain(|interp| {
let r = resolve_one(interp, &context_for(interp.id), &resolved);
if r == UNRESOLVED {
return true;
}
resolved.insert(interp.id, r);
false
});
// 每轮至少解开一条才继续;循环、自引用、缺失或不可用的锚点都在无进展时留下 C。
// 不能固定遍数:模型回复可以把任意长的依赖链倒着写。
if pending.len() == before {
break;
}
}
for interp in pending {
resolved.insert(interp.id, UNRESOLVED);
}
resolved
}
/// 算的时候文档的日期换成提及所在那一节的起算点。
fn context_at(context: &DocumentDating, now: Option<usize>) -> DocumentDating {
let mut scoped = context.clone();
if let Some(entry) = now.and_then(|i| context.entries.get(i)) {
scoped.date = Some(entry.from.clone());
scoped.date_words = Some(entry.words.clone());
}
scoped
}
/// 推送的陈述把 `when` / `ended` 写成完整日期或带区时刻时,这里就把它读成一条解释
/// (#1089;0045 决定 8:结构化的时间戳不是时间词)。形状是点、参照是照写的绝对值、
/// 粒度是字写到的那一级——与模型对同样的字该给的回答一致。`from` 存换算成 UTC 后的
/// 部件:`DateParts` 不带区,偏移在 `parse_time` 里已经折进值里;存 UTC 部件的解释
/// 再算一遍得到同一个值,存原样的本地钟点反而会读出另一个时刻。
///
/// 只收 `parse_time` 读到「日」或更细的:`YYYY-MM-DD` 与带 `Z` 或偏移的
/// `YYYY-MM-DDTHH[:MM[:SS]]`。光杆的年、年月、以及任何读不动的字都回 `None`,
/// 照旧走模型那条路——这一刀不替代码认时间词。
fn stated_reading(text: &str, id: i64) -> Option<Interpretation> {
let (t, precision) = utopia_extract::parse_time(text)?;
use chrono::{Datelike, Timelike};
let (granularity, hour, minute, second) = match precision {
"day" => (Granularity::Day, None, None, None),
"hour" => (Granularity::Hour, Some(t.hour()), None, None),
"minute" => (Granularity::Minute, Some(t.hour()), Some(t.minute()), None),
"second" => (
Granularity::Second,
Some(t.hour()),
Some(t.minute()),
Some(t.second()),
),
// 光杆的年、年月不在这刀里(#1089 的界),退回 None 让模型读
_ => return None,
};
Some(Interpretation {
id,
shape: Shape::Point,
reference: Reference::Absolute {
from: DateParts {
year: t.year(),
quarter: None,
month: Some(t.month()),
day: Some(t.day()),
hour,
minute,
second,
},
to: None,
},
granularity,
})
}
/// 一条陈述的起与止:`when` 给起(点与区间也给止),`ended` 给止。
fn combine(when: Option<Resolved>, ended: Option<Resolved>) -> Resolved {
let mut r = when.unwrap_or(UNRESOLVED);
if let Some(e) = ended {
let to = e.to.or(e.from);
let to_p = e.to_p.or(e.from_p);
if to.is_some() || to_p.is_some() {
r.to = to;
r.to_p = to_p;
}
if r.grade == "C" {
r.grade = e.grade;
}
}
r
}
/// 解析一篇文档的全部时间提及(任务 `resolve_time`)。幂等:再跑一次覆盖上一次的结果,
/// 所以锚点晚到(改了文档日期、后一块给了期间)时重排一次即可(决定 4 的第一步)
pub async fn resolve_document(state: &AppState, document_id: Uuid) -> anyhow::Result<()> {
let pool = &state.pool;
let doc = utopia_store::documents::get(pool, document_id).await?;
if doc.deleted_at.is_some() {
return Ok(());
}
let kb = utopia_store::kbs::get(pool, doc.kb_id).await?;
let settings = utopia_store::settings::get(pool, kb.workspace_id).await?;
let client = settings.as_ref().and_then(llm_util::chat_client);
// 推送来的陈述(0054):`when` / `ended` 写的完整日期或带区时刻由代码直接读(#1089),
// 没有对话模型也照常解;别的文档照旧——没有对话模型,这一步就没有替它读字的人
let pushed = crate::pipeline::source_kind(state, doc.source_id)
.await?
.as_deref()
== Some("statements");
if !pushed && client.is_none() {
anyhow::bail!("Chat model not configured; cannot resolve time");
}
// 1. 文档时间上下文:抽取时各块报上来的(0064)。这里不问模型
let context: DocumentDating = match doc.time_context.clone() {
Some(json) => {
let context: DocumentDating = serde_json::from_value(json)?;
// 整篇的起算点照旧记成文档的日期(文库排序、引擎给没起点的行排次序都读它)
if crate::extraction_open::dated_at(&doc).is_none() {
if let Some((t, _)) = context.date.as_ref().and_then(parts_to_time) {
utopia_store::documents::set_content_date(pool, document_id, t).await?;
}
}
context
}
// 抽取一条日期都没报:文档没说自己是哪天的。不再另问一次开头(0064 决定 1)——
// 那一次调用在抽取报了「没有」的文档上问的是同一个问题,测量里二十篇有十六篇这样
// 白问;文档里写了日期的,抽取都报上来了
None => DocumentDating::default(),
};
// 这一刀之前读开头定出来、存在文档上的日期(只有日期、没有条目):它就是整篇的起算点,
// 和抽取报上来的一样进条目里,下面给陈述作证、给相对的时间词当基准都从条目里找
let mut context = context;
if context.entries.is_empty() {
if let (Some(date), Some(words)) = (context.date.clone(), context.date_words.clone()) {
context.entries.push(utopia_extract::time::TimeEntry {
kind: "now".into(),
name: String::new(),
words,
from: date,
to: None,
scope: Vec::new(),
chunk: None,
char_start: None,
});
}
}
attest_statements(state, &doc, &context).await?;
// 抽取报上来的期间(0064)并进文档命名的期间里:解释时按名字指它
for e in context
.entries
.clone()
.iter()
.filter(|e| e.kind == "period")
{
let name = if e.name.is_empty() { &e.words } else { &e.name };
if let (Some(to), false) = (
e.to.clone(),
context
.periods
.iter()
.any(|p| p.name.eq_ignore_ascii_case(name)),
) {
context.periods.push(NamedPeriod {
name: name.clone(),
from: e.from.clone(),
to,
});
}
}
let context = context;
// 2. 提及:同一篇里同样的字在同样的句子里只解释一次
let mentions = utopia_store::time_mentions::for_document(pool, document_id).await?;
if mentions.is_empty() {
return Ok(());
}
// 每条提及所在的那一节里管事的起算点(0064 决定 4):从它那一块正文里的标题读出所在的
// 节,再在文档报上来的日期里找范围最深的那个 `now`。一篇文档里两份周报各有各的提报日,
// 「上周」在哪一节就从哪一节的日期起算。没有条目的文档(老的、推送来的)照旧用文档的日期
let chunk_text: HashMap<Uuid, String> =
sqlx::query_as::<_, (Uuid, String)>("SELECT id, text FROM chunks WHERE document_id = $1")
.bind(document_id)
.fetch_all(pool)
.await?
.into_iter()
.collect();
let now_of = |m: &utopia_store::time_mentions::MentionToResolve| -> Option<usize> {
let text = chunk_text.get(&m.chunk_id)?;
let path = headings_at(text, usize::try_from(m.char_start).unwrap_or(0));
let found = now_in_force(&context.entries, &path)?;
context.entries.iter().position(|e| std::ptr::eq(e, found))
};
type Key = (String, String, Option<usize>);
let mut distinct: Vec<Key> = Vec::new();
let mut index: HashMap<Key, usize> = HashMap::new();
let mut key_of: HashMap<Uuid, Key> = HashMap::new();
// 推送来的陈述(0054):载荷写的完整日期或带区时刻由代码读成解释(#1089)。
// 解释与别的提及同去同回,只是它从不进问模型的清单——重问也只能是这个答案,
// 代码读过的不许模型盖掉;判据是文档来自 `statements` 来源,不是字长得像日期,
// 普通文档里同样的字照旧交给模型
let mut presolved: HashMap<usize, Interpretation> = HashMap::new();
for m in &mentions {
let key = (m.text.clone(), m.sentence.clone(), now_of(m));
key_of.insert(m.id, key.clone());
if index.contains_key(&key) {
continue;
}
index.insert(key.clone(), distinct.len());
distinct.push(key);
if pushed {
if let Some(interp) = stated_reading(&m.text, (distinct.len() - 1) as i64) {
presolved.insert(distinct.len() - 1, interp);
}
}
}
let ctx = TimeContext {
date: context.date.as_ref(),
date_words: context.date_words.as_deref(),
periods: &context.periods,
fiscal_year_end: context.fiscal_year_end,
};
let mut interpretations: Vec<Interpretation> = presolved.values().cloned().collect();
let mut received = HashSet::new();
let mut malformed = 0usize;
// 问两轮:第一轮全部,第二轮只问第一轮没答到的。模型漏答的提及从前就留着字、没有解释,
// 也没有人再问(测量台上的「上周」三遍都是这样)。代码已经读出答案的不问
let mut todo: Vec<usize> = (0..distinct.len())
.filter(|i| !presolved.contains_key(i))
.collect();
if let (Some(settings), Some(client)) = (settings.as_ref(), client.as_ref()) {
for round in 0..2 {
if round == 1 {
todo.retain(|i| !received.contains(&(*i as i64)));
if todo.is_empty() {
break;
}
tracing::info!(%document_id, unanswered = todo.len(), "时间解释有没答到的,再问一次");
}
for batch in todo.clone().chunks(BATCH) {
let inputs: Vec<MentionInput<'_>> = batch
.iter()
.map(|&i| MentionInput {
id: i as i64,
text: &distinct[i].0,
sentence: &distinct[i].1,
})
.collect();
let ids: Vec<i64> = inputs.iter().map(|m| m.id).collect();
let messages = build_interpretation_messages(&ctx, &inputs);
let reply = match chat_retrying_rate_limits_at(
state,
settings,
client,
&messages,
Some(0.0),
)
.await
{
Ok(r) => r,
Err(e) => {
tracing::warn!(%document_id, error = %e, "时间解释调用失败,这一批留作未解析");
continue;
}
};
let (interps, skipped) = match parse_interpretation_response(&reply.text, &ids) {
Ok(x) => x,
Err(e) => {
tracing::warn!(%document_id, error = %e, "时间解释回复解析失败,这一批留作未解析");
continue;
}
};
malformed += skipped;
if skipped > 0 {
// 坏条目要看得见是哪一条、坏在哪:只报一个数的话,「上周」三遍都没日期也查不出原因
tracing::warn!(%document_id, skipped, reply = %reply.text.chars().take(600).collect::<String>(), "时间解释里有读不了的条目");
}
received.extend(interps.iter().map(|interp| interp.id));
interpretations.extend(interps);
}
}
}
// 收到解释和算出日期是两件事:补答只问没收到的,计算则看全部批次和补答里的解释。
// 这样下游不用再问模型,也能用上后一批或补答才给出的锚点。
let computed = resolve_interpretations(&interpretations, |id| {
let now = usize::try_from(id)
.ok()
.and_then(|i| distinct.get(i))
.and_then(|key| key.2);
context_at(&context, now)
});
let mut resolved: HashMap<usize, (Interpretation, Resolved)> = HashMap::new();
for interp in interpretations {
if let Ok(i) = usize::try_from(interp.id) {
let r = computed[&interp.id];
resolved.insert(i, (interp, r));
}
}
// 3. 写回提及,再按陈述合起止
let mut per_fact: HashMap<Uuid, (Option<Resolved>, Option<Resolved>)> = HashMap::new();
let (mut a, mut b, mut c) = (0usize, 0usize, 0usize);
for m in &mentions {
let Some(&i) = key_of.get(&m.id).and_then(|k| index.get(k)) else {
continue;
};
let Some((interp, r)) = resolved.get(&i) else {
// 推送的文档没有对话模型可问(#1089):代码读不动的提及按 C 记——「有提及、
// 没能放上轴」和「没有时间词」要分得出;任务照常收工,不因一个没配的模型
// 留下永远失败的任务。解释列留空:没有人读过它,不编一条出来
if pushed && client.is_none() {
utopia_store::time_mentions::set_resolution(
pool, m.id, "C", None, None, None, None,
)
.await?;
c += 1;
let slot = per_fact.entry(m.fact_id).or_insert((None, None));
if m.role == "ended" {
slot.1 = Some(UNRESOLVED);
} else {
slot.0 = Some(UNRESOLVED);
}
}
// 有模型而没答到的:留着字,不写等级(下次重跑再问)
continue;
};
utopia_store::time_mentions::set_interpretation(
pool,
m.id,
serde_json::to_value(interp.shape)?
.as_str()
.unwrap_or("point"),
&serde_json::to_value(&interp.reference)?,
granularity_str(interp.granularity),
)
.await?;
utopia_store::time_mentions::set_resolution(
pool, m.id, r.grade, r.from, r.from_p, r.to, r.to_p,
)
.await?;
match r.grade {
"A" => a += 1,
"B" => b += 1,
_ => c += 1,
}
let slot = per_fact.entry(m.fact_id).or_insert((None, None));
if m.role == "ended" {
slot.1 = Some(*r);
} else {
slot.0 = Some(*r);
}
}
let mut dated = 0usize;
for (fact_id, (when, ended)) in per_fact {
let r = combine(when, ended);
// 起点的等级只看起点那条提及。combine 在起点锚不到时借结束端的等级来报数,
// 这里不借:引擎问的是「这一行的起点是怎么来的」(0045 第 3 刀)
let grade = when.map(|w| w.grade);
let placed = r.from.is_some() || r.to.is_some() || r.to_p.is_some();
// 什么都没算出来也要写等级 C:只有这一列说得出「这句话有时间词、我们没能把它
// 放到轴上」,否则它和「整句没有时间词」在库里长得一模一样
if !placed && grade != Some("C") {
continue;
}
utopia_store::graph::set_open_validity(
pool, fact_id, r.from, r.from_p, r.to, r.to_p, grade,
)
.await?;
if placed {
dated += 1;
}
}
tracing::info!(
%document_id,
mentions = mentions.len(),
grade_a = a,
grade_b = b,
grade_c = c,
malformed,
statements_dated = dated,
"时间提及解析完成"
);
if dated > 0 {
state.emit_graph(doc.kb_id);
}
Ok(())
}
/// 见证的名字:日期的名字加它的字(「提报日期 2026年9月4日」)。没有名字的光是字;封面上
/// 一个光秃秃的日期,模型常把日期自己又填成名字,那就只写一遍
fn witness_name(name: &str, words: &str) -> String {
let (name, words) = (name.trim(), words.trim());
if name.is_empty() || name == words {
words.to_string()
} else {
format!("{name} {words}")
}
}
/// 这篇文档的陈述各由它所在那一节里文本说话的那一刻作证(0064 决定 3)。
///
/// 一条陈述在哪一节,看它的引文在它那一块里的位置、那一块正文里的标题;管着它的是范围
/// 最深的那个 `now`。没有的不写——见证留空,这条陈述在任何时点都成立(决定 5)。
/// 这是「截至」,不是起点:报告里的「所属市场为全球」说的是那天是这样,不是从那天起
async fn attest_statements(
state: &AppState,
doc: &utopia_core::models::Document,
context: &DocumentDating,
) -> anyhow::Result<()> {
let pool = &state.pool;
if !context.entries.iter().any(|e| e.kind == "now") {
// 这一遍文档一条日期都没说:上一遍记在证据上的也不算数了
sqlx::query(
"UPDATE fact_evidence SET attested_at = NULL, attested_by = NULL
WHERE document_id = $1 AND attested_at IS NOT NULL",
)
.bind(doc.id)
.execute(pool)
.await?;
return Ok(());
}
let rows: Vec<(Uuid, Uuid, String, Option<i32>)> = sqlx::query_as(
"SELECT fe.fact_id, fe.chunk_id, c.text, fe.quote_start
FROM fact_evidence fe
JOIN facts f ON f.id = fe.fact_id
JOIN chunks c ON c.id = fe.chunk_id
WHERE fe.document_id = $1 AND c.superseded_at IS NULL
AND f.layer = 'open' AND f.invalidated_at IS NULL",
)
.bind(doc.id)
.fetch_all(pool)
.await?;
let mut moved = 0usize;
for (fact_id, chunk_id, text, start) in rows {
let path = headings_at(&text, usize::try_from(start.unwrap_or(0)).unwrap_or(0));
let witness = now_in_force(&context.entries, &path).and_then(|now| {
let (at, _) = parts_to_time(&now.from)?;
Some((at, witness_name(&now.name, &now.words)))
});
// 每条证据记下自己这一节的日期(没说的记成空):事实上只留最早的那一个,证据所在
// 的文档删了之后要照还在的证据重算,得知道每一条各是哪天
utopia_store::graph::witness_evidence(
pool,
fact_id,
chunk_id,
witness.as_ref().map(|(at, by)| (*at, by.as_str())),
)
.await?;
let Some((at, by)) = witness else {
continue;
};
if utopia_store::graph::attest_statement(pool, fact_id, at, &by).await? {
moved += 1;
}
}
// 已经物化出来的、规则算出来的类型化行跟着它们的陈述走
let typed = utopia_store::materialize::sync_typed_attestation(pool, doc.kb_id, None).await?;
// 见证动了的行换了它在唯一性时间线上的位置:只把这些行所在的时间线重算一遍,不是整个库
// ——每篇文档都把全库的时间线各开一个事务重算一遍,库一大就是每篇几千个事务。
// 先提交同步,再拿时间线锁,不在持有 UPDATE 行锁时等咨询锁(与物化提交后对账的顺序一致)
let reconciled = utopia_store::temporal::reconcile_moved_facts(pool, doc.kb_id, &typed).await?;
let typed = typed.len();
if moved > 0 || typed > 0 {
tracing::info!(document_id = %doc.id, statements = moved, typed,
corrected = reconciled.corrected.len(), conflicts = reconciled.conflicts,
"陈述按它所在那一节的日期作了证");
state.emit_graph(doc.kb_id);
}
Ok(())
}
#[cfg(test)]
#[path = "time_context_tests.rs"]
mod context_tests;
#[cfg(test)]
#[path = "time_attestation_tests.rs"]
mod attestation_tests;
#[cfg(test)]
#[path = "time_resolution_pushed_tests.rs"]
mod pushed_tests;
#[cfg(test)]
mod tests {
use super::*;
/// 推送载荷里写明的值(#1089):完整日期与带区时刻读成点状绝对解释,精度随字;
/// 光杆的年、年月、读不动的字都回 None——不替代码认时间词
#[test]
fn a_stated_value_reads_at_the_precision_it_writes() {
let read = |s: &str| {
let interp = stated_reading(s, 0)?;
let Reference::Absolute { from, to } = interp.reference else {
return None;
};
assert_eq!(interp.shape, Shape::Point);
assert!(to.is_none());
Some((from, interp.granularity))
};
let date = |y, m, d, h, mi, s| DateParts {
year: y,
quarter: None,
month: Some(m),
day: Some(d),
hour: h,
minute: mi,
second: s,
};
assert_eq!(
read("2026-09-23"),
Some((date(2026, 9, 23, None, None, None), Granularity::Day))
);
assert_eq!(
read("2026-09-23T08Z"),
Some((date(2026, 9, 23, Some(8), None, None), Granularity::Hour))
);
assert_eq!(
read("2026-09-23T08:14Z"),
Some((
date(2026, 9, 23, Some(8), Some(14), None),
Granularity::Minute
))
);
assert_eq!(
read("2026-09-23T08:14:03Z"),
Some((
date(2026, 9, 23, Some(8), Some(14), Some(3)),
Granularity::Second
))
);
// 偏移折进值里:+08:00 的 08:14 是 UTC 的 00:14
assert_eq!(
read("2026-09-23T08:14:03+08:00"),
Some((
date(2026, 9, 23, Some(0), Some(14), Some(3)),
Granularity::Second
))
);
// 这一刀之外的字:光杆的年、年月、自然语言
for s in ["2026", "2026-09", "last Tuesday", "ended", ""] {
assert!(read(s).is_none(), "{s:?} is not code-resolved");
}
}
#[test]
fn a_bare_date_is_named_once() {
assert_eq!(
witness_name("提报日期", "2026年9月4日"),
"提报日期 2026年9月4日"
);
assert_eq!(witness_name("", "2024年10月10日"), "2024年10月10日");
assert_eq!(
witness_name("2024年10月10日", " 2024年10月10日"),
"2024年10月10日"
);
}
use utopia_extract::time::NamedPeriod;
fn parts(y: i32, m: Option<u32>, d: Option<u32>) -> DateParts {
DateParts {
quarter: None,
year: y,
month: m,
day: d,
hour: None,
minute: None,
second: None,
}
}
fn at(s: &str) -> DateTime<Utc> {
DateTime::parse_from_rfc3339(s).unwrap().with_timezone(&Utc)
}
fn ctx_dated(y: i32, m: u32, d: u32) -> DocumentDating {
DocumentDating {
entries: Vec::new(),
date: Some(parts(y, Some(m), Some(d))),
date_words: Some("x".into()),
periods: vec![NamedPeriod {
name: "fiscal 2027".into(),
from: parts(2026, Some(1), Some(26)),
to: parts(2027, Some(1), Some(25)),
}],
fiscal_year_end: Some((1, 25)),
skipped: 0,
}
}
fn day_point(date: &str, grade: &'static str) -> Resolved {
Resolved {
from: Some(at(date)),
from_p: Some("day"),
to: Some(at(date)),
to_p: Some("day"),
grade,
}
}
fn absolute_day(id: i64) -> Interpretation {
Interpretation {
id,
shape: Shape::Point,
reference: Reference::Absolute {
from: parts(2024, Some(1), Some(1)),
to: None,
},
granularity: Granularity::Day,
}
}
fn next_day(id: i64, anchor_id: i64) -> Interpretation {
Interpretation {
reference: Reference::Anchored {
anchor: Anchor::Mention { id: anchor_id },
offset: Some(Offset {
count: 1,
unit: Unit::Day,
direction: Direction::After,
}),
},
..absolute_day(id)
}
}
#[test]
fn mention_dependencies_resolve_in_all_reply_orders() {
let items = [
serde_json::json!([0, "point", {"kind": "absolute", "from": {"y": 2024, "m": 1, "d": 1}}, "day"]),
serde_json::json!([1, "point", {"kind": "anchored", "anchor": {"kind": "mention", "id": 0}, "offset": {"count": 1, "unit": "day", "direction": "after"}}, "day"]),
serde_json::json!([2, "point", {"kind": "anchored", "anchor": {"kind": "mention", "id": 1}, "offset": {"count": 1, "unit": "day", "direction": "after"}}, "day"]),
];
let expected = HashMap::from([
(0, day_point("2024-01-01T00:00:00Z", "A")),
(1, day_point("2024-01-02T00:00:00Z", "B")),
(2, day_point("2024-01-03T00:00:00Z", "B")),
]);
for order in [
[0, 1, 2],
[0, 2, 1],
[1, 0, 2],
[1, 2, 0],
[2, 0, 1],
[2, 1, 0],
] {
let reply = serde_json::json!({"m": order.map(|i| items[i].clone())});
let (interpretations, skipped) =
parse_interpretation_response(&reply.to_string(), &[0, 1, 2]).unwrap();
assert_eq!(skipped, 0);
assert_eq!(interpretations.len(), 3);
let resolved = resolve_interpretations(&interpretations, |_| DocumentDating::default());
assert_eq!(resolved, expected, "reply order: {order:?}");
}
}
#[test]
fn a_long_reverse_chain_does_not_follow_numeric_ids_or_a_fixed_pass_limit() {
// 编号上下交错,与依赖次序无关;链长也超过一批的大小。
let ids: Vec<i64> = (0..81).map(|depth| 500 + (depth * 37) % 101).collect();
let mut interpretations = vec![absolute_day(ids[0])];
for pair in ids.windows(2) {
interpretations.push(next_day(pair[1], pair[0]));
}
interpretations.reverse();
let resolved = resolve_interpretations(&interpretations, |_| DocumentDating::default());
assert_eq!(resolved.len(), ids.len());
for (depth, id) in ids.iter().enumerate() {
let date = at("2024-01-01T00:00:00Z") + Duration::days(depth as i64);
assert_eq!(
resolved[id],
Resolved {
from: Some(date),
from_p: Some("day"),
to: Some(date),
to_p: Some("day"),
grade: if depth == 0 { "A" } else { "B" },
},
"depth {depth}, id {id}"
);
}
}
#[test]
fn independent_chains_resolve_while_cycles_and_missing_anchors_stay_unresolved() {
let second_root = Interpretation {
reference: Reference::Absolute {
from: parts(2025, Some(6), Some(10)),
to: None,
},
..absolute_day(20)
};
let interpretations = [
next_day(2, 1),
next_day(30, 30), // 自引用
next_day(31, 32),
next_day(32, 31), // 循环
next_day(33, 999), // 缺失的解释
next_day(34, 31), // 依赖循环的下游
next_day(22, 21),
next_day(1, 0),
next_day(21, 20),
second_root,
absolute_day(0),
];
let resolved = resolve_interpretations(&interpretations, |_| ctx_dated(2030, 1, 1));
assert_eq!(
resolved,
HashMap::from([
(0, day_point("2024-01-01T00:00:00Z", "A")),
(1, day_point("2024-01-02T00:00:00Z", "B")),
(2, day_point("2024-01-03T00:00:00Z", "B")),
(20, day_point("2025-06-10T00:00:00Z", "A")),
(21, day_point("2025-06-11T00:00:00Z", "B")),
(22, day_point("2025-06-12T00:00:00Z", "B")),
(30, UNRESOLVED),
(31, UNRESOLVED),
(32, UNRESOLVED),
(33, UNRESOLVED),
(34, UNRESOLVED),
])
);
}
#[test]
fn received_interpretations_can_use_anchors_from_later_batches_and_the_makeup_reply() {
let first_reply = r#"{"m": [
[2, "point", {"kind": "anchored", "anchor": {"kind": "mention", "id": 1}, "offset": {"count": 1, "unit": "day", "direction": "after"}}, "day"],
[1, "point", {"kind": "anchored", "anchor": {"kind": "mention", "id": 40}, "offset": {"count": 1, "unit": "day", "direction": "after"}}, "day"]
]}"#;
let (mut interpretations, skipped) =
parse_interpretation_response(first_reply, &[0, 1, 2]).unwrap();
assert_eq!(skipped, 0);
let before = resolve_interpretations(&interpretations, |_| DocumentDating::default());
assert_eq!(before, HashMap::from([(1, UNRESOLVED), (2, UNRESOLVED)]));
assert!(!before.contains_key(&0), "未回答与已回答但未解析的提及不同");
let later_batch = r#"{"m": [
[40, "point", {"kind": "anchored", "anchor": {"kind": "mention", "id": 0}, "offset": {"count": 1, "unit": "day", "direction": "after"}}, "day"]
]}"#;
let (later, skipped) = parse_interpretation_response(later_batch, &[40]).unwrap();
assert_eq!(skipped, 0);
interpretations.extend(later);
let still_waiting =
resolve_interpretations(&interpretations, |_| DocumentDating::default());
assert_eq!(still_waiting[&2], UNRESOLVED);
let makeup_reply = r#"{"m": [
[0, "point", {"kind": "absolute", "from": {"y": 2024, "m": 1, "d": 1}}, "day"]
]}"#;
let (makeup, skipped) = parse_interpretation_response(makeup_reply, &[0]).unwrap();
assert_eq!(skipped, 0);
interpretations.extend(makeup);
let after = resolve_interpretations(&interpretations, |_| DocumentDating::default());
assert_eq!(
after,
HashMap::from([
(0, day_point("2024-01-01T00:00:00Z", "A")),
(40, day_point("2024-01-02T00:00:00Z", "B")),
(1, day_point("2024-01-03T00:00:00Z", "B")),
(2, day_point("2024-01-04T00:00:00Z", "B")),
])
);
}
#[test]
fn dependency_resolution_keeps_each_mentions_section_context() {
let mut context = ctx_dated(2030, 1, 1);
for (section, year) in [("First report", 2024), ("Second report", 2025)] {
context.entries.push(utopia_extract::time::TimeEntry {
kind: "now".into(),
name: String::new(),
words: year.to_string(),
from: parts(year, Some(1), Some(1)),
to: None,
scope: vec![section.into()],
chunk: None,
char_start: None,
});
}
let document_anchor = |id| Interpretation {
reference: Reference::Anchored {
anchor: Anchor::Document,
offset: None,
},
..absolute_day(id)
};
// 偶数在第一节,奇数在第二节;两条链各自从本节日期起算。
let interpretations = [
next_day(4, 2),
next_day(5, 3),
next_day(2, 0),
next_day(3, 1),
document_anchor(1),
document_anchor(0),
];
let resolved = resolve_interpretations(&interpretations, |id| {
context_at(&context, Some((id % 2) as usize))
});
assert_eq!(
resolved,
HashMap::from([
(0, day_point("2024-01-01T00:00:00Z", "B")),
(2, day_point("2024-01-02T00:00:00Z", "B")),
(4, day_point("2024-01-03T00:00:00Z", "B")),
(1, day_point("2025-01-01T00:00:00Z", "B")),
(3, day_point("2025-01-02T00:00:00Z", "B")),
(5, day_point("2025-01-03T00:00:00Z", "B")),
])
);
}
#[test]
fn dependency_resolution_preserves_dateless_endings_and_unusable_anchors() {
let interpretations = [
next_day(1, 0),
Interpretation {
shape: Shape::Until,
..absolute_day(0)
},
next_day(3, 2),
Interpretation {
shape: Shape::EndedUnknown,
..next_day(2, 2)
},
];
let resolved = resolve_interpretations(&interpretations, |_| DocumentDating::default());
assert_eq!(
resolved,
HashMap::from([
(
0,
Resolved {
from: None,
from_p: None,
..day_point("2024-01-01T00:00:00Z", "A")
}
),
(1, UNRESOLVED),
(
2,
Resolved {
to_p: Some(ENDED_UNKNOWN),
grade: "A",
..UNRESOLVED
}
),
(3, UNRESOLVED),
])
);
}
#[test]
fn parts_give_the_precision_the_words_state() {
assert_eq!(parts_to_time(&parts(2024, None, None)).unwrap().1, "year");
assert_eq!(
parts_to_time(&parts(2024, Some(3), None)).unwrap().1,
"month"
);
let (t, p) = parts_to_time(&parts(2011, Some(3), Some(4))).unwrap();
assert_eq!((t, p), (at("2011-03-04T00:00:00Z"), "day"));
assert!(parts_to_time(&parts(2024, Some(13), None)).is_none());
}
#[test]
fn an_absolute_date_is_grade_a_and_a_point_has_two_equal_ends() {
let i = Interpretation {
id: 0,
shape: Shape::Point,
reference: Reference::Absolute {
from: parts(2011, Some(3), Some(4)),
to: None,
},
granularity: Granularity::Day,
};
let r = resolve_one(&i, &ctx_dated(2026, 9, 2), &HashMap::new());
assert_eq!(r.grade, "A");
assert_eq!(r.from, Some(at("2011-03-04T00:00:00Z")));
assert_eq!(r.to, r.from);
assert_eq!((r.from_p, r.to_p), (Some("day"), Some("day")));
}
#[test]
fn a_bare_year_stays_a_year_even_if_the_model_says_day() {
let i = Interpretation {
id: 0,
shape: Shape::Since,
reference: Reference::Absolute {
from: parts(1987, None, None),
to: None,
},
granularity: Granularity::Day,
};
let r = resolve_one(&i, &ctx_dated(2026, 9, 2), &HashMap::new());
assert_eq!(
(r.from, r.from_p, r.to),
(Some(at("1987-01-01T00:00:00Z")), Some("year"), None)
);
}
#[test]
fn today_and_last_year_anchor_to_the_document_as_grade_b() {
let today = Interpretation {
id: 0,
shape: Shape::Point,
reference: Reference::Anchored {
anchor: Anchor::Document,
offset: None,
},
granularity: Granularity::Day,
};
let r = resolve_one(&today, &ctx_dated(2026, 9, 2), &HashMap::new());
assert_eq!((r.grade, r.from), ("B", Some(at("2026-09-02T00:00:00Z"))));
let last_year = Interpretation {
id: 1,
shape: Shape::Interval,
reference: Reference::Anchored {
anchor: Anchor::Document,
offset: Some(Offset {
count: 1,
unit: Unit::Year,
direction: Direction::Before,
}),
},
granularity: Granularity::Year,
};
let r = resolve_one(&last_year, &ctx_dated(2026, 9, 2), &HashMap::new());
assert_eq!(
(r.grade, r.from, r.from_p),
("B", Some(at("2025-01-01T00:00:00Z")), Some("year"))
);
// 没有文档日期就锚不到
let undated = DocumentDating::default();
assert_eq!(resolve_one(&today, &undated, &HashMap::new()), UNRESOLVED);
}
#[test]
fn a_named_period_is_an_interval_from_the_context() {
let i = Interpretation {
id: 0,
shape: Shape::Point,
reference: Reference::Period {
name: "Fiscal 2027".into(),
from: None,
to: None,
},
granularity: Granularity::Day,
};
let r = resolve_one(&i, &ctx_dated(2026, 9, 2), &HashMap::new());
assert_eq!(r.grade, "B");
assert_eq!(r.from, Some(at("2026-01-26T00:00:00Z")));
assert_eq!(r.to, Some(at("2027-01-25T00:00:00Z")));
// 文中自己写了起止的期间是 A 级
let stated = Interpretation {
reference: Reference::Period {
name: "three months ended July 26, 2026".into(),
from: Some(parts(2026, Some(4), Some(27))),
to: Some(parts(2026, Some(7), Some(26))),
},
..i
};
assert_eq!(
resolve_one(&stated, &DocumentDating::default(), &HashMap::new()).grade,
"A"
);
}
#[test]
fn a_stated_quarter_is_the_three_months_it_names() {
let i = Interpretation {
id: 0,
shape: Shape::Point,
reference: Reference::Absolute {
from: DateParts {
quarter: Some(3),
..parts(2025, None, None)
},
to: None,
},
granularity: Granularity::Month,
};
let r = resolve_one(&i, &DocumentDating::default(), &HashMap::new());
assert_eq!(r.grade, "A");
assert_eq!(r.from, Some(at("2025-07-01T00:00:00Z")));
assert_eq!(r.from_p, Some("month"));
assert_eq!(r.to, Some(at("2025-09-01T00:00:00Z")));
assert_eq!(r.to_p, Some("month"));
}
#[test]
fn two_years_later_follows_the_mention_it_names() {
let mut earlier = HashMap::new();
earlier.insert(
7,
Resolved {
from: Some(at("2019-01-01T00:00:00Z")),
from_p: Some("year"),
to: Some(at("2019-01-01T00:00:00Z")),
to_p: Some("year"),
grade: "A",
},
);
let i = Interpretation {
id: 8,
shape: Shape::Point,
reference: Reference::Anchored {
anchor: Anchor::Mention { id: 7 },
offset: Some(Offset {
count: 2,
unit: Unit::Year,
direction: Direction::After,
}),
},
granularity: Granularity::Year,
};
let r = resolve_one(&i, &DocumentDating::default(), &earlier);
assert_eq!(
(r.grade, r.from, r.from_p),
("B", Some(at("2021-01-01T00:00:00Z")), Some("year"))
);
}
#[test]
fn an_ending_without_a_date_and_a_when_plus_ended_combine() {
let ended = Interpretation {
id: 0,
shape: Shape::EndedUnknown,
reference: Reference::None,
granularity: Granularity::Day,
};
let e = resolve_one(&ended, &DocumentDating::default(), &HashMap::new());
assert_eq!((e.to, e.to_p, e.grade), (None, Some(ENDED_UNKNOWN), "A"));
let since = Resolved {
from: Some(at("2020-01-01T00:00:00Z")),
from_p: Some("year"),
to: None,
to_p: None,
grade: "A",
};
let until = Resolved {
from: Some(at("2024-06-01T00:00:00Z")),
from_p: Some("month"),
to: None,
to_p: None,
grade: "A",
};
let r = combine(Some(since), Some(until));
assert_eq!(
(r.from, r.to, r.to_p),
(since.from, until.from, Some("month"))
);
assert_eq!(combine(None, Some(e)).to_p, Some(ENDED_UNKNOWN));
}
#[test]
fn this_quarter_is_the_whole_quarter_and_the_fiscal_calendar_moves_it() {
let this_quarter = Interpretation {
id: 0,
shape: Shape::Point,
reference: Reference::Anchored {
anchor: Anchor::Document,
offset: Some(Offset {
count: 0,
unit: Unit::Quarter,
direction: Direction::After,
}),
},
granularity: Granularity::Month,
};
// 日历季:9 月 2 日在第三季(7–9 月)
let calendar = DocumentDating {
fiscal_year_end: None,
..ctx_dated(2026, 9, 2)
};
let r = resolve_one(&this_quarter, &calendar, &HashMap::new());
assert_eq!(
(r.from, r.to),
(
Some(at("2026-07-01T00:00:00Z")),
Some(at("2026-09-01T00:00:00Z"))
)
);
assert_eq!(
(r.from_p, r.to_p, r.grade),
(Some("month"), Some("month"), "B")
);
// 财年结束于 1 月 25 日:季首月是 2、5、8、11 月,9 月 2 日在 8–10 月那一季
let r = resolve_one(&this_quarter, &ctx_dated(2026, 9, 2), &HashMap::new());
assert_eq!(
(r.from, r.to),
(
Some(at("2026-08-01T00:00:00Z")),
Some(at("2026-10-01T00:00:00Z"))
)
);
// 上一季度
let last_quarter = Interpretation {
reference: Reference::Anchored {
anchor: Anchor::Document,
offset: Some(Offset {
count: 1,
unit: Unit::Quarter,
direction: Direction::Before,
}),
},
..this_quarter
};
let r = resolve_one(&last_quarter, &calendar, &HashMap::new());
assert_eq!(r.from, Some(at("2026-04-01T00:00:00Z")));
}
#[test]
fn as_of_a_period_means_its_end_and_a_whole_year_is_one_bucket() {
let year_end = Interpretation {
id: 0,
shape: Shape::AsOf,
reference: Reference::Anchored {
anchor: Anchor::Period {
name: "fiscal 2027".into(),
},
offset: None,
},
granularity: Granularity::Day,
};
let r = resolve_one(&year_end, &ctx_dated(2026, 9, 2), &HashMap::new());
assert_eq!((r.from, r.grade), (Some(at("2027-01-25T00:00:00Z")), "B"));
let whole_year = Interpretation {
id: 1,
shape: Shape::Interval,
reference: Reference::Anchored {
anchor: Anchor::Document,
offset: Some(Offset {
count: 0,
unit: Unit::Year,
direction: Direction::After,
}),
},
granularity: Granularity::Year,
};
let r = resolve_one(&whole_year, &ctx_dated(2024, 1, 1), &HashMap::new());
assert_eq!(
(r.from, r.to, r.from_p, r.to_p),
(
Some(at("2024-01-01T00:00:00Z")),
Some(at("2024-01-01T00:00:00Z")),
Some("year"),
Some("year")
)
);
}
#[test]
fn a_period_with_one_stated_bound_writes_only_that_bound() {
let ended = Interpretation {
id: 0,
shape: Shape::Interval,
reference: Reference::Period {
name: "three months ended June 30, 2019".into(),
from: None,
to: Some(parts(2019, Some(6), Some(30))),
},
granularity: Granularity::Day,
};
let r = resolve_one(&ended, &DocumentDating::default(), &HashMap::new());
assert_eq!(
(r.from, r.to, r.grade),
(None, Some(at("2019-06-30T00:00:00Z")), "A")
);
}
#[test]
fn month_arithmetic_clamps_to_the_month_end() {
let t = at("2024-03-31T00:00:00Z");
let back = shift(
t,
&Offset {
count: 1,
unit: Unit::Month,
direction: Direction::Before,
},
)
.unwrap();
assert_eq!(back, at("2024-02-29T00:00:00Z"));
let q = shift(
t,
&Offset {
count: 1,
unit: Unit::Quarter,
direction: Direction::After,
},
)
.unwrap();
assert_eq!(q, at("2024-06-30T00:00:00Z"));
}
}