Make freshness and timing drive city-card trust

Users need to know whether a city can be acted on before reading the full explanation. City cards now expose METAR or official-observation freshness, model update timing, market quote freshness, and AI state in a dedicated trust block, while the calendar view groups rows into action-oriented timing buckets with a single reason per city.

Constraint: Keep the existing card and calendar data contracts; derive freshness and action reasons from fields already present in the frontend payload.
Rejected: Add another long explanatory paragraph | it would repeat the same trust problem instead of making the first glance clearer.
Confidence: high
Scope-risk: moderate
Reversibility: clean
Tested: npm run build
Not-tested: Live browser visual QA with stale METAR and delayed quote examples.

frontend/components/dashboard/scan-terminal/CalendarView.tsx

@@ -3,7 +3,10 @@ import { getWindowPhaseMeta } from "@/components/dashboard/OpportunityTable";
 import type { ScanOpportunityRow } from "@/lib/dashboard-types";
 import { getLocalizedCityName } from "@/lib/dashboard-home-copy";
 import { formatTemperatureValue } from "@/lib/dashboard-utils";
-import { formatShortDate, getPeakCountdownMeta } from "@/components/dashboard/scan-terminal/decision-utils";
+import {
+  formatShortDate,
+  getPeakCountdownMeta,
+} from "@/components/dashboard/scan-terminal/decision-utils";
 
 const CALENDAR_UPCOMING_HORIZON_MINUTES = 12 * 60;
 const CALENDAR_POST_PEAK_GRACE_MINUTES = 3 * 60;
@@ -16,6 +19,13 @@ type CalendarMeta = ReturnType<typeof getPeakCountdownMeta> & {
   endAtMs?: number | null;
 };
 
