per(scheduler): 将内联的cron-parser替换为基于服务的nextTick计算

- 提取cron间隔/下次触发逻辑到可重用的服务函数中
- 计算scheduledAt(纯cron)和estimatedAt(上次tick + 间隔)

Author: 2512132839

backend/src/routes/scheduledRoutes.js

@@ -16,32 +16,13 @@ import {
   getScheduledJobsHourlyAnalytics,
 } from "../services/scheduledJobRunService.js";
 import { scheduledTaskRegistry } from "../scheduled/ScheduledTaskRegistry.js";
-import { CronExpressionParser } from "cron-parser";
 import { isCloudflareWorkerEnvironment } from "../utils/environmentUtils.js";
-import { getSchedulerTickState } from "../services/schedulerTickerStateService.js";
+import { computeSchedulerTickerNextTick, getSchedulerTickState } from "../services/schedulerTickerStateService.js";
 
 // 调度任务相关路由（仅 Docker/Node 环境使用 + 管理员配置）
 const scheduledRoutes = new Hono();
 const requireAdmin = usePolicy("admin.all");
 
-/**
- * 从 cron 规则计算“下一次触发时间”（UTC ISO）
- * @param {string} cron
- * @param {string} nowIso
- * @returns {{ nextFireAt: string | null, error: string | null }}
- */
-function computeNextFireAtFromCron(cron, nowIso) {
-  if (!cron || typeof cron !== "string") {
-    return { nextFireAt: null, error: "cron 为空" };
-  }
-  try {
-    const expr = CronExpressionParser.parse(cron, { currentDate: nowIso });
-    return { nextFireAt: expr.next().toDate().toISOString(), error: null };
-  } catch (e) {
-    return { nextFireAt: null, error: e?.message || String(e) };
-  }
-}
-
 // ==================== Handler 类型 API ====================
 
 // 获取所有 handler 类型列表（管理员）
@@ -240,23 +221,16 @@ scheduledRoutes.get("/api/admin/scheduled/ticker", requireAdmin, async (c) => {
         ? "default"
         : "missing";
 
-  // 计算“下一次触发时间”
-  let nextFireAt = null;
-  let cronParseError = null;
   const tickState = await getSchedulerTickState(c.env.DB);
   const observedCron = tickState.lastCron || null;
   // 1) lastCron（来自“真实触发”的 cron）
   // 2) Docker 环境回退到 configuredCron（因为 Docker 的触发器就是靠它配置的）
   // 3) Workers 环境没有 lastCron 前，无法计算 next（只能等待首次真实触发）
   const activeCron = observedCron || (runtime === "docker" ? configuredCron : null);
-  if (activeCron) {
-    const res = computeNextFireAtFromCron(activeCron, nowIso);
-    nextFireAt = res.nextFireAt;
-    cronParseError = res.error;
-  }
 
   const lastTickMs = tickState.lastMs;
   const lastTickAt = lastTickMs ? new Date(lastTickMs).toISOString() : null;
+  const nextTick = computeSchedulerTickerNextTick({ activeCron, nowIso, lastTickMs });
 
   return jsonOk(
     c,
@@ -276,13 +250,16 @@ scheduledRoutes.get("/api/admin/scheduled/ticker", requireAdmin, async (c) => {
         source: lastTickMs ? "system_settings" : null,
       },
       nextTick: {
-        at: nextFireAt,
-        cronParseError,
+        at: nextTick.at,
+        scheduledAt: nextTick.scheduledAt,
+        estimatedAt: nextTick.estimatedAt,
+        intervalSec: nextTick.intervalSec,
+        cronParseError: nextTick.cronParseError,
       },
       note:
         runtime === "cloudflare" && !observedCron
           ? "尚未观察到平台触发器的首次真实触发：暂时无法计算预计下次触发时间；首次触发后会自动显示。"
-          : "提示：这里显示的是“预计时间”（按 cron 规则计算），实际触发可能存在延迟；到点后可点右下角刷新校准。",
+          : "提示：at 优先按“上次真实触发 + 间隔”估算（可能包含延迟）；scheduledAt 是 cron 的计划时间（通常是整分/整 5 分钟）。到点后可点右下角刷新校准。",
     },
     "获取平台触发器状态成功",
   );

backend/src/services/schedulerTickerStateService.js

@@ -1,5 +1,6 @@
 import { DbTables } from "../constants/index.js";
 import { SETTING_FLAGS, SETTING_GROUPS, SETTING_TYPES } from "../constants/settings.js";
+import { CronExpressionParser } from "cron-parser";
 
 // 用于存储“外部触发器（CF/Docker tick）真实触发状态”的固定 key
 // - 只维护 1 行（system_settings.key 为主键）
@@ -97,3 +98,89 @@ export async function upsertSchedulerTickState(db, state) {
     });
   }
 }
