From 962bef227692c41269149248ca77710e74af13a0 Mon Sep 17 00:00:00 2001
From: xfy <i@rua.plus>
Date: Mon, 29 Jun 2026 15:42:40 +0800
Subject: [PATCH] fix(ssr-cache): log generation bump and effective
 SSR_CACHE_SECS
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Dioxus 0.7 的增量渲染器把 IncrementalRenderer 封装在 FullstackState 内部
(pub(crate)),应用侧无法拿到句柄调用 invalidate(),世代号机制只是"未来就绪"
状态。实际失效仍依赖 SSR_CACHE_SECS 兜底 TTL,但此前写入路径完全静默,部署者
无法从日志判断"文章已写入、只是 SSR 缓存未失效",易误判成 DB/发布问题。

- bump_global_generation() 增加 info 日志(带 new_generation),诚实说明 Dioxus
  0.7 不读取此值、需等 TTL 过期。
- main.rs 启动时打印生效的 SSR_CACHE_SECS(滞后上界),提示可调小缩短滞后。
---
 src/main.rs      | 22 +++++++++++++---------
 src/ssr_cache.rs | 15 +++++++++++++--
 2 files changed, 26 insertions(+), 11 deletions(-)

diff --git a/src/main.rs b/src/main.rs
index 3a541ba..59c32a3 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -325,16 +325,20 @@ fn main() {
             // 配置增量渲染缓存，默认缓存 3600 秒，可通过 SSR_CACHE_SECS 覆盖。
             // 注意：src/ssr_cache.rs 中的世代号是未来就绪基础设施，当前并不会使
             // Dioxus 0.7 的 SSR 缓存实际失效（Dioxus 未暴露相应 API）。在 API 可用
-            // 之前，SSR_CACHE_SECS 仍是唯一有效的兜底 TTL。
+            // 之前，SSR_CACHE_SECS 仍是唯一有效的兜底 TTL——它就是内容写入后
+            // SSR 页面可见滞后的上界。
+            let ssr_cache_secs = std::env::var("SSR_CACHE_SECS")
+                .ok()
+                .and_then(|s| s.parse().ok())
+                .unwrap_or(3600);
+            tracing::info!(
+                ssr_cache_secs,
+                "增量渲染缓存生效（写入后内容可见滞后的上界）；\
+                 调小可缩短滞后，代价是 SSR 重渲染更频繁"
+            );
             let config = ServeConfig::builder().incremental(
-                dioxus::server::IncrementalRendererConfig::default().invalidate_after(
-                    std::time::Duration::from_secs(
-                        std::env::var("SSR_CACHE_SECS")
-                            .ok()
-                            .and_then(|s| s.parse().ok())
-                            .unwrap_or(3600),
-                    ),
-                ),
+                dioxus::server::IncrementalRendererConfig::default()
+                    .invalidate_after(std::time::Duration::from_secs(ssr_cache_secs)),
             );
 
             // SSR 世代号中间件：把当前全局世代号注入请求扩展，并对 GET 请求的
diff --git a/src/ssr_cache.rs b/src/ssr_cache.rs
index 9e8e49c..b78ec1f 100644
--- a/src/ssr_cache.rs
+++ b/src/ssr_cache.rs
@@ -41,10 +41,21 @@ static GLOBAL_GENERATION: LazyLock<AtomicU64> = LazyLock::new(AtomicU64::default
 pub struct SsrGeneration(pub u64);
 
 /// 原子递增并返回新的全局世代号。
+///
+/// 任何文章写入操作都会调用本函数,标记 SSR 渲染结果已过期。当前 Dioxus 0.7
+/// 不读取此世代号(详见模块文档),实际失效仍依赖 `SSR_CACHE_SECS` 兜底 TTL。
+/// 此处打一条 info 日志,既证明写入路径已执行,也提醒部署者此处存在滞后——
+/// 避免"我改了文章怎么没变"被误判成 DB/发布链路问题。
 pub fn bump_global_generation() -> u64 {
-    GLOBAL_GENERATION
+    let new = GLOBAL_GENERATION
         .fetch_add(1, Ordering::SeqCst)
-        .wrapping_add(1)
+        .wrapping_add(1);
+    tracing::info!(
+        new_generation = new,
+        "SSR 世代号已递增（写入路径触发）。注意：Dioxus 0.7 不读取此值，\
+         SSR 缓存需等待 SSR_CACHE_SECS 过期后才反映新内容"
+    );
+    new
 }
 
 /// 返回当前全局世代号。