diff --git a/server-rs/crates/module-runtime/src/civil_calendar.rs b/server-rs/crates/module-runtime/src/civil_calendar.rs
index 036bf1a2d..5b43da801 100644
--- a/server-rs/crates/module-runtime/src/civil_calendar.rs
+++ b/server-rs/crates/module-runtime/src/civil_calendar.rs
@@ -34,6 +34,10 @@ pub fn days_from_civil(year: i32, month: u8, day: u8) -> i64 {
 }
 
 /// 1970-01-01 起的日序号 → 公历年月日。
+///
+/// 只接受由 [`days_from_civil`] 产生、或落在公历可表示范围内的日序号（约 ±7.9e11 天，即
+/// `i32` 年份区间）。内部用 `saturating_add` 防止中间结果溢出：传入远小于/远大于该范围的
+/// 极端值时不会 panic，但会饱和并返回无意义的年月日，因此调用方需自行保证输入范围。
 pub fn civil_from_days(date_key: i64) -> (i32, u8, u8) {
     // 中文注释：days_from_civil 的反向算法，避免依赖运行环境时区。
     let z = date_key.saturating_add(719_468);