+type CalendarActionGroup = {
+  key: "now" | "next" | "later" | "past";
+  label: string;
+  subtitle: string;
+  sort: number;
+};
+
 function normalizeCalendarCityKey(value?: string | null) {
   return String(value || "")
     .trim()
@@ -154,6 +164,133 @@ function isCalendarActionable(row: ScanOpportunityRow, meta: CalendarMeta, nowMs
   return startDelta >= 0 && startDelta <= CALENDAR_UPCOMING_HORIZON_MINUTES;
 }
 
+function getCalendarActionGroup(
+  row: ScanOpportunityRow,
+  meta: CalendarMeta,
+  nowMs: number,
+  locale: string,
+): CalendarActionGroup {
+  const isEn = locale === "en-US";
+  const phase = String(row.window_phase || "").toLowerCase();
+  const startDelta =
+    meta.startAtMs != null ? (meta.startAtMs - nowMs) / MINUTE_MS : finiteCalendarNumber(row.minutes_until_peak_start);
+  const endDelta =
+    meta.endAtMs != null ? (meta.endAtMs - nowMs) / MINUTE_MS : finiteCalendarNumber(row.minutes_until_peak_end);
+  const isPast =
+    phase === "post_peak" ||
+    (endDelta != null && endDelta < 0) ||
+    meta.key === "past";
+  if (isPast) {
+    return {
+      key: "past",
+      label: isEn ? "Past peak · confirm" : "已过峰值，等待确认",
+      subtitle: isEn ? "Check whether a new high printed; avoid chasing if it did not." : "确认是否刷新高点；若无新高，避免追高。",
+      sort: 3,
+    };
+  }
+  const isNow =
+    phase === "active_peak" ||
+    (startDelta != null && startDelta <= 60) ||
+    meta.key === "active";
+  if (isNow) {
+    return {
+      key: "now",
+      label: isEn ? "Watch now" : "现在可看",
+      subtitle: isEn ? "Peak window is live or close enough to require immediate checks." : "峰值窗口正在进行或即将开始，需要马上核对。",
+      sort: 0,
+    };
+  }
+  if (startDelta != null && startDelta <= 180) {
+    return {
+      key: "next",
+      label: isEn ? "In 1-3 hours" : "1-3 小时内",
+      subtitle: isEn ? "Prepare the setup and wait for the next observation." : "提前准备，只等下一轮观测确认。",
+      sort: 1,
+    };
+  }
+  return {
+    key: "later",
+    label: isEn ? "Later today" : "今天稍后",
+    subtitle: isEn ? "Keep on the board, but do not spend attention yet." : "先放在行动面板，不需要立刻盯盘。",
+    sort: 2,
+  };
+}
+
+function getCalendarModelUpper(row: ScanOpportunityRow) {
+  const values = [
+    finiteCalendarNumber(row.cluster_core_high),
+    ...Object.values(row.model_cluster_sources || {}).map((value) => finiteCalendarNumber(value)),
+  ].filter((value): value is number => value != null);
+  return values.length ? Math.max(...values) : null;
+}
+
+function getCalendarModelLower(row: ScanOpportunityRow) {
+  const values = [
+    finiteCalendarNumber(row.cluster_core_low),
+    ...Object.values(row.model_cluster_sources || {}).map((value) => finiteCalendarNumber(value)),
+  ].filter((value): value is number => value != null);
+  return values.length ? Math.min(...values) : null;
+}
+
+function firstSentence(value?: string | null) {
+  const text = String(value || "").trim();
+  if (!text) return "";
+  const match = text.match(/^.*?[。.!?？](?:\s|$)/);
+  return (match?.[0] || text).trim();
+}
+
+function buildCalendarCoreReason(
+  row: ScanOpportunityRow,
+  group: CalendarActionGroup,
+  locale: string,
+) {
+  const isEn = locale === "en-US";
+  const tempSymbol = row.temp_symbol || "°C";
+  const currentTemp = finiteCalendarNumber(row.current_temp ?? row.metar_context?.last_temp);
+  const modelUpper = getCalendarModelUpper(row);
+  const modelLower = getCalendarModelLower(row);
+  const modelSpread =
+    modelUpper != null && modelLower != null ? modelUpper - modelLower : null;
+  if (currentTemp != null && modelUpper != null && currentTemp > modelUpper + 0.2) {
+    return isEn
+      ? `Observed ${formatTemperatureValue(currentTemp, tempSymbol)} is above the model upper bound; watch whether the high keeps revising up.`
+      : `实测已高于模型上沿，需关注是否继续上修`;
+  }
+  if (group.key === "past") {
+    return isEn
+      ? "Peak window has passed; avoid chasing if no new high prints."
+      : "峰值窗口已过，若无新高应避免追高";
+  }
+  if (row.metar_status?.stale_for_today || row.metar_context?.stale_for_today) {
+    return isEn
+      ? "METAR is stale, so use it as background only."
+      : "METAR 已过旧，仅作背景参考";
+  }
+  if (currentTemp != null && modelLower != null && currentTemp < modelLower - 0.5) {
+    return isEn
+      ? "Observed temperature is still below the model core; wait for the next report."
+      : "实测仍低于模型核心区，等待下一报文确认";
+  }
+  if (Number(row.cluster_model_count || 0) >= 4 && modelSpread != null && modelSpread <= 2) {
+    return isEn
+      ? "Models are tightly aligned; the next observation should decide direction."
+      : "模型高度一致，等待下一报文确认方向";
+  }
+  const aiReason = firstSentence(
+    isEn
+      ? row.ai_watchlist_reason_en || row.ai_forecast_match_reason_en || row.ai_reason_en || row.ai_city_thesis_en
+      : row.ai_watchlist_reason_zh || row.ai_forecast_match_reason_zh || row.ai_reason_zh || row.ai_city_thesis_zh,
+  );
+  if (aiReason) return aiReason;
+  return group.key === "now"
+    ? isEn
+      ? "Peak timing is close; open the card and verify live evidence."
+      : "峰值时间接近，打开卡片核对实况证据"
+    : isEn
+      ? "Keep it on the action board until the next observation."
+      : "先放入行动面板，等待下一轮观测";
+}
+
 export function CalendarView({
   rows,
   locale,
@@ -181,31 +318,38 @@ export function CalendarView({
   }, []);
 
   const groups = useMemo(() => {
-    const order = ["active", "next", "today", "later", "past"];
     const byPhase = new Map<
       string,
       {
         label: string;
+        subtitle: string;
         sort: number;
-        items: Array<{ row: ScanOpportunityRow; meta: CalendarMeta }>;
+        items: Array<{ row: ScanOpportunityRow; meta: CalendarMeta; reason: string }>;
       }
     >();
     dedupeCalendarRows(rows).forEach((row) => {
       const meta = buildCalendarMeta(row, locale, snapshotMs, nowMs);
       if (!isCalendarActionable(row, meta, nowMs)) return;
-      const current = byPhase.get(meta.key) || {
-        label: meta.groupLabel,
-        sort: order.indexOf(meta.key) >= 0 ? order.indexOf(meta.key) : order.length,
+      const actionGroup = getCalendarActionGroup(row, meta, nowMs, locale);
+      const current = byPhase.get(actionGroup.key) || {
+        label: actionGroup.label,
+        subtitle: actionGroup.subtitle,
+        sort: actionGroup.sort,
         items: [],
       };
-      current.items.push({ row, meta });
-      byPhase.set(meta.key, current);
+      current.items.push({
+        row,
+        meta,
+        reason: buildCalendarCoreReason(row, actionGroup, locale),
+      });
+      byPhase.set(actionGroup.key, current);
     });
     return Array.from(byPhase.entries())
       .sort(([, left], [, right]) => left.sort - right.sort)
       .map(([key, group]) => ({
         key,
         label: group.label,
+        subtitle: group.subtitle,
         items: group.items.sort((left, right) => {
           if (left.meta.sort !== right.meta.sort) return left.meta.sort - right.meta.sort;
           return Number(right.row.edge_percent || 0) - Number(left.row.edge_percent || 0);
@@ -233,9 +377,7 @@ export function CalendarView({
             <div>
               <div className="scan-calendar-date">{group.label}</div>
               <div className="scan-calendar-subtitle">
-                {locale === "en-US"
-                  ? "Ordered by DEB peak-window countdown"
-                  : "按 DEB 峰值窗口倒计时排序"}
+                {group.subtitle}
               </div>
             </div>
             <div className="scan-calendar-count">
@@ -243,7 +385,7 @@ export function CalendarView({
             </div>
           </div>
           <div className="scan-calendar-grid">
-            {group.items.map(({ row, meta }) => (
+            {group.items.map(({ row, meta, reason }) => (
               <button
                 key={row.id}
                 type="button"
@@ -275,6 +417,7 @@ export function CalendarView({
                     {meta.cityWindowLabel || meta.detail}
                   </small>
                 </div>
+                <p className="scan-calendar-reason">{reason}</p>
                 <div className="scan-calendar-action">
                   <span>{locale === "en-US" ? "DEB high" : "DEB 预测高点"}</span>
                   <b>