Code Review 第二轮修复:前端 HTTP 统一 + 数据采集可靠性

F1: 统一前端 HTTP 客户端
- 新增 frontend/src/lib/http.ts(共享客户端,统一超时/错误/401 处理)
- Matches.tsx 的列表/分页/进行中/预测请求改用 http 客户端
- 公开站与 Admin 行为一致

D2: events 采集按联赛分批提交
- _run_bzzoiro 改为 per-league 独立事务,避免超长事务
- 单联赛失败不影响其他联赛

F3: 仪表盘真实计数
- admin_stats 补充 matches/stats/standings 真实聚合
- Dashboard 展示比赛总数/已完赛/统计行/积分榜

F4: LLM 连通性测试不依赖 match_id=1
- 新增 POST /admin/llm/ping 端点(只发一次 chat,不依赖比赛)
- testLLMConnection 优先调用 ping,失败回退旧方式

F5: 导航改用 React Router Link
- App.tsx 中 <a href> 全部替换为 <Link to>

D5: 删除 away_possession 死代码
- bzzoiro.py 中移除计算与注释

D1: 管线基础设施表文档化
- RawEvent/IngestFailure/DataQualityCheck/DataLineage 添加「预留未启用」注释

Co-Authored-By: new-provider/LongCat-2.0 <<EMAIL>>

frontend/src/App.tsx

@@ -11,7 +11,7 @@
  * - 未登录访问管理 → AdminLayout 门禁 → 登录页(不静默失败)
  */
 
-import { BrowserRouter, Routes, Route, Navigate } from 'react-router-dom'
+import { BrowserRouter, Routes, Route, Navigate, Link } from 'react-router-dom'
 import { ErrorBoundary } from './components/ErrorBoundary'
 import Matches from './pages/Matches'
 import Standings from './pages/Standings'
