fix: 缓存 API 日期加 3 天宽限期，超期降级回 today

宽限期内信任缓存（避免周末/假日误报），超过 3 天降级回
today 比较（提示可能有新数据），兼顾两端场景。

Author: Astro-Han

quantclass_sync_internal/data_query.py

@@ -20,6 +20,9 @@
 # 状态颜色阈值（自然日）
 _DAYS_YELLOW = 1  # >= 1 天落后: 黄色
 _DAYS_RED = 4     # >= 4 天落后: 红色
+# 缓存宽限期：上次同步记录的 API 日期在此天数内视为可信，超出后降级回 today。
+# 3 天覆盖普通周末和含周一假期的三天长周末。
+_STALE_GRACE_DAYS = 3
 
 
 def _parse_date(date_str: Optional[str]) -> Optional[date]:
@@ -82,15 +85,16 @@ def get_products_overview(
         local_date = read_local_timestamp_date(data_root, product)
         last = last_results.get(product, {})
         last_status = last.get("status", "")
-        last_reason = last.get("reason_code", "")
-        # 门控确认已追平（up_to_date）且本地有数据 → 直接视为 0 天落后
-        # 其他情况用上次记录的 API 日期作为参考；
-        # 旧安装无 date_time 字段时 _parse_date 返回 None，降级回 today（等价修复前行为）
-        if last_reason == "up_to_date" and local_date is not None:
-            behind = 0
-        else:
-            ref_date = _parse_date(last.get("date_time", "")) or today
-            behind = _days_behind(local_date, ref_date)
+        # 用缓存的 API 日期作为参考，避免周末/假日误报落后；
+        # 缓存超过宽限期或无缓存时降级回 today，提示可能有新数据
+        cached_api_date = _parse_date(last.get("date_time", ""))
+        cache_fresh = (
+            cached_api_date is not None
+            and today is not None
+            and (today - cached_api_date).days <= _STALE_GRACE_DAYS
+        )
+        ref_date = cached_api_date if cache_fresh else today
+        behind = _days_behind(local_date, ref_date)
         color = _status_color(behind, last_status)
         overview.append({
             "name": product,

tests/test_data_query.py

@@ -214,6 +214,33 @@ def test_overview_up_to_date_reason_shows_green(self):
         self.assertEqual(overview[0]["days_behind"], 0)
         self.assertEqual(overview[0]["status_color"], "green")
 
+    def test_overview_stale_cache_degrades_to_today(self):
+        """缓存的 API 日期超过宽限期后，降级回 today 比较。
+
+        回归测试：防止长期未同步的产品永远显示绿色。
+        """
+        self._write_timestamp("stock-trading-data", "2026-03-10")
+        self._write_report("run_report_20260310_update.json", [
+            {"product": "stock-trading-data", "status": "ok", "reason_code": "ok",
+             "error": "", "date_time": "2026-03-10"},
+        ])
+
+        import unittest.mock
+        with unittest.mock.patch(
+            "quantclass_sync_internal.data_query.report_dir_path",
+            return_value=self.log_dir,
+        ):
+            # 4 天后查看（超出 3 天宽限期），应降级回 today
+            overview = get_products_overview(
+                self.data_root,
+                ["stock-trading-data"],
+                today=date(2026, 3, 14),
+            )
+
+        # today - local = 4 天，应显示红色
+        self.assertEqual(overview[0]["days_behind"], 4)
+        self.assertEqual(overview[0]["status_color"], "red")
+
     def test_overview_with_error_product(self):
         """产品上次失败时应为红色。"""
         self._write_timestamp("stock-fin-data-xbx", "2026-03-13")