fix(market): 右侧面板详情行情 stale 回退与补价稳定性

避免实时失败时基本行情闪空：Hub/Engine 增加缓存与 K 线合成回退，客户端按标的缓存快照并在 quote 缺失时 fresh 补价。

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: Rui

client-ui/src/api/client.ts

@@ -418,12 +418,16 @@ export const research = {
     })
   },
 
-  stockDetail: async (codeOrRef: string | InstrumentRef) => {
+  stockDetail: async (codeOrRef: string | InstrumentRef, opts?: { fresh?: boolean }) => {
     const instrument = cnEquityRef(codeOrRef)
     const code = hubInstrumentCode(instrument)
+    const body = {
+      ...hubInstrumentBody(instrument),
+      ...(opts?.fresh ? { fresh: true } : {}),
+    }
     const resp = await postInstrument<StockDetailData | UnifiedInstrumentSnapshotDto>(
       '/instruments/snapshot',
-      hubInstrumentBody(instrument),
+      body,
       undefined,
       30000,
     )
@@ -453,6 +457,7 @@ export const research = {
 
   etfSnapshot: async (
     instrument: InstrumentRef,
+    opts?: { fresh?: boolean },
     signal?: AbortSignal,
   ): Promise<
     import('../types/schemas').ApiResponse<import('../types/market').EtfSnapshotData>
@@ -464,9 +469,13 @@ export const research = {
       nav: null,
       quote: null,
     }
+    const body = {
+      ...hubInstrumentBody(instrument),
+      ...(opts?.fresh ? { fresh: true } : {}),
+    }
     const resp = await apiCall<
       import('../types/market').EtfSnapshotData | UnifiedInstrumentSnapshotDto
-    >('etf_snapshot', hubInstrumentBody(instrument), { signal }, 20000)
+    >('etf_snapshot', body, { signal }, 20000)
     if (resp.success && resp.data && isUnifiedSnapshot(resp.data)) {
       return toApiResponse('etf_snapshot', resp, fallback, unifiedSnapshotToEtfSnapshot(resp.data))
     }
@@ -597,8 +606,13 @@ export const research = {
       counts: { cn_stocks: number; cn_etfs: number; us: number; crypto: number }
     } }>('/instruments/summary'),
 
-  instrumentSnapshot: async (instrument: InstrumentRef, signal?: AbortSignal) => {
-    const resp = await postInstrument<UnifiedInstrumentSnapshotDto>('/instruments/snapshot', hubInstrumentBody(instrument), signal)
+  instrumentSnapshot: async (
+    instrument: InstrumentRef,
+    opts?: { fresh?: boolean },
+    signal?: AbortSignal,
+  ) => {
+    const body = { ...hubInstrumentBody(instrument), ...(opts?.fresh ? { fresh: true } : {}) }
+    const resp = await postInstrument<UnifiedInstrumentSnapshotDto>('/instruments/snapshot', body, signal)
     if (resp.success && resp.data && isUnifiedSnapshot(resp.data)) {
       return {
         ...resp,

client-ui/src/market/CrossMarketSnapshotDetail.tsx

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { Spinner, Text, makeStyles, mergeClasses } from '@fluentui/react-components'
 import { EditRegular } from '@fluentui/react-icons'
 import { research } from '../api/client'
+import { quoteDtoToCrossMarket } from './instrument-adapters'
 import type { CryptoSnapshotData, UsSnapshotData, WatchlistItem } from '../types/market'
 import type { InstrumentRef } from '../types/instrument'
 import {
@@ -25,6 +26,7 @@ import { hasApplicationCapability } from './capabilities'
 import { isWatchlistItemWithinQuoteGrace } from './watchlistQuotes'
 import TradingViewChart from './TradingViewChart'
 import { DETAIL_PANEL_CHART_MAX_HEIGHT_PX } from './chartViewConfig'
+import { mergeSnapshotPreserveQuote } from './detailSnapshotUtils'
 import { opptrixTokens, opptrixCssVars } from '../theme/tokens'
 import { ghostInteractive } from '../theme/mixins'
 import { listRowKey } from '../utils/listRowKey'
@@ -269,25 +271,33 @@ function MiniKline({
   )
 }
 
-async function loadSnapshot(ref: InstrumentRef): Promise<EquityDetail | CryptoSnapshotData> {
+async function loadSnapshot(
+  ref: InstrumentRef,
+  opts?: { fresh?: boolean },
+): Promise<EquityDetail | CryptoSnapshotData> {
   if (!hasApplicationCapability(ref, 'snapshot')) {
     throw new Error('该标的暂不支持快照')
   }
-  const resp = await research.instrumentSnapshot(ref)
+  const resp = await research.instrumentSnapshot(ref, { fresh: opts?.fresh })
   if (!resp.success || !resp.data || typeof resp.data !== 'object') {
     throw new Error(resp.message || SNAPSHOT_LOAD_ERROR_COPY)
   }
-  return resp.data as EquityDetail | CryptoSnapshotData
-}
-
-/** 刷新成功但新 quote 为空时保留上一份，避免摘要闪没 */
-function mergeSnapshotPreserveQuote(
-  prev: EquityDetail | CryptoSnapshotData | null,
-  next: EquityDetail | CryptoSnapshotData,
-): EquityDetail | CryptoSnapshotData {
-  if (next.quote != null) return next
-  if (prev?.quote == null) return next
-  return { ...next, quote: prev.quote }
+  const data = resp.data as EquityDetail | CryptoSnapshotData
+  if (!data.quote && (ref.market === 'US' || ref.market === 'HK')) {
+    try {
+      const quoteResp = await research.instrumentQuote(ref, { fresh: true })
+      const q = quoteResp.success && quoteResp.data?.quote
+        ? quoteResp.data.quote
+        : null
+      if (q) {
+        return {
+          ...data,
+          quote: quoteDtoToCrossMarket(q),
+        }
+      }
+    } catch { /* ignore */ }
+  }
+  return data
 }
 
 function detailFootnote(ref: InstrumentRef, quote: { quoteSession?: string; sessionLabel?: string } | null): string {
@@ -346,34 +356,43 @@ export default function CrossMarketSnapshotDetail({
   const isCrypto = ref?.market === 'CRYPTO'
   const isEquity = ref?.market === 'US' || ref?.market === 'HK'
 
-  const [snapshot, setSnapshot] = useState<EquityDetail | CryptoSnapshotData | null>(null)
+  const [snapshotByKey, setSnapshotByKey] = useState<Record<string, EquityDetail | CryptoSnapshotData>>({})
   const [fetching, setFetching] = useState(false)
   const [error, setError] = useState<string | null>(null)
   const [, setGraceTick] = useState(0)
   const loadSeqRef = useRef(0)
-  const snapshotRef = useRef<EquityDetail | CryptoSnapshotData | null>(null)
   const initialRetryRef = useRef(0)
-  snapshotRef.current = snapshot
+  const freshLoadedRef = useRef<Set<string>>(new Set())
+  const snapshotByKeyRef = useRef(snapshotByKey)
+  snapshotByKeyRef.current = snapshotByKey
+  const snapshot = snapshotByKey[instrumentIdentity] ?? null
 
-  const load = useCallback(async () => {
+  const load = useCallback(async (opts?: { fresh?: boolean }) => {
     if (!ref) return
     const seq = ++loadSeqRef.current
     setFetching(true)
     let scheduleRetry = false
     try {
-      const data = await loadSnapshot(ref)
+      const data = await loadSnapshot(ref, { fresh: opts?.fresh })
       if (seq !== loadSeqRef.current) return
-      setSnapshot(prev => mergeSnapshotPreserveQuote(prev, data))
+      setSnapshotByKey(prev => {
+        const prior = prev[instrumentIdentity] ?? null
+        return {
+          ...prev,
+          [instrumentIdentity]: mergeSnapshotPreserveQuote(prior, data),
+        }
+      })
       setError(null)
       initialRetryRef.current = 0
+      if (opts?.fresh) freshLoadedRef.current.add(instrumentIdentity)
     } catch (e) {
       if (seq !== loadSeqRef.current) return
-      const hadQuote = snapshotRef.current?.quote != null
+      const hadQuote = snapshotByKeyRef.current[instrumentIdentity]?.quote != null
       if (!hadQuote && initialRetryRef.current < SNAPSHOT_INITIAL_MAX_RETRIES) {
         initialRetryRef.current += 1
         scheduleRetry = true
         window.setTimeout(() => {
-          void load()
+          void load({ fresh: true })
         }, SNAPSHOT_INITIAL_RETRY_MS * initialRetryRef.current)
         return
       }
@@ -383,22 +402,22 @@ export default function CrossMarketSnapshotDetail({
         setFetching(false)
       }
     }
-  }, [ref])
+  }, [ref, instrumentIdentity])
 
   useEffect(() => {
-    setSnapshot(null)
-    setError(null)
-    initialRetryRef.current = 0
     loadSeqRef.current += 1
+    initialRetryRef.current = 0
+    setError(null)
   }, [instrumentIdentity])
 
   useEffect(() => {
     if (!ref) return undefined
-    void load()
+    const fresh = !freshLoadedRef.current.has(instrumentIdentity)
+    void load({ fresh })
     const ms = isCrypto ? 30_000 : 90_000
-    const timer = window.setInterval(() => { void load() }, ms)
+    const timer = window.setInterval(() => { void load({ fresh: false }) }, ms)
     return () => window.clearInterval(timer)
-  }, [load, isCrypto, instrumentIdentity])
+  }, [load, isCrypto, instrumentIdentity, ref])
 
   useEffect(() => {
     if (!isWatchlistItemWithinQuoteGrace(stock)) return undefined

client-ui/src/market/EtfDetailTab.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useMemo, useState } from 'react'
+import { useEffect, useMemo, useRef, useState } from 'react'
 import { Spinner, Tab, TabList, Text, makeStyles, mergeClasses } from '@fluentui/react-components'
 import { research } from '../api/client'
 import type {
@@ -17,6 +17,8 @@ import {
   resolveDisplayStockName,
 } from './format'
 import { resolveWatchlistInstrument, watchlistItemKey, normalizeWatchlistItem } from './instrument'
+import { mergeDetailPreserveQuote } from './detailSnapshotUtils'
+import { patchEtfSnapshotQuoteIfMissing } from './detailQuoteFallback'
 import TradingViewChart from './TradingViewChart'
 import { DETAIL_PANEL_CHART_MAX_HEIGHT_PX } from './chartViewConfig'
 import EtfDecisionCard from './EtfDecisionCard'
@@ -302,7 +304,11 @@ function performanceRows(profile: EtfProfileData | null): Array<{ label: string;
 export default function EtfDetailTab({ stock }: Props) {
   const s = useStyles()
   const [tab, setTab] = useState<EtfTab>('overview')
-  const [snapshot, setSnapshot] = useState<EtfSnapshotData | null>(null)
+  const [snapshotByKey, setSnapshotByKey] = useState<Record<string, EtfSnapshotData>>({})
+  const freshLoadedRef = useRef<Set<string>>(new Set())
+  const loadSeqRef = useRef(0)
+  const snapshotByKeyRef = useRef(snapshotByKey)
+  snapshotByKeyRef.current = snapshotByKey
   const [navRows, setNavRows] = useState<EtfNavPoint[]>([])
   const [holdings, setHoldings] = useState<EtfHoldingRow[]>([])
   const [scorecard, setScorecard] = useState<EtfScorecardData | null>(null)
@@ -349,41 +355,54 @@ export default function EtfDetailTab({ stock }: Props) {
       })
   }
 
+  const snapshot = stockKey ? (snapshotByKey[stockKey] ?? null) : null
+
   useEffect(() => {
-    if (!chartInstrument) {
-      setSnapshot(null)
-      setNavRows([])
-      setHoldings([])
-      setScorecard(null)
+    if (!chartInstrument || !stockKey) {
       setError('')
       setScorecardError('')
       return undefined
     }
     let cancelled = false
+    const seq = ++loadSeqRef.current
+    const fresh = !freshLoadedRef.current.has(stockKey)
     setTab('overview')
     setLoading(true)
     setError('')
-    research.etfSnapshot(chartInstrument)
-      .then(resp => {
-        if (cancelled) return
+    research.etfSnapshot(chartInstrument, { fresh })
+      .then(async resp => {
+        if (cancelled || seq !== loadSeqRef.current) return
         if (!resp.success || !resp.data) {
-          setError(resp.message || '暂时无法加载 ETF 信息，请稍后再试')
-          setSnapshot(null)
+          if (!snapshotByKeyRef.current[stockKey]) {
+            setError(resp.message || '暂时无法加载 ETF 信息，请稍后再试')
+          }
           return
         }
-        setSnapshot(resp.data)
+        if (fresh) freshLoadedRef.current.add(stockKey)
+        const patched = await patchEtfSnapshotQuoteIfMissing(chartInstrument, resp.data)
+        if (cancelled || seq !== loadSeqRef.current) return
+        setSnapshotByKey(prev => ({
+          ...prev,
+          [stockKey]: mergeDetailPreserveQuote(prev[stockKey] ?? null, patched),
+        }))
+        setError('')
       })
       .catch(e => {
-        if (!cancelled) {
+        if (cancelled || seq !== loadSeqRef.current) return
+        if (!snapshotByKeyRef.current[stockKey]) {
           setError(e instanceof Error ? e.message : '加载失败')
-          setSnapshot(null)
         }
       })
       .finally(() => {
-        if (!cancelled) setLoading(false)
+        if (!cancelled && seq === loadSeqRef.current) setLoading(false)
       })
     return () => { cancelled = true }
-  }, [chartInstrument])
+  }, [chartInstrument, stockKey])
+
+  useEffect(() => {
+    loadSeqRef.current += 1
+    setError('')
+  }, [stockKey])
 
   useEffect(() => {
     if (!stockCode || tab !== 'decision') return undefined