@@ -40,15 +40,15 @@ function StandingsLayout({ children }: { children: React.ReactNode }) {
           <div className="flex items-center justify-between border-b border-ink-200 py-2 text-2xs text-ink-500">
             <span>{dateLine()}</span>
             <nav className="flex items-center gap-4" aria-label="页面导航">
-              <a href="/" className="text-ink-500 hover:text-press transition-colors">
+              <Link to="/" className="text-ink-500 hover:text-press transition-colors">
                 比赛 / 预测
-              </a>
-              <a href="/admin/eval" className="text-ink-500 hover:text-press transition-colors">
+              </Link>
+              <Link to="/admin/eval" className="text-ink-500 hover:text-press transition-colors">
                 评估
-              </a>
-              <a href="/admin" className="flex items-center gap-1 text-ink-500 hover:text-press transition-colors">
+              </Link>
+              <Link to="/admin" className="flex items-center gap-1 text-ink-500 hover:text-press transition-colors">
                 <span aria-hidden="true">⚙</span> 管理
-              </a>
+              </Link>
             </nav>
           </div>
         </div>
@@ -81,15 +81,15 @@ function HomePage() {
           <div className="flex items-center justify-between border-b border-ink-200 py-2 text-2xs text-ink-500">
             <span>{dateLine()}</span>
             <nav className="flex items-center gap-4" aria-label="页面导航">
-              <a href="/standings" className="text-ink-500 hover:text-press transition-colors">
+              <Link to="/standings" className="text-ink-500 hover:text-press transition-colors">
                 积分榜
-              </a>
-              <a href="/admin/eval" className="text-ink-500 hover:text-press transition-colors">
+              </Link>
+              <Link to="/admin/eval" className="text-ink-500 hover:text-press transition-colors">
                 评估
-              </a>
-              <a href="/admin" className="flex items-center gap-1 text-ink-500 hover:text-press transition-colors">
+              </Link>
+              <Link to="/admin" className="flex items-center gap-1 text-ink-500 hover:text-press transition-colors">
                 <span aria-hidden="true">⚙</span> 管理
-              </a>
+              </Link>
             </nav>
           </div>
         </div>

frontend/src/admin/dal.ts

@@ -293,14 +293,17 @@ export function clearSetting(key: string) {
  * 测试 LLM 连接 — 调用预测端点验证
  */
 export async function testLLMConnection(matchId?: number): Promise<any> {
-  return api.post(
-    `${API_BASE}/predict`,
-    {
-      match_id: matchId || 1,
-      mode: 'single',
-    },
-    { timeoutMs: 300_000 },
-  )
+  // F4 修复: 优先使用不依赖比赛的 ping 端点
+  try {
+    return await api.post(`${API_BASE}/admin/llm/ping`, {})
+  } catch {
+    // 回退到旧方式(兼容)
+    return api.post(
+      `${API_BASE}/predict`,
+      { match_id: matchId || 1, mode: 'single' },
+      { timeoutMs: 300_000 },
+    )
+  }
 }
 
 /**

frontend/src/admin/pages/Dashboard.tsx

@@ -116,18 +116,39 @@ export default function Dashboard() {
         <CardHeader title="近期预测活动" description="预测 API 的调用量统计" />
         <CardBody>
           {stats ? (
-            <div className="grid grid-cols-3 gap-4 text-center">
-              <div>
-                <div className="font-serif text-3xl font-bold tabular-nums text-ink-900">{stats.predictions.last_24h}</div>
-                <div className="mt-1 text-2xs text-ink-400">近 24 小时</div>
+            <div className="space-y-4">
+              <div className="grid grid-cols-3 gap-4 text-center">
+                <div>
+                  <div className="font-serif text-3xl font-bold tabular-nums text-ink-900">{stats.predictions.last_24h}</div>
+                  <div className="mt-1 text-2xs text-ink-400">近 24 小时</div>
+                </div>
+                <div>
+                  <div className="font-serif text-3xl font-bold tabular-nums text-ink-900">{stats.predictions.last_7d}</div>
+                  <div className="mt-1 text-2xs text-ink-400">近 7 天</div>
+                </div>
+                <div>
+                  <div className="font-serif text-3xl font-bold tabular-nums text-ink-900">{stats.predictions.total}</div>
+                  <div className="mt-1 text-2xs text-ink-400">累计</div>
+                </div>
               </div>
-              <div>
-                <div className="font-serif text-3xl font-bold tabular-nums text-ink-900">{stats.predictions.last_7d}</div>
-                <div className="mt-1 text-2xs text-ink-400">近 7 天</div>
-              </div>
-              <div>
-                <div className="font-serif text-3xl font-bold tabular-nums text-ink-900">{stats.predictions.total}</div>
-                <div className="mt-1 text-2xs text-ink-400">累计</div>
+              {/* F3 修复: 真实比赛计数(非 limit=100 近似) */}
+              <div className="grid grid-cols-4 gap-3 border-t border-ink-200 pt-3 text-center">
+                <div>
+                  <div className="font-serif text-xl font-bold tabular-nums text-ink-900">{stats.matches?.total ?? 0}</div>
+                  <div className="mt-0.5 text-2xs text-ink-400">比赛总数</div>
+                </div>
+                <div>
+                  <div className="font-serif text-xl font-bold tabular-nums text-ink-900">{stats.matches?.finished ?? 0}</div>
+                  <div className="mt-0.5 text-2xs text-ink-400">已完赛</div>
+                </div>
+                <div>
+                  <div className="font-serif text-xl font-bold tabular-nums text-ink-900">{stats.stats?.total ?? 0}</div>
+                  <div className="mt-0.5 text-2xs text-ink-400">统计行</div>
+                </div>
+                <div>
+                  <div className="font-serif text-xl font-bold tabular-nums text-ink-900">{stats.standings?.total ?? 0}</div>
+                  <div className="mt-0.5 text-2xs text-ink-400">积分榜</div>
+                </div>
               </div>
             </div>
           ) : (

frontend/src/admin/types.ts

@@ -366,4 +366,7 @@ export interface AdminStats {
     last_24h: number
     last_7d: number
   }
+  matches?: { total: number; finished: number }
+  stats?: { total: number }
+  standings?: { total: number }
 }

frontend/src/lib/http.ts

@@ -0,0 +1,100 @@
+/**
+ * 共享 HTTP 客户端(公开站 + Admin 统一)
+ *
+ * 特性:
+ *   - 统一超时(默认 30s,可覆盖)
+ *   - 统一错误处理(ApiError)
+ *   - 401 自动广播(Admin 场景)
+ *   - JSON/HTML 容错解析
+ *   - 请求竞态防护(可选 signal)
+ */
+
+import { UNAUTHORIZED_EVENT } from '../admin/api'
+
+const API_BASE = '/api/v1'
+const DEFAULT_TIMEOUT = 30_000
+
+export class ApiError extends Error {
+  constructor(
+    message: string,
+    public status: number,
+    public data?: unknown,
+  ) {
+    super(message)
+    this.name = 'ApiError'
+  }
+}
+
+interface RequestOptions {
+  timeoutMs?: number
+  skipAuthHandling?: boolean
+  signal?: AbortSignal
+  method?: string
+  body?: string
+}
+
+async function request<T>(path: string, options: RequestOptions = {}): Promise<T> {
+  const url = path.startsWith('http') ? path : path.startsWith('/') ? path : `${API_BASE}${path}`
+  const { timeoutMs = DEFAULT_TIMEOUT, skipAuthHandling, signal } = options
+
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+
+  // 如果外部传了 signal,也关联到内部 controller
+  if (signal) {
+    signal.addEventListener('abort', () => controller.abort(), { once: true })
+  }
+
+  try {
+    const res = await fetch(url, {
+      signal: controller.signal,
+      headers: { 'Content-Type': 'application/json' },
+    })
+
+    if (!res.ok) {
+      const rawText = await res.text()
+      let detail: unknown = rawText
+      try {
+        detail = JSON.parse(rawText)
+      } catch {
+        // 非 JSON(如 HTML 错误页),保留原始文本
+      }
+      let message =
+        detail && typeof detail === 'object' && detail !== null && 'detail' in detail
+          ? String((detail as { detail: unknown }).detail)
+          : `HTTP ${res.status}: ${res.statusText}`
+
+      if (res.status === 401 && !skipAuthHandling) {
+        message += '\n登录已过期,请重新登录。'
+        window.dispatchEvent(new CustomEvent(UNAUTHORIZED_EVENT))
+      }
+      throw new ApiError(message, res.status, detail)
+    }
+
+    if (res.status === 204) {
+      return undefined as T
+    }
+
+    return res.json() as Promise<T>
+  } catch (err) {
+    if (err instanceof ApiError) throw err
+    if (err instanceof DOMException && err.name === 'AbortError') {
+      throw new ApiError('请求超时,请稍后重试', 0)
+    }
+    throw new ApiError(
+      err instanceof Error ? err.message : '网络错误,请检查连接',
+      0,
+    )
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+export const http = {
+  get: <T>(path: string, opts?: RequestOptions) => request<T>(path, { ...opts }),
+  post: <T>(path: string, body?: unknown, opts?: RequestOptions) =>
+    request<T>(path, { ...opts, method: 'POST', body: body ? JSON.stringify(body) : undefined }),
+  put: <T>(path: string, body?: unknown, opts?: RequestOptions) =>
+    request<T>(path, { ...opts, method: 'PUT', body: body ? JSON.stringify(body) : undefined }),
+  delete: <T>(path: string, opts?: RequestOptions) => request<T>(path, { ...opts, method: 'DELETE' }),
+}

frontend/src/pages/Matches.tsx

@@ -3,6 +3,7 @@ import TeamSideTag from '../components/TeamSideTag'
 import { fetchMatchDetail, fetchMatchContext } from '../admin/dal'
 import type { MatchDetailOut, MatchContextOut, MatchRecentPrediction, TeamRecentMatch } from '../admin/types'
 import type { MatchStatsDetail } from '../admin/types'
+import { http } from '../lib/http'
 
 interface Match {
   id: number
@@ -238,11 +239,8 @@ export default function Matches() {
     setError(null)
     try {
       const params = new URLSearchParams({ league, status, limit: '50' })
-      const res = await fetch(`/api/v1/matches?${params}`)
+      const data = await http.get<{ items: Match[]; next_cursor: string | null }>(`/matches?${params}`)
       if (seq !== loadSeq.current) return // 已有更新的请求,丢弃本次结果
-      if (!res.ok) throw new Error(`HTTP ${res.status}`)
-      const data = await res.json()
-      if (seq !== loadSeq.current) return
       setMatches(data.items)
       setNextCursor(data.next_cursor ?? null)
     } catch (e) {
@@ -260,10 +258,7 @@ export default function Matches() {
     setLoadingMore(true)
     try {
       const params = new URLSearchParams({ league, status, limit: '50', cursor: nextCursor })
-      const res = await fetch(`/api/v1/matches?${params}`)
-      if (seq !== loadSeq.current) return
-      if (!res.ok) throw new Error(`HTTP ${res.status}`)
-      const data = await res.json()
+      const data = await http.get<{ items: Match[]; next_cursor: string | null }>(`/matches?${params}`)
       if (seq !== loadSeq.current) return
       setMatches(prev => [...prev, ...data.items])
       setNextCursor(data.next_cursor ?? null)
@@ -279,9 +274,7 @@ export default function Matches() {
   const loadLive = useCallback(async () => {
     try {
       const params = new URLSearchParams({ league, status: 'in_play', limit: '20' })
-      const res = await fetch(`/api/v1/matches?${params}`)
-      if (!res.ok) return
-      const data = await res.json()
+      const data = await http.get<{ items: Match[] }>(`/matches?${params}`)
       setLiveMatches(data.items ?? [])
     } catch {
       /* ignore:进行中非核心功能 */
@@ -340,19 +333,11 @@ export default function Matches() {
     predictAbort.current = controller
     const timer = setTimeout(() => controller.abort(), 300_000)
     try {
-      const res = await fetch('/api/v1/predict', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ match_id: m.id, mode: 'multi' }),
+      const data = await http.post<Prediction>('/predict', { match_id: m.id, mode: 'multi' }, {
+        timeoutMs: 300_000,
         signal: controller.signal,
       })
       if (seq !== predictSeq.current) return
-      if (!res.ok) {
-        const t = await res.text()
-        throw new Error(`HTTP ${res.status}: ${t}`)
-      }
-      const data = await res.json()
-      if (seq !== predictSeq.current) return
       setPrediction(data)
     } catch (e) {
       if (seq !== predictSeq.current) return