Add chart freshness diagnostics

2026-06-10 15:34:34 +08:00
parent ba012736c9
commit 5a7d302d11
14 changed files with 833 additions and 42 deletions
@@ -33,6 +33,15 @@ function parseRequestedCities(req: NextRequest) {
 }

 function buildCityDetailBatchTimeoutPayload(requestedCities: string[]) {
+  const city_status = Object.fromEntries(
+    requestedCities.map((city) => [
+      city,
+      {
+        status: "proxy_timeout",
+        duration_ms: null,
+      },
+    ]),
+  );
  return {
    cities: requestedCities,
    details: {},
@@ -40,6 +49,18 @@ function buildCityDetailBatchTimeoutPayload(requestedCities: string[]) {
    missing: requestedCities,
    partial: true,
    timeout: true,
+    diagnostics: {
+      version: 1,
+      response_source: "next_proxy_timeout",
+      partial: true,
+      partial_reason: "proxy_timeout",
+      requested_count: requestedCities.length,
+      completed_count: 0,
+      missing_count: requestedCities.length,
+      error_count: 0,
+      proxy_timeout_ms: DETAIL_BATCH_PROXY_TIMEOUT_MS,
+      city_status,
+    },
  };
 }

@@ -33,6 +33,7 @@ import {
  mergeRowObservationIntoHourly,
  normObs,
  prefersHighFrequencyRunwayResolution,
+  readCityDetailBatchDiagnostics,
  readSessionCache,
  selectCompactSecondaryTemp,
  selectDisplayRunwayTemp,
@@ -134,6 +135,115 @@ function rowObservationSignature(row: ScanOpportunityRow | null) {
  return hasObservation ? pieces.map((piece) => String(piece ?? "")).join("|") : "";
 }

+type ChartDetailStatus = "idle" | "loading" | "fresh" | "stale_cache" | "degraded";
+type ChartDetailSource =
+  | "none"
+  | "memory_cache"
+  | "session_cache"
+  | "network"
+  | "force_refresh"
+  | "partial_or_timeout";
+
+type ChartFreshnessState = {
+  rowAppliedAtMs: number | null;
+  rowObservationTime: string | null;
+  ssePatchAppliedAtMs: number | null;
+  sseObservedAt: string | null;
+  sseRevision: number | null;
+  sseEmittedAtMs: number | null;
+  sseServerToClientLatencySec: number | null;
+  sseCollectorToClientLatencySec: number | null;
+  sseSourceToCollectorLatencySec: number | null;
+  detailRequestedAtMs: number | null;
+  detailResolvedAtMs: number | null;
+  detailErrorAtMs: number | null;
+  detailStatus: ChartDetailStatus;
+  detailSource: ChartDetailSource;
+};
+
+function createChartFreshnessState(
+  overrides: Partial<ChartFreshnessState> = {},
+): ChartFreshnessState {
+  return {
+    rowAppliedAtMs: null,
+    rowObservationTime: null,
+    ssePatchAppliedAtMs: null,
+    sseObservedAt: null,
+    sseRevision: null,
+    sseEmittedAtMs: null,
+    sseServerToClientLatencySec: null,
+    sseCollectorToClientLatencySec: null,
+    sseSourceToCollectorLatencySec: null,
+    detailRequestedAtMs: null,
+    detailResolvedAtMs: null,
+    detailErrorAtMs: null,
+    detailStatus: "idle",
+    detailSource: "none",
+    ...overrides,
+  };
+}
+
+function ageSeconds(fromMs: number | null | undefined, nowMs: number) {
+  if (!Number.isFinite(fromMs)) return null;
+  return Math.max(0, Math.round((nowMs - Number(fromMs)) / 1000));
+}
+
+function buildChartFreshnessContext(state: ChartFreshnessState, nowMs = Date.now()) {
+  const rowAgeSec = ageSeconds(state.rowAppliedAtMs, nowMs);
+  const sseAgeSec = ageSeconds(state.ssePatchAppliedAtMs, nowMs);
+  let livePath: "none" | "row" | "sse" = "none";
+  let liveAgeSec: number | null = null;
+  if (rowAgeSec !== null) {
+    livePath = "row";
+    liveAgeSec = rowAgeSec;
+  }
+  if (sseAgeSec !== null && (liveAgeSec === null || sseAgeSec <= liveAgeSec)) {
+    livePath = "sse";
+    liveAgeSec = sseAgeSec;
+  }
+
+  return {
+    live_path: livePath,
+    live_age_sec: liveAgeSec,
+    row_applied_age_sec: rowAgeSec,
+    row_observation_time: state.rowObservationTime,
+    sse_patch_age_sec: sseAgeSec,
+    sse_observed_at: state.sseObservedAt,
+    sse_revision: state.sseRevision,
+    sse_emitted_at_ms: state.sseEmittedAtMs,
+    sse_server_to_client_latency_sec: state.sseServerToClientLatencySec,
+    sse_collector_to_client_latency_sec: state.sseCollectorToClientLatencySec,
+    sse_source_to_collector_latency_sec: state.sseSourceToCollectorLatencySec,
+    detail_status: state.detailStatus,
+    detail_source: state.detailSource,
+    detail_request_age_sec: ageSeconds(state.detailRequestedAtMs, nowMs),
+    detail_age_sec: ageSeconds(state.detailResolvedAtMs, nowMs),
+    detail_error_age_sec: ageSeconds(state.detailErrorAtMs, nowMs),
+  };
+}
+
+function rowObservationTimeForFreshness(row: ScanOpportunityRow | null) {
+  if (!row) return null;
+  const metarContext = row.metar_context || null;
+  return String(
+    metarContext?.airport_obs_time ||
+      metarContext?.last_observation_time ||
+      metarContext?.last_time ||
+      row.local_time ||
+      "",
+  ).trim() || null;
+}
+
+function patchObservationTimeForFreshness(patch: { changes?: Record<string, unknown> } | null | undefined) {
+  const changes = patch?.changes || {};
+  return String(
+    changes.observed_at_utc ||
+      changes.observed_at_local ||
+      changes.obs_time ||
+      "",
+  ).trim() || null;
+}
+
 function getWundergroundDailyHigh(hourly: HourlyForecast) {
  return validNumber(hourly?.wundergroundCurrent?.max_so_far) ?? null;
 }
@@ -458,6 +568,9 @@ export function LiveTemperatureThresholdChart({
  const [detailError, setDetailError] = useState<string | null>(null);
  const [detailRetryNonce, setDetailRetryNonce] = useState(0);
  const [showingStaleDetail, setShowingStaleDetail] = useState(false);
+  const [chartFreshness, setChartFreshness] = useState<ChartFreshnessState>(() =>
+    createChartFreshnessState(),
+  );
  const hasLoadedHourlyDetailRef = useRef(false);
  const chartVisibilityRef = useRef<HTMLDivElement | null>(null);
  const lastPatchAtRef = useRef<number>(Date.now());
@@ -486,8 +599,28 @@ export function LiveTemperatureThresholdChart({
    formatCityLocalDate(row?.tz_offset_seconds),
  );
  const currentRowObservationSignature = useMemo(() => rowObservationSignature(row), [row]);
+  const markDetailRequest = useCallback((source: ChartDetailSource) => {
+    setChartFreshness((prev) => ({
+      ...prev,
+      detailRequestedAtMs: Date.now(),
+      detailStatus: "loading",
+      detailSource: source,
+    }));
+  }, []);
+  const markDetailDegraded = useCallback((options?: { showUserError?: boolean }) => {
+    if (options?.showUserError) {
+      setDetailError(isEn ? "Detail temporarily unavailable." : "详情暂不可用");
+    }
+    setChartFreshness((prev) => ({
+      ...prev,
+      detailErrorAtMs: Date.now(),
+      detailStatus: "degraded",
+      detailSource: "partial_or_timeout",
+    }));
+  }, [isEn]);

  useEffect(() => {
+    const now = Date.now();
    setUserToggledKeys({});
    setZoomRange(null);
    setViewMode("full");
@@ -499,8 +632,15 @@ export function LiveTemperatureThresholdChart({
    setDetailError(null);
    setDetailRetryNonce(0);
    setShowingStaleDetail(false);
+    setChartFreshness(createChartFreshnessState({
+      rowAppliedAtMs: currentRowObservationSignature ? now : null,
+      rowObservationTime: rowObservationTimeForFreshness(row),
+      detailRequestedAtMs: city && detailLoadDelayMs === 0 ? now : null,
+      detailStatus: city && detailLoadDelayMs === 0 ? "loading" : "idle",
+      detailSource: city && detailLoadDelayMs === 0 ? "network" : "none",
+    }));
    hasLoadedHourlyDetailRef.current = false;
-    lastPatchAtRef.current = Date.now();
+    lastPatchAtRef.current = now;
    lastAppliedPatchRevisionRef.current = 0;
    lastProbabilityRefreshAtRef.current = 0;
    lastForegroundRefreshAtRef.current = 0;
@@ -551,6 +691,7 @@ export function LiveTemperatureThresholdChart({

  const applySuccessfulHourlyDetail = useCallback((data: HourlyForecast, options?: { updateLiveTemp?: boolean }) => {
    if (!data) return;
+    const loadedAtMs = Date.now();
    const rowSeed = seedHourlyForecastFromRow(row);
    const dataWithCurrentRow = mergeHourlyWithLiveObservations(data, rowSeed, row);
    hasLoadedHourlyDetailRef.current = true;
@@ -561,16 +702,32 @@ export function LiveTemperatureThresholdChart({
    setHourly((prev) => mergeHourlyWithLiveObservations(dataWithCurrentRow, prev, row));
    setDetailError(null);
    setShowingStaleDetail(false);
+    setChartFreshness((prev) => ({
+      ...prev,
+      detailResolvedAtMs: loadedAtMs,
+      detailErrorAtMs: null,
+      detailStatus: "fresh",
+      detailSource:
+        prev.detailSource === "none" || prev.detailSource === "partial_or_timeout"
+          ? "network"
+          : prev.detailSource,
+    }));
  }, [row]);

  useEffect(() => {
    if (!city || !currentRowObservationSignature) return;
    if (lastRowObservationSignatureRef.current === currentRowObservationSignature) return;
+    const now = Date.now();
    lastRowObservationSignatureRef.current = currentRowObservationSignature;
    const rowSeed = seedHourlyForecastFromRow(row);
    const temp = getLiveTempFromHourly(rowSeed);
    if (temp !== null) setLiveTemp(temp);
    setHourly((prev) => mergeRowObservationIntoHourly(prev ?? rowSeed, row));
+    setChartFreshness((prev) => ({
+      ...prev,
+      rowAppliedAtMs: now,
+      rowObservationTime: rowObservationTimeForFreshness(row),
+    }));
  }, [city, currentRowObservationSignature, row]);

  useEffect(() => {
@@ -581,10 +738,12 @@ export function LiveTemperatureThresholdChart({

    const cacheKey = `${city}:${targetResolution}`;
    let cached = _hourlyCache.get(cacheKey);
+    let cachedSource: ChartDetailSource = cached ? "memory_cache" : "none";
    if (!cached || Date.now() - Number(cached.ts || 0) >= HOURLY_CACHE_TTL_MS) {
      const sessionEntry = readSessionCache(cacheKey, { allowStale: true });
      if (sessionEntry) {
        cached = sessionEntry;
+        cachedSource = "session_cache";
        _hourlyCache.set(cacheKey, sessionEntry);
      }
    }
@@ -595,6 +754,12 @@ export function LiveTemperatureThresholdChart({
      hasLoadedHourlyDetailRef.current = true;
      setHourly(cached.data);
      setShowingStaleDetail(!hasFreshCache);
+      setChartFreshness((prev) => ({
+        ...prev,
+        detailResolvedAtMs: Number(cached.ts || Date.now()),
+        detailStatus: hasFreshCache ? "fresh" : "stale_cache",
+        detailSource: cachedSource,
+      }));
    }

    if (hasFreshCache) {
@@ -625,6 +790,7 @@ export function LiveTemperatureThresholdChart({
      setShowingStaleDetail(false);
    }
    setIsHourlyLoading(true);
+    markDetailRequest("network");
    let cancelled = false;

    const timer = setTimeout(() => {
@@ -632,13 +798,15 @@ export function LiveTemperatureThresholdChart({
        .then((data) => {
          if (cancelled) return;
          if (!data) {
-            setDetailError(isEn ? "Data temporarily unavailable." : "数据暂不可用");
+            markDetailDegraded({ showUserError: true });
            return;
          }
          applySuccessfulHourlyDetail(data);
        })
        .catch(() => {
-          if (!cancelled) setDetailError(isEn ? "Data temporarily unavailable." : "数据暂不可用");
+          if (!cancelled) {
+            markDetailDegraded({ showUserError: true });
+          }
        })
        .finally(() => {
          if (!cancelled) setIsHourlyLoading(false);
@@ -660,17 +828,29 @@ export function LiveTemperatureThresholdChart({
    slotIndex,
    detailLoadReady,
    detailRetryNonce,
-    isEn,
+    markDetailDegraded,
+    markDetailRequest,
    applySuccessfulHourlyDetail,
  ]);

  useEffect(() => {
    if (!latestPatch || latestPatch.revision <= lastAppliedPatchRevisionRef.current) return;
+    const patchAppliedAtMs = Date.now();
    lastAppliedPatchRevisionRef.current = latestPatch.revision;
-    lastPatchAtRef.current = Date.now();
+    lastPatchAtRef.current = patchAppliedAtMs;
    const tempValue = validNumber(latestPatch.changes.temp);
    if (tempValue !== null) setLiveTemp(tempValue);
    setHourly((prev) => mergePatchIntoHourly(prev ?? seedHourlyForecastFromRow(row), latestPatch));
+    setChartFreshness((prev) => ({
+      ...prev,
+      ssePatchAppliedAtMs: patchAppliedAtMs,
+      sseObservedAt: patchObservationTimeForFreshness(latestPatch),
+      sseRevision: latestPatch.revision,
+      sseEmittedAtMs: latestPatch.delivery?.sse_emitted_at_ms ?? null,
+      sseServerToClientLatencySec: latestPatch.delivery?.server_to_client_latency_sec ?? null,
+      sseCollectorToClientLatencySec: latestPatch.delivery?.collector_to_client_latency_sec ?? null,
+      sseSourceToCollectorLatencySec: latestPatch.delivery?.source_to_collector_latency_sec ?? null,
+    }));

    const hasObservationChange =
      tempValue !== null ||
@@ -684,36 +864,54 @@ export function LiveTemperatureThresholdChart({

    let cancelled = false;
    const refreshProbabilityOverlayAfterPatch = () => {
+      markDetailRequest("force_refresh");
      fetchHourlyForecastForCity(city, { ignoreCache: true, resolution: targetResolution })
        .then((data) => {
-          if (cancelled || !data) return;
+          if (cancelled) return;
+          if (!data) {
+            markDetailDegraded();
+            return;
+          }
          applySuccessfulHourlyDetail(data);
        })
-        .catch(() => {});
+        .catch(() => {
+          if (!cancelled) {
+            markDetailDegraded();
+          }
+        });
    };

    refreshProbabilityOverlayAfterPatch();
    return () => {
      cancelled = true;
    };
-  }, [latestPatch, row, city, targetResolution, compact, isActive, isMaximized, applySuccessfulHourlyDetail]);
+  }, [latestPatch, row, city, targetResolution, compact, isActive, isMaximized, markDetailDegraded, markDetailRequest, applySuccessfulHourlyDetail]);

  useEffect(() => {
    if (!resyncVersion || !city) return;
    let cancelled = false;
+    markDetailRequest("force_refresh");
    fetchHourlyForecastForCity(city, { ignoreCache: true, resolution: targetResolution })
      .then((data) => {
-        if (cancelled || !data) return;
+        if (cancelled) return;
+        if (!data) {
+          markDetailDegraded();
+          return;
+        }
        applySuccessfulHourlyDetail(data);
      })
-      .catch(() => {})
+      .catch(() => {
+        if (!cancelled) {
+          markDetailDegraded();
+        }
+      })
      .finally(() => {
        if (!cancelled) setIsHourlyLoading(false);
      });
    return () => {
      cancelled = true;
    };
-  }, [resyncVersion, city, targetResolution, applySuccessfulHourlyDetail]);
+  }, [resyncVersion, city, targetResolution, markDetailDegraded, markDetailRequest, applySuccessfulHourlyDetail]);

  // ── SSE fallback: only full-fetch if a visible chart has seen no patch for one METAR cadence ──
  useEffect(() => {
@@ -721,14 +919,24 @@ export function LiveTemperatureThresholdChart({
    let cancelled = false;

    const refreshFullDetail = () => {
-      lastPatchAtRef.current = Date.now();
+      const now = Date.now();
+      lastPatchAtRef.current = now;
+      markDetailRequest("force_refresh");

      fetchHourlyForecastForCity(city, { ignoreCache: true, resolution: targetResolution })
        .then((data) => {
-          if (cancelled || !data) return;
+          if (cancelled) return;
+          if (!data) {
+            markDetailDegraded();
+            return;
+          }
          applySuccessfulHourlyDetail(data, { updateLiveTemp: true });
        })
-        .catch(() => {})
+        .catch(() => {
+          if (!cancelled) {
+            markDetailDegraded();
+          }
+        })
        .finally(() => {
          if (!cancelled) setIsHourlyLoading(false);
        });
@@ -746,7 +954,7 @@ export function LiveTemperatureThresholdChart({
      cancelled = true;
      clearInterval(id);
    };
-  }, [city, compact, isActive, isMaximized, targetResolution, applySuccessfulHourlyDetail]);
+  }, [city, compact, isActive, isMaximized, targetResolution, markDetailDegraded, markDetailRequest, applySuccessfulHourlyDetail]);

  useEffect(() => {
    if (!shouldPollLiveChart({ city, compact, isActive, isMaximized })) return;
@@ -766,13 +974,22 @@ export function LiveTemperatureThresholdChart({

      lastForegroundRefreshAtRef.current = now;
      lastPatchAtRef.current = now;
+      markDetailRequest("force_refresh");

      fetchHourlyForecastForCity(city, { ignoreCache: true, resolution: targetResolution })
        .then((data) => {
-          if (cancelled || !data) return;
+          if (cancelled) return;
+          if (!data) {
+            markDetailDegraded();
+            return;
+          }
          applySuccessfulHourlyDetail(data, { updateLiveTemp: true });
        })
-        .catch(() => {});
+        .catch(() => {
+          if (!cancelled) {
+            markDetailDegraded();
+          }
+        });
    };

    const handleVisibilityChange = () => {
@@ -787,7 +1004,7 @@ export function LiveTemperatureThresholdChart({
      document.removeEventListener("visibilitychange", handleVisibilityChange);
      window.removeEventListener("focus", refreshForegroundFullDetail);
    };
-  }, [city, compact, isActive, isMaximized, targetResolution, applySuccessfulHourlyDetail]);
+  }, [city, compact, isActive, isMaximized, targetResolution, markDetailDegraded, markDetailRequest, applySuccessfulHourlyDetail]);

  useEffect(() => {
    if (!city || !currentCityLocalDate) return;
@@ -797,19 +1014,27 @@ export function LiveTemperatureThresholdChart({

    localDayRolloverFetchDateRef.current = currentCityLocalDate;
    let cancelled = false;
+    markDetailRequest("force_refresh");
    fetchHourlyForecastForCity(city, { ignoreCache: true, resolution: targetResolution })
      .then((data) => {
-        if (cancelled || !data) return;
+        if (cancelled) return;
+        if (!data) {
+          markDetailDegraded();
+          return;
+        }
        applySuccessfulHourlyDetail(data);
      })
      .catch(() => {
-        if (!cancelled) localDayRolloverFetchDateRef.current = "";
+        if (!cancelled) {
+          localDayRolloverFetchDateRef.current = "";
+          markDetailDegraded();
+        }
      });

    return () => {
      cancelled = true;
    };
-  }, [city, currentCityLocalDate, hourly?.localDate, row?.local_date, targetResolution, applySuccessfulHourlyDetail]);
+  }, [city, currentCityLocalDate, hourly?.localDate, row?.local_date, targetResolution, markDetailDegraded, markDetailRequest, applySuccessfulHourlyDetail]);

  const chartHourly = useMemo<HourlyForecast>(() => {
    if (!hourly) return hourly;
@@ -1012,6 +1237,14 @@ export function LiveTemperatureThresholdChart({

  const subtitle = row ? (isEn ? "Live & Forecast" : "实测与预测") : "";
  const showDetailErrorBadge = !compact || isActive || isMaximized;
+  const chartFreshnessContext = useMemo(
+    () => buildChartFreshnessContext(chartFreshness),
+    [chartFreshness],
+  );
+  const detailBatchDiagnostics = useMemo(
+    () => readCityDetailBatchDiagnostics(city, targetResolution),
+    [city, targetResolution, chartFreshness.detailRequestedAtMs, chartFreshness.detailErrorAtMs, chartFreshness.detailResolvedAtMs],
+  );

  const handleZoomReset = useCallback(() => {
    setZoomRange(null);
@@ -1072,8 +1305,9 @@ export function LiveTemperatureThresholdChart({
  const handleRetryDetail = useCallback(() => {
    setDetailError(null);
    setIsHourlyLoading(true);
+    markDetailRequest("network");
    setDetailRetryNonce((value) => value + 1);
-  }, []);
+  }, [markDetailRequest]);

  const handleReportIssue = useCallback((event: React.MouseEvent<HTMLButtonElement>) => {
    event.stopPropagation();
@@ -1087,6 +1321,12 @@ export function LiveTemperatureThresholdChart({
      is_active: isActive,
      is_maximized: isMaximized,
      detail_error: detailError,
+      freshness: chartFreshnessContext,
+      detail_batch_diagnostics: detailBatchDiagnostics,
+      live_path: chartFreshnessContext.live_path,
+      live_age_sec: chartFreshnessContext.live_age_sec,
+      detail_status: chartFreshnessContext.detail_status,
+      detail_source: chartFreshnessContext.detail_source,
      is_hourly_loading: isHourlyLoading,
      showing_stale_detail: showingStaleDetail,
      target_resolution: targetResolution,
@@ -1104,11 +1344,13 @@ export function LiveTemperatureThresholdChart({
  }, [
    activeSeries,
    chartLocalDate,
+    chartFreshnessContext,
    chartSeries,
    city,
    compact,
    currentMetarTemp,
    currentRunwayTemp,
+    detailBatchDiagnostics,
    detailError,
    hasRunwayData,
    isActive,
@@ -1304,6 +1546,7 @@ export function LiveTemperatureThresholdChart({
          showRunwayDetails={showRunwayDetails}
          isHourlyLoading={isHourlyLoading}
          detailError={detailError}
+          detailStatus={chartFreshness.detailStatus}
          showingStaleDetail={showingStaleDetail}
          showDetailErrorBadge={showDetailErrorBadge}
          refAreaLeft={refAreaLeft}
@@ -1342,6 +1585,7 @@ export const __getWundergroundDailyHighForTest = getWundergroundDailyHigh;
 export const __getInitialDetailLoadDelayMsForTest = getInitialDetailLoadDelayMs;
 export const __shouldFetchCityDetailForChartForTest = shouldFetchCityDetailForChart;
 export const __shouldPollLiveChartForTest = shouldPollLiveChart;
+export const __buildChartFreshnessContextForTest = buildChartFreshnessContext;
 export const __mergePatchIntoHourlyForTest = mergePatchIntoHourly;
 export const __selectCompactSecondaryTempForTest = selectCompactSecondaryTemp;
 export const __selectDisplayRunwayTempForTest = selectDisplayRunwayTemp;
@@ -111,6 +111,7 @@ function TemperatureChartCanvasComponent({
  showRunwayDetails,
  isHourlyLoading,
  detailError,
+  detailStatus,
  showingStaleDetail,
  showDetailErrorBadge = true,
  refAreaLeft,
@@ -139,6 +140,7 @@ function TemperatureChartCanvasComponent({
  showRunwayDetails: boolean;
  isHourlyLoading: boolean;
  detailError?: string | null;
+  detailStatus?: string | null;
  showingStaleDetail?: boolean;
  showDetailErrorBadge?: boolean;
  refAreaLeft: number | null;
@@ -226,6 +228,10 @@ function TemperatureChartCanvasComponent({
  const shouldShowUnavailableState = Boolean(row?.city) && Boolean(detailError) && !isHourlyLoading && !hasDrawableChartContent;
  const shouldShowBackgroundError =
    showDetailErrorBadge && Boolean(row?.city) && Boolean(detailError) && !isHourlyLoading && hasDrawableChartContent;
+  const backgroundErrorLabel =
+    showingStaleDetail || detailStatus === "stale_cache"
+      ? (isEn ? "Detail cache" : "详情缓存")
+      : (isEn ? "Detail degraded" : "详情降级");

  return (
    <div className={clsx("relative flex flex-1 flex-col p-2", compact ? "min-h-[120px]" : "min-h-[240px]")}>
@@ -389,7 +395,7 @@ function TemperatureChartCanvasComponent({
        {shouldShowUnavailableState && (
          <div className="absolute inset-0 z-10 grid place-items-center px-4 text-center">
            <div className="max-w-[260px] rounded border border-amber-200 bg-amber-50/95 px-3 py-2 text-[11px] font-semibold text-amber-700 shadow-sm">
-              <div>{isEn ? "Data temporarily unavailable" : "数据暂不可用"}</div>
+              <div>{isEn ? "Detail temporarily unavailable" : "详情暂不可用"}</div>
              <button
                type="button"
                onClick={onRetryDetail}
@@ -410,7 +416,7 @@ function TemperatureChartCanvasComponent({
      </div>
      {shouldShowBackgroundError && (
        <div className="absolute right-3 top-12 z-10 inline-flex items-center gap-1.5 rounded border border-amber-200 bg-amber-50/95 px-2 py-1 text-[10px] font-semibold text-amber-700 shadow-sm">
-          <span>{showingStaleDetail ? (isEn ? "Showing cache" : "显示缓存") : (isEn ? "Update failed" : "更新失败")}</span>
+          <span>{backgroundErrorLabel}</span>
          <button
            type="button"
            onClick={onRetryDetail}
@@ -6,6 +6,7 @@ import {
 } from "@/lib/refresh-policy";
 import { scanTerminalQueryPolicy } from "@/components/dashboard/scan-terminal/scan-terminal-client";
 import {
+  __buildChartFreshnessContextForTest,
  __getInitialDetailLoadDelayMsForTest,
  __shouldFetchCityDetailForChartForTest,
  __shouldPollLiveChartForTest,
@@ -15,9 +16,11 @@ import {
  HOURLY_CACHE_TTL_MS,
  __resolveCityDetailFromBatchForTest,
  __readHourlyCacheEntryForTest,
+  __rememberCityDetailBatchDiagnosticsForTest,
  __resetHourlyDetailRequestQueueForTest,
  __runQueuedHourlyDetailRequestForTest,
  clearCityDetailCache,
+  readCityDetailBatchDiagnostics,
 } from "@/components/dashboard/scan-terminal/temperature-chart-logic";

 function assert(condition: unknown, message: string) {
@@ -119,6 +122,90 @@ export async function runTests() {
    __shouldPollLiveChartForTest({ city: "shanghai", compact: true, isActive: false, isMaximized: false }) === true,
    "compact grid slots are visible charts and should run the no-patch fallback guard",
  );
+  assert(
+    typeof __buildChartFreshnessContextForTest === "function",
+    "temperature charts should expose a structured freshness context for feedback diagnostics",
+  );
+  const degradedFreshness = __buildChartFreshnessContextForTest(
+    {
+      rowAppliedAtMs: 1_000,
+      rowObservationTime: "12:45",
+      ssePatchAppliedAtMs: 5_000,
+      sseObservedAt: "2026-06-10T04:48:00Z",
+      sseRevision: 42,
+      detailRequestedAtMs: 7_000,
+      detailResolvedAtMs: null,
+      detailErrorAtMs: 9_000,
+      detailStatus: "degraded",
+      detailSource: "partial_or_timeout",
+      sseEmittedAtMs: 5_500,
+      sseServerToClientLatencySec: 5,
+      sseCollectorToClientLatencySec: 60,
+      sseSourceToCollectorLatencySec: 64,
+    },
+    11_000,
+  );
+  assert(
+    degradedFreshness.live_path === "sse" &&
+      degradedFreshness.live_age_sec === 6 &&
+      degradedFreshness.row_applied_age_sec === 10 &&
+      degradedFreshness.sse_patch_age_sec === 6,
+    "freshness context should make the newest live row/SSE path observable independently of detail loading",
+  );
+  assert(
+    degradedFreshness.detail_status === "degraded" &&
+      degradedFreshness.detail_source === "partial_or_timeout" &&
+      degradedFreshness.detail_request_age_sec === 4 &&
+      degradedFreshness.detail_error_age_sec === 2 &&
+      degradedFreshness.detail_age_sec === null,
+    "freshness context should report degraded full-detail state without implying the live point is unavailable",
+  );
+  assert(
+    degradedFreshness.sse_emitted_at_ms === 5_500 &&
+      degradedFreshness.sse_server_to_client_latency_sec === 5 &&
+      degradedFreshness.sse_collector_to_client_latency_sec === 60 &&
+      degradedFreshness.sse_source_to_collector_latency_sec === 64,
+    "freshness context should expose SSE delivery and collector latency diagnostics",
+  );
+  __rememberCityDetailBatchDiagnosticsForTest("Paris", "10m", {
+    response_source: "next_proxy_timeout",
+    partial_reason: "proxy_timeout",
+    city_status: { paris: { status: "proxy_timeout" } },
+  });
+  const rememberedBatchDiagnostics = readCityDetailBatchDiagnostics("paris", "10m");
+  assert(
+    rememberedBatchDiagnostics?.response_source === "next_proxy_timeout" &&
+      rememberedBatchDiagnostics?.city_status?.paris?.status === "proxy_timeout",
+    "chart logic should retain the latest detail-batch diagnostics for feedback context",
+  );
+  assert(
+    chartSource.includes("readCityDetailBatchDiagnostics") &&
+      chartSource.includes("detail_batch_diagnostics"),
+    "temperature chart feedback context should include the latest detail-batch diagnostics",
+  );
+  const rowWinsFreshness = __buildChartFreshnessContextForTest(
+    {
+      rowAppliedAtMs: 10_000,
+      rowObservationTime: "12:50",
+      ssePatchAppliedAtMs: 5_000,
+      sseObservedAt: "2026-06-10T04:48:00Z",
+      sseRevision: 42,
+      sseEmittedAtMs: null,
+      sseServerToClientLatencySec: null,
+      sseCollectorToClientLatencySec: null,
+      sseSourceToCollectorLatencySec: null,
+      detailRequestedAtMs: null,
+      detailResolvedAtMs: null,
+      detailErrorAtMs: null,
+      detailStatus: "idle",
+      detailSource: "none",
+    },
+    11_000,
+  );
+  assert(
+    rowWinsFreshness.live_path === "row" && rowWinsFreshness.live_age_sec === 1,
+    "freshness context should report the newest live path when a scan-row update is newer than the last SSE patch",
+  );
  assert(
    __shouldPollLiveChartForTest({ city: "shanghai", compact: false, isActive: false, isMaximized: false }) === false,
    "inactive non-compact charts should not run live polling",
@@ -192,7 +279,7 @@ export async function runTests() {
  );
  assert(
    chartSource.includes("allowStale: true") &&
-      chartCanvasSourceIncludes(chartSource, "数据暂不可用") &&
+      chartCanvasSourceIncludes(chartSource, "详情暂不可用") &&
      chartCanvasSourceIncludes(chartSource, "handleRetryDetail"),
    "city detail charts should show stale cache first and expose a retryable unavailable state",
  );
@@ -1,5 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
+import {
+  __applySsePatchForTest,
+  getLatestPatchesSnapshot,
+} from "@/hooks/use-sse-patches";

 function assert(condition: unknown, message: string) {
  if (!condition) throw new Error(message);
@@ -127,6 +131,36 @@ export function runTests() {
      !subscriptionBlock.includes("ensureSsePatchConnection();"),
    "city subscription mount/unmount should schedule one coalesced SSE reconnect instead of reconnecting per chart",
  );
+  const originalDateNow = Date.now;
+  try {
+    Date.now = () => 1_000_000;
+    __applySsePatchForTest({
+      type: "city_observation_patch.v1",
+      city: "Latency City",
+      source: "amsc_awos",
+      obs_time: "2026-06-10T04:50:00Z",
+      observed_at_utc: "2026-06-10T04:50:00Z",
+      revision: 987001,
+      ts: 940_000,
+      sse_emitted_at_ms: 995_000,
+      payload: {
+        temp: 30.5,
+        latency_sec: 64,
+        received_at_utc: "2026-06-10T04:51:04Z",
+      },
+    });
+    const latencyPatch = getLatestPatchesSnapshot().get("latency city") as any;
+    assert(
+      latencyPatch?.delivery?.client_received_at_ms === 1_000_000 &&
+        latencyPatch?.delivery?.sse_emitted_at_ms === 995_000 &&
+        latencyPatch?.delivery?.server_to_client_latency_sec === 5 &&
+        latencyPatch?.delivery?.collector_to_client_latency_sec === 60 &&
+        latencyPatch?.delivery?.source_to_collector_latency_sec === 64,
+      "frontend patch hook should retain SSE delivery latency diagnostics for feedback context",
+    );
+  } finally {
+    Date.now = originalDateNow;
+  }

  const bffEventsRoute = readFrontendFile("app", "api", "events", "route.ts");
  assert(bffEventsRoute.includes("searchParams"), "Next.js SSE proxy must forward query parameters to FastAPI");
@@ -249,7 +283,9 @@ export function runTests() {
      chart.includes("refreshProbabilityOverlayAfterPatch"),
    "temperature chart must trigger a throttled background probability refresh after live observation patches",
  );
-  const patchEffectBlock = chart.match(/useEffect\(\(\) => \{\s*if \(!latestPatch[\s\S]*?\}, \[latestPatch, row, city, targetResolution, compact, isActive, isMaximized, applySuccessfulHourlyDetail\]\);/)?.[0] || "";
+  const patchEffectBlock = chart.match(
+    /useEffect\(\(\) => \{\s*if \(!latestPatch[\s\S]*?refreshProbabilityOverlayAfterPatch\(\);[\s\S]*?\}, \[[^\]]*latestPatch[^\]]*applySuccessfulHourlyDetail[^\]]*\]\);/,
+  )?.[0] || "";
  assert(
    patchEffectBlock.includes("refreshProbabilityOverlayAfterPatch") &&
      patchEffectBlock.includes("ignoreCache: true") &&
@@ -372,6 +372,43 @@ const SESSION_CACHE_PREFIX = "polyweather_city_detail_v1:";
 const SESSION_CACHE_TTL_MS = DASHBOARD_REFRESH_POLICY_MS.metar;

 type HourlyCacheEntry = { ts: number; data: HourlyForecast };
+type CityDetailBatchDiagnostics = Record<string, any>;
+type CityDetailBatchDiagnosticsEntry = { ts: number; data: CityDetailBatchDiagnostics };
+
+const _cityDetailBatchDiagnosticsCache = new Map<string, CityDetailBatchDiagnosticsEntry>();
+
+function cityDetailBatchDiagnosticsKey(city: string, resolution: string) {
+  return `${normalizeCityKey(city)}:${resolution || "10m"}`;
+}
+
+function rememberCityDetailBatchDiagnostics(
+  city: string,
+  resolution: string,
+  diagnostics: unknown,
+) {
+  if (!diagnostics || typeof diagnostics !== "object") return;
+  const key = cityDetailBatchDiagnosticsKey(city, resolution);
+  if (!key.startsWith(":")) {
+    _cityDetailBatchDiagnosticsCache.set(key, {
+      ts: Date.now(),
+      data: diagnostics as CityDetailBatchDiagnostics,
+    });
+  }
+}
+
+function readCityDetailBatchDiagnostics(
+  city: string,
+  resolution: string,
+): CityDetailBatchDiagnostics | null {
+  const key = cityDetailBatchDiagnosticsKey(city, resolution);
+  const entry = _cityDetailBatchDiagnosticsCache.get(key);
+  if (!entry) return null;
+  if (Date.now() - Number(entry.ts || 0) >= HOURLY_CACHE_TTL_MS) {
+    _cityDetailBatchDiagnosticsCache.delete(key);
+    return null;
+  }
+  return entry.data;
+}

 function isFreshHourlyCacheEntry(
  entry: HourlyCacheEntry | null | undefined,
@@ -459,6 +496,7 @@ function runQueuedHourlyDetailRequest<T>(task: () => Promise<T>): Promise<T> {
 export function clearCityDetailCache() {
  _hourlyCache.clear();
  _hourlyRequestCache.clear();
+  _cityDetailBatchDiagnosticsCache.clear();
  if (typeof window !== "undefined") {
    try {
      for (let i = sessionStorage.length - 1; i >= 0; i--) {
@@ -1288,6 +1326,7 @@ type HourlyForecastFetchOptions = {
 type CityDetailBatchPayload = {
  cities?: string[];
  details?: Record<string, CityDetail | null | undefined>;
+  diagnostics?: CityDetailBatchDiagnostics;
  errors?: Record<string, string>;
  missing?: string[];
  partial?: boolean;
@@ -1449,6 +1488,7 @@ async function flushCityDetailBatch(queueKey: string) {
    }

    const details = payload?.details || {};
+    const diagnostics = payload?.diagnostics || null;
    const partialMissingCities =
      payload?.partial === true
        ? new Set((payload.missing || []).map((city) => normalizeCityKey(city)))
@@ -1456,6 +1496,7 @@ async function flushCityDetailBatch(queueKey: string) {
    await Promise.all(
      cities.map(async (city) => {
        const waiters = queue.waiters.get(city);
+        rememberCityDetailBatchDiagnostics(city, queue.resolution, diagnostics);
        const detail = resolveCityDetailFromBatch(details, city);
        const data = primeCityDetailCache(city, queue.resolution, detail);
        if (data) {
@@ -2817,6 +2858,7 @@ export {
  normObs,
  normalizeCityKey,
  prefersHighFrequencyRunwayResolution,
+  readCityDetailBatchDiagnostics,
  readSessionCache,
  selectCompactSecondaryTemp,
  selectDisplayRunwayTemp,
@@ -2824,6 +2866,7 @@ export {
  seriesStats,
  shouldPollLiveChart,
  validNumber,
+  rememberCityDetailBatchDiagnostics as __rememberCityDetailBatchDiagnosticsForTest,
 };

 export type { EvidenceSeries, HourlyForecast, PeakGlowMeta, PeakGlowState, ProbabilityOverlay };
@@ -71,6 +71,26 @@ export function runTests() {
    /partial:\s*true/,
    "city detail batch proxy timeout fallback should preserve partial response semantics",
  );
+  assert.match(
+    detailBatchProxy,
+    /diagnostics:\s*{/,
+    "city detail batch proxy timeout fallback should include structured diagnostics",
+  );
+  assert.match(
+    detailBatchProxy,
+    /response_source:\s*"next_proxy_timeout"/,
+    "city detail batch proxy timeout diagnostics should identify the proxy timeout layer",
+  );
+  assert.match(
+    detailBatchProxy,
+    /partial_reason:\s*"proxy_timeout"/,
+    "city detail batch proxy timeout diagnostics should distinguish proxy timeout from backend partial timeout",
+  );
+  assert.match(
+    detailBatchProxy,
+    /city_status/,
+    "city detail batch proxy timeout diagnostics should include per-city status",
+  );
  assert.match(
    detailBatchProxy,
    /status:\s*200/,
@@ -39,4 +39,15 @@ export function runTests() {
      source.includes("1500"),
    "ops feedback page must document fixed reward point guidelines",
  );
+  assert(
+    source.includes("feedbackFreshnessBadges") &&
+      source.includes("freshness?.live_path") &&
+      source.includes("freshness?.live_age_sec") &&
+      source.includes("sse_server_to_client_latency_sec") &&
+      source.includes("sse_collector_to_client_latency_sec") &&
+      source.includes("sse_source_to_collector_latency_sec") &&
+      source.includes("detail_batch_diagnostics") &&
+      source.includes("partial_reason"),
+    "ops feedback page must summarize live freshness, SSE latency and detail-batch diagnostics",
+  );
 }
@@ -78,6 +78,111 @@ function contextSummary(context?: Record<string, unknown>) {
  return pieces.length ? pieces.join(" · ") : "terminal";
 }

+function objectRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
+
+function finiteNumber(value: unknown) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : null;
+}
+
+function formatSeconds(value: unknown) {
+  const number = finiteNumber(value);
+  return number === null ? null : `${number}s`;
+}
+
+function latencyTone(value: unknown) {
+  const number = finiteNumber(value);
+  if (number === null) return "border-slate-200 bg-slate-50 text-slate-600";
+  if (number >= 300) return "border-red-200 bg-red-50 text-red-700";
+  if (number >= 60) return "border-amber-200 bg-amber-50 text-amber-700";
+  return "border-emerald-200 bg-emerald-50 text-emerald-700";
+}
+
+function feedbackFreshnessBadges(context?: Record<string, unknown>) {
+  const freshness = objectRecord(context?.freshness);
+  const detailBatchDiagnostics = objectRecord(context?.detail_batch_diagnostics);
+  const badges: Array<{ key: string; label: string; tone: string }> = [];
+
+  const livePath = String(freshness?.live_path || context?.live_path || "").trim();
+  const liveAge = formatSeconds(freshness?.live_age_sec ?? context?.live_age_sec);
+  if (livePath) {
+    badges.push({
+      key: "live",
+      label: liveAge ? `实时 ${livePath} ${liveAge}` : `实时 ${livePath}`,
+      tone: latencyTone(freshness?.live_age_sec ?? context?.live_age_sec),
+    });
+  }
+
+  const detailStatus = String(freshness?.detail_status || context?.detail_status || "").trim();
+  const detailSource = String(freshness?.detail_source || context?.detail_source || "").trim();
+  if (detailStatus) {
+    badges.push({
+      key: "detail",
+      label: detailSource ? `详情 ${detailStatus}/${detailSource}` : `详情 ${detailStatus}`,
+      tone: ["degraded", "stale_cache"].includes(detailStatus)
+        ? "border-amber-200 bg-amber-50 text-amber-700"
+        : "border-slate-200 bg-slate-50 text-slate-600",
+    });
+  }
+
+  const sseServerToClientLatency = formatSeconds(freshness?.sse_server_to_client_latency_sec);
+  if (sseServerToClientLatency) {
+    badges.push({
+      key: "sse-server",
+      label: `SSE ${sseServerToClientLatency}`,
+      tone: latencyTone(freshness?.sse_server_to_client_latency_sec),
+    });
+  }
+
+  const sseCollectorToClientLatency = formatSeconds(freshness?.sse_collector_to_client_latency_sec);
+  if (sseCollectorToClientLatency) {
+    badges.push({
+      key: "sse-collector",
+      label: `采集到前端 ${sseCollectorToClientLatency}`,
+      tone: latencyTone(freshness?.sse_collector_to_client_latency_sec),
+    });
+  }
+
+  const sseSourceToCollectorLatency = formatSeconds(freshness?.sse_source_to_collector_latency_sec);
+  if (sseSourceToCollectorLatency) {
+    badges.push({
+      key: "sse-source",
+      label: `源到采集 ${sseSourceToCollectorLatency}`,
+      tone: latencyTone(freshness?.sse_source_to_collector_latency_sec),
+    });
+  }
+
+  const partialReason = String(detailBatchDiagnostics?.partial_reason || "").trim();
+  const responseSource = String(detailBatchDiagnostics?.response_source || "").trim();
+  if (partialReason || responseSource) {
+    badges.push({
+      key: "batch",
+      label: responseSource
+        ? `批量 ${partialReason || "ok"} · ${responseSource}`
+        : `批量 ${partialReason}`,
+      tone: partialReason
+        ? "border-amber-200 bg-amber-50 text-amber-700"
+        : "border-slate-200 bg-slate-50 text-slate-600",
+    });
+  }
+
+  const missingCount = finiteNumber(detailBatchDiagnostics?.missing_count);
+  const errorCount = finiteNumber(detailBatchDiagnostics?.error_count);
+  if (missingCount || errorCount) {
+    badges.push({
+      key: "batch-counts",
+      label: `缺失 ${missingCount || 0} · 错误 ${errorCount || 0}`,
+      tone: "border-red-200 bg-red-50 text-red-700",
+    });
+  }
+
+  return badges;
+}
+
 export function FeedbackPageClient() {
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState("");
@@ -299,6 +404,7 @@ export function FeedbackPageClient() {
                    const rewardPoints = Number(row.reward_points || 0);
                    const rewardStatus = String(row.reward_status || "").toLowerCase();
                    const hasReward = rewardStatus === "granted" && rewardPoints > 0;
+                    const freshnessBadges = feedbackFreshnessBadges(row.context);
                    return (
                      <tr key={row.id} className="border-b border-slate-100 align-top">
                        <td className="py-3 pr-4">
@@ -318,6 +424,18 @@ export function FeedbackPageClient() {
                              {String(row.context?.detail_error || "").slice(0, 120)}
                            </div>
                          )}
+                          {freshnessBadges.length > 0 && (
+                            <div className="mt-2 flex max-w-xs flex-wrap gap-1.5">
+                              {freshnessBadges.map((item) => (
+                                <span
+                                  key={item.key}
+                                  className={`rounded border px-1.5 py-0.5 text-[10px] font-bold ${item.tone}`}
+                                >
+                                  {item.label}
+                                </span>
+                              ))}
+                            </div>
+                          )}
                        </td>
                        <td className="py-3 pr-4 font-mono text-xs text-slate-500">
                          {row.user_email || row.user_id || "—"}
@@ -15,6 +15,13 @@ export type CityPatch = {
  changes: Record<string, unknown>;
  revision: number;
  ts?: number;
+  delivery?: {
+    client_received_at_ms: number;
+    sse_emitted_at_ms?: number | null;
+    server_to_client_latency_sec?: number | null;
+    collector_to_client_latency_sec?: number | null;
+    source_to_collector_latency_sec?: number | null;
+  };
 };

 type ObservationPatchV1 = {
@@ -30,6 +37,7 @@ type ObservationPatchV1 = {
  source_cadence_sec?: number | null;
  revision?: number;
  ts?: number;
+  sse_emitted_at_ms?: number | null;
  payload?: Record<string, unknown>;
 };

@@ -105,6 +113,34 @@ function resolveSseReplayLimit(cityCount: number) {
  return Math.max(SSE_REPLAY_BASE_LIMIT, Math.min(SSE_REPLAY_MAX_LIMIT, requested));
 }

+function finiteNumber(value: unknown): number | null {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : null;
+}
+
+function latencySeconds(fromMs: number | null, toMs: number) {
+  if (fromMs === null) return null;
+  return Math.max(0, Math.round((toMs - fromMs) / 1000));
+}
+
+function buildPatchDelivery(
+  patch: Partial<CityPatch> & ObservationPatchV1,
+  clientReceivedAtMs: number,
+  payload?: Record<string, unknown>,
+) {
+  const sseEmittedAtMs = finiteNumber(patch.sse_emitted_at_ms);
+  const collectorReceivedAtMs = finiteNumber(patch.ts);
+  const sourceToCollectorLatencySec =
+    finiteNumber(payload?.latency_sec) ?? finiteNumber((patch.changes as Record<string, unknown> | undefined)?.latency_sec);
+  return {
+    client_received_at_ms: clientReceivedAtMs,
+    sse_emitted_at_ms: sseEmittedAtMs,
+    server_to_client_latency_sec: latencySeconds(sseEmittedAtMs, clientReceivedAtMs),
+    collector_to_client_latency_sec: latencySeconds(collectorReceivedAtMs, clientReceivedAtMs),
+    source_to_collector_latency_sec: sourceToCollectorLatencySec,
+  };
+}
+
 function currentConnectionKey() {
  return `${useFallbackUrl ? "fallback" : "direct"}:${subscribedCityList().join("|")}:${lastRevision}`;
 }
@@ -219,7 +255,10 @@ function registerCitySubscription(city: string) {
  };
 }

-function normalizeLegacyPatch(patch: Partial<CityPatch>): CityPatch | null {
+function normalizeLegacyPatch(
+  patch: Partial<CityPatch> & ObservationPatchV1,
+  clientReceivedAtMs: number,
+): CityPatch | null {
  const city = normalizeCityKey(patch.city);
  const changes = patch.changes;
  const revision = Number(patch.revision);
@@ -232,10 +271,14 @@ function normalizeLegacyPatch(patch: Partial<CityPatch>): CityPatch | null {
    changes: changes as Record<string, unknown>,
    revision,
    ts: typeof patch.ts === "number" ? patch.ts : Date.now(),
+    delivery: buildPatchDelivery(patch, clientReceivedAtMs),
  };
 }

-function normalizeV1Patch(patch: ObservationPatchV1): CityPatch | null {
+function normalizeV1Patch(
+  patch: ObservationPatchV1,
+  clientReceivedAtMs: number,
+): CityPatch | null {
  const city = normalizeCityKey(patch.city);
  const revision = Number(patch.revision);
  const payload = patch.payload;
@@ -262,17 +305,19 @@ function normalizeV1Patch(patch: ObservationPatchV1): CityPatch | null {
    changes,
    revision,
    ts: typeof patch.ts === "number" ? patch.ts : Date.now(),
+    delivery: buildPatchDelivery(patch, clientReceivedAtMs, payload),
  };
 }

 function normalizeIncomingPatch(payload: unknown): CityPatch | null {
  if (!payload || typeof payload !== "object") return null;
  const patch = payload as Partial<CityPatch> & ObservationPatchV1;
+  const clientReceivedAtMs = Date.now();
  if (patch.type === "city_patch" || !patch.type) {
-    return normalizeLegacyPatch(patch);
+    return normalizeLegacyPatch(patch, clientReceivedAtMs);
  }
  if (patch.type === V1_EVENT_TYPE) {
-    return normalizeV1Patch(patch);
+    return normalizeV1Patch(patch, clientReceivedAtMs);
  }
  return null;
 }
@@ -4,6 +4,7 @@ from fastapi.testclient import TestClient

 from web.app import app
 from web.routers import sse_router
+from web.sse_manager import SseManager


 def _decode_sse_events(text: str):
@@ -15,6 +16,25 @@ def _decode_sse_events(text: str):
    return events


+def test_sse_format_event_stamps_emit_time_for_latency_diagnostics(monkeypatch):
+    monkeypatch.setattr("web.sse_manager.time.time", lambda: 1780750904.5)
+
+    frame = SseManager._format_event(
+        {
+            "type": "city_observation_patch.v1",
+            "revision": 123,
+            "city": "busan",
+            "source": "amos",
+            "ts": 1780750864062,
+            "payload": {"temp": 23.0},
+        }
+    )
+
+    event = _decode_sse_events(frame)[0]
+    assert event["sse_emitted_at_ms"] == 1780750904500
+    assert event["payload"]["temp"] == 23.0
+
+
 def test_events_endpoint_replays_only_requested_cities(monkeypatch):
    captured = {}

@@ -1012,6 +1012,13 @@ def test_city_detail_batch_returns_busy_when_global_builder_slot_is_full(monkeyp
    assert payload["busy"] is True
    assert payload["details"] == {}
    assert payload["missing"] == ["paris", "shanghai"]
+    assert payload["diagnostics"]["partial_reason"] == "busy"
+    assert payload["diagnostics"]["response_source"] == "busy"
+    assert payload["diagnostics"]["requested_count"] == 2
+    assert payload["diagnostics"]["completed_count"] == 0
+    assert payload["diagnostics"]["missing_count"] == 2
+    assert payload["diagnostics"]["city_status"]["paris"]["status"] == "busy"
+    assert payload["diagnostics"]["city_status"]["shanghai"]["status"] == "busy"
    assert build_calls == 0


@@ -1102,6 +1109,17 @@ def test_city_detail_batch_returns_completed_details_when_one_city_is_slow(monke
    assert payload["partial"] is True
    assert payload["missing"] == ["slow"]
    assert payload["errors"] == {}
+    assert payload["diagnostics"]["partial_reason"] == "timeout"
+    assert payload["diagnostics"]["requested_count"] == 3
+    assert payload["diagnostics"]["completed_count"] == 2
+    assert payload["diagnostics"]["missing_count"] == 1
+    assert payload["diagnostics"]["error_count"] == 0
+    assert payload["diagnostics"]["batch_concurrency"] == 2
+    assert payload["diagnostics"]["partial_timeout_ms"] == 20
+    assert payload["diagnostics"]["city_status"]["fast"]["status"] == "ok"
+    assert payload["diagnostics"]["city_status"]["other"]["status"] == "ok"
+    assert payload["diagnostics"]["city_status"]["slow"]["status"] == "timeout"
+    assert isinstance(payload["diagnostics"]["city_status"]["fast"]["duration_ms"], (int, float))
    assert "slow" not in completed


@@ -973,6 +973,90 @@ def _city_detail_batch_partial_timeout_seconds() -> Optional[float]:
    return max(0.001, min(60.0, timeout_ms / 1000.0))


+def _city_detail_batch_partial_timeout_ms() -> Optional[int]:
+    timeout_sec = _city_detail_batch_partial_timeout_seconds()
+    if timeout_sec is None:
+        return None
+    return int(round(timeout_sec * 1000.0))
+
+
+def _city_detail_batch_partial_reason(
+    *,
+    busy: bool,
+    missing: List[str],
+    errors: Dict[str, str],
+) -> Optional[str]:
+    if busy:
+        return "busy"
+    if missing and errors:
+        return "timeout_error"
+    if missing:
+        return "timeout"
+    if errors:
+        return "error"
+    return None
+
+
+def _build_city_detail_batch_diagnostics(
+    *,
+    city_names: List[str],
+    details: Dict[str, Any],
+    errors: Dict[str, str],
+    missing: List[str],
+    resolution: Optional[str],
+    detail_scope: str,
+    force_refresh: bool,
+    response_source: str,
+    busy: bool = False,
+    city_durations_ms: Optional[Dict[str, float]] = None,
+) -> Dict[str, Any]:
+    city_durations_ms = city_durations_ms or {}
+    missing_set = set(missing)
+    error_set = set(errors)
+    detail_set = set(details)
+    partial_reason = _city_detail_batch_partial_reason(
+        busy=busy,
+        missing=missing,
+        errors=errors,
+    )
+    city_status: Dict[str, Dict[str, Any]] = {}
+    for city in city_names:
+        if busy:
+            status = "busy"
+        elif city in missing_set:
+            status = "timeout"
+        elif city in error_set:
+            status = "error"
+        elif city in detail_set:
+            status = "ok"
+        else:
+            status = "missing"
+        city_status[city] = {
+            "status": status,
+            "duration_ms": city_durations_ms.get(city),
+        }
+        if city in errors:
+            city_status[city]["error"] = errors[city]
+
+    return {
+        "version": 1,
+        "response_source": response_source,
+        "partial": bool(partial_reason),
+        "partial_reason": partial_reason,
+        "requested_count": len(city_names),
+        "completed_count": len(details),
+        "missing_count": len(missing),
+        "error_count": len(errors),
+        "batch_concurrency": _city_detail_batch_concurrency(),
+        "global_concurrency": _city_detail_batch_global_concurrency(),
+        "partial_timeout_ms": _city_detail_batch_partial_timeout_ms(),
+        "force_refresh": force_refresh,
+        "resolution": resolution,
+        "scope": detail_scope,
+        "city_status": city_status,
+    }
+
+
 async def get_city_detail_batch_payload(
    request: Request,
    *,
@@ -1014,30 +1098,52 @@ async def get_city_detail_batch_payload(
        async def _build_uncached_payload() -> Dict[str, Any]:
            build_semaphore = _city_detail_batch_build_semaphore()
            if not build_semaphore.acquire(blocking=False):
+                missing = list(city_names)
+                errors: Dict[str, str] = {}
+                details: Dict[str, Any] = {}
                return {
                    "cities": city_names,
-                    "details": {},
-                    "errors": {},
-                    "missing": list(city_names),
+                    "details": details,
+                    "errors": errors,
+                    "missing": missing,
                    "partial": True,
                    "busy": True,
                    "stale_reason": "city detail batch builder is busy",
+                    "diagnostics": _build_city_detail_batch_diagnostics(
+                        city_names=city_names,
+                        details=details,
+                        errors=errors,
+                        missing=missing,
+                        resolution=resolution,
+                        detail_scope=detail_scope,
+                        force_refresh=force_refresh,
+                        response_source="busy",
+                        busy=True,
+                    ),
                }

            try:
                semaphore = asyncio.Semaphore(_city_detail_batch_concurrency())
+                city_durations_ms: Dict[str, float] = {}

                async def _build_with_limit(city: str) -> Tuple[str, Dict[str, Any]]:
                    async with semaphore:
-                        return await _build_city_detail_batch_item_async(
-                            city,
-                            force_refresh=force_refresh,
-                            market_slug=market_slug,
-                            target_date=target_date,
-                            resolution=resolution,
-                            detail_scope=detail_scope,
-                            timing_recorder=timer,
-                        )
+                        started = time.perf_counter()
+                        try:
+                            return await _build_city_detail_batch_item_async(
+                                city,
+                                force_refresh=force_refresh,
+                                market_slug=market_slug,
+                                target_date=target_date,
+                                resolution=resolution,
+                                detail_scope=detail_scope,
+                                timing_recorder=timer,
+                            )
+                        finally:
+                            city_durations_ms[city] = round(
+                                (time.perf_counter() - started) * 1000.0,
+                                1,
+                            )

                task_by_city = {
                    city: asyncio.create_task(_build_with_limit(city))
@@ -1076,6 +1182,17 @@ async def get_city_detail_batch_payload(
                    "errors": errors,
                    "missing": missing,
                    "partial": bool(missing or errors),
+                    "diagnostics": _build_city_detail_batch_diagnostics(
+                        city_names=city_names,
+                        details=details,
+                        errors=errors,
+                        missing=missing,
+                        resolution=resolution,
+                        detail_scope=detail_scope,
+                        force_refresh=force_refresh,
+                        response_source="fresh_build",
+                        city_durations_ms=city_durations_ms,
+                    ),
                }
            finally:
                build_semaphore.release()
@@ -162,6 +162,11 @@ class SseManager:

    @staticmethod
    def _format_event(event: dict[str, Any]) -> str:
+        if str(event.get("type") or "").startswith("city_observation_patch"):
+            event = {
+                **event,
+                "sse_emitted_at_ms": int(time.time() * 1000),
+            }
        return f"data: {json.dumps(event, ensure_ascii=False, separators=(',', ':'))}\n\n"