+
+/**
+ * 从 cron 估算“触发间隔秒数”
+ *
+ *
+ * 用 cron-parser 连续取两次 next，做差值。
+ *
+ * @param {string|null} cron
+ * @param {string} nowIso
+ * @returns {{ intervalSec: number|null, error: string|null }}
+ */
+export function computeCronIntervalSec(cron, nowIso) {
+  const raw = typeof cron === "string" ? cron.trim() : "";
+  if (!raw) return { intervalSec: null, error: "cron 为空" };
+  try {
+    const expr = CronExpressionParser.parse(raw, { currentDate: nowIso });
+    const next1 = expr.next().toDate();
+    const next2 = expr.next().toDate();
+    const diffMs = next2.getTime() - next1.getTime();
+    const intervalSec = diffMs > 0 ? Math.floor(diffMs / 1000) : null;
+    return { intervalSec, error: null };
+  } catch (e) {
+    return { intervalSec: null, error: e?.message || String(e) };
+  }
+}
+
+/**
+ * 从 cron 计算下一次“计划触发时间”（UTC ISO）
+ * @param {string|null} cron
+ * @param {string} nowIso
+ * @returns {{ scheduledAt: string|null, error: string|null }}
+ */
+export function computeNextScheduledAtFromCron(cron, nowIso) {
+  const raw = typeof cron === "string" ? cron.trim() : "";
+  if (!raw) return { scheduledAt: null, error: "cron 为空" };
+  try {
+    const expr = CronExpressionParser.parse(raw, { currentDate: nowIso });
+    const scheduledAt = expr.next().toDate().toISOString();
+    return { scheduledAt, error: null };
+  } catch (e) {
+    return { scheduledAt: null, error: e?.message || String(e) };
+  }
+}
+
+/**
+ * 计算“平台触发器 ticker”的 nextTick（给 /api/admin/scheduled/ticker 用）
+ *
+ * - at：给前端倒计时用的预计时间（优先 estimatedAt）
+ * - scheduledAt：按 cron 规则算出来的“计划时间”（经常是整分/整 5 分钟）
+ * - estimatedAt：按 lastTickMs + intervalSec 推算出来的“体感时间”
+ * - intervalSec：从 cron 估算出来的间隔
+ *
+ * @param {{ activeCron: string|null, nowIso: string, lastTickMs: number|null }} params
+ */
+export function computeSchedulerTickerNextTick({ activeCron, nowIso, lastTickMs }) {
+  const cron = typeof activeCron === "string" && activeCron.trim() ? activeCron.trim() : null;
+
+  const scheduledRes = computeNextScheduledAtFromCron(cron, nowIso);
+  const intervalRes = computeCronIntervalSec(cron, nowIso);
+
+  const intervalSec = intervalRes.intervalSec;
+  const hasLastTick =
+    typeof lastTickMs === "number" && Number.isFinite(lastTickMs) && lastTickMs > 0;
+
+  const canEstimate =
+    hasLastTick &&
+    typeof intervalSec === "number" &&
+    Number.isFinite(intervalSec) &&
+    intervalSec > 0;
+
+  const estimatedAt = canEstimate
+    ? new Date(lastTickMs + intervalSec * 1000).toISOString()
+    : null;
+
+  const at = estimatedAt || scheduledRes.scheduledAt || null;
+
+  const cronParseError = scheduledRes.error || intervalRes.error || null;
+
+  return {
+    at,
+    scheduledAt: scheduledRes.scheduledAt,
+    estimatedAt,
+    intervalSec,
+    cronParseError,
+  };
+}