chore(P3): baseline 落库下沉 + MatchPredictPanel 拆分 + 多 worker/CSRF 文档

P3-2 baseline 落库从路由下沉到服务层(predict_baseline 内直接落库),
删除路由层 _persist_baseline,三种模式统一 result.prediction_id,对外 JSON 不变。

P3-1 MatchPredictPanel.PredictionPanel 拆为 OutcomePanel/AgentsPanel/ReasoningPanel
三个子组件,本文件保留 PredictModal/PredictProgress/Spinner,对外导出路径不变。

P3-3 docs 加 ⚠️ 多 worker 陷阱红字 + STRICT_SINGLE_WORKER 环境变量(启动期强制拒绝多 worker)。
P3-4 docs 新增「同站部署 vs 跨站 CSRF」节。

docs/05-data.md

@@ -63,6 +63,36 @@
 `src/data/team_names.py` 维护 `NORMALIZE_MAP`(如 `Man City` → `Manchester City`),未命中映射的队名原样返回。
 归一前先做 Unicode NFKD 去重音。
 
+**唯一键是归一后英文名**:`teams.name` 带 `UNIQUE` 约束,所有入库路径均经 `TeamRepository.get_or_create` 收敛归一化
+(events / standings 管线在调用前归一,仓库层再做一次幂等归一作为兜底)。创建新 Team 时打 `info` 日志记录「原始名 → 归一后名」。
+
+> ⚠️ **`normalize` 当前大小写敏感**:仅当入参大小写与 `NORMALIZE_MAP` 键完全匹配时才触发映射
+>(如 `"Man City"` → `"Manchester City"`,但 `"man city"` 原样保留)。上游 bzzoiro 返回的队名首字母大写,
+>实际命中无问题;若新增数据源返回全小写/全大写队名,需先 `title()` 再归一,否则会绕过映射产生重复 Team。
+
+**改名 / 合并流程**(人工):
+
+当发现两个 `teams` 行实际是同一球队(如 `Manchester City` 与 `Man City` 因历史数据大小写差异各占一行):
+
+1. 确定**保留行**(通常选归一后规范名、且被更多 Match 引用的那行)。
+2. 将被删行的所有引用指向保留行(`UPDATE matches SET home_team_id = 保留id WHERE home_team_id = 删行id`,客场同理;
+   `standings` / `match_stats` 按 `team_id` 同理)。
+3. 删掉多余行:`DELETE FROM teams WHERE id = 删行id`。
+
+> 此过程引入外键约束风险,务必在事务中执行并先 `BEGIN; ... ` 验证行数后再 `COMMIT`。
+> 暂不做自动合并(避免误合相似名),仅通过下方 Admin 接口列出「近似重名」候选,由人工判定。
+
+## Admin:近似重名候选
+
+`GET /api/v1/admin/team-name-duplicates` 只读列出启发式相似候选(大小写差异、子串包含、前缀碰撞),不做自动合并。
+典型用途:定期巡检,发现候选后走上方人工 SQL 合并。启发式规则:
+
+- **大小写变体**:`lower(name)` 相同但 `name` 不同(如 `Arsenal FC` / `arsenal fc`)。
+- **子串包含**:A 是 B 的子串且长度 ≥ 5(如 `Manchester` / `Manchester City`)。
+- **前缀碰撞**:前 8 个字符相同的两队。
+
+命中任一规则即列为候选,按相似度分组返回。
+
 ## 数据库 Schema
 
 12 张表:核心业务表 5 张见下方 DDL,其余 7 张(积分榜/配置/调度/治理)见后文表格。

docs/06-deployment.md

@@ -46,6 +46,9 @@ curl http://localhost:8000/health
 - [ ] **6. 反代信任头** — `TRUST_PROXY_HEADERS=True`,且**仅可信反代可达 API**;反代需设置 `X-Forwarded-For`(`$proxy_add_x_forwarded_for`)与 `X-Real-IP`,否则限流/日志按反代 IP 计数
 - [ ] **7. 限流前置到网关** — 推荐 Nginx `limit_req`(配置见[安全与限流](#安全与限流));应用内限流与 KeyRing 为**单进程内存实现**,多 worker 各自独立计数会把实际配额放大 N 倍(启动时会打印一次性告警)
 - [ ] **8. uvicorn 单 worker** — compose/Dockerfile 默认单 worker,保持即可;需横向扩容时先在网关统一限流,再起多实例(每实例仍单 worker)
+
+> ⚠️ **多 worker 陷阱**:应用内限流(`_RateLimiter`)与 KeyRing 均为**进程内纯内存状态**,多 worker 部署(如 `uvicorn --workers 4`)时各进程**各自独立计数、互不共享**——实际限流配额会被放大 N 倍、KeyRing 限流状态也不同步。
+> 若确需多 worker,必须前置 Nginx/网关做**全局限流**(见[安全与限流](#安全与限流)),并设环境变量 `STRICT_SINGLE_WORKER=True`(见下)在启动期强制拒绝多 worker,避免静默配额漂移。
 - [ ] **9. 启动后健康检查** — `curl /health` 返回 200(存活);`curl /health/ready` 返回 200(就绪,校验数据库连通,不可达时 503)
 - [ ] **10. 数据库迁移** — compose/Dockerfile 启动命令已内置 `alembic upgrade head && uvicorn …`,升级镜像重启即自动迁移,无需手动执行
 
@@ -99,10 +102,29 @@ cd frontend && npm install && npm run dev
 | `LLM_AGGREGATOR_MODEL` | ❌ | — | 终裁模型(回落 `LLM_MODEL`) |
 | `BZZOIRO_KEY` | ✅ | — | bzzoiro 数据源 Key(唯一数据源) |
 | `CORS_ORIGINS` | ❌ | `http://localhost:5173,...` | 允许的跨域来源 |
+| `STRICT_SINGLE_WORKER` | ❌ | `False` | `True` 时若以多 worker 启动则拒绝(防限流配额漂移) |
 | `SECRET_KEY` | ❌ | — | 加密主密钥(生产环境必填) |
 | `ADMIN_PASSWORD` | ❌ | — | 管理后台密码(留空=不启用) |
 | `ADMIN_API_KEY` | ❌ | — | 机器/脚本调用的 API Key |
 
+## 同站部署 vs 跨站 CSRF
+
+ Profeto 管理鉴权使用 **HttpOnly Cookie 会话**(登录后服务端写入),`allow_credentials=True` 的 CORS 配置允许浏览器跨域携带 Cookie——这也引入了 CSRF 面。部署拓扑决定风险等级:
+
+**同站部署(推荐)**: 前端与 API 同域(反代把 `/` 与 `/api` 都转发到同一后端,或同源端口)。
+  - 浏览器视为 **same-origin**,CORS 不触发;`SameSite=Lax` 会话 Cookie 天然阻断跨站请求携带。
+  - 风险最低。`CORS_ORIGINS` 可设为空或同域来源,仅作兜底。
+
+**跨站部署**: 前端与 API 不同域(如前端 `app.example.com`、API `api.example.com`,或开发时 `localhost:3000` → `localhost:8000`)。
+  - 必须把 API 域名列入 `CORS_ORIGINS`,且 `allow_credentials=True` 才能携带 Cookie。
+  - 此时任何被允许域下的页面都能构造带 Cookie 的请求 → **CSRF 面**:
+    - 状态变更接口(采集/回测/改密等写操作)要求**管理员 Cookie + 同域**,攻击者无法从第三方站点读取 Cookie,但可构造跨域表单/请求——`SameSite=Lax` 会阻断跨站 POST 表单提交(顶级导航 GET 仍放行),这是当前主要防线。
+    - `GET /api/v1/admin/*` 只读接口受 `SameSite=Lax` 下顶级导航可能被利用,但攻击者无法读取响应(CORS 不匹配时浏览器拦截)。
+  - **加固建议**:
+    1. 反代层加 `Origin`/`Referer` 校验,仅放行 `CORS_ORIGINS` 列表中的来源(即便 FastAPI CORS 已通过,反代校验是多一层纵深)。
+    2. 写操作要求自定义请求头(如 `X-Requested-With: XMLHttpRequest`),第三方站点无法在无预检下添加自定义头,天然阻断简单跨站 POST。
+    3. 生产强制 HTTPS(`APP_ENV=production` 下 Cookie 自动 `Secure`),防中间人窃 Cookie。
+
 ## LLM 提供商配置示例
 
 ### OpenAI

frontend/src/pages/matches/components/AgentsPanel.tsx

@@ -0,0 +1,171 @@
+/**
+ * AgentsPanel: 五路专家意见 —— 可折叠 + 状态摘要 + 权重条形图 + 单路详情。
+ *
+ * P3-1: 从 MatchPredictPanel.PredictionPanel 拆出,渲染逻辑原样搬迁。
+ */
+import { useState } from 'react'
+import type { AgentReport, Prediction } from '../../types'
+import { AGENT_LABELS, CN_NUM } from '../../types'
+
+const STATUS_BADGE: Record<string, { label: string; cls: string }> = {
+  ok: { label: '正常', cls: 'text-ink-500' },
+  no_data: { label: '无数据', cls: 'text-ink-400' },
+  error: { label: '调用失败', cls: 'text-press' },
+  parse_error: { label: '解析失败', cls: 'text-press' },
+}
+
+const SUFFICIENCY_LABEL: Record<string, string> = {
+  high: '充分',
+  medium: '一般',
+  low: '偏少',
+  none: '无',
+}
+
+/** home_edge(-1~1,正=利主队)的可视化:以中线为原点的双向细条 */
+function EdgeBar({ value }: { value: number }) {
+  const v = Math.max(-1, Math.min(1, value))
+  const half = Math.abs(v) * 50
+  return (
+    <div className="relative h-px w-full bg-ink-200" role="presentation">
+      <span className="absolute left-1/2 top-1/2 h-2 w-px -translate-x-1/2 -translate-y-1/2 bg-ink-400" />
+      <span
+        className={`absolute top-0 h-px transition-all duration-500 ${v >= 0 ? 'bg-press' : 'bg-ink-600'}`}
+        style={
+          v >= 0
+            ? { left: '50%', width: `${half}%` }
+            : { right: '50%', width: `${half}%` }
+        }
+      />
+    </div>
+  )
+}
+
+/** 单路专家意见:汉字编号 + 细线行 */
+function AgentCard({ report: r, no }: { report: AgentReport; no: string }) {
+  const badge = STATUS_BADGE[r.status] ?? { label: r.status, cls: 'text-ink-400' }
+  const inactive = r.status !== 'ok'
+
+  return (
+    <details className="group border-b border-ink-200">
+      <summary className="flex cursor-pointer list-none items-baseline gap-2.5 px-1 py-3">
+        <span className="font-serif text-sm text-ink-400">{no}</span>
+        <span className="text-sm font-medium text-ink-900">{AGENT_LABELS[r.agent] ?? r.agent}</span>
+        <span className={`text-2xs ${badge.cls}`}>{badge.label}</span>
+
+        <span className="ml-auto flex items-baseline gap-3 text-2xs tabular-nums text-ink-500">
+          {r.status === 'ok' && r.subjective_confidence !== null && (
+            <span>信心 {Math.round(r.subjective_confidence * 100)}%</span>
+          )}
+          {r.status === 'ok' && r.probable_score && (
+            <span className="font-serif font-bold text-ink-800">{r.probable_score}</span>
+          )}
+          <svg viewBox="0 0 20 20" className="h-3 w-3 self-center text-ink-300 transition-transform group-open:rotate-90" fill="currentColor" aria-hidden="true">
+            <path d="M7.3 5.3a1 1 0 011.4 0l4 4a1 1 0 010 1.4l-4 4a1 1 0 01-1.4-1.4L10.6 10 7.3 6.7a1 1 0 010-1.4z" />
+          </svg>
+        </span>
+      </summary>
+
+      <div className="space-y-3 px-1 pb-4 pl-7">
+        {inactive && (
+          <p className="text-xs leading-relaxed text-ink-500">
+            {r.status === 'no_data' && '该维度没有可用数据,已跳过 LLM 分析以节省额度(不影响其他专家)。'}
+            {r.status === 'error' && '该专家调用失败,本次结论未纳入其视角(fail-open 设计,不阻断整体预测)。'}
+            {r.status === 'parse_error' && '模型输出未通过格式校验,该报告已丢弃。'}
+          </p>
+        )}
+
+        {!inactive && r.home_edge !== null && (
+          <div>
+            <div className="mb-1.5 flex items-baseline justify-between text-2xs">
+              <span className="text-ink-500">主队优势</span>
+              <span className={`font-semibold tabular-nums ${r.home_edge > 0 ? 'text-press' : r.home_edge < 0 ? 'text-ink-700' : 'text-ink-500'}`}>
+                {r.home_edge > 0 ? '+' : ''}{r.home_edge.toFixed(2)}
+              </span>
+            </div>
+            <EdgeBar value={r.home_edge} />
+            <div className="mt-1 flex justify-between text-2xs text-ink-400">
+              <span>利客队</span>
+              <span>利主队</span>
+            </div>
+          </div>
+        )}
+
+        {r.analysis && (
+          <p className="font-serif text-sm leading-loose text-ink-700">{r.analysis}</p>
+        )}
+
+        {r.key_evidence.length > 0 && (
+          <ul className="space-y-1.5">
+            {r.key_evidence.map((e, i) => (
+              <li key={i} className="flex gap-2 text-xs leading-relaxed text-ink-600">
+                <span className="flex-shrink-0 text-ink-300" aria-hidden="true">—</span>
+                <span>{e}</span>
+              </li>
+            ))}
+          </ul>
+        )}
+
+        {r.exp_home_goals !== null && r.exp_away_goals !== null && (
+          <p className="text-xs text-ink-500">
+            进球期望 <span className="font-serif font-bold tabular-nums text-ink-900">{r.exp_home_goals.toFixed(1)} - {r.exp_away_goals.toFixed(1)}</span>
+          </p>
+        )}
+
+        {!inactive && (
+          <p className="border-t border-ink-100 pt-2.5 text-2xs text-ink-400">
+            数据充分度 {SUFFICIENCY_LABEL[r.data_sufficiency] ?? r.data_sufficiency}
+            <span className="mx-2 text-ink-200">|</span>
+            <span className="font-mono">{r.model}</span>
+            {r.latency_ms !== null && <span className="ml-2 tabular-nums">{r.latency_ms}ms</span>}
+          </p>
+        )}
+      </div>
+    </details>
+  )
+}
+
+export function AgentsPanel({ prediction }: { prediction: Prediction }) {
+  const [expertsOpen, setExpertsOpen] = useState(false)
+  const degraded = prediction.status === 'degraded' || prediction.status === 'failed'
+  const reports = prediction.agent_outputs ?? []
+  const okReports = reports.filter(r => r.status === 'ok')
+
+  if (reports.length === 0) return null
+
+  return (
+    <section>
+      <button
+        onClick={() => setExpertsOpen(o => !o)}
+        className="flex w-full items-center justify-between border-b border-ink-200 pb-2 text-left"
+      >
+        <span className="section-head mb-0">五路专家意见({okReports.length}/{reports.length} 路有效)</span>
+        <span className="text-2xs text-ink-400">{expertsOpen ? '收起' : '展开'}</span>
+      </button>
+
+      {!degraded && prediction.agent_weights && Object.keys(prediction.agent_weights).length > 0 && (
+        <div className="mt-3 space-y-1.5">
+          <span className="text-2xs text-ink-500">终裁权重分布</span>
+          {Object.entries(prediction.agent_weights)
+            .sort((a, b) => b[1] - a[1])
+            .map(([k, v]) => (
+              <div key={k} className="grid grid-cols-[96px_minmax(0,1fr)_40px] items-center gap-2">
+                <span className="truncate text-2xs text-ink-500">{AGENT_LABELS[k] ?? k}</span>
+                <div className="h-1.5 bg-paper-100">
+                  <div className="h-full bg-press" style={{ width: `${Math.round(v * 100)}%` }} />
+                </div>
+                <span className="text-right text-2xs tabular-nums text-ink-500">{Math.round(v * 100)}%</span>
+              </div>
+            ))}
+        </div>
+      )}
+
+      {expertsOpen && (
+        <div className="mt-2">
+          {reports.map((r, i) => (
+            <AgentCard key={r.agent} report={r} no={CN_NUM[i] ?? String(i + 1)} />
+          ))}
+        </div>
+      )}
+    </section>
+  )
+}

frontend/src/pages/matches/components/MatchPredictPanel.tsx

@@ -6,37 +6,11 @@
  */
 import { useEffect, useState } from 'react'
 import TeamSideTag from '../../../components/TeamSideTag'
-import type { AgentReport, Match, Prediction } from '../types'
-import { AGENT_LABELS, CN_NUM, OUTCOME_LABEL } from '../types'
-
-/** 置信度细线:0~1 数值的低调可视化 */
-function Meter({ value }: { value: number }) {
-  const pct = Math.max(0, Math.min(100, Math.round(value * 100)))
-  return (
-    <div className="h-px w-full bg-ink-200" role="presentation">
-      <div className="h-px bg-press transition-[width] duration-500" style={{ width: `${pct}%` }} />
-    </div>
-  )
-}
-
-/** home_edge(-1~1,正=利主队)的可视化:以中线为原点的双向细条 */
-function EdgeBar({ value }: { value: number }) {
-  const v = Math.max(-1, Math.min(1, value))
-  const half = Math.abs(v) * 50
-  return (
-    <div className="relative h-px w-full bg-ink-200" role="presentation">
-      <span className="absolute left-1/2 top-1/2 h-2 w-px -translate-x-1/2 -translate-y-1/2 bg-ink-400" />
-      <span
-        className={`absolute top-0 h-px transition-all duration-500 ${v >= 0 ? 'bg-press' : 'bg-ink-600'}`}
-        style={
-          v >= 0
-            ? { left: '50%', width: `${half}%` }
-            : { right: '50%', width: `${half}%` }
-        }
-      />
-    </div>
-  )
-}
+import type { Match, Prediction } from '../types'
+import { AGENT_LABELS } from '../types'
+import { AgentsPanel } from './AgentsPanel'
+import { OutcomePanel } from './OutcomePanel'
+import { ReasoningPanel } from './ReasoningPanel'
 
 function Spinner({ className = '' }: { className?: string }) {
   return (
@@ -53,77 +27,73 @@ function Spinner({ className = '' }: { className?: string }) {
 }
 
 /** 胜平负一行文字:选中的红字加方块标记,未选中的退灰 */
-function OutcomeLine({
-  pick,
-  confidence,
+.**
+ * P3-1:PredictionPanel 不再自绘,改为组合三个子组件:
+ *   OutcomePanel(比分/胜平负/成本) / AgentsPanel(专家意见) / ReasoningPanel(终裁/降级)。
+ * 渲染输出与拆分前完全一致(仅降级警示 + 报头 + 元信息仍在此处)。
+ */
+function PredictionPanel({
+  prediction,
+  match,
+  embedded = false,
 }: {
-  pick: string | null
-  confidence: number | null
+  prediction: Prediction
+  match: Match
+  /** 弹窗嵌入模式:弹窗已提供报头,这里省略自带版头 */
+  embedded?: boolean
 }) {
-  const options = ['1', 'X', '2'] as const
+  const homeName = match.home_team_zh || match.home_team
+  const awayName = match.away_team_zh || match.away_team
+  const degraded = prediction.status === 'degraded' || prediction.status === 'failed'
+  const reports = prediction.agent_outputs ?? []
+  const okReports = reports.filter(r => r.status === 'ok')
+
   return (
-    <div>
-      <div className="flex items-baseline justify-center gap-6 sm:gap-10">
-        {options.map(o => {
-          const on = pick === o
-          return (
-            <div key={o} className="flex flex-col items-center gap-1">
-              <span className={`flex items-center gap-1.5 text-sm ${on ? 'font-semibold text-press' : 'text-ink-400'}`}>
-                {on && <span className="inline-block h-2 w-2 bg-press" aria-hidden="true" />}
-                {OUTCOME_LABEL[o]}
-              </span>
-              {on && confidence !== null && (
-                <span className="text-2xs tabular-nums text-ink-500">
-                  置信 {Math.round(confidence * 100)}%
-                </span>
-              )}
-            </div>
-          )
-        })}
+    <article className={embedded ? 'bg-paper-50' : 'border border-ink-900 bg-paper-50'}>
+      {!embedded && (
+      <div className="flex flex-wrap items-baseline justify-between gap-2 border-b border-ink-900 bg-paper-100 px-4 py-2.5 sm:px-5">
+        <h3 className="flex flex-wrap items-center gap-1.5 font-serif text-sm font-bold text-ink-900">
+          预测版 ·
+          <TeamSideTag side="home" />
+          {homeName}
+          <span>对</span>
+          <TeamSideTag side="away" />
+          {awayName}
+        </h3>
+        <span className="text-2xs tabular-nums text-ink-500">
+          {prediction.provider} / {prediction.model}
+          {prediction.latency_ms !== null && ` · ${(prediction.latency_ms / 1000).toFixed(1)}s`}
+        </span>
       </div>
-      {pick && confidence !== null && (
-        <div className="mx-auto mt-3 max-w-xs">
-          <Meter value={confidence} />
-          <p className="mt-1 text-center text-2xs text-ink-400">主观置信度,非统计概率</p>
-        </div>
       )}
-    </div>
-  )
-}
 
-/** 预测成本展示:耗时 + token + 限流余量 */
-function PredictionCost({ prediction }: { prediction: Prediction }) {
-  const latency = prediction.latency_ms != null ? `${(prediction.latency_ms / 1000).toFixed(1)}s` : null
-  const tokens = prediction.prompt_tokens != null || prediction.completion_tokens != null
-    ? `${prediction.prompt_tokens ?? '?'}/${prediction.completion_tokens ?? '?'}`
-    : null
+      <div className="space-y-7 px-4 py-6 sm:px-5">
+        {degraded && (
+          <div className="border-l-2 border-press bg-press-wash/40 px-4 py-3">
+            <p className="font-serif text-sm font-bold text-press-dark">
+              {prediction.status === 'failed' ? '预测失败' : '预测降级(degraded)'}
+            </p>
+            <p className="mt-1.5 whitespace-pre-wrap text-xs leading-relaxed text-ink-600">
+              {prediction.reasoning || '所有专家均无有效数据或调用失败,无法生成可靠比分。'}
+            </p>
+          </div>
+        )}
 
-  if (!latency && !tokens && prediction.rate_limit_remaining == null) return null
+        {!degraded && <OutcomePanel prediction={prediction} match={match} />}
 
-  return (
-    <div className="border-t border-ink-200 pt-3 text-2xs text-ink-500">
-      <div className="flex flex-wrap items-center justify-center gap-x-4 gap-y-1">
-        {latency && (
-          <span className="inline-flex items-center gap-1">
-            <span aria-hidden="true" className="opacity-60">⏱</span>耗时 {latency}
-          </span>
-        )}
-        {tokens && (
-          <span className="inline-flex items-center gap-1">
-            <span aria-hidden="true" className="opacity-60">Tok</span>prompt/completion: {tokens}
-          </span>
-        )}
-        {prediction.rate_limit_remaining != null && prediction.rate_limit_remaining <= 3 && (
-          <span className="text-press" title="每分钟最多 10 次预测">
-            剩余配额: {prediction.rate_limit_remaining}/10(分钟)
-          </span>
-        )}
+        <p className="text-center text-2xs text-ink-500">
+          `多专家模式 · ${okReports.length}/${reports.length} 路有效`
+          {prediction.prompt_version && ` · prompt ${prediction.prompt_version}`}
+        </p>
+
+        <AgentsPanel prediction={prediction} />
+
+        <ReasoningPanel prediction={prediction} />
       </div>
-    </div>
+    </article>
   )
 }
 
-/** 预测过程阶段(按时长模拟;结果到达即跳到完成) */
 function PredictProgress() {
   const [elapsed, setElapsed] = useState(0)
   useEffect(() => {
@@ -199,256 +169,6 @@ function PredictProgress() {
     </div>
   )
 }
-
-const STATUS_BADGE: Record<string, { label: string; cls: string }> = {
-  ok: { label: '正常', cls: 'text-ink-500' },
-  no_data: { label: '无数据', cls: 'text-ink-400' },
-  error: { label: '调用失败', cls: 'text-press' },
-  parse_error: { label: '解析失败', cls: 'text-press' },
-}
-
-const SUFFICIENCY_LABEL: Record<string, string> = {
-  high: '充分',
-  medium: '一般',
-  low: '偏少',
-  none: '无',
-}
-
-/** 单路专家意见:汉字编号 + 细线行 */
-function AgentCard({ report: r, no }: { report: AgentReport; no: string }) {
-  const badge = STATUS_BADGE[r.status] ?? { label: r.status, cls: 'text-ink-400' }
-  const inactive = r.status !== 'ok'
-
-  return (
-    <details className="group border-b border-ink-200">
-      <summary className="flex cursor-pointer list-none items-baseline gap-2.5 px-1 py-3">
-        <span className="font-serif text-sm text-ink-400">{no}</span>
-        <span className="text-sm font-medium text-ink-900">{AGENT_LABELS[r.agent] ?? r.agent}</span>
-        <span className={`text-2xs ${badge.cls}`}>{badge.label}</span>
-
-        <span className="ml-auto flex items-baseline gap-3 text-2xs tabular-nums text-ink-500">
-          {r.status === 'ok' && r.subjective_confidence !== null && (
-            <span>信心 {Math.round(r.subjective_confidence * 100)}%</span>
-          )}
-          {r.status === 'ok' && r.probable_score && (
-            <span className="font-serif font-bold text-ink-800">{r.probable_score}</span>
-          )}
-          <svg viewBox="0 0 20 20" className="h-3 w-3 self-center text-ink-300 transition-transform group-open:rotate-90" fill="currentColor" aria-hidden="true">
-            <path d="M7.3 5.3a1 1 0 011.4 0l4 4a1 1 0 010 1.4l-4 4a1 1 0 01-1.4-1.4L10.6 10 7.3 6.7a1 1 0 010-1.4z" />
-          </svg>
-        </span>
-      </summary>
-
-      <div className="space-y-3 px-1 pb-4 pl-7">
-        {/* 无数据 / 失败时给出明确说明,避免用户以为是空白 bug */}
-        {inactive && (
-          <p className="text-xs leading-relaxed text-ink-500">
-            {r.status === 'no_data' && '该维度没有可用数据,已跳过 LLM 分析以节省额度(不影响其他专家)。'}
-            {r.status === 'error' && '该专家调用失败,本次结论未纳入其视角(fail-open 设计,不阻断整体预测)。'}
-            {r.status === 'parse_error' && '模型输出未通过格式校验,该报告已丢弃。'}
-          </p>
-        )}
-
-        {!inactive && r.home_edge !== null && (
-          <div>
-            <div className="mb-1.5 flex items-baseline justify-between text-2xs">
-              <span className="text-ink-500">主队优势</span>
-              <span className={`font-semibold tabular-nums ${r.home_edge > 0 ? 'text-press' : r.home_edge < 0 ? 'text-ink-700' : 'text-ink-500'}`}>
-                {r.home_edge > 0 ? '+' : ''}{r.home_edge.toFixed(2)}
-              </span>
-            </div>
-            <EdgeBar value={r.home_edge} />
-            <div className="mt-1 flex justify-between text-2xs text-ink-400">
-              <span>利客队</span>
-              <span>利主队</span>
-            </div>
-          </div>
-        )}
-
-        {r.analysis && (
-          <p className="font-serif text-sm leading-loose text-ink-700">{r.analysis}</p>
-        )}
-
-        {r.key_evidence.length > 0 && (
-          <ul className="space-y-1.5">
-            {r.key_evidence.map((e, i) => (
-              <li key={i} className="flex gap-2 text-xs leading-relaxed text-ink-600">
-                <span className="flex-shrink-0 text-ink-300" aria-hidden="true">—</span>
-                <span>{e}</span>
-              </li>
-            ))}
-          </ul>
-        )}
-
-        {r.exp_home_goals !== null && r.exp_away_goals !== null && (
-          <p className="text-xs text-ink-500">
-            进球期望 <span className="font-serif font-bold tabular-nums text-ink-900">{r.exp_home_goals.toFixed(1)} - {r.exp_away_goals.toFixed(1)}</span>
-          </p>
-        )}
-
-        {!inactive && (
-          <p className="border-t border-ink-100 pt-2.5 text-2xs text-ink-400">
-            数据充分度 {SUFFICIENCY_LABEL[r.data_sufficiency] ?? r.data_sufficiency}
-            <span className="mx-2 text-ink-200">|</span>
-            <span className="font-mono">{r.model}</span>
-            {r.latency_ms !== null && <span className="ml-2 tabular-nums">{r.latency_ms}ms</span>}
-          </p>
-        )}
-      </div>
-    </details>
-  )
-}
-
-function PredictionPanel({
-  prediction,
-  match,
-  embedded = false,
-}: {
-  prediction: Prediction
-  match: Match
-  /** 弹窗嵌入模式:弹窗已提供报头,这里省略自带版头 */
-  embedded?: boolean
-}) {
-  const homeName = match.home_team_zh || match.home_team
-  const [expertsOpen, setExpertsOpen] = useState(false)
-  const awayName = match.away_team_zh || match.away_team
-  const degraded = prediction.status === 'degraded' || prediction.status === 'failed'
-  const reports = prediction.agent_outputs ?? []
-  const okReports = reports.filter(r => r.status === 'ok')
-
-  return (
-    <article className={embedded ? 'bg-paper-50' : 'border border-ink-900 bg-paper-50'}>
-      {!embedded && (
-      <div className="flex flex-wrap items-baseline justify-between gap-2 border-b border-ink-900 bg-paper-100 px-4 py-2.5 sm:px-5">
-        <h3 className="flex flex-wrap items-center gap-1.5 font-serif text-sm font-bold text-ink-900">
-          预测版 ·
-          <TeamSideTag side="home" />
-          {homeName}
-          <span>对</span>
-          <TeamSideTag side="away" />
-          {awayName}
-        </h3>
-        <span className="text-2xs tabular-nums text-ink-500">
-          {prediction.provider} / {prediction.model}
-          {prediction.latency_ms !== null && ` · ${(prediction.latency_ms / 1000).toFixed(1)}s`}
-        </span>
-      </div>
-      )}
-
-      <div className="space-y-7 px-4 py-6 sm:px-5">
-        {/* ── degraded / failed 态:醒目警示 + 原因,不展示虚假比分 ── */}
-        {degraded && (
-          <div className="border-l-2 border-press bg-press-wash/40 px-4 py-3">
-            <p className="font-serif text-sm font-bold text-press-dark">
-              {prediction.status === 'failed' ? '预测失败' : '预测降级(degraded)'}
-            </p>
-            <p className="mt-1.5 whitespace-pre-wrap text-xs leading-relaxed text-ink-600">
-              {prediction.reasoning || '所有专家均无有效数据或调用失败,无法生成可靠比分。'}
-            </p>
-          </div>
-        )}
-
-        {/* ── 主结论(仅 success 展示) ── */}
-        {!degraded && (
-          <>
-            <div className="text-center">
-              <p className="font-serif text-5xl font-bold tabular-nums leading-none text-ink-900 sm:text-6xl">
-                {prediction.pred_home_goals ?? '-'}
-                <span className="mx-3 font-normal text-ink-300">:</span>
-                {prediction.pred_away_goals ?? '-'}
-              </p>
-              <p className="mt-3 text-2xs tracking-[0.5em] text-ink-400">预测比分</p>
-              {prediction.alt_pred_home_goals != null && prediction.alt_pred_away_goals != null && (
-                <p className="mt-2 text-2xs tabular-nums text-ink-400">
-                  备选{' '}
-                  <span className="font-serif text-sm font-bold tabular-nums text-ink-600">
-                    {prediction.alt_pred_home_goals}<span className="mx-0.5 font-normal text-ink-300">:</span>{prediction.alt_pred_away_goals}
-                  </span>
-                </p>
-              )}
-            </div>
-
-            <div className="border-y border-ink-200 py-4">
-              <OutcomeLine pick={prediction.pred_1x2} confidence={prediction.subjective_confidence} />
-            </div>
-          </>
-        )}
-
-        {/* ── 成本信息(耗时 + token + 限流余量) ── */}
-        {!degraded && (
-          <PredictionCost prediction={prediction} />
-        )}
-
-        {/* ── 元信息 ── */}
-        <p className="text-center text-2xs text-ink-500">
-          `多专家模式 · ${okReports.length}/${reports.length} 路有效`
-          {prediction.prompt_version && ` · prompt ${prediction.prompt_version}`}
-        </p>
-
-        {/* ── 终裁/降级说明意见 ── */}
-        {prediction.reasoning && degraded && (
-          <section>
-            <h4 className="section-head mb-2">降级原因</h4>
-            <blockquote className="border-l-2 border-press pl-4">
-              <p className="whitespace-pre-wrap font-serif text-sm leading-loose text-ink-700">{prediction.reasoning}</p>
-            </blockquote>
-          </section>
-        )}
-
-        {/* ── 专家意见(多模式):可折叠 + 状态摘要 + 权重条形图 ── */}
-        {reports.length > 0 && (
-          <section>
-            <button
-              onClick={() => setExpertsOpen(o => !o)}
-              className="flex w-full items-center justify-between border-b border-ink-200 pb-2 text-left"
-            >
-              <span className="section-head mb-0">五路专家意见({okReports.length}/{reports.length} 路有效)</span>
-              <span className="text-2xs text-ink-400">{expertsOpen ? '收起' : '展开'}</span>
-            </button>
-
-            {/* 权重条形图(仅 success 且有权重时显示) */}
-            {!degraded && prediction.agent_weights && Object.keys(prediction.agent_weights).length > 0 && (
-              <div className="mt-3 space-y-1.5">
-                <span className="text-2xs text-ink-500">终裁权重分布</span>
-                {Object.entries(prediction.agent_weights)
-                  .sort((a, b) => b[1] - a[1])
-                  .map(([k, v]) => (
-                    <div key={k} className="grid grid-cols-[96px_minmax(0,1fr)_40px] items-center gap-2">
-                      <span className="truncate text-2xs text-ink-500">{AGENT_LABELS[k] ?? k}</span>
-                      <div className="h-1.5 bg-paper-100">
-                        <div className="h-full bg-press" style={{ width: `${Math.round(v * 100)}%` }} />
-                      </div>
-                      <span className="text-right text-2xs tabular-nums text-ink-500">{Math.round(v * 100)}%</span>
-                    </div>
-                  ))}
-              </div>
-            )}
-
-            {expertsOpen && (
-              <div className="mt-2">
-                {reports.map((r, i) => (
-                  <AgentCard key={r.agent} report={r} no={CN_NUM[i] ?? String(i + 1)} />
-                ))}
-              </div>
-            )}
-          </section>
-        )}
-
-        {/* ── 终裁意见(success) ── */}
-        {prediction.reasoning && !degraded && (
-          <section>
-            <h4 className="section-head mb-3">终裁意见</h4>
-            <blockquote className="border-l-2 border-press pl-4">
-              <p className="whitespace-pre-wrap font-serif text-sm leading-loose text-ink-700">{prediction.reasoning}</p>
-            </blockquote>
-          </section>
-        )}
-      </div>
-    </article>
-  )
-}
-
-/** 预测弹窗:进行中显示过程可视化,完成后显示预测版,失败显示原因 */
 export function PredictModal({
   match,
   predicting,

frontend/src/pages/matches/components/OutcomePanel.tsx

@@ -0,0 +1,126 @@
+/**
+ * OutcomePanel: 预测主结论 —— 比分 / 胜平负 / 置信度 / 成本。
+ *
+ * P3-1: 从 MatchPredictPanel.PredictionPanel 拆出,渲染逻辑原样搬迁。
+ */
+import TeamSideTag from '../../../../components/TeamSideTag'
+import type { Match, Prediction } from '../../types'
+import { OUTCOME_LABEL } from '../../types'
+
+/** 置信度细线:0~1 数值的低调可视化 */
+function Meter({ value }: { value: number }) {
+  const pct = Math.max(0, Math.min(100, Math.round(value * 100)))
+  return (
+    <div className="h-px w-full bg-ink-200" role="presentation">
+      <div className="h-px bg-press transition-[width] duration-500" style={{ width: `${pct}%` }} />
+    </div>
+  )
+}
+
+/** 胜平负一行文字:选中的红字加方块标记,未选中的退灰 */
+function OutcomeLine({
+  pick,
+  confidence,
+}: {
+  pick: string | null
+  confidence: number | null
+}) {
+  const options = ['1', 'X', '2'] as const
+  return (
+    <div>
+      <div className="flex items-baseline justify-center gap-6 sm:gap-10">
+        {options.map(o => {
+          const on = pick === o
+          return (
+            <div key={o} className="flex flex-col items-center gap-1">
+              <span className={`flex items-center gap-1.5 text-sm ${on ? 'font-semibold text-press' : 'text-ink-400'}`}>
+                {on && <span className="inline-block h-2 w-2 bg-press" aria-hidden="true" />}
+                {OUTCOME_LABEL[o]}
+              </span>
+              {on && confidence !== null && (
+                <span className="text-2xs tabular-nums text-ink-500">
+                  置信 {Math.round(confidence * 100)}%
+                </span>
+              )}
+            </div>
+          )
+        })}
+      </div>
+      {pick && confidence !== null && (
+        <div className="mx-auto mt-3 max-w-xs">
+          <Meter value={confidence} />
+          <p className="mt-1 text-center text-2xs text-ink-400">主观置信度,非统计概率</p>
+        </div>
+      )}
+    </div>
+  )
+}
+
+/** 预测成本展示:耗时 + token + 限流余量 */
+function PredictionCost({ prediction }: { prediction: Prediction }) {
+  const latency = prediction.latency_ms != null ? `${(prediction.latency_ms / 1000).toFixed(1)}s` : null
+  const tokens = prediction.prompt_tokens != null || prediction.completion_tokens != null
+    ? `${prediction.prompt_tokens ?? '?'}/${prediction.completion_tokens ?? '?'}`
+    : null
+
+  if (!latency && !tokens && prediction.rate_limit_remaining == null) return null
+
+  return (
+    <div className="border-t border-ink-200 pt-3 text-2xs text-ink-500">
+      <div className="flex flex-wrap items-center justify-center gap-x-4 gap-y-1">
+        {latency && (
+          <span className="inline-flex items-center gap-1">
+            <span aria-hidden="true" className="opacity-60">⏱</span>耗时 {latency}
+          </span>
+        )}
+        {tokens && (
+          <span className="inline-flex items-center gap-1">
+            <span aria-hidden="true" className="opacity-60">Tok</span>prompt/completion: {tokens}
+          </span>
+        )}
+        {prediction.rate_limit_remaining != null && prediction.rate_limit_remaining <= 3 && (
+          <span className="text-press" title="每分钟最多 10 次预测">
+            剩余配额: {prediction.rate_limit_remaining}/10(分钟)
+          </span>
+        )}
+      </div>
+    </div>
+  )
+}
+
+export function OutcomePanel({ prediction, match }: { prediction: Prediction; match: Match }) {
+  const homeName = match.home_team_zh || match.home_team
+  const awayName = match.away_team_zh || match.away_team
+  const degraded = prediction.status === 'degraded' || prediction.status === 'failed'
+
+  return (
+    <>
+      {!degraded && (
+        <div className="text-center">
+          <p className="font-serif text-5xl font-bold tabular-nums leading-none text-ink-900 sm:text-6xl">
+            {prediction.pred_home_goals ?? '-'}
+            <span className="mx-3 font-normal text-ink-300">:</span>
+            {prediction.pred_away_goals ?? '-'}
+          </p>
+          <p className="mt-3 text-2xs tracking-[0.5em] text-ink-400">预测比分</p>
+          {prediction.alt_pred_home_goals != null && prediction.alt_pred_away_goals != null && (
+            <p className="mt-2 text-2xs tabular-nums text-ink-400">
+              备选{' '}
+              <span className="font-serif text-sm font-bold tabular-nums text-ink-600">
+                {prediction.alt_pred_home_goals}<span className="mx-0.5 font-normal text-ink-300">:</span>{prediction.alt_pred_away_goals}
+              </span>
+            </p>
+          )}
+        </div>
+      )}
+
+      {!degraded && (
+        <div className="border-y border-ink-200 py-4">
+          <OutcomeLine pick={prediction.pred_1x2} confidence={prediction.subjective_confidence} />
+        </div>
+      )}
+
+      {!degraded && <PredictionCost prediction={prediction} />}
+    </>
+  )
+}

frontend/src/pages/matches/components/ReasoningPanel.tsx

@@ -0,0 +1,34 @@
+/**
+ * ReasoningPanel: 终裁意见 / 降级原因 —— 预测的文本解释。
+ *
+ * P3-1: 从 MatchPredictPanel.PredictionPanel 拆出,渲染逻辑原样搬迁。
+ */
+import type { Prediction } from '../../types'
+
+export function ReasoningPanel({ prediction }: { prediction: Prediction }) {
+  const degraded = prediction.status === 'degraded' || prediction.status === 'failed'
+
+  if (!prediction.reasoning) return null
+
+  // 降级态:reasoning 展示为「降级原因」
+  if (degraded) {
+    return (
+      <section>
+        <h4 className="section-head mb-2">降级原因</h4>
+        <blockquote className="border-l-2 border-press pl-4">
+          <p className="whitespace-pre-wrap font-serif text-sm leading-loose text-ink-700">{prediction.reasoning}</p>
+        </blockquote>
+      </section>
+    )
+  }
+
+  // 成功态:reasoning 展示为「终裁意见」
+  return (
+    <section>
+      <h4 className="section-head mb-3">终裁意见</h4>
+      <blockquote className="border-l-2 border-press pl-4">
+        <p className="whitespace-pre-wrap font-serif text-sm leading-loose text-ink-700">{prediction.reasoning}</p>
+      </blockquote>
+    </section>
+  )
+}

src/api/app.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import logging
+import os
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
 
@@ -40,6 +41,24 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]:
             "多 worker 部署请将限流前置到 Nginx/网关,或以单 worker 运行"
         )
 
+    # P3-3:STRICT_SINGLE_WORKER 启动期强制校验,拒绝多 worker 静默配额漂移。
+    # uvicorn 通过 --workers 传入;此处以环境变量 UVICORN_WORKERS 或启动参数判定。
+    # 为避免耦合 uvicorn 内部,仅校验一个显式传入的标记:当 STRICT_SINGLE_WORKER=True 时,
+    # 要求环境变量 UVICORN_WORKERS 不为空且 <=1,否则拒绝启动。
+    if settings.STRICT_SINGLE_WORKER:
+        workers = os.environ.get("UVICORN_WORKERS", "1")
+        try:
+            n_workers = int(workers)
+        except ValueError:
+            n_workers = 1
+        if n_workers > 1:
+            raise RuntimeError(
+                f"STRICT_SINGLE_WORKER=True 但以 {n_workers} worker 启动会被拒绝 "
+                f"(应用内限流/KeyRing 多 worker 下各自独立计数,配额放大 {n_workers} 倍)。"
+                f"请前置 Nginx/网关全局限流后再启用多 worker,或保持单 worker。"
+            )
+        logger.info("STRICT_SINGLE_WORKER=True:已确认单 worker 启动,限流配额不会漂移")
+
     # 注册默认定时任务(如果数据库中没有)
     from src.db.base import AsyncSessionLocal
     from sqlalchemy import select

src/api/routes/admin_config.py

@@ -0,0 +1,88 @@
+"""后台管理:配置项 CRUD(settings)与运行日志查询。
+
+所有接口需管理员鉴权(require_admin)。路由前缀 /api/v1/admin。
+配置项白名单见 src/core/runtime_config.py SETTING_DEFS,之外的 key 一律拒绝。
+"""
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from pydantic import BaseModel
+
+from src.api.deps import require_admin
+from src.core.log_buffer import get_entries
+from src.core.runtime_config import (
+    SETTING_DEFS,
+    clear_runtime_value,
+    get_setting_origin,
+    mask_value,
+    set_runtime_value,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/v1/admin", tags=["admin"], dependencies=[Depends(require_admin)])
+
+
+class SettingUpdateIn(BaseModel):
+    value: str
+
+
+@router.get("/settings")
+async def list_settings():
+    """全部可配置项(脱敏),供后台各配置页渲染。"""
+    out = []
+    for key, defn in SETTING_DEFS.items():
+        origin, value = await get_setting_origin(key)
+        out.append(
+            {
+                "key": key,
+                "label": defn.label,
+                "description": defn.description,
+                "sensitive": defn.sensitive,
+                "configured": origin != "none",
+                "masked": mask_value(value, defn.sensitive),
+                "origin": origin,
+            }
+        )
+    return out
+
+
+@router.get("/logs")
+async def read_logs(
+    level: str | None = Query(None, description="最低级别: DEBUG/INFO/WARNING/ERROR"),
+    keyword: str | None = Query(None, description="消息或 logger 关键字"),
+    limit: int = Query(200, ge=1, le=1000),
+):
+    """查询应用运行日志(内存环形缓冲,最新在前;进程重启后清零)。"""
+    entries = get_entries(level, keyword, limit)
+    return {"entries": entries, "count": len(entries)}
+
+
+@router.put("/settings/{key}")
+async def update_setting(key: str, body: SettingUpdateIn):
+    """更新配置项(写入 app_settings 覆盖 .env)。传空值请改用 DELETE。"""
+    if key not in SETTING_DEFS:
+        raise HTTPException(404, f"不支持的配置项: {key}")
+    value = body.value.strip()
+    if not value:
+        raise HTTPException(400, "值不能为空;如需回落 .env 请调用清除接口")
+    await set_runtime_value(key, value)
+    defn = SETTING_DEFS[key]
+    return {"key": key, "masked": mask_value(value, defn.sensitive), "origin": "db"}
+
+
+@router.delete("/settings/{key}")
+async def clear_setting(key: str):
+    """清除 DB 覆盖值,回落 .env 默认。"""
+    if key not in SETTING_DEFS:
+        raise HTTPException(404, f"不支持的配置项: {key}")
+    await clear_runtime_value(key)
+    origin, value = await get_setting_origin(key)
+    defn = SETTING_DEFS[key]
+    return {
+        "key": key,
+        "masked": mask_value(value, defn.sensitive),
+        "origin": origin,
+    }

src/api/routes/admin_datasources.py

@@ -0,0 +1,228 @@
+"""后台管理:数据源列表/连通性测试、KeyRing 状态、采集健康概览。
+
+所有接口需管理员鉴权(require_admin)。路由前缀 /api/v1/admin。
+"""
+from __future__ import annotations
+
+import logging
+import time
+from datetime import date, datetime
+
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy import func, select
+
+from src.api.deps import require_admin
+from src.core.config import settings
+from src.core.http_client import get_client
+from src.core.runtime_config import (
+    SETTING_DEFS,
+    get_runtime_value,
+    get_setting_origin,
+    mask_value,
+)
+from src.db.base import AsyncSession, get_db_read
+from src.db.models import Match, MatchStats, Standing
+from src.data.key_ring import get_key_ring
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/v1/admin", tags=["admin"], dependencies=[Depends(require_admin)])
+
+# ── 数据源元数据(bzzoiro 单一数据源) ────────────────────────────
+
+_SOURCES: list[dict] = [
+    {
+        "name": "bzzoiro",
+        "label": "Bzzoiro",
+        "description": "唯一数据源:赛程比分 + 积分榜 + 比赛详细统计(xG/射门/控球等)",
+        "setting_keys": ["BZZOIRO_KEY", "BZZOIRO_BASE"],
+    },
+]
+
+
+async def _last_ingestion(db: AsyncSession, source: str) -> datetime | None:
+    """源最近一次采集时间(取自数据血缘字段,无记录返回 None)。"""
+    return (
+        await db.execute(
+            select(func.max(MatchStats.retrieved_at)).where(MatchStats.source == source)
+        )
+    ).scalar()
+
+
+@router.get("/datasources")
+async def list_datasources(db: AsyncSession = Depends(get_db_read)):
+    """数据源列表:各配置项的脱敏值、来源(db/env/none)与最近采集时间。"""
+    result = []
+    for src in _SOURCES:
+        settings_out = []
+        for key in src["setting_keys"]:
+            origin, value = await get_setting_origin(key)
+            defn = SETTING_DEFS[key]
+            settings_out.append(
+                {
+                    "key": key,
+                    "label": defn.label,
+                    "description": defn.description,
+                    "sensitive": defn.sensitive,
+                    "configured": origin != "none",
+                    "masked": mask_value(value, defn.sensitive),
+                    "origin": origin,
+                }
+            )
+        key_configured = all(s["configured"] for s in settings_out) if settings_out else True
+        last = await _last_ingestion(db, src["name"])
+        result.append(
+            {
+                "name": src["name"],
+                "label": src["label"],
+                "description": src["description"],
+                "key_configured": key_configured,
+                "last_ingestion": last.isoformat() if last else None,
+                "settings": settings_out,
+            }
+        )
+    return result
+
+
+# ── 连通性测试 ──────────────────────────────────────────────────
+
+_TEST_TIMEOUT = 15
+
+
+async def _probe(url: str, headers: dict | None = None, params: dict | None = None) -> dict:
+    """单次 HTTP 探测,返回 (ok, status, latency_ms, detail)。不重试。"""
+    client = get_client()
+    start = time.monotonic()
+    try:
+        resp = await client.get(url, headers=headers, params=params, timeout=_TEST_TIMEOUT)
+    except Exception as e:
+        return {
+            "ok": False,
+            "status": None,
+            "latency_ms": int((time.monotonic() - start) * 1000),
+            "detail": f"无法连接: {e}",
+        }
+    latency = int((time.monotonic() - start) * 1000)
+    status = resp.status_code
+    if status == 200:
+        detail = "连接成功"
+    elif status in (401, 403):
+        detail = "服务可达,但密钥无效或无权限"
+    else:
+        detail = f"服务返回 HTTP {status}"
+    return {"ok": status == 200, "status": status, "latency_ms": latency, "detail": detail}
+
+
+@router.post("/datasources/{name}/test")
+async def test_datasource(name: str):
+    """轻量连通性测试:真实请求上游一次,不触发任何入库。"""
+    src = next((s for s in _SOURCES if s["name"] == name), None)
+    if src is None:
+        raise HTTPException(404, f"未知数据源: {name}")
+
+    if name == "bzzoiro":
+        key = await get_runtime_value("BZZOIRO_KEY")
+        if not key:
+            return {"ok": False, "status": None, "latency_ms": 0, "detail": "BZZOIRO_KEY 未配置"}
+        base = (await get_runtime_value("BZZOIRO_BASE")).rstrip("/")
+        today = date.today().isoformat()
+        return await _probe(
+            f"{base}/events/",
+            headers={"Authorization": f"Token {key}", "Accept": "application/json"},
+            params={"date_from": today, "date_to": today},
+        )
+
+    raise HTTPException(404, f"未知数据源: {name}")
+
+
+# ── 数据源健康/最近采集状态(只读,不触发采集) ──────────────────────
+
+
+@router.get("/ingest/status")
+async def ingest_status(db: AsyncSession = Depends(get_db_read)):
+    """数据源采集健康概览(bzzoiro 单源;只读,不触发任何采集)。"""
+    bzzoiro_key = await get_runtime_value("BZZOIRO_KEY")
+    bzzoiro_base = await get_runtime_value("BZZOIRO_BASE")
+
+    # 比赛覆盖
+    match_row = (
+        await db.execute(
+            select(
+                func.count().label("cnt"),
+                func.max(Match.match_date).label("latest_match_date"),
+                func.max(Match.created_at).label("latest_row_at"),
+            ).where(Match.match_status == "finished")
+        )
+    ).one()
+    # 统计覆盖(精确 retrieved_at)
+    stats_row = (
+        await db.execute(
+            select(
+                func.count().label("cnt"),
+                func.max(MatchStats.retrieved_at).label("latest_retrieved"),
+            ).where(MatchStats.source == "bzzoiro")
+        )
+    ).one()
+    # 积分榜覆盖
+    standings_row = (
+        await db.execute(select(func.count()).select_from(Standing))
+    ).scalar()
+
+    bzzoiro = {
+        "name": "bzzoiro",
+        "label": "Bzzoiro",
+        "key_configured": bool(bzzoiro_key),
+        "base_url": (bzzoiro_base.rstrip("/") if bzzoiro_base else None) or settings.BZZOIRO_BASE,
+        "reachable": None,  # 不主动探测
+        "last_success_at": (stats_row.latest_retrieved or match_row.latest_row_at),
+        "last_success_at_iso": (
+            stats_row.latest_retrieved or match_row.latest_row_at
+        ).isoformat() if (stats_row.latest_retrieved or match_row.latest_row_at) else None,
+        "latest_match_date": match_row.latest_match_date.isoformat() if match_row.latest_match_date else None,
+        "recent_count": match_row.cnt or 0,
+        "stats_count": stats_row.cnt or 0,
+        "standings_count": standings_row or 0,
+        "note": "last_success_at 取 match_stats.retrieved_at(统计回填)与 matches.created_at(比赛行)的较大者",
+        "last_failure": _last_failure_log("bzzoiro"),
+    }
+
+    return {"sources": [bzzoiro]}
+
+
+@router.get("/keyring/status")
+async def keyring_status():
+    """KeyRing 运行状态:当前使用的 key、冷却状态、轮转信息(供管理后台展示)。"""
+    base = (await get_runtime_value("BZZOIRO_BASE")).rstrip("/")
+    raw_keys = await get_runtime_value("BZZOIRO_KEY")
+    ring = get_key_ring(base, raw_keys)
+    st = ring.stats()
+    st["base_url"] = base
+    st["cooldown_seconds"] = ring._cooldown
+    st["has_multiple"] = ring.has_multiple
+    st["active_key"] = ring.active_key
+    return st
+
+
+@router.post("/keyring/cooldown/reset")
+async def keyring_reset_cooldown():
+    """手动重置所有 key 的冷却状态(用于紧急恢复)。"""
+    base = (await get_runtime_value("BZZOIRO_BASE")).rstrip("/")
+    raw_keys = await get_runtime_value("BZZOIRO_KEY")
+    ring = get_key_ring(base, raw_keys)
+    ring._blocked_until.clear()
+    return {"ok": True, "message": "已重置所有 key 冷却状态", "stats": ring.stats()}
+
+
+def _last_failure_log(source: str) -> dict | None:
+    """从系统日志缓冲中查找某数据源的最近一次错误(仅作参考,非专用失败表)。"""
+    from src.core.log_buffer import get_entries
+    entries = get_entries(min_level="ERROR", keyword=source, limit=5)
+    if not entries:
+        return None
+    e = entries[0]
+    return {
+        "at": datetime.fromtimestamp(e["ts"]).isoformat(),
+        "logger": e["logger"],
+        "detail": e["message"][:200],
+        "note": "approx:来自内存日志缓冲,非专用采集失败表;进程重启后清零",
+    }

src/api/routes/admin_llm.py

@@ -0,0 +1,126 @@
+"""后台管理:LLM 专家/终裁配置、可用模型探测、连通性测试。
+
+所有接口需管理员鉴权(require_admin)。路由前缀 /api/v1/admin。
+"""
+from __future__ import annotations
+
+import logging
+import time
+
+import httpx
+from fastapi import APIRouter, Depends
+
+from src.api.deps import require_admin
+from src.core.config import settings
+from src.core.http_client import get_client
+from src.core.runtime_config import (
+    AGENT_META,
+    SETTING_DEFS,
+    get_runtime_value,
+    get_setting_origin,
+    mask_value,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/v1/admin", tags=["admin"], dependencies=[Depends(require_admin)])
+
+
+@router.get("/llm/agents")
+async def list_llm_agents():
+    """各专家/终裁的独立 LLM 配置状态(含当前生效模型的解析结果)。"""
+    out = []
+    for agent in AGENT_META:
+        aid = agent["id"].upper()
+        pfx = f"AGENT_{aid}_"
+        fields = {}
+        for suffix in ("MODEL", "BASE_URL", "API_KEY"):
+            origin, value = await get_setting_origin(f"{pfx}{suffix}")
+            defn = SETTING_DEFS[f"{pfx}{suffix}"]
+            fields[suffix.lower()] = {
+                "configured": origin != "none",
+                "masked": mask_value(value, defn.sensitive),
+                "origin": origin,
+            }
+        # 生效模型 = 覆盖 → 层级默认(专家/终裁 env) → 全局 LLM_MODEL
+        tier_default = (
+            settings.LLM_AGGREGATOR_MODEL if agent["id"] == "aggregator" else settings.LLM_SPECIALIST_MODEL
+        )
+        effective_model = (
+            fields["model"]["masked"]
+            if fields["model"]["configured"]
+            else (tier_default or await get_runtime_value("LLM_MODEL"))
+        )
+        out.append(
+            {
+                "id": agent["id"],
+                "label": agent["label"],
+                "fields": fields,
+                "effective_model": effective_model,
+            }
+        )
+    return out
+
+
+@router.get("/llm/models")
+async def list_llm_models():
+    """探测当前 LLM 服务可用的模型列表(OpenAI 兼容 GET /models)。
+
+    只读探测,不产生费用;配置缺失或服务不可达时返回 ok=false 与原因。
+    """
+    base_url = (await get_runtime_value("LLM_BASE_URL")).rstrip("/")
+    api_key = await get_runtime_value("LLM_API_KEY")
+    if not base_url or not api_key:
+        return {"ok": False, "models": [], "detail": "LLM_BASE_URL 或 LLM_API_KEY 未配置"}
+
+    client = get_client()
+    start = time.monotonic()
+    try:
+        resp = await client.get(
+            f"{base_url}/models",
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=httpx.Timeout(connect=10.0, read=20.0, write=10.0, pool=10.0),
+        )
+    except Exception as e:
+        return {
+            "ok": False,
+            "models": [],
+            "latency_ms": int((time.monotonic() - start) * 1000),
+            "detail": f"无法连接 LLM 服务: {e}",
+        }
+
+    latency = int((time.monotonic() - start) * 1000)
+    if resp.status_code in (401, 403):
+        return {"ok": False, "models": [], "latency_ms": latency, "detail": "密钥无效或无权限(HTTP 401/403)"}
+    if resp.status_code != 200:
+        return {"ok": False, "models": [], "latency_ms": latency, "detail": f"服务返回 HTTP {resp.status_code}"}
+
+    try:
+        data = resp.json()
+    except Exception:
+        return {"ok": False, "models": [], "latency_ms": latency, "detail": "响应不是合法 JSON"}
+
+    models: list[str] = []
+    items = data.get("data") if isinstance(data, dict) else None
+    if isinstance(items, list):
+        models = sorted(
+            str(m.get("id")) for m in items if isinstance(m, dict) and m.get("id")
+        )
+    if not models:
+        return {"ok": False, "models": [], "latency_ms": latency, "detail": "服务未返回模型列表"}
+    return {"ok": True, "models": models, "latency_ms": latency, "detail": f"共 {len(models)} 个可用模型"}
+
+
+@router.post("/llm/ping")
+async def llm_ping():
+    """LLM 连通性测试(不依赖比赛)。只发一次 chat 请求验证配置。"""
+    from src.llm.provider import get_default_provider
+    p = await get_default_provider()
+    resp = await p.chat(
+        system="你是测试助手。",
+        user="ping",
+        max_tokens=10,
+    )
+    if resp.error:
+        return {"ok": False, "message": resp.error}
+    return {"ok": True, "message": "LLM 连接正常", "model": p.model}

src/api/routes/admin_quality.py

@@ -0,0 +1,343 @@
+"""后台管理:管理区统计、数据完整性分析、数据质量检查。
+
+所有接口需管理员鉴权(require_admin)。路由前缀 /api/v1/admin。
+"""
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timedelta, timezone
+
+from fastapi import APIRouter, Depends
+from sqlalchemy import func, select
+
+from src.api.deps import require_admin
+from src.db.base import AsyncSession, get_db_read
+from src.db.models import DataQualityCheck, IngestFailure, League, Match, MatchStats, Prediction, Standing
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/v1/admin", tags=["admin"], dependencies=[Depends(require_admin)])
+
+
+@router.get("/stats")
+async def admin_stats(db: AsyncSession = Depends(get_db_read)):
+    """管理区统计(只读):预测次数 + 比赛覆盖。轻量聚合,无 LLM 调用。"""
+    day_ago = datetime.now(timezone.utc) - timedelta(days=1)
+    week_ago = datetime.now(timezone.utc) - timedelta(days=7)
+    r = (
+        await db.execute(
+            select(
+                func.count().label("total"),
+                func.count().filter(Prediction.created_at >= day_ago).label("last_24h"),
+                func.count().filter(Prediction.created_at >= week_ago).label("last_7d"),
+            )
+        )
+    ).one()
+    # F3 修复: 补充真实比赛计数(非 limit=100 近似)
+    match_cnt = (await db.execute(select(func.count()).select_from(Match))).scalar() or 0
+    finished_cnt = (await db.execute(select(func.count()).where(Match.match_status == "finished"))).scalar() or 0
+    stats_cnt = (await db.execute(select(func.count()).select_from(MatchStats))).scalar() or 0
+    standings_cnt = (await db.execute(select(func.count()).select_from(Standing))).scalar() or 0
+    return {
+        "predictions": {"total": r.total, "last_24h": r.last_24h, "last_7d": r.last_7d},
+        "matches": {"total": match_cnt, "finished": finished_cnt},
+        "stats": {"total": stats_cnt},
+        "standings": {"total": standings_cnt},
+    }
+
+
+# ── 数据完整性分析(可视化数据源) ────────────────────────────────
+
+
+@router.get("/data-completeness")
+async def data_completeness(db: AsyncSession = Depends(get_db_read)):
+    """按联赛统计数据完整性:比赛覆盖、字段覆盖、积分榜覆盖。
+
+    前端「数据完整性」页据此渲染,回答三个问题:
+      1. 数据是否齐全(各联赛比赛/统计/积分榜量级)
+      2. 字段是否齐全(每张统计表各字段非空率)
+      3. 覆盖是否新鲜(最近一场/最近一次采集)
+    """
+    from src.data.config import BZZOIRO_LEAGUE_IDS, LEAGUE_NAMES, LEAGUE_COUNTRIES
+
+    out_leagues: list[dict] = []
+    for code, bzz_id in BZZOIRO_LEAGUE_IDS.items():
+        # 比赛覆盖
+        m = (
+            await db.execute(
+                select(
+                    func.count().label("total"),
+                    func.count().filter(Match.match_status == "finished").label("finished"),
+                    func.count().filter(Match.match_status == "scheduled").label("scheduled"),
+                    func.count().filter(Match.source_event_id.is_not(None)).label("with_source_id"),
+                    func.max(Match.match_date).label("latest_match"),
+                    func.min(Match.match_date).label("earliest_match"),
+                )
+                .select_from(Match)
+                .join(League, League.id == Match.league_id)
+                .where(League.code == code)
+            )
+        ).one()
+        # 统计字段覆盖(联表 matches)
+        s = (
+            await db.execute(
+                select(
+                    func.count().label("rows"),
+                    func.count(MatchStats.home_xg).label("xg"),
+                    func.count(MatchStats.home_shots).label("shots"),
+                    func.count(MatchStats.home_possession).label("possession"),
+                    func.count(MatchStats.home_corners).label("corners"),
+                    func.count(MatchStats.home_fouls).label("fouls"),
+                    func.count(MatchStats.home_big_chances).label("big_chances"),
+                    func.count(MatchStats.home_yellow_cards).label("cards"),
+                )
+                .select_from(MatchStats)
+                .join(Match, Match.id == MatchStats.match_id)
+                .join(League, League.id == Match.league_id)
+                .where(League.code == code)
+            )
+        ).one()
+        # 积分榜覆盖
+        st = (
+            await db.execute(
+                select(
+                    func.count().label("rows"),
+                    func.max(Standing.retrieved_at).label("latest_retrieved"),
+                )
+                .select_from(Standing)
+                .join(League, League.id == Standing.league_id)
+                .where(League.code == code)
+            )
+        ).one()
+
+        stats_rows = s.rows or 0
+        pct = lambda n: round(n / stats_rows * 100, 1) if stats_rows else 0.0  # noqa: E731
+        out_leagues.append(
+            {
+                "code": code,
+                "name": LEAGUE_NAMES.get(code, code),
+                "country": LEAGUE_COUNTRIES.get(code),
+                "matches": {
+                    "total": m.total or 0,
+                    "finished": m.finished or 0,
+                    "scheduled": m.scheduled or 0,
+                    "with_source_id": m.with_source_id or 0,
+                    "earliest_match": m.earliest_match.isoformat() if m.earliest_match else None,
+                    "latest_match": m.latest_match.isoformat() if m.latest_match else None,
+                },
+                "stats": {
+                    "rows": stats_rows,
+                    "fields": {
+                        "xg": {"count": s.xg or 0, "pct": pct(s.xg or 0)},
+                        "shots": {"count": s.shots or 0, "pct": pct(s.shots or 0)},
+                        "possession": {"count": s.possession or 0, "pct": pct(s.possession or 0)},
+                        "corners": {"count": s.corners or 0, "pct": pct(s.corners or 0)},
+                        "fouls": {"count": s.fouls or 0, "pct": pct(s.fouls or 0)},
+                        "big_chances": {"count": s.big_chances or 0, "pct": pct(s.big_chances or 0)},
+                        "cards": {"count": s.cards or 0, "pct": pct(s.cards or 0)},
+                    },
+                },
+                "standings": {
+                    "rows": st.rows or 0,
+                    "latest_retrieved": st.latest_retrieved.isoformat() if st.latest_retrieved else None,
+                },
+            }
+        )
+
+    # 整体健康信号
+    total_finished = sum(l["matches"]["finished"] for l in out_leagues)
+    total_stats = sum(l["stats"]["rows"] for l in out_leagues)
+    stats_coverage = round(total_stats / total_finished * 100, 1) if total_finished else 0.0
+    issues: list[str] = []
+    for l in out_leagues:
+        if l["matches"]["finished"] == 0:
+            issues.append(f"{l['name']}: 无已完赛比赛,请先运行「比赛数据」采集")
+        elif l["stats"]["rows"] == 0:
+            issues.append(f"{l['name']}: 已完赛 {l['matches']['finished']} 场但无统计回填,请运行「统计回填」采集")
+        elif stats_coverage < 80:
+            issues.append(f"{l['name']}: 统计覆盖率仅 {stats_coverage}%,建议增量回填")
+        if l["standings"]["rows"] == 0:
+            issues.append(f"{l['name']}: 无积分榜数据,请运行「积分榜」采集")
+    if not issues:
+        issues.append("各联赛数据完整度良好")
+
+    return {
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "leagues": out_leagues,
+        "totals": {
+            "finished_matches": total_finished,
+            "stats_rows": total_stats,
+            "stats_coverage_pct": stats_coverage,
+        },
+        "issues": issues,
+    }
+
+
+# ── 数据质量检查 API ────────────────────────────────────────────
+
+
+@router.get("/data-quality")
+async def data_quality_checks(db: AsyncSession = Depends(get_db_read)):
+    """数据质量检查结果(只读)。"""
+    # 最近的失败记录
+    failures = (
+        await db.execute(
+            select(IngestFailure)
+            .where(IngestFailure.status.in_(["pending", "retrying"]))
+            .order_by(IngestFailure.created_at.desc())
+            .limit(20)
+        )
+    ).scalars().all()
+
+    # 最近的质量检查
+    checks = (
+        await db.execute(
+            select(DataQualityCheck)
+            .order_by(DataQualityCheck.checked_at.desc())
+            .limit(20)
+        )
+    ).scalars().all()
+
+    return {
+        "failures": [
+            {
+                "id": f.id,
+                "source": f.source_system,
+                "entity_type": f.entity_type,
+                "source_record_id": f.source_record_id,
+                "error_type": f.error_type,
+                "error_detail": f.error_detail,
+                "retry_count": f.retry_count,
+                "status": f.status,
+                "created_at": f.created_at.isoformat() if f.created_at else None,
+            }
+            for f in failures
+        ],
+        "checks": [
+            {
+                "id": c.id,
+                "check_name": c.check_name,
+                "entity_type": c.entity_type,
+                "passed": c.passed,
+                "severity": c.severity,
+                "detail": c.detail,
+                "checked_at": c.checked_at.isoformat() if c.checked_at else None,
+            }
+            for c in checks
+        ],
+    }
+
+
+@router.post("/data-quality/run")
+async def run_data_quality_check(db: AsyncSession = Depends(get_db_read)):
+    """手动触发一次数据质量检查。"""
+    checks = []
+
+    # 检查1: 已完赛但无统计的比赛
+    finished_no_stats = (
+        await db.execute(
+            select(func.count())
+            .select_from(Match)
+            .outerjoin(MatchStats, Match.id == MatchStats.match_id)
+            .where(Match.match_status == "finished")
+            .where(MatchStats.id.is_(None))
+        )
+    ).scalar() or 0
+
+    checks.append(DataQualityCheck(
+        check_name="finished_without_stats",
+        entity_type="match",
+        actual_value=float(finished_no_stats),
+        passed=finished_no_stats == 0,
+        severity="warning" if finished_no_stats > 0 else "info",
+        detail={"message": f"{finished_no_stats} 场已完赛比赛缺少统计数据"},
+    ))
+
+    # 检查2: 积分榜缺失的联赛
+    leagues_without_standings = (
+        await db.execute(
+            select(func.count())
+            .select_from(League)
+            .outerjoin(Standing, League.id == Standing.league_id)
+            .where(Standing.id.is_(None))
+        )
+    ).scalar() or 0
+
+    checks.append(DataQualityCheck(
+        check_name="league_without_standings",
+        entity_type="league",
+        actual_value=float(leagues_without_standings),
+        passed=leagues_without_standings == 0,
+        severity="warning" if leagues_without_standings > 0 else "info",
+        detail={"message": f"{leagues_without_standings} 个联赛缺少积分榜"},
+    ))
+
+    for c in checks:
+        db.add(c)
+    await db.commit()
+
+    return {"ok": True, "checks": [{"name": c.check_name, "passed": c.passed} for c in checks]}
+
+
+# ── 近似重名候选(只读,启发式,不做自动合并) ──────────────────────
+
+
+@router.get("/team-name-duplicates")
+async def team_name_duplicates(db: AsyncSession = Depends(get_db_read)):
+    """只读列出近似重名候选(大小写变体/子串包含/前缀碰撞)。
+
+    启发式规则(命中任一即列为候选):
+      - 大小写变体: lower(name) 相同但 name 不同
+      - 子串包含: A 是 B 的子串且 len(A) ≥ 5
+      - 前缀碰撞: 前 8 字符相同(忽略大小写)
+
+    仅作排查参考,合并需走人工 SQL(见 docs/05-data.md)。
+    """
+    teams = (await db.execute(select(Team.id, Team.name))).all()
+    by_lower: dict[str, list[dict]] = {}
+    for t in teams:
+        key = (t.name or "").lower()
+        by_lower.setdefault(key, []).append({"id": t.id, "name": t.name})
+
+    groups: list[dict] = []
+
+    # 规则1: 大小写变体(lower 相同但原名不同)
+    for key, members in by_lower.items():
+        if len(members) > 1:
+            groups.append({
+                "rule": "case_variant",
+                "key": key,
+                "members": members,
+            })
+
+    # 规则2 & 3: 子串包含 / 前缀碰撞(仅在 lower 名不同的组间比较)
+    distinct = [m for members in by_lower.values() for m in members]
+    seen_pairs: set[tuple[int, int]] = set()
+    for i, a in enumerate(distinct):
+        na = (a["name"] or "").lower()
+        for b in distinct[i + 1:]:
+            nb = (b["name"] or "").lower()
+            if na == nb:
+                continue  # 已被规则1覆盖
+            pair = (min(a["id"], b["id"]), max(a["id"], b["id"]))
+            if pair in seen_pairs:
+                continue
+            hit = None
+            if len(na) >= 5 and na in nb:
+                hit = "substring"
+            elif len(nb) >= 5 and nb in na:
+                hit = "substring"
+            elif len(na) >= 8 and len(nb) >= 8 and na[:8] == nb[:8]:
+                hit = "prefix"
+            if hit:
+                seen_pairs.add(pair)
+                groups.append({
+                    "rule": hit,
+                    "members": [a, b],
+                })
+
+    return {
+        "count": len(groups),
+        "hint": "命中任一启发式仅表示'可疑',合并前请人工确认是否同一球队",
+        "groups": groups,
+    }

src/api/routes/admin_settings.py

@@ -1,668 +1,25 @@
-"""后台管理路由:数据源配置的查看、修改与连通性测试。
+"""后台管理路由聚合入口:按职责拆分为四个子模块,统一挂载。
 
-所有接口需管理员鉴权(require_admin)。配置项白名单见
-src/core/runtime_config.py SETTING_DEFS,之外的 key 一律拒绝。
+所有路由仍挂在 /api/v1/admin,且均带 dependencies=[Depends(require_admin)]
+(鉴权由各子路由器声明,行为与拆分前完全一致)。
+
+子模块:
+  - admin_datasources  数据源列表/连通性测试、KeyRing、采集健康概览
+  - admin_config        settings CRUD、运行日志
+  - admin_llm           LLM agents/models/ping
+  - admin_quality       stats、data-completeness、data-quality
 """
 from __future__ import annotations
 
-import logging
-import time
-from datetime import date, datetime, timedelta, timezone
-
-from fastapi import APIRouter, Depends, HTTPException, Query
-from pydantic import BaseModel
-from sqlalchemy import func, select
-import httpx
-
-from src.api.deps import require_admin
-from src.core.config import settings
-from src.core.http_client import get_client
-from src.core.log_buffer import get_entries
-from src.core.runtime_config import (
-    AGENT_META,
-    SETTING_DEFS,
-    clear_runtime_value,
-    get_runtime_value,
-    get_setting_origin,
-    mask_value,
-    set_runtime_value,
-)
-from src.db.base import AsyncSession, get_db_read
-from src.db.models import League, Match, MatchStats, Standing
-from src.data.key_ring import get_key_ring, parse_keys
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(prefix="/api/v1/admin", tags=["admin"], dependencies=[Depends(require_admin)])
-
-# ── 数据源元数据(bzzoiro 单一数据源) ────────────────────────────
-
-_SOURCES: list[dict] = [
-    {
-        "name": "bzzoiro",
-        "label": "Bzzoiro",
-        "description": "唯一数据源:赛程比分 + 积分榜 + 比赛详细统计(xG/射门/控球等)",
-        "setting_keys": ["BZZOIRO_KEY", "BZZOIRO_BASE"],
-    },
-]
-
-
-class SettingUpdateIn(BaseModel):
-    value: str
-
-
-async def _last_ingestion(db: AsyncSession, source: str) -> datetime | None:
-    """源最近一次采集时间(取自数据血缘字段,无记录返回 None)。"""
-    return (
-        await db.execute(
-            select(func.max(MatchStats.retrieved_at)).where(MatchStats.source == source)
-        )
-    ).scalar()
-
-
-@router.get("/datasources")
-async def list_datasources(db: AsyncSession = Depends(get_db_read)):
-    """数据源列表:各配置项的脱敏值、来源(db/env/none)与最近采集时间。"""
-    result = []
-    for src in _SOURCES:
-        settings_out = []
-        for key in src["setting_keys"]:
-            origin, value = await get_setting_origin(key)
-            defn = SETTING_DEFS[key]
-            settings_out.append(
-                {
-                    "key": key,
-                    "label": defn.label,
-                    "description": defn.description,
-                    "sensitive": defn.sensitive,
-                    "configured": origin != "none",
-                    "masked": mask_value(value, defn.sensitive),
-                    "origin": origin,
-                }
-            )
-        key_configured = all(s["configured"] for s in settings_out) if settings_out else True
-        last = await _last_ingestion(db, src["name"])
-        result.append(
-            {
-                "name": src["name"],
-                "label": src["label"],
-                "description": src["description"],
-                "key_configured": key_configured,
-                "last_ingestion": last.isoformat() if last else None,
-                "settings": settings_out,
-            }
-        )
-    return result
-
-
-@router.get("/settings")
-async def list_settings():
-    """全部可配置项(脱敏),供后台各配置页渲染。"""
-    out = []
-    for key, defn in SETTING_DEFS.items():
-        origin, value = await get_setting_origin(key)
-        out.append(
-            {
-                "key": key,
-                "label": defn.label,
-                "description": defn.description,
-                "sensitive": defn.sensitive,
-                "configured": origin != "none",
-                "masked": mask_value(value, defn.sensitive),
-                "origin": origin,
-            }
-        )
-    return out
-
-
-# ── LLM 可用模型检测 ────────────────────────────────────────────
-
-
-@router.get("/logs")
-async def read_logs(
-    level: str | None = Query(None, description="最低级别: DEBUG/INFO/WARNING/ERROR"),
-    keyword: str | None = Query(None, description="消息或 logger 关键字"),
-    limit: int = Query(200, ge=1, le=1000),
-):
-    """查询应用运行日志(内存环形缓冲,最新在前;进程重启后清零)。"""
-    entries = get_entries(level, keyword, limit)
-    return {"entries": entries, "count": len(entries)}
-
-
-@router.get("/llm/agents")
-async def list_llm_agents():
-    """各专家/终裁的独立 LLM 配置状态(含当前生效模型的解析结果)。"""
-    out = []
-    for agent in AGENT_META:
-        aid = agent["id"].upper()
-        pfx = f"AGENT_{aid}_"
-        fields = {}
-        for suffix in ("MODEL", "BASE_URL", "API_KEY"):
-            origin, value = await get_setting_origin(f"{pfx}{suffix}")
-            defn = SETTING_DEFS[f"{pfx}{suffix}"]
-            fields[suffix.lower()] = {
-                "configured": origin != "none",
-                "masked": mask_value(value, defn.sensitive),
-                "origin": origin,
-            }
-        # 生效模型 = 覆盖 → 层级默认(专家/终裁 env) → 全局 LLM_MODEL
-        tier_default = (
-            settings.LLM_AGGREGATOR_MODEL if agent["id"] == "aggregator" else settings.LLM_SPECIALIST_MODEL
-        )
-        effective_model = (
-            fields["model"]["masked"]
-            if fields["model"]["configured"]
-            else (tier_default or await get_runtime_value("LLM_MODEL"))
-        )
-        out.append(
-            {
-                "id": agent["id"],
-                "label": agent["label"],
-                "fields": fields,
-                "effective_model": effective_model,
-            }
-        )
-    return out
-
-
-@router.get("/llm/models")
-async def list_llm_models():
-    """探测当前 LLM 服务可用的模型列表(OpenAI 兼容 GET /models)。
-
-    只读探测,不产生费用;配置缺失或服务不可达时返回 ok=false 与原因。
-    """
-    base_url = (await get_runtime_value("LLM_BASE_URL")).rstrip("/")
-    api_key = await get_runtime_value("LLM_API_KEY")
-    if not base_url or not api_key:
-        return {"ok": False, "models": [], "detail": "LLM_BASE_URL 或 LLM_API_KEY 未配置"}
-
-    client = get_client()
-    start = time.monotonic()
-    try:
-        resp = await client.get(
-            f"{base_url}/models",
-            headers={"Authorization": f"Bearer {api_key}"},
-            timeout=httpx.Timeout(connect=10.0, read=20.0, write=10.0, pool=10.0),
-        )
-    except Exception as e:
-        return {
-            "ok": False,
-            "models": [],
-            "latency_ms": int((time.monotonic() - start) * 1000),
-            "detail": f"无法连接 LLM 服务: {e}",
-        }
-
-    latency = int((time.monotonic() - start) * 1000)
-    if resp.status_code in (401, 403):
-        return {"ok": False, "models": [], "latency_ms": latency, "detail": "密钥无效或无权限(HTTP 401/403)"}
-    if resp.status_code != 200:
-        return {"ok": False, "models": [], "latency_ms": latency, "detail": f"服务返回 HTTP {resp.status_code}"}
-
-    try:
-        data = resp.json()
-    except Exception:
-        return {"ok": False, "models": [], "latency_ms": latency, "detail": "响应不是合法 JSON"}
-
-    models: list[str] = []
-    items = data.get("data") if isinstance(data, dict) else None
-    if isinstance(items, list):
-        models = sorted(
-            str(m.get("id")) for m in items if isinstance(m, dict) and m.get("id")
-        )
-    if not models:
-        return {"ok": False, "models": [], "latency_ms": latency, "detail": "服务未返回模型列表"}
-    return {"ok": True, "models": models, "latency_ms": latency, "detail": f"共 {len(models)} 个可用模型"}
-
-
-@router.put("/settings/{key}")
-async def update_setting(key: str, body: SettingUpdateIn):
-    """更新配置项(写入 app_settings 覆盖 .env)。传空值请改用 DELETE。"""
-    if key not in SETTING_DEFS:
-        raise HTTPException(404, f"不支持的配置项: {key}")
-    value = body.value.strip()
-    if not value:
-        raise HTTPException(400, "值不能为空;如需回落 .env 请调用清除接口")
-    await set_runtime_value(key, value)
-    defn = SETTING_DEFS[key]
-    return {"key": key, "masked": mask_value(value, defn.sensitive), "origin": "db"}
-
-
-@router.delete("/settings/{key}")
-async def clear_setting(key: str):
-    """清除 DB 覆盖值,回落 .env 默认。"""
-    if key not in SETTING_DEFS:
-        raise HTTPException(404, f"不支持的配置项: {key}")
-    await clear_runtime_value(key)
-    origin, value = await get_setting_origin(key)
-    defn = SETTING_DEFS[key]
-    return {
-        "key": key,
-        "masked": mask_value(value, defn.sensitive),
-        "origin": origin,
-    }
-
-
-# ── 连通性测试 ──────────────────────────────────────────────────
-
-_TEST_TIMEOUT = 15
-
-
-async def _probe(url: str, headers: dict | None = None, params: dict | None = None) -> dict:
-    """单次 HTTP 探测,返回 (ok, status, latency_ms, detail)。不重试。"""
-    client = get_client()
-    start = time.monotonic()
-    try:
-        resp = await client.get(url, headers=headers, params=params, timeout=_TEST_TIMEOUT)
-    except Exception as e:
-        return {
-            "ok": False,
-            "status": None,
-            "latency_ms": int((time.monotonic() - start) * 1000),
-            "detail": f"无法连接: {e}",
-        }
-    latency = int((time.monotonic() - start) * 1000)
-    status = resp.status_code
-    if status == 200:
-        detail = "连接成功"
-    elif status in (401, 403):
-        detail = "服务可达,但密钥无效或无权限"
-    else:
-        detail = f"服务返回 HTTP {status}"
-    return {"ok": status == 200, "status": status, "latency_ms": latency, "detail": detail}
-
-
-@router.post("/datasources/{name}/test")
-async def test_datasource(name: str):
-    """轻量连通性测试:真实请求上游一次,不触发任何入库。"""
-    src = next((s for s in _SOURCES if s["name"] == name), None)
-    if src is None:
-        raise HTTPException(404, f"未知数据源: {name}")
-
-    if name == "bzzoiro":
-        key = await get_runtime_value("BZZOIRO_KEY")
-        if not key:
-            return {"ok": False, "status": None, "latency_ms": 0, "detail": "BZZOIRO_KEY 未配置"}
-        base = (await get_runtime_value("BZZOIRO_BASE")).rstrip("/")
-        today = date.today().isoformat()
-        return await _probe(
-            f"{base}/events/",
-            headers={"Authorization": f"Token {key}", "Accept": "application/json"},
-            params={"date_from": today, "date_to": today},
-        )
-
-    raise HTTPException(404, f"未知数据源: {name}")
-
-
-@router.post("/llm/ping")
-async def llm_ping():
-    """LLM 连通性测试(不依赖比赛)。只发一次 chat 请求验证配置。"""
-    from src.llm.provider import get_default_provider
-    p = await get_default_provider()
-    resp = await p.chat(
-        system="你是测试助手。",
-        user="ping",
-        max_tokens=10,
-    )
-    if resp.error:
-        return {"ok": False, "message": resp.error}
-    return {"ok": True, "message": "LLM 连接正常", "model": p.model}
-
-
-# ── 数据源健康/最近采集状态(只读,不触发采集) ──────────────────────
-
-
-@router.get("/ingest/status")
-async def ingest_status(db: AsyncSession = Depends(get_db_read)):
-    """数据源采集健康概览(bzzoiro 单源;只读,不触发任何采集)。"""
-    bzzoiro_key = await get_runtime_value("BZZOIRO_KEY")
-    bzzoiro_base = await get_runtime_value("BZZOIRO_BASE")
-
-    # 比赛覆盖
-    match_row = (
-        await db.execute(
-            select(
-                func.count().label("cnt"),
-                func.max(Match.match_date).label("latest_match_date"),
-                func.max(Match.created_at).label("latest_row_at"),
-            ).where(Match.match_status == "finished")
-        )
-    ).one()
-    # 统计覆盖(精确 retrieved_at)
-    stats_row = (
-        await db.execute(
-            select(
-                func.count().label("cnt"),
-                func.max(MatchStats.retrieved_at).label("latest_retrieved"),
-            ).where(MatchStats.source == "bzzoiro")
-        )
-    ).one()
-    # 积分榜覆盖
-    standings_row = (
-        await db.execute(select(func.count()).select_from(Standing))
-    ).scalar()
-
-    bzzoiro = {
-        "name": "bzzoiro",
-        "label": "Bzzoiro",
-        "key_configured": bool(bzzoiro_key),
-        "base_url": (bzzoiro_base.rstrip("/") if bzzoiro_base else None) or settings.BZZOIRO_BASE,
-        "reachable": None,  # 不主动探测
-        "last_success_at": (stats_row.latest_retrieved or match_row.latest_row_at),
-        "last_success_at_iso": (
-            stats_row.latest_retrieved or match_row.latest_row_at
-        ).isoformat() if (stats_row.latest_retrieved or match_row.latest_row_at) else None,
-        "latest_match_date": match_row.latest_match_date.isoformat() if match_row.latest_match_date else None,
-        "recent_count": match_row.cnt or 0,
-        "stats_count": stats_row.cnt or 0,
-        "standings_count": standings_row or 0,
-        "note": "last_success_at 取 match_stats.retrieved_at(统计回填)与 matches.created_at(比赛行)的较大者",
-        "last_failure": _last_failure_log("bzzoiro"),
-    }
-
-    return {"sources": [bzzoiro]}
-
-
-@router.get("/keyring/status")
-async def keyring_status():
-    """KeyRing 运行状态:当前使用的 key、冷却状态、轮转信息(供管理后台展示)。"""
-    base = (await get_runtime_value("BZZOIRO_BASE")).rstrip("/")
-    raw_keys = await get_runtime_value("BZZOIRO_KEY")
-    ring = get_key_ring(base, raw_keys)
-    st = ring.stats()
-    st["base_url"] = base
-    st["cooldown_seconds"] = ring._cooldown
-    st["has_multiple"] = ring.has_multiple
-    st["active_key"] = ring.active_key
-    return st
-
-
-@router.post("/keyring/cooldown/reset")
-async def keyring_reset_cooldown():
-    """手动重置所有 key 的冷却状态(用于紧急恢复)。"""
-    base = (await get_runtime_value("BZZOIRO_BASE")).rstrip("/")
-    raw_keys = await get_runtime_value("BZZOIRO_KEY")
-    ring = get_key_ring(base, raw_keys)
-    ring._blocked_until.clear()
-    return {"ok": True, "message": "已重置所有 key 冷却状态", "stats": ring.stats()}
-
-
-def _last_failure_log(source: str) -> dict | None:
-    """从系统日志缓冲中查找某数据源的最近一次错误(仅作参考,非专用失败表)。"""
-    entries = get_entries(min_level="ERROR", keyword=source, limit=5)
-    if not entries:
-        return None
-    e = entries[0]
-    return {
-        "at": datetime.fromtimestamp(e["ts"]).isoformat(),
-        "logger": e["logger"],
-        "detail": e["message"][:200],
-        "note": "approx:来自内存日志缓冲,非专用采集失败表;进程重启后清零",
-    }
-
-
-@router.get("/stats")
-async def admin_stats(db: AsyncSession = Depends(get_db_read)):
-    """管理区统计(只读):预测次数 + 比赛覆盖。轻量聚合,无 LLM 调用。"""
-    from sqlalchemy import func, text
-    from src.db.models import Prediction, Match, MatchStats, Standing
-    day_ago = datetime.now(timezone.utc) - timedelta(days=1)
-    week_ago = datetime.now(timezone.utc) - timedelta(days=7)
-    r = (
-        await db.execute(
-            select(
-                func.count().label("total"),
-                func.count().filter(Prediction.created_at >= day_ago).label("last_24h"),
-                func.count().filter(Prediction.created_at >= week_ago).label("last_7d"),
-            )
-        )
-    ).one()
-    # F3 修复: 补充真实比赛计数(非 limit=100 近似)
-    match_cnt = (await db.execute(select(func.count()).select_from(Match))).scalar() or 0
-    finished_cnt = (await db.execute(select(func.count()).where(Match.match_status == "finished"))).scalar() or 0
-    stats_cnt = (await db.execute(select(func.count()).select_from(MatchStats))).scalar() or 0
-    standings_cnt = (await db.execute(select(func.count()).select_from(Standing))).scalar() or 0
-    return {
-        "predictions": {"total": r.total, "last_24h": r.last_24h, "last_7d": r.last_7d},
-        "matches": {"total": match_cnt, "finished": finished_cnt},
-        "stats": {"total": stats_cnt},
-        "standings": {"total": standings_cnt},
-    }
-
-
-# ── 数据完整性分析(可视化数据源) ────────────────────────────────
-
-
-@router.get("/data-completeness")
-async def data_completeness(db: AsyncSession = Depends(get_db_read)):
-    """按联赛统计数据完整性:比赛覆盖、字段覆盖、积分榜覆盖。
-
-    前端「数据完整性」页据此渲染,回答三个问题:
-      1. 数据是否齐全(各联赛比赛/统计/积分榜量级)
-      2. 字段是否齐全(每张统计表各字段非空率)
-      3. 覆盖是否新鲜(最近一场/最近一次采集)
-    """
-    from src.data.config import BZZOIRO_LEAGUE_IDS, LEAGUE_NAMES, LEAGUE_COUNTRIES
-
-    out_leagues: list[dict] = []
-    for code, bzz_id in BZZOIRO_LEAGUE_IDS.items():
-        # 比赛覆盖
-        m = (
-            await db.execute(
-                select(
-                    func.count().label("total"),
-                    func.count().filter(Match.match_status == "finished").label("finished"),
-                    func.count().filter(Match.match_status == "scheduled").label("scheduled"),
-                    func.count().filter(Match.source_event_id.is_not(None)).label("with_source_id"),
-                    func.max(Match.match_date).label("latest_match"),
-                    func.min(Match.match_date).label("earliest_match"),
-                )
-                .select_from(Match)
-                .join(League, League.id == Match.league_id)
-                .where(League.code == code)
-            )
-        ).one()
-        # 统计字段覆盖(联表 matches)
-        s = (
-            await db.execute(
-                select(
-                    func.count().label("rows"),
-                    func.count(MatchStats.home_xg).label("xg"),
-                    func.count(MatchStats.home_shots).label("shots"),
-                    func.count(MatchStats.home_possession).label("possession"),
-                    func.count(MatchStats.home_corners).label("corners"),
-                    func.count(MatchStats.home_fouls).label("fouls"),
-                    func.count(MatchStats.home_big_chances).label("big_chances"),
-                    func.count(MatchStats.home_yellow_cards).label("cards"),
-                )
-                .select_from(MatchStats)
-                .join(Match, Match.id == MatchStats.match_id)
-                .join(League, League.id == Match.league_id)
-                .where(League.code == code)
-            )
-        ).one()
-        # 积分榜覆盖
-        st = (
-            await db.execute(
-                select(
-                    func.count().label("rows"),
-                    func.max(Standing.retrieved_at).label("latest_retrieved"),
-                )
-                .select_from(Standing)
-                .join(League, League.id == Standing.league_id)
-                .where(League.code == code)
-            )
-        ).one()
-
-        stats_rows = s.rows or 0
-        pct = lambda n: round(n / stats_rows * 100, 1) if stats_rows else 0.0  # noqa: E731
-        out_leagues.append(
-            {
-                "code": code,
-                "name": LEAGUE_NAMES.get(code, code),
-                "country": LEAGUE_COUNTRIES.get(code),
-                "matches": {
-                    "total": m.total or 0,
-                    "finished": m.finished or 0,
-                    "scheduled": m.scheduled or 0,
-                    "with_source_id": m.with_source_id or 0,
-                    "earliest_match": m.earliest_match.isoformat() if m.earliest_match else None,
-                    "latest_match": m.latest_match.isoformat() if m.latest_match else None,
-                },
-                "stats": {
-                    "rows": stats_rows,
-                    "fields": {
-                        "xg": {"count": s.xg or 0, "pct": pct(s.xg or 0)},
-                        "shots": {"count": s.shots or 0, "pct": pct(s.shots or 0)},
-                        "possession": {"count": s.possession or 0, "pct": pct(s.possession or 0)},
-                        "corners": {"count": s.corners or 0, "pct": pct(s.corners or 0)},
-                        "fouls": {"count": s.fouls or 0, "pct": pct(s.fouls or 0)},
-                        "big_chances": {"count": s.big_chances or 0, "pct": pct(s.big_chances or 0)},
-                        "cards": {"count": s.cards or 0, "pct": pct(s.cards or 0)},
-                    },
-                },
-                "standings": {
-                    "rows": st.rows or 0,
-                    "latest_retrieved": st.latest_retrieved.isoformat() if st.latest_retrieved else None,
-                },
-            }
-        )
-
-    # 整体健康信号
-    total_finished = sum(l["matches"]["finished"] for l in out_leagues)
-    total_stats = sum(l["stats"]["rows"] for l in out_leagues)
-    stats_coverage = round(total_stats / total_finished * 100, 1) if total_finished else 0.0
-    issues: list[str] = []
-    for l in out_leagues:
-        if l["matches"]["finished"] == 0:
-            issues.append(f"{l['name']}: 无已完赛比赛,请先运行「比赛数据」采集")
-        elif l["stats"]["rows"] == 0:
-            issues.append(f"{l['name']}: 已完赛 {l['matches']['finished']} 场但无统计回填,请运行「统计回填」采集")
-        elif stats_coverage < 80:
-            issues.append(f"{l['name']}: 统计覆盖率仅 {stats_coverage}%,建议增量回填")
-        if l["standings"]["rows"] == 0:
-            issues.append(f"{l['name']}: 无积分榜数据,请运行「积分榜」采集")
-    if not issues:
-        issues.append("各联赛数据完整度良好")
-
-    return {
-        "generated_at": datetime.now(timezone.utc).isoformat(),
-        "leagues": out_leagues,
-        "totals": {
-            "finished_matches": total_finished,
-            "stats_rows": total_stats,
-            "stats_coverage_pct": stats_coverage,
-        },
-        "issues": issues,
-    }
-
-
-# ── 数据质量检查 API ────────────────────────────────────────────
-
-
-@router.get("/data-quality")
-async def data_quality_checks(db: AsyncSession = Depends(get_db_read)):
-    """数据质量检查结果(只读)。"""
-    from src.db.models import IngestFailure, DataQualityCheck
-    from sqlalchemy import func
-
-    # 最近的失败记录
-    failures = (
-        await db.execute(
-            select(IngestFailure)
-            .where(IngestFailure.status.in_(["pending", "retrying"]))
-            .order_by(IngestFailure.created_at.desc())
-            .limit(20)
-        )
-    ).scalars().all()
-
-    # 最近的质量检查
-    checks = (
-        await db.execute(
-            select(DataQualityCheck)
-            .order_by(DataQualityCheck.checked_at.desc())
-            .limit(20)
-        )
-    ).scalars().all()
-
-    return {
-        "failures": [
-            {
-                "id": f.id,
-                "source": f.source_system,
-                "entity_type": f.entity_type,
-                "source_record_id": f.source_record_id,
-                "error_type": f.error_type,
-                "error_detail": f.error_detail,
-                "retry_count": f.retry_count,
-                "status": f.status,
-                "created_at": f.created_at.isoformat() if f.created_at else None,
-            }
-            for f in failures
-        ],
-        "checks": [
-            {
-                "id": c.id,
-                "check_name": c.check_name,
-                "entity_type": c.entity_type,
-                "passed": c.passed,
-                "severity": c.severity,
-                "detail": c.detail,
-                "checked_at": c.checked_at.isoformat() if c.checked_at else None,
-            }
-            for c in checks
-        ],
-    }
-
-
-@router.post("/data-quality/run")
-async def run_data_quality_check(db: AsyncSession = Depends(get_db_read)):
-    """手动触发一次数据质量检查。"""
-    from src.db.models import DataQualityCheck, Match, MatchStats, Standing, League
-    from sqlalchemy import func
-
-    checks = []
-
-    # 检查1: 已完赛但无统计的比赛
-    finished_no_stats = (
-        await db.execute(
-            select(func.count())
-            .select_from(Match)
-            .outerjoin(MatchStats, Match.id == MatchStats.match_id)
-            .where(Match.match_status == "finished")
-            .where(MatchStats.id.is_(None))
-        )
-    ).scalar() or 0
-
-    checks.append(DataQualityCheck(
-        check_name="finished_without_stats",
-        entity_type="match",
-        actual_value=float(finished_no_stats),
-        passed=finished_no_stats == 0,
-        severity="warning" if finished_no_stats > 0 else "info",
-        detail={"message": f"{finished_no_stats} 场已完赛比赛缺少统计数据"},
-    ))
-
-    # 检查2: 积分榜缺失的联赛
-    leagues_without_standings = (
-        await db.execute(
-            select(func.count())
-            .select_from(League)
-            .outerjoin(Standing, League.id == Standing.league_id)
-            .where(Standing.id.is_(None))
-        )
-    ).scalar() or 0
-
-    checks.append(DataQualityCheck(
-        check_name="league_without_standings",
-        entity_type="league",
-        actual_value=float(leagues_without_standings),
-        passed=leagues_without_standings == 0,
-        severity="warning" if leagues_without_standings > 0 else "info",
-        detail={"message": f"{leagues_without_standings} 个联赛缺少积分榜"},
-    ))
-
-    for c in checks:
-        db.add(c)
-    await db.commit()
-
-    return {"ok": True, "checks": [{"name": c.check_name, "passed": c.passed} for c in checks]}
+from fastapi import APIRouter
+
+from src.api.routes.admin_config import router as admin_config_router
+from src.api.routes.admin_datasources import router as admin_datasources_router
+from src.api.routes.admin_llm import router as admin_llm_router
+from src.api.routes.admin_quality import router as admin_quality_router
+
+router = APIRouter()
+router.include_router(admin_datasources_router)
+router.include_router(admin_config_router)
+router.include_router(admin_llm_router)
+router.include_router(admin_quality_router)

src/api/routes/ingest.py

@@ -16,7 +16,8 @@ from fastapi import APIRouter, Depends, HTTPException
 from src.api.deps import require_admin
 from src.api.schemas import IngestBzzoiroRequest
 from src.data.config import BZZOIRO_LEAGUE_IDS
-from src.data.bzzoiro import ingest_bzzoiro_event_stats, ingest_bzzoiro_standings
+from src.data.bzzoiro_standings import ingest_bzzoiro_standings
+from src.data.bzzoiro_stats import ingest_bzzoiro_event_stats
 from src.data.sources import get_source
 from src.db.unit_of_work import get_uow
 

src/api/routes/predict.py

@@ -64,11 +64,9 @@ async def predict(req: PredictRequest, request: Request):
         raise HTTPException(500, "预测失败,请查看服务器日志")
 
     # D2: 三种模式统一返回 PredictResult —— 字段映射单一化,无 dict 分支。
-    # 仅 baseline 的 prediction_id 需要在此落库补齐(服务层不落库)。
-    if req.mode == "baseline":
-        prediction_id = await _persist_baseline(req.match_id, result)
-    else:
-        prediction_id = result.prediction_id
+    # P3-2:baseline 已在服务层(predict_baseline)落库并回填真实 prediction_id,
+    # 路由层不再需要特殊的 _persist_baseline,与 single/multi 路径统一。
+    prediction_id = result.prediction_id
 
     # 3. 结果映射(无 DB 访问)
     logger.info(
@@ -101,36 +99,6 @@ async def predict(req: PredictRequest, request: Request):
     )
 
 
-async def _persist_baseline(match_id: int, baseline: PredictResult) -> int:
-    """将基线预测结果写入 prediction 表,复用 upsert 语义。"""
-    from src.db.unit_of_work import get_uow
-    from src.llm.predict import _upsert_prediction
-
-    async with get_uow() as session:
-        pred = await _upsert_prediction(
-            session,
-            match_id=match_id,
-            provider_name="baseline",
-            model="baseline",
-            mode="baseline",
-            run_type="live",  # baseline 是 live 预测的变体,符合 ck_run_type_enum
-            values={
-                "prompt_version": baseline.prompt_version,
-                "prompt_tokens": baseline.prompt_tokens or 0,
-                "completion_tokens": baseline.completion_tokens or 0,
-                "latency_ms": baseline.latency_ms or 0,
-                "pred_home_goals": baseline.pred_home_goals,
-                "pred_away_goals": baseline.pred_away_goals,
-                "pred_1x2": baseline.pred_1x2,
-                "subjective_confidence": baseline.subjective_confidence,
-                "reasoning": baseline.reasoning,
-                "raw_response": baseline.raw,
-                "status": "success",
-            },
-        )
-        return pred.id
-
-
 @router.get("/predictions", response_model=list[PredictionOut], dependencies=[Depends(require_admin)])
 async def list_predictions(
     match_id: int | None = None,

src/api/routes/schedules.py

@@ -10,7 +10,8 @@ from sqlalchemy import select, delete
 from src.api.deps import require_admin
 from src.api.schemas import ScheduleIn, ScheduleUpdate, ScheduleOut
 from src.core.scheduler import scheduler
-from src.data.bzzoiro import ingest_bzzoiro_event_stats, ingest_bzzoiro_standings
+from src.data.bzzoiro_standings import ingest_bzzoiro_standings
+from src.data.bzzoiro_stats import ingest_bzzoiro_event_stats
 from src.data.sources import get_source
 from src.data.config import BZZOIRO_LEAGUE_IDS
 from src.db.base import AsyncSession, get_db_read

src/core/config.py

@@ -11,6 +11,10 @@ class Settings(BaseSettings):
     # --- app ---
     APP_ENV: str = "development"
     LOG_LEVEL: str = "INFO"
+    # P3-3:多 worker 时应用内限流与 KeyRing 各自独立计数(配额放大 N 倍)。
+    # 设为 True 时若以多 worker 启动 uvicorn 则拒绝启动,避免静默配额漂移。
+    # 仅在你已前置 Nginx/网关做全局限流、确认不需要此守护时留空/False。
+    STRICT_SINGLE_WORKER: bool = False
     # 生产环境强制要求管理鉴权配置,即使 APP_ENV=production 也生效。
     # True 时若 auth_configured() 为 False 则拒绝(503),development 保持 fail-open。
     REQUIRE_ADMIN_AUTH: bool = False

src/data/bzzoiro.py

@@ -1,793 +1,71 @@
-"""Bzzoiro 数据源:抓取 + 入库(单一数据源)。
+"""Bzzoiro 数据源:抓取 + 入库(单一数据源)—— 聚合门面。
 
-三条管线:
-  1. events   — 比赛日程/比分(/events/),含 source_event_id 血缘
-  2. standings— 联赛积分榜快照(/leagues/{id}/standings/)
-  3. stats    — 已完赛比赛详细统计回填(/events/{id}/stats/)
+实现按管线拆分(单文件 → 多模块),本模块只做再导出,保持两个不变量:
+  1. sources._load_sources() 仍从本模块导入 BzzoiroSource(注册表入口不变);
+  2. 测试与脚本对 `bz.<名称>` 的 monkeypatch 语义不变 —— 子模块在运行期
+     经本门面解析可替换协作者(抓取函数 / Bronze 写入助手 / REQUEST_INTERVAL),
+     与拆分前的单文件行为一致。
+
+三条管线(各自模块):
+  1. events   — 比赛日程/比分(/events/),含 source_event_id 血缘  → bzzoiro_events.py
+  2. standings— 联赛积分榜快照(/leagues/{id}/standings/)          → bzzoiro_standings.py
+  3. stats    — 已完赛比赛详细统计回填(/events/{id}/stats/)        → bzzoiro_stats.py
+
+共享基础:HTTP 抓取(多 key 轮换)与字段转换 → bzzoiro_common.py;
+Bronze 基础设施(RawEvent/IngestFailure/DataLineage)→ pipeline_write.py。
 
 D4(工程债): Team/League/Match 的查找/创建经 Repository 层(src/db/repositories.py),
-本模块不直接控制事务(commit/rollback 由调用方 UnitOfWork 控制,这里只 flush)。
-Standing/RawEvent/Lineage 等管线内私有读写仍在本模块内实现,不强行 Repository 化。
+各管线不直接控制事务(commit/rollback 由调用方 UnitOfWork 控制,只 flush)。
+Standing/RawEvent/Lineage 等管线内私有读写仍不强行 Repository 化。
 """
 from __future__ import annotations
 
-import asyncio
-import logging
-import random
-from collections.abc import Iterable
-from datetime import datetime, timedelta, timezone
-
-from sqlalchemy import select
-
-import httpx
-
-from src.core.runtime_config import get_runtime_value
-from src.core.http_client import get_client
-from src.data.config import BZZOIRO_LEAGUE_IDS, LEAGUE_COUNTRIES, LEAGUE_NAMES, REQUEST_INTERVAL
-from src.data.key_ring import _mask, get_key_ring
-from src.data.normalize import normalize_bzzoiro
-from src.data.team_names_zh import zh_name
-from src.data.sources import register
-from src.db.models import Match, MatchStats, Standing, Team, RawEvent, IngestFailure, DataLineage
-from src.db.repositories import LeagueRepository, MatchRepository, TeamRepository
-
-logger = logging.getLogger(__name__)
-
-
-def _to_date(value):
-    """把 datetime / date / str 统一成 `date`。"""
-    if value is None:
-        return None
-    if hasattr(value, "date") and callable(value.date):
-        return value.date()
-    return value
-
-
-def _to_int_or_none(value) -> int | None:
-    """宽松转 int(用于上游 ID 解析,失败返回 None 不抛错)。"""
-    if value is None:
-        return None
-    try:
-        return int(str(value).strip())
-    except (TypeError, ValueError):
-        return None
-
-
-def _match_key(home_team_id: int, away_team_id: int, match_date) -> tuple[int, int, str]:
-    """比赛去重键:(主队, 客队, 天级日期 ISO 字符串)。
-
-    统一在这里构造,避免"预加载时用 str(date)、写入时用 isoformat()"这类
-    隐式格式依赖 —— 两者当前恰好相等,但一旦有人改动其一就会静默失配,
-    导致所有比赛被判为不存在而重复插入。
-    """
-    d = _to_date(match_date)
-    return (home_team_id, away_team_id, d.isoformat() if d is not None else "")
-
-
-async def _fetch_json_async(path: str, params: dict | None = None, max_retries: int = 3) -> dict | list:
-    """异步 HTTP(bzzoiro 使用 httpx,不再阻塞事件循环线程池)。
-
-    多 key 轮换:遇到 429 自动切换到下一个 key;全部 key 冷却时等待最早恢复。
-    """
-    base = (await get_runtime_value("BZZOIRO_BASE")).rstrip("/")
-    raw_keys = await get_runtime_value("BZZOIRO_KEY")
-    ring = get_key_ring(base, raw_keys)
-
-    url = f"{base}/{path.lstrip('/')}"
-    key = ring.get()
-    if not key:
-        raise RuntimeError("BZZOIRO_KEY 未设置")
-
-    last_exc: Exception | None = None
-    for attempt in range(max_retries):
-        headers = {
-            "Authorization": f"Token {key}",
-            "Accept": "application/json",
-        }
-        try:
-            client = get_client()
-            # 整请求兜底: httpx 无 total 超时,用 wait_for 防「滴水式」限速挂死
-            resp = await asyncio.wait_for(
-                client.get(
-                    url, headers=headers, params=params,
-                    timeout=httpx.Timeout(connect=10.0, read=30.0, write=10.0, pool=10.0),
-                ),
-                timeout=60.0,
-            )
-            resp.raise_for_status()
-            return resp.json()
-        except Exception as e:
-            last_exc = e
-            status = getattr(getattr(e, "response", None), "status_code", None)
-            if status == 429:
-                # 限流:标记当前 key 冷却,切换到下一个
-                new_key = ring.report_rate_limited(key)
-                if new_key and new_key != key:
-                    logger.info("bzzoiro 429 → 切换 key: %s → %s,立即重试", _mask(key), _mask(new_key))
-                    key = new_key
-                    continue  # 立即重试,不等待
-                # 单 key 或全部冷却:等待最早恢复的 key
-                wait = ring.wait_if_all_blocked()
-                if wait > 0:
-                    logger.warning("bzzoiro 全部 key 冷却,等待 %.1fs 后重试", wait)
-                    await asyncio.sleep(min(wait, 30.0))
-                else:
-                    delay = min(2 ** attempt, 16) + random.uniform(0, 1)
-                    logger.warning("bzzoiro 429, retry %d in %.1fs", attempt + 1, delay)
-                    await asyncio.sleep(delay)
-                key = ring.get() or key
-                continue
-            if 500 <= (status or 0) < 600:
-                delay = min(2 ** attempt, 16) + random.uniform(0, 1)
-                logger.warning("bzzoiro %d, retry %d in %.1fs", status, attempt + 1, delay)
-                await asyncio.sleep(delay)
-                continue
-            # 网络错误(连接失败/超时)也退避重试
-            if isinstance(e, (TimeoutError, ConnectionError, OSError)):
-                delay = min(2 ** attempt, 16) + random.uniform(0, 1)
-                logger.warning("bzzoiro network error, retry %d in %.1fs: %s", attempt + 1, delay, e)
-                await asyncio.sleep(delay)
-                continue
-            raise
-    raise RuntimeError(f"bzzoiro request failed after {max_retries} attempts: {last_exc}")
-
-
-async def fetch_bzzoiro_events(
-    league_code: str,
-    *,
-    status: str = "finished",
-    date_from: str | None = None,
-    date_to: str | None = None,
-    limit: int = 200,
-) -> list[dict]:
-    """抓取 bzzoiro 原始事件(纯异步,无需 run_in_executor)。"""
-    league_id = BZZOIRO_LEAGUE_IDS.get(league_code)
-    if league_id is None:
-        raise ValueError(f"未知联赛代码: {league_code}")
-
-    rows: list[dict] = []
-    offset = 0
-    while True:
-        params: dict = {
-            "league_id": league_id,
-            "status": status,
-            "limit": limit,
-            "offset": offset,
-        }
-        if date_from:
-            params["date_from"] = str(date_from)[:10]
-        if date_to:
-            params["date_to"] = str(date_to)[:10]
-        payload = await _fetch_json_async("/events/", params)
-        batch = payload.get("results") or []
-        if not batch:
-            break
-        rows.extend(batch)
-        total = payload.get("total")
-        offset += limit
-        if total is not None and offset >= total:
-            break
-        if len(batch) < limit:
-            break
-        await asyncio.sleep(REQUEST_INTERVAL)
-    return rows
-
-
-@register
-class BzzoiroSource:
-    """bzzoiro 数据源(实现 DataSource 协议)。"""
-
-    name = "bzzoiro"
-
-    async def ingest(
-        self,
-        db,
-        *,
-        leagues: Iterable[str],
-        date_from: str | None = None,
-        date_to: str | None = None,
-        status: str = "finished",
-    ) -> dict:
-        """采集 bzzoiro → 入库。返回统计。
-
-        注意: 本方法不控制事务(commit/rollback),由调用方通过 UnitOfWork 控制。
-        """
-        result: dict = {"leagues": {}, "total_inserted": 0, "total_updated": 0, "errors": []}
-
-        for code in leagues:
-            league_r: dict = {"inserted": 0, "updated": 0, "errors": []}
-            try:
-                raw_events = await fetch_bzzoiro_events(code, status=status, date_from=date_from, date_to=date_to)
-            except Exception as e:
-                # 单联赛抓取失败隔离:记录错误后继续其余联赛,不拖垮整批
-                logger.exception("bzzoiro fetch failed for %s", code)
-                league_r["errors"].append(f"fetch failed: {e}")
-                await _safe_write_ingest_failure(
-                    db,
-                    entity_type="events",
-                    source_record_id=None,
-                    error=e,
-                    raw_payload={"league": code, "status": status, "date_from": date_from, "date_to": date_to},
-                )
-                result["leagues"][code] = league_r
-                continue
-
-            # D4: 联赛查找/创建经 LeagueRepository(事务仍由调用方 UoW 提交)
-            league = await LeagueRepository(db).get_or_create(
-                code, LEAGUE_NAMES.get(code, code), LEAGUE_COUNTRIES.get(code)
-            )
-            team_r = TeamRepository(db)
-            match_r = MatchRepository(db)
-
-            # === 批量优化: 预加载球队和已有比赛到内存 ===
-            team_name_to_id: dict[str, int] = {}
-            existing_matches: dict[tuple[int, int, str], Match] = {}  # 完整对象,避免重复查询
-            # (NormalizedMatch, 原始 event) 成对保存:后续写 source_event_id 时
-            # 必须用配对的那条 event,不能依赖外层循环变量残留值。
-            normalized_matches: list[tuple] = []
-
-            if raw_events:
-                # 一次遍历: 收集球队名 + 规范化
-                all_team_names = set()
-                for raw in raw_events:
-                    nm = normalize_bzzoiro(raw, code)
-                    if nm is not None:
-                        try:
-                            nm.validate()
-                        except Exception as e:
-                            # P1-3: 统一使用 warning,不追加到 errors(仅运行时错误入 errors)
-                            logger.warning("normalize skip: %s", e)
-                            continue
-                        normalized_matches.append((nm, raw))
-                        all_team_names.add(nm.home_team)
-                        all_team_names.add(nm.away_team)
-
-                if all_team_names:
-                    team_name_to_id = {
-                        name: t.id
-                        for name, t in (await team_r.get_all_by_names(list(all_team_names))).items()
-                    }
-
-                # P1-2: 按需加载,只加载 raw_events 涉及日期范围的比赛(加 30 天缓冲)
-                # 避免加载联赛全部历史比赛到内存(多赛季采集时内存溢出)
-                if normalized_matches:
-                    # normalized_matches 存的是 (nm, raw) 元组,遍历需解包
-                    dates = [nm.date for nm, _raw in normalized_matches if nm.date is not None]
-                    if dates:
-                        min_dt = min(dates) - timedelta(days=30)
-                        max_dt = max(dates) + timedelta(days=30)
-                        matches_in_range = await match_r.find_by_league_and_date_range(
-                            league.id, min_dt, max_dt
-                        )
-                        existing_matches = {
-                            _match_key(m.home_team_id, m.away_team_id, m.match_date_date): m
-                            for m in matches_in_range
-                        }
-                # else: existing_matches 保持空 dict(全量新比赛)
-
-            # D1: Bronze 层批次信息(每联赛每批次一个 batch_id;seen 防同批重复写入)
-            now = datetime.now(timezone.utc)
-            bronze_batch_id = f"bzzoiro-events-{code}-{now:%Y%m%d%H%M%S}"
-            bronze_written: set[str] = set()
-
-            for nm, raw in normalized_matches:
-                # D1: RawEvent 幂等键(上游 id 或合成键),插入/变更更新共用
-                record_id = _events_record_id(code, nm, raw)
-
-                # 球队: 内存查找 + 按需创建(D4: 经 TeamRepository)
-                home_team_id = team_name_to_id.get(nm.home_team)
-                if home_team_id is None:
-                    home = await team_r.get_or_create(nm.home_team, name_zh=zh_name(nm.home_team))
-                    home_team_id = home.id
-                    team_name_to_id[nm.home_team] = home_team_id
-
-                away_team_id = team_name_to_id.get(nm.away_team)
-                if away_team_id is None:
-                    away = await team_r.get_or_create(nm.away_team, name_zh=zh_name(nm.away_team))
-                    away_team_id = away.id
-                    team_name_to_id[nm.away_team] = away_team_id
-
-                # 查找已有比赛: 内存查找
-                match_key = _match_key(home_team_id, away_team_id, nm.date)
-                existing_match = existing_matches.get(match_key)
-
-                if existing_match is None:
-                    m = Match(
-                        league_id=league.id,
-                        season=nm.season_label or None,
-                        home_team_id=home_team_id,
-                        away_team_id=away_team_id,
-                        match_date=nm.date,
-                        match_date_date=_to_date(nm.date),
-                        match_status=nm.match_status,
-                        home_goals=nm.home_goals,
-                        away_goals=nm.away_goals,
-                        home_ht_goals=nm.home_ht_goals,
-                        away_ht_goals=nm.away_ht_goals,
-                        match_stage=nm.match_stage,
-                        source_event_id=_to_int_or_none(raw.get("id")),
-                    )
-                    db.add(m)
-                    await db.flush()
-                    existing_matches[match_key] = m  # 防止同批重复
-                    # 统计字段不在 /events/ 载荷中(单独由 stats 管线回填),
-                    # 此处不再创建 MatchStats。
-                    league_r["inserted"] += 1
-                    # D1: 成功插入 → 补写 Bronze 层(原始载荷 + 血缘)
-                    if record_id not in bronze_written:
-                        bronze_written.add(record_id)
-                        await _write_events_bronze(
-                            db,
-                            source_record_id=record_id,
-                            raw_payload=raw,
-                            target_match_id=m.id,
-                            league_code=code,
-                            match_status=nm.match_status,
-                            batch_id=bronze_batch_id,
-                        )
-                else:
-                    # 已有比赛: 直接从内存获取对象更新(无需再查询)
-                    changed = False
-                    if existing_match.match_status != nm.match_status and nm.match_status == "finished":
-                        existing_match.match_status = nm.match_status
-                        changed = True
-                    if existing_match.home_goals is None and nm.home_goals is not None:
-                        existing_match.home_goals = nm.home_goals
-                        existing_match.away_goals = nm.away_goals
-                        existing_match.home_ht_goals = nm.home_ht_goals
-                        existing_match.away_ht_goals = nm.away_ht_goals
-                        changed = True
-                    if existing_match.match_stage is None and nm.match_stage:
-                        existing_match.match_stage = nm.match_stage
-                        changed = True
-                    if existing_match.source_event_id is None:
-                        eid = _to_int_or_none(raw.get("id"))
-                        if eid is not None:
-                            existing_match.source_event_id = eid
-                            changed = True
-                    if changed:
-                        league_r["updated"] += 1
-                        # D1: 变更更新 → 补写血缘(RawEvent 幂等键不变,重复采集自动跳过)
-                        if record_id not in bronze_written:
-                            bronze_written.add(record_id)
-                            await _write_events_bronze(
-                                db,
-                                source_record_id=record_id,
-                                raw_payload=raw,
-                                target_match_id=existing_match.id,
-                                league_code=code,
-                                match_status=nm.match_status,
-                                batch_id=bronze_batch_id,
-                            )
-
-            # 注意: 不在此处 commit,由调用方 UnitOfWork 控制事务
-            result["leagues"][code] = league_r
-            result["total_inserted"] += league_r["inserted"]
-            result["total_updated"] += league_r["updated"]
-        return result
-
-
-# ============================================================
-# 管线基础设施:RawEvent / IngestFailure / DataLineage
-# ============================================================
-
-
-async def _write_raw_event(db, source_system: str, source_record_id: str, raw_payload: dict, batch_id: str | None = None) -> None:
-    """写入 Bronze 层原始事件(幂等:同 source_record_id 跳过)。"""
-    from sqlalchemy import select as _select
-    stmt = _select(RawEvent).where(
-        RawEvent.source_system == source_system,
-        RawEvent.source_record_id == source_record_id,
-    )
-    existing = (await db.execute(stmt)).scalar_one_or_none()
-    if existing is None:
-        db.add(RawEvent(
-            source_system=source_system,
-            source_record_id=source_record_id,
-            raw_payload=raw_payload,
-            ingest_batch_id=batch_id,
-        ))
-
-
-async def _write_ingest_failure(db, source_system: str, entity_type: str, source_record_id: str | None, error_type: str, error_detail: str | None, raw_payload: dict | None = None) -> None:
-    """写入采集失败死信。"""
-    db.add(IngestFailure(
-        source_system=source_system,
-        entity_type=entity_type,
-        source_record_id=source_record_id,
-        error_type=error_type,
-        error_detail=error_detail,
-        raw_payload=raw_payload,
-    ))
-
-
-async def _safe_write_ingest_failure(
-    db,
-    *,
-    entity_type: str,
-    source_record_id: str | None,
-    error: Exception,
-    raw_payload: dict | None = None,
-) -> None:
-    """抓取失败时尽力写入死信表(失败不影响主流程)。
-
-    死信是「可观测性」基础设施,与 RawEvent/Lineage 同级:写入失败只记
-    warning,绝不能让原始抓取错误之外的新异常打断采集循环。
-    """
-    try:
-        await _write_ingest_failure(
-            db, "bzzoiro", entity_type, source_record_id,
-            "fetch_error", str(error), raw_payload,
-        )
-    except Exception:
-        logger.warning(
-            "写入 ingest_failures 死信失败(entity=%s, record=%s): %s",
-            entity_type, source_record_id, error, exc_info=True,
-        )
-
-
-async def _write_lineage(db, source_system: str, source_record_id: str, target_table: str, target_id: int | None, transform_name: str, transform_detail: dict | None = None, batch_id: str | None = None) -> None:
-    """写入 ETL 血缘追踪。"""
-    db.add(DataLineage(
-        source_system=source_system,
-        source_record_id=source_record_id,
-        target_table=target_table,
-        target_id=target_id,
-        transform_name=transform_name,
-        transform_detail=transform_detail,
-        batch_id=batch_id,
-    ))
-
-
-def _events_record_id(league_code: str, nm, raw: dict) -> str:
-    """events 载荷的 RawEvent 幂等键。
-
-    优先用上游 event id;缺失时用 (league:home:away:date) 合成稳定键 ——
-    取 normalize 后的队名与天级日期(与 _match_key 同口径),不依赖 DB 自增 id,
-    保证同一来源比赛重复采集时命中同一条 RawEvent,不产生重复原始载荷。
-    """
-    eid = _to_int_or_none(raw.get("id"))
-    if eid is not None:
-        return str(eid)
-    d = _to_date(nm.date)
-    date_part = d.isoformat() if d is not None else "na"
-    return f"{league_code}:{nm.home_team}:{nm.away_team}:{date_part}"
-
-
-async def _write_events_bronze(
-    db,
-    *,
-    source_record_id: str,
-    raw_payload: dict,
-    target_match_id: int | None,
-    league_code: str,
-    match_status: str | None,
-    batch_id: str,
-) -> None:
-    """events 成功插入/更新单场比赛后的 Bronze 层补写:RawEvent(幂等) + DataLineage。
-
-    D1(工程债):此前只有 stats 回填写 RawEvent/Lineage,events 管线作为比赛
-    主数据的唯一入口反而不留溯源记录。幂等性由 _write_raw_event 的
-    source_record_id 查重保证;best-effort:基础设施写入失败只记 warning,
-    绝不拖垮采集主流程(与 _safe_write_ingest_failure 同级约束)。
-    """
-    try:
-        await _write_raw_event(db, "bzzoiro", source_record_id, raw_payload, batch_id)
-        await _write_lineage(
-            db, "bzzoiro", source_record_id,
-            "matches", target_match_id, "events_ingest",
-            {"league": league_code, "match_status": match_status},
-            batch_id,
-        )
-    except Exception:
-        logger.warning(
-            "events Bronze 写入失败(record=%s, match=%s),不影响采集主流程",
-            source_record_id, target_match_id, exc_info=True,
-        )
-
-
-# ============================================================
-# 积分榜管线:/leagues/{id}/standings/ → standings 表
-# ============================================================
-
-async def fetch_bzzoiro_standings(league_code: str, season: str | None = None) -> dict:
-    """抓取联赛积分榜(纯抓取,不入库)。season 为 None 时取当前赛季。"""
-    league_id = BZZOIRO_LEAGUE_IDS.get(league_code)
-    if league_id is None:
-        raise ValueError(f"未知联赛代码: {league_code}")
-    params: dict = {}
-    if season:
-        params["season"] = season
-    return await _fetch_json_async(f"/leagues/{league_id}/standings/", params)
-
-
-def _season_label_from_dates(start_date, end_date) -> str:
-    """从赛季起止日期推导赛季标签(与 derive_season_label 语义一致)。"""
-    try:
-        if isinstance(start_date, str):
-            start = datetime.fromisoformat(start_date[:10])
-        else:
-            start = start_date
-        y = start.year
-        return f"{y}-{y + 1}" if start.month >= 8 else f"{y - 1}-{y}"
-    except (TypeError, ValueError):
-        return "?"
-
-
-async def ingest_bzzoiro_standings(db, *, leagues: Iterable[str], season: str | None = None) -> dict:
-    """采集积分榜 → upsert standings 表。
-
-    season 为 None 时采集当前赛季(bzzoiro 默认返回 is_current 赛季)。
-    球队名与 events 管线使用同一 normalize 规则,保证 Team 匹配。
-    """
-    from src.data.team_names import normalize as normalize_name
-
-    result: dict = {"leagues": {}, "total_upserted": 0, "errors": []}
-    for code in leagues:
-        league_r: dict = {"upserted": 0, "teams_created": 0, "rows": 0, "errors": []}
-        try:
-            payload = await fetch_bzzoiro_standings(code, season=season)
-        except Exception as e:
-            logger.exception("bzzoiro standings fetch failed for %s", code)
-            league_r["errors"].append(str(e))
-            await _safe_write_ingest_failure(
-                db,
-                entity_type="standings",
-                source_record_id=None,
-                error=e,
-                raw_payload={"league": code, "season": season},
-            )
-            result["leagues"][code] = league_r
-            result["errors"].append(f"{code}: {e}")
-            continue
-
-        rows = payload.get("standings") or []
-        if not rows:
-            result["leagues"][code] = {"error": "无积分榜数据(赛季未开始或未提供)"}
-            result["errors"].append(f"{code}: 无积分榜数据")
-            continue
-
-        # 联赛(get-or-create,D4: 经 LeagueRepository)
-        league = await LeagueRepository(db).get_or_create(
-            code, LEAGUE_NAMES.get(code, code), LEAGUE_COUNTRIES.get(code)
-        )
-        team_r = TeamRepository(db)
-
-        # 赛季标签:优先用返回的 season 对象推导
-        season_obj = payload.get("season") or {}
-        season_label = _season_label_from_dates(
-            season_obj.get("start_date"), season_obj.get("end_date")
-        )
-        if season_label == "?":
-            season_label = season or ""
-
-        # 批量预载球队(与 events 管线使用同一 normalize 规则,保证 Team 匹配)
-        names = {normalize_name(str(r.get("team_name", ""))) for r in rows}
-        names.discard("")
-        team_map: dict[str, Team] = await team_r.get_all_by_names(list(names))
-
-        now = datetime.now(timezone.utc)
-        for r in rows:
-            team_name = normalize_name(str(r.get("team_name", "")))
-            if not team_name:
-                continue
-            team = team_map.get(team_name)
-            if team is None:
-                team = await team_r.get_or_create(team_name, name_zh=zh_name(team_name))
-                team_map[team_name] = team
-                league_r["teams_created"] += 1
-
-            zone = r.get("zone") or {}
-            values = dict(
-                position=_to_int_or_none(r.get("position")) or 0,
-                played=_to_int_or_none(r.get("played")) or 0,
-                won=_to_int_or_none(r.get("won")) or 0,
-                drawn=_to_int_or_none(r.get("drawn")) or 0,
-                lost=_to_int_or_none(r.get("lost")) or 0,
-                goals_for=_to_int_or_none(r.get("gf")) or 0,
-                goals_against=_to_int_or_none(r.get("ga")) or 0,
-                goal_diff=_to_int_or_none(r.get("gd")) or 0,
-                points=_to_int_or_none(r.get("pts")) or 0,
-                xg_for=_to_float_or_none(r.get("xgf")),
-                xg_against=_to_float_or_none(r.get("xga")),
-                form=r.get("form") or None,
-                zone=zone.get("label") or zone.get("key") or None,
-                updated_at=now,
-                retrieved_at=now,
-            )
-
-            # 同一联赛同一赛季只保留最新快照:按 (league, season, team) upsert
-            stmt = select(Standing).where(
-                Standing.league_id == league.id,
-                Standing.season == season_label,
-                Standing.team_id == team.id,
-            )
-            standing = (await db.execute(stmt)).scalar_one_or_none()
-            if standing is None:
-                standing = Standing(
-                    league_id=league.id, season=season_label, team_id=team.id, **values
-                )
-                db.add(standing)
-            else:
-                for k, v in values.items():
-                    setattr(standing, k, v)
-            league_r["upserted"] += 1
-
-        league_r["rows"] = len(rows)
-        result["leagues"][code] = league_r
-        result["total_upserted"] += league_r["upserted"]
-        logger.info(
-            "bzzoiro standings 采集完成: %s 赛季 %s, upsert %d/%d",
-            code, season_label, league_r["upserted"], league_r["rows"],
-        )
-    return result
-
-
-# ============================================================
-# 统计回填管线:/events/{id}/stats/ → match_stats 表
-# ============================================================
-
-# bzzoiro stats 字段 → MatchStats 字段映射(stats.home / stats.away 下)
-_STATS_FIELD_MAP = {
-    "xg": ("home_xg", "away_xg"),                    # 回退 expected_goals
-    "ball_possession": ("home_possession", None),     # 只取主队值,客队=100-home
-    "total_shots": ("home_shots", "away_shots"),
-    "shots_on_target": ("home_shots_on_target", "away_shots_on_target"),
-    "corner_kicks": ("home_corners", "away_corners"),
-    "yellow_cards": ("home_yellow_cards", "away_yellow_cards"),
-    "red_cards": ("home_red_cards", "away_red_cards"),
-    "big_chances": ("home_big_chances", "away_big_chances"),
-    "fouls": ("home_fouls", "away_fouls"),
-}
-
-
-def _pick(d: dict, *keys):
-    """按优先级取第一个非空字段值。"""
-    for k in keys:
-        v = d.get(k)
-        if v is not None:
-            return v
-    return None
-
-
-def _stats_from_payload(payload: dict) -> dict:
-    """把 /events/{id}/stats/ 响应映射成 MatchStats 字段 dict。
-
-    响应结构: {"event_id": ..., "stats": {"home": {...}, "away": {...}}}
-    """
-    stats = (payload or {}).get("stats") or {}
-    home = stats.get("home") or {}
-    away = stats.get("away") or {}
-    out: dict = {}
-
-    xg_h = _pick(home, "xg", "expected_goals")
-    xg_a = _pick(away, "xg", "expected_goals")
-    if xg_h is not None:
-        out["home_xg"] = _to_float_or_none(xg_h)
-    if xg_a is not None:
-        out["away_xg"] = _to_float_or_none(xg_a)
-
-    poss = home.get("ball_possession")
-    if poss is not None:
-        p = _to_float_or_none(poss)
-        if p is not None:
-            out["home_possession"] = p
-
-    for src, (h_fld, a_fld) in _STATS_FIELD_MAP.items():
-        if src in ("xg", "ball_possession"):
-            continue  # 已处理
-        hv = home.get(src)
-        av = away.get(src)
-        if hv is not None and h_fld:
-            out[h_fld] = _to_int_or_none(hv)
-        if av is not None and a_fld:
-            out[a_fld] = _to_int_or_none(av)
-    return out
-
-
-def _to_float_or_none(value) -> float | None:
-    if value is None:
-        return None
-    try:
-        return float(str(value).strip())
-    except (TypeError, ValueError):
-        return None
-
-
-async def ingest_bzzoiro_event_stats(
-    db,
-    *,
-    leagues: Iterable[str],
-    limit: int = 100,
-    only_missing: bool = True,
-) -> dict:
-    """回填已完赛比赛的详细统计(逐场调 /events/{id}/stats/)。
-
-    筛选条件: match_status=finished 且 source_event_id 非空。
-    only_missing=True 时跳过已有统计的比赛(增量);False 则全量刷新。
-    limit 控制单次最多处理的比赛数(上游限速 1.2s/请求,大批量需分次触发)。
-    """
-    result: dict = {"fetched": 0, "created": 0, "updated": 0, "skipped": 0, "errors": []}
-
-    league_ids = [BZZOIRO_LEAGUE_IDS[c] for c in leagues if c in BZZOIRO_LEAGUE_IDS]
-    if not league_ids:
-        result["errors"].append("无有效联赛代码")
-        return result
-
-    # D4: 候选比赛查询经 MatchRepository(含 stats 预加载,筛选/排序/limit 语义不变)
-    matches = await MatchRepository(db).find_finished_with_stats(
-        league_ids, limit=limit * 3 if only_missing else limit
-    )
-
-    now = datetime.now(timezone.utc)
-    processed = 0
-    for m in matches:
-        if processed >= limit:
-            break
-        if only_missing and m.stats is not None and m.stats.home_shots is not None:
-            result["skipped"] += 1
-            continue
-        processed += 1
-        try:
-            payload = await _fetch_json_async(f"/events/{m.source_event_id}/stats/")
-        except Exception as e:
-            logger.warning("stats fetch failed match=%s event=%s: %s", m.id, m.source_event_id, e)
-            result["errors"].append(f"match {m.id}: {e}")
-            await _safe_write_ingest_failure(
-                db,
-                entity_type="match_stats",
-                source_record_id=str(m.source_event_id),
-                error=e,
-                raw_payload={"match_id": m.id},
-            )
-            await asyncio.sleep(REQUEST_INTERVAL)
-            continue
-
-        result["fetched"] += 1
-        fields = _stats_from_payload(payload)
-        if not fields:
-            result["skipped"] += 1
-            await asyncio.sleep(REQUEST_INTERVAL)
-            continue
-
-        if m.stats is None:
-            available_at = m.match_date + timedelta(hours=2) if m.match_date else now
-            m.stats = MatchStats(
-                match_id=m.id,
-                source="bzzoiro",
-                source_record_id=str(m.source_event_id),
-                retrieved_at=now,
-                available_at=available_at,
-            )
-            db.add(m.stats)
-            result["created"] += 1
-        else:
-            result["updated"] += 1
-            if m.stats.source is None:
-                m.stats.source = "bzzoiro"
-                m.stats.source_record_id = str(m.source_event_id)
-            if m.stats.retrieved_at is None:
-                m.stats.retrieved_at = now
-            if m.stats.available_at is None and m.match_date:
-                m.stats.available_at = m.match_date + timedelta(hours=2)
-
-        for fld, v in fields.items():
-            if hasattr(m.stats, fld):
-                setattr(m.stats, fld, v)
-
-        # 管线基础设施:写入 RawEvent + DataLineage
-        batch_id = f"bzzoiro-stats-{m.source_event_id}-{now.strftime('%Y%m%d%H%M%S')}"
-        try:
-            await _write_raw_event(db, "bzzoiro", str(m.source_event_id), payload, batch_id)
-            await _write_lineage(db, "bzzoiro", str(m.source_event_id), "match_stats", m.stats.id if m.stats else None, "stats_backfill", {"match_id": m.id}, batch_id)
-        except Exception:
-            pass  # 基础设施写入失败不影响主流程
-
-        await asyncio.sleep(REQUEST_INTERVAL)
-
-    logger.info(
-        "bzzoiro stats 回填完成: 抓取 %d, 新建 %d, 更新 %d, 跳过 %d, 错误 %d",
-        result["fetched"], result["created"], result["updated"],
-        result["skipped"], len(result["errors"]),
-    )
-    return result
+# ── 配置常量(原文件即从 config 再导出,维持 bz.REQUEST_INTERVAL 等引用) ──
+from src.data.config import (  # noqa: F401
+    BZZOIRO_LEAGUE_IDS,
+    LEAGUE_COUNTRIES,
+    LEAGUE_NAMES,
+    REQUEST_INTERVAL,
+)
+from src.data.key_ring import _mask  # noqa: F401  (R1 测试引用 bz._mask)
+from src.data.normalize import normalize_bzzoiro  # noqa: F401
+
+# ── 共享原语:HTTP 抓取 + 宽松字段转换 ──
+from src.data.bzzoiro_common import (  # noqa: F401
+    _fetch_json_async,
+    _match_key,
+    _to_date,
+    _to_float_or_none,
+    _to_int_or_none,
+)
+
+# ── 管线基础设施:RawEvent / IngestFailure / DataLineage ──
+from src.data.pipeline_write import (  # noqa: F401
+    _safe_write_ingest_failure,
+    _write_ingest_failure,
+    _write_lineage,
+    _write_raw_event,
+)
+
+# ── events 管线:BzzoiroSource(注册表入口)+ 抓取/入库 ──
+from src.data.bzzoiro_events import (  # noqa: F401
+    BzzoiroSource,
+    _events_record_id,
+    _write_events_bronze,
+    fetch_bzzoiro_events,
+)
+
+# ── standings 管线 ──
+from src.data.bzzoiro_standings import (  # noqa: F401
+    _season_label_from_dates,
+    _write_standings_bronze,
+    fetch_bzzoiro_standings,
+    ingest_bzzoiro_standings,
+)
+
+# ── stats 回填管线 ──
+from src.data.bzzoiro_stats import (  # noqa: F401
+    _pick,
+    _stats_from_payload,
+    ingest_bzzoiro_event_stats,
+)

src/data/bzzoiro_common.py

@@ -0,0 +1,123 @@
+"""bzzoiro 管线共享原语:HTTP 抓取(多 key 轮换)与宽松字段转换。
+
+从 bzzoiro.py 拆出(单文件 → 多模块):仅放无业务语义的共享基础,
+三条管线(events/standings/stats)与聚合门面见 bzzoiro.py。
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import random
+
+import httpx
+
+from src.core.http_client import get_client
+from src.core.runtime_config import get_runtime_value
+from src.data.key_ring import _mask, get_key_ring
+
+logger = logging.getLogger(__name__)
+
+
+def _to_date(value):
+    """把 datetime / date / str 统一成 `date`。"""
+    if value is None:
+        return None
+    if hasattr(value, "date") and callable(value.date):
+        return value.date()
+    return value
+
+
+def _to_int_or_none(value) -> int | None:
+    """宽松转 int(用于上游 ID 解析,失败返回 None 不抛错)。"""
+    if value is None:
+        return None
+    try:
+        return int(str(value).strip())
+    except (TypeError, ValueError):
+        return None
+
+
+def _to_float_or_none(value) -> float | None:
+    try:
+        return float(str(value).strip())
+    except (TypeError, ValueError):
+        return None
+
+
+def _match_key(home_team_id: int, away_team_id: int, match_date) -> tuple[int, int, str]:
+    """比赛去重键:(主队, 客队, 天级日期 ISO 字符串)。
+
+    统一在这里构造,避免"预加载时用 str(date)、写入时用 isoformat()"这类
+    隐式格式依赖 —— 两者当前恰好相等,但一旦有人改动其一就会静默失配,
+    导致所有比赛被判为不存在而重复插入。
+    """
+    d = _to_date(match_date)
+    return (home_team_id, away_team_id, d.isoformat() if d is not None else "")
+
+
+async def _fetch_json_async(path: str, params: dict | None = None, max_retries: int = 3) -> dict | list:
+    """异步 HTTP(bzzoiro 使用 httpx,不再阻塞事件循环线程池)。
+
+    多 key 轮换:遇到 429 自动切换到下一个 key;全部 key 冷却时等待最早恢复。
+    """
+    base = (await get_runtime_value("BZZOIRO_BASE")).rstrip("/")
+    raw_keys = await get_runtime_value("BZZOIRO_KEY")
+    ring = get_key_ring(base, raw_keys)
+
+    url = f"{base}/{path.lstrip('/')}"
+    key = ring.get()
+    if not key:
+        raise RuntimeError("BZZOIRO_KEY 未设置")
+
+    last_exc: Exception | None = None
+    for attempt in range(max_retries):
+        headers = {
+            "Authorization": f"Token {key}",
+            "Accept": "application/json",
+        }
+        try:
+            client = get_client()
+            # 整请求兜底: httpx 无 total 超时,用 wait_for 防「滴水式」限速挂死
+            resp = await asyncio.wait_for(
+                client.get(
+                    url, headers=headers, params=params,
+                    timeout=httpx.Timeout(connect=10.0, read=30.0, write=10.0, pool=10.0),
+                ),
+                timeout=60.0,
+            )
+            resp.raise_for_status()
+            return resp.json()
+        except Exception as e:
+            last_exc = e
+            status = getattr(getattr(e, "response", None), "status_code", None)
+            if status == 429:
+                # 限流:标记当前 key 冷却,切换到下一个
+                new_key = ring.report_rate_limited(key)
+                if new_key and new_key != key:
+                    logger.info("bzzoiro 429 → 切换 key: %s → %s,立即重试", _mask(key), _mask(new_key))
+                    key = new_key
+                    continue  # 立即重试,不等待
+                # 单 key 或全部冷却:等待最早恢复的 key
+                wait = ring.wait_if_all_blocked()
+                if wait > 0:
+                    logger.warning("bzzoiro 全部 key 冷却,等待 %.1fs 后重试", wait)
+                    await asyncio.sleep(min(wait, 30.0))
+                else:
+                    delay = min(2 ** attempt, 16) + random.uniform(0, 1)
+                    logger.warning("bzzoiro 429, retry %d in %.1fs", attempt + 1, delay)
+                    await asyncio.sleep(delay)
+                key = ring.get() or key
+                continue
+            if 500 <= (status or 0) < 600:
+                delay = min(2 ** attempt, 16) + random.uniform(0, 1)
+                logger.warning("bzzoiro %d, retry %d in %.1fs", status, attempt + 1, delay)
+                await asyncio.sleep(delay)
+                continue
+            # 网络错误(连接失败/超时)也退避重试
+            if isinstance(e, (TimeoutError, ConnectionError, OSError)):
+                delay = min(2 ** attempt, 16) + random.uniform(0, 1)
+                logger.warning("bzzoiro network error, retry %d in %.1fs: %s", attempt + 1, delay, e)
+                await asyncio.sleep(delay)
+                continue
+            raise
+    raise RuntimeError(f"bzzoiro request failed after {max_retries} attempts: {last_exc}")

src/data/bzzoiro_events.py

@@ -0,0 +1,310 @@
+"""bzzoiro events 管线:比赛日程/比分抓取(/events/)与入库(matches 表)。
+
+从 bzzoiro.py 拆出。比赛主数据唯一入口;Team/League/Match 查找/创建经
+Repository 层,事务由调用方 UnitOfWork 控制(分批事务约定不变)。
+
+可替换协作者(抓取函数 / Bronze 写入助手 / REQUEST_INTERVAL)在运行期
+经聚合门面 src.data.bzzoiro 解析 —— 与拆分前的单文件 monkeypatch 语义一致。
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Iterable
+from datetime import datetime, timedelta, timezone
+
+from src.data.bzzoiro_common import _match_key, _to_date, _to_int_or_none
+from src.data.config import BZZOIRO_LEAGUE_IDS, LEAGUE_COUNTRIES, LEAGUE_NAMES
+from src.data.normalize import normalize_bzzoiro
+from src.data.sources import register
+from src.data.team_names_zh import zh_name
+from src.db.models import Match
+from src.db.repositories import LeagueRepository, MatchRepository, TeamRepository
+
+logger = logging.getLogger(__name__)
+
+
+async def fetch_bzzoiro_events(
+    league_code: str,
+    *,
+    status: str = "finished",
+    date_from: str | None = None,
+    date_to: str | None = None,
+    limit: int = 200,
+) -> list[dict]:
+    """抓取 bzzoiro 原始事件(纯异步,无需 run_in_executor)。"""
+    from src.data import bzzoiro as bz
+
+    league_id = BZZOIRO_LEAGUE_IDS.get(league_code)
+    if league_id is None:
+        raise ValueError(f"未知联赛代码: {league_code}")
+
+    rows: list[dict] = []
+    offset = 0
+    while True:
+        params: dict = {
+            "league_id": league_id,
+            "status": status,
+            "limit": limit,
+            "offset": offset,
+        }
+        if date_from:
+            params["date_from"] = str(date_from)[:10]
+        if date_to:
+            params["date_to"] = str(date_to)[:10]
+        payload = await bz._fetch_json_async("/events/", params)
+        batch = payload.get("results") or []
+        if not batch:
+            break
+        rows.extend(batch)
+        total = payload.get("total")
+        offset += limit
+        if total is not None and offset >= total:
+            break
+        if len(batch) < limit:
+            break
+        await asyncio.sleep(bz.REQUEST_INTERVAL)
+    return rows
+
+
+@register
+class BzzoiroSource:
+    """bzzoiro 数据源(实现 DataSource 协议)。"""
+
+    name = "bzzoiro"
+
+    async def ingest(
+        self,
+        db,
+        *,
+        leagues: Iterable[str],
+        date_from: str | None = None,
+        date_to: str | None = None,
+        status: str = "finished",
+    ) -> dict:
+        """采集 bzzoiro → 入库。返回统计。
+
+        注意: 本方法不控制事务(commit/rollback),由调用方通过 UnitOfWork 控制。
+        """
+        from src.data import bzzoiro as bz
+
+        result: dict = {"leagues": {}, "total_inserted": 0, "total_updated": 0, "errors": []}
+
+        for code in leagues:
+            league_r: dict = {"inserted": 0, "updated": 0, "errors": []}
+            try:
+                raw_events = await bz.fetch_bzzoiro_events(code, status=status, date_from=date_from, date_to=date_to)
+            except Exception as e:
+                # 单联赛抓取失败隔离:记录错误后继续其余联赛,不拖垮整批
+                logger.exception("bzzoiro fetch failed for %s", code)
+                league_r["errors"].append(f"fetch failed: {e}")
+                await bz._safe_write_ingest_failure(
+                    db,
+                    entity_type="events",
+                    source_record_id=None,
+                    error=e,
+                    raw_payload={"league": code, "status": status, "date_from": date_from, "date_to": date_to},
+                )
+                result["leagues"][code] = league_r
+                continue
+
+            # D4: 联赛查找/创建经 LeagueRepository(事务仍由调用方 UoW 提交)
+            league = await LeagueRepository(db).get_or_create(
+                code, LEAGUE_NAMES.get(code, code), LEAGUE_COUNTRIES.get(code)
+            )
+            team_r = TeamRepository(db)
+            match_r = MatchRepository(db)
+
+            # === 批量优化: 预加载球队和已有比赛到内存 ===
+            team_name_to_id: dict[str, int] = {}
+            existing_matches: dict[tuple[int, int, str], Match] = {}  # 完整对象,避免重复查询
+            # (NormalizedMatch, 原始 event) 成对保存:后续写 source_event_id 时
+            # 必须用配对的那条 event,不能依赖外层循环变量残留值。
+            normalized_matches: list[tuple] = []
+
+            if raw_events:
+                # 一次遍历: 收集球队名 + 规范化
+                all_team_names = set()
+                for raw in raw_events:
+                    nm = normalize_bzzoiro(raw, code)
+                    if nm is not None:
+                        try:
+                            nm.validate()
+                        except Exception:
+                            continue
+                        normalized_matches.append((nm, raw))
+                        all_team_names.add(nm.home_team)
+                        all_team_names.add(nm.away_team)
+
+                if all_team_names:
+                    team_name_to_id = {
+                        name: t.id
+                        for name, t in (await team_r.get_all_by_names(list(all_team_names))).items()
+                    }
+
+                # P1-2: 按需加载,只加载 raw_events 涉及日期范围的比赛(加 30 天缓冲)
+                # 避免加载联赛全部历史比赛到内存(多赛季采集时内存溢出)
+                if normalized_matches:
+                    # normalized_matches 存的是 (nm, raw) 元组,遍历需解包
+                    dates = [nm.date for nm, _raw in normalized_matches if nm.date is not None]
+                    if dates:
+                        min_dt = min(dates) - timedelta(days=30)
+                        max_dt = max(dates) + timedelta(days=30)
+                        matches_in_range = await match_r.find_by_league_and_date_range(
+                            league.id, min_dt, max_dt
+                        )
+                        existing_matches = {
+                            _match_key(m.home_team_id, m.away_team_id, m.match_date_date): m
+                            for m in matches_in_range
+                        }
+                # else: existing_matches 保持空 dict(全量新比赛)
+
+            # D1: Bronze 层批次信息(每联赛每批次一个 batch_id;seen 防同批重复写入)
+            now = datetime.now(timezone.utc)
+            bronze_batch_id = f"bzzoiro-events-{code}-{now:%Y%m%d%H%M%S}"
+            bronze_written: set[str] = set()
+
+            for nm, raw in normalized_matches:
+                # D1: RawEvent 幂等键(上游 id 或合成键),插入/变更更新共用
+                record_id = _events_record_id(code, nm, raw)
+
+                # 球队: 内存查找 + 按需创建(D4: 经 TeamRepository)
+                home_team_id = team_name_to_id.get(nm.home_team)
+                if home_team_id is None:
+                    home = await team_r.get_or_create(nm.home_team, name_zh=zh_name(nm.home_team))
+                    home_team_id = home.id
+                    team_name_to_id[nm.home_team] = home_team_id
+
+                away_team_id = team_name_to_id.get(nm.away_team)
+                if away_team_id is None:
+                    away = await team_r.get_or_create(nm.away_team, name_zh=zh_name(nm.away_team))
+                    away_team_id = away.id
+                    team_name_to_id[nm.away_team] = away_team_id
+
+                # 查找已有比赛: 内存查找
+                match_key = _match_key(home_team_id, away_team_id, nm.date)
+                existing_match = existing_matches.get(match_key)
+
+                if existing_match is None:
+                    m = Match(
+                        league_id=league.id,
+                        season=nm.season_label or None,
+                        home_team_id=home_team_id,
+                        away_team_id=away_team_id,
+                        match_date=nm.date,
+                        match_date_date=_to_date(nm.date),
+                        match_status=nm.match_status,
+                        home_goals=nm.home_goals,
+                        away_goals=nm.away_goals,
+                        home_ht_goals=nm.home_ht_goals,
+                        away_ht_goals=nm.away_ht_goals,
+                        match_stage=nm.match_stage,
+                        source_event_id=_to_int_or_none(raw.get("id")),
+                    )
+                    db.add(m)
+                    await db.flush()
+                    existing_matches[match_key] = m  # 防止同批重复
+                    # 统计字段不在 /events/ 载荷中(单独由 stats 管线回填),
+                    # 此处不再创建 MatchStats。
+                    league_r["inserted"] += 1
+                    # D1: 成功插入 → 补写 Bronze 层(原始载荷 + 血缘)
+                    if record_id not in bronze_written:
+                        bronze_written.add(record_id)
+                        await _write_events_bronze(
+                            db,
+                            source_record_id=record_id,
+                            raw_payload=raw,
+                            target_match_id=m.id,
+                            league_code=code,
+                            match_status=nm.match_status,
+                            batch_id=bronze_batch_id,
+                        )
+                else:
+                    # 已有比赛: 直接从内存获取对象更新(无需再查询)
+                    changed = False
+                    if existing_match.match_status != nm.match_status and nm.match_status == "finished":
+                        existing_match.match_status = nm.match_status
+                        changed = True
+                    if existing_match.home_goals is None and nm.home_goals is not None:
+                        existing_match.home_goals = nm.home_goals
+                        existing_match.away_goals = nm.away_goals
+                        existing_match.home_ht_goals = nm.home_ht_goals
+                        existing_match.away_ht_goals = nm.away_ht_goals
+                        changed = True
+                    if existing_match.match_stage is None and nm.match_stage:
+                        existing_match.match_stage = nm.match_stage
+                        changed = True
+                    if existing_match.source_event_id is None:
+                        eid = _to_int_or_none(raw.get("id"))
+                        if eid is not None:
+                            existing_match.source_event_id = eid
+                            changed = True
+                    if changed:
+                        league_r["updated"] += 1
+                        # D1: 变更更新 → 补写血缘(RawEvent 幂等键不变,重复采集自动跳过)
+                        if record_id not in bronze_written:
+                            bronze_written.add(record_id)
+                            await _write_events_bronze(
+                                db,
+                                source_record_id=record_id,
+                                raw_payload=raw,
+                                target_match_id=existing_match.id,
+                                league_code=code,
+                                match_status=nm.match_status,
+                                batch_id=bronze_batch_id,
+                            )
+
+            # 注意: 不在此处 commit,由调用方 UnitOfWork 控制事务
+            result["leagues"][code] = league_r
+            result["total_inserted"] += league_r["inserted"]
+            result["total_updated"] += league_r["updated"]
+        return result
+
+
+def _events_record_id(league_code: str, nm, raw: dict) -> str:
+    """events 载荷的 RawEvent 幂等键。
+
+    优先用上游 event id;缺失时用 (league:home:away:date) 合成稳定键 ——
+    取 normalize 后的队名与天级日期(与 _match_key 同口径),不依赖 DB 自增 id,
+    保证同一来源比赛重复采集时命中同一条 RawEvent,不产生重复原始载荷。
+    """
+    eid = _to_int_or_none(raw.get("id"))
+    if eid is not None:
+        return str(eid)
+    d = _to_date(nm.date)
+    date_part = d.isoformat() if d is not None else "na"
+    return f"{league_code}:{nm.home_team}:{nm.away_team}:{date_part}"
+
+
+async def _write_events_bronze(
+    db,
+    *,
+    source_record_id: str,
+    raw_payload: dict,
+    target_match_id: int | None,
+    league_code: str,
+    match_status: str | None,
+    batch_id: str,
+) -> None:
+    """events 成功插入/更新单场比赛后的 Bronze 层补写:RawEvent(幂等) + DataLineage。
+
+    D1(工程债):此前只有 stats 回填写 RawEvent/Lineage,events 管线作为比赛
+    主数据的唯一入口反而不留溯源记录。幂等性由 _write_raw_event 的
+    source_record_id 查重保证;best-effort:基础设施写入失败只记 warning,
+    绝不拖垮采集主流程(与 _safe_write_ingest_failure 同级约束)。
+    """
+    from src.data import bzzoiro as bz
+
+    try:
+        await bz._write_raw_event(db, "bzzoiro", source_record_id, raw_payload, batch_id)
+        await bz._write_lineage(
+            db, "bzzoiro", source_record_id,
+            "matches", target_match_id, "events_ingest",
+            {"league": league_code, "match_status": match_status},
+            batch_id,
+        )
+    except Exception:
+        logger.warning(
+            "events Bronze 写入失败(record=%s, match=%s),不影响采集主流程",
+            source_record_id, target_match_id, exc_info=True,
+        )

src/data/bzzoiro_standings.py

@@ -0,0 +1,215 @@
+"""bzzoiro standings 管线:联赛积分榜快照(/leagues/{id}/standings/)→ standings 表。
+
+从 bzzoiro.py 拆出。同一联赛同一赛季只保留最新快照(按 (league, season, team)
+upsert);球队名与 events 管线使用同一 normalize 规则,保证 Team 匹配。
+
+可替换协作者(抓取函数 / Bronze 写入助手)在运行期经聚合门面
+src.data.bzzoiro 解析 —— 与拆分前的单文件 monkeypatch 语义一致。
+"""
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterable
+from datetime import datetime, timezone
+
+from sqlalchemy import select
+
+from src.data.bzzoiro_common import _to_float_or_none, _to_int_or_none
+from src.data.config import BZZOIRO_LEAGUE_IDS, LEAGUE_COUNTRIES, LEAGUE_NAMES
+from src.data.team_names_zh import zh_name
+from src.db.models import Standing, Team
+from src.db.repositories import LeagueRepository, TeamRepository
+
+logger = logging.getLogger(__name__)
+
+
+async def fetch_bzzoiro_standings(league_code: str, season: str | None = None) -> dict:
+    """抓取联赛积分榜(纯抓取,不入库)。season 为 None 时取当前赛季。"""
+    from src.data import bzzoiro as bz
+
+    league_id = BZZOIRO_LEAGUE_IDS.get(league_code)
+    if league_id is None:
+        raise ValueError(f"未知联赛代码: {league_code}")
+    params: dict = {}
+    if season:
+        params["season"] = season
+    return await bz._fetch_json_async(f"/leagues/{league_id}/standings/", params)
+
+
+def _season_label_from_dates(start_date, end_date) -> str:
+    """从赛季起止日期推导赛季标签(与 derive_season_label 语义一致)。"""
+    try:
+        if isinstance(start_date, str):
+            start = datetime.fromisoformat(start_date[:10])
+        else:
+            start = start_date
+        if start is None:
+            return "?"
+        y = start.year
+        return f"{y}-{y + 1}" if start.month >= 8 else f"{y - 1}-{y}"
+    except (TypeError, ValueError):
+        return "?"
+
+
+async def ingest_bzzoiro_standings(db, *, leagues: Iterable[str], season: str | None = None) -> dict:
+    """采集积分榜 → upsert standings 表。
+
+    season 为 None 时采集当前赛季(bzzoiro 默认返回 is_current 赛季)。
+    球队名与 events 管线使用同一 normalize 规则,保证 Team 匹配。
+    """
+    from src.data import bzzoiro as bz
+    from src.data.team_names import normalize as normalize_name
+
+    result: dict = {"leagues": {}, "total_upserted": 0, "errors": []}
+    for code in leagues:
+        league_r: dict = {"upserted": 0, "teams_created": 0, "rows": 0, "errors": []}
+        try:
+            payload = await bz.fetch_bzzoiro_standings(code, season=season)
+        except Exception as e:
+            logger.exception("bzzoiro standings fetch failed for %s", code)
+            league_r["errors"].append(str(e))
+            await bz._safe_write_ingest_failure(
+                db,
+                entity_type="standings",
+                source_record_id=None,
+                error=e,
+                raw_payload={"league": code, "season": season},
+            )
+            result["leagues"][code] = league_r
+            result["errors"].append(f"{code}: {e}")
+            continue
+
+        rows = payload.get("standings") or []
+        if not rows:
+            result["leagues"][code] = {"error": "无积分榜数据(赛季未开始或未提供)"}
+            result["errors"].append(f"{code}: 无积分榜数据")
+            continue
+
+        # 联赛(get-or-create,D4: 经 LeagueRepository)
+        league = await LeagueRepository(db).get_or_create(
+            code, LEAGUE_NAMES.get(code, code), LEAGUE_COUNTRIES.get(code)
+        )
+        team_r = TeamRepository(db)
+
+        # 赛季标签:优先用返回的 season 对象推导
+        season_obj = payload.get("season") or {}
+        season_label = _season_label_from_dates(
+            season_obj.get("start_date"), season_obj.get("end_date")
+        )
+        if season_label == "?":
+            season_label = season or ""
+
+        # 批量预载球队(与 events 管线使用同一 normalize 规则,保证 Team 匹配)
+        names = {normalize_name(str(r.get("team_name", ""))) for r in rows}
+        names.discard("")
+        team_map: dict[str, Team] = await team_r.get_all_by_names(list(names))
+
+        now = datetime.now(timezone.utc)
+        for r in rows:
+            team_name = normalize_name(str(r.get("team_name", "")))
+            if not team_name:
+                continue
+            team = team_map.get(team_name)
+            if team is None:
+                team = await team_r.get_or_create(team_name, name_zh=zh_name(team_name))
+                team_map[team_name] = team
+                league_r["teams_created"] += 1
+
+            zone = r.get("zone") or {}
+            values = dict(
+                position=_to_int_or_none(r.get("position")) or 0,
+                played=_to_int_or_none(r.get("played")) or 0,
+                won=_to_int_or_none(r.get("won")) or 0,
+                drawn=_to_int_or_none(r.get("drawn")) or 0,
+                lost=_to_int_or_none(r.get("lost")) or 0,
+                goals_for=_to_int_or_none(r.get("gf")) or 0,
+                goals_against=_to_int_or_none(r.get("ga")) or 0,
+                goal_diff=_to_int_or_none(r.get("gd")) or 0,
+                points=_to_int_or_none(r.get("pts")) or 0,
+                xg_for=_to_float_or_none(r.get("xgf")),
+                xg_against=_to_float_or_none(r.get("xga")),
+                form=r.get("form") or None,
+                zone=zone.get("label") or zone.get("key") or None,
+                updated_at=now,
+                retrieved_at=now,
+            )
+
+            # 同一联赛同一赛季只保留最新快照:按 (league, season, team) upsert
+            stmt = select(Standing).where(
+                Standing.league_id == league.id,
+                Standing.season == season_label,
+                Standing.team_id == team.id,
+            )
+            standing = (await db.execute(stmt)).scalar_one_or_none()
+            if standing is None:
+                standing = Standing(
+                    league_id=league.id, season=season_label, team_id=team.id, **values
+                )
+                db.add(standing)
+            else:
+                for k, v in values.items():
+                    setattr(standing, k, v)
+            league_r["upserted"] += 1
+
+        league_r["rows"] = len(rows)
+
+        # D1(对称 events/stats 管线): 联赛成功 upsert → 补写 Bronze 层。
+        # 幂等键 standings:{league}:{season}:积分榜是联赛级快照,一次成功
+        # 采集写一条 RawEvent(整份原始载荷)+ 一条血缘。season 用实际入库的
+        # 标签(由载荷推导,与 Standing.season 同口径),不依赖调用方传参,
+        # 保证不同调用方(season=None 或显式传参)对同一赛季命中同一条 RawEvent。
+        if league_r["upserted"] > 0:
+            bronze_batch_id = f"bzzoiro-standings-{code}-{now:%Y%m%d%H%M%S}"
+            await _write_standings_bronze(
+                db,
+                source_record_id=f"standings:{code}:{season_label}",
+                raw_payload=payload,
+                league_id=league.id,
+                league_code=code,
+                season_label=season_label,
+                rows_upserted=league_r["upserted"],
+                batch_id=bronze_batch_id,
+            )
+
+        result["leagues"][code] = league_r
+        result["total_upserted"] += league_r["upserted"]
+        logger.info(
+            "bzzoiro standings 采集完成: %s 赛季 %s, upsert %d/%d",
+            code, season_label, league_r["upserted"], league_r["rows"],
+        )
+    return result
+
+
+async def _write_standings_bronze(
+    db,
+    *,
+    source_record_id: str,
+    raw_payload: dict,
+    league_id: int | None,
+    league_code: str,
+    season_label: str,
+    rows_upserted: int,
+    batch_id: str,
+) -> None:
+    """standings 成功 upsert 一个联赛后的 Bronze 层补写:RawEvent(幂等) + DataLineage。
+
+    与 _write_events_bronze 同级约束:幂等性由 _write_raw_event 的
+    source_record_id 查重保证(积分榜是联赛级快照,同联赛同赛季重复采集
+    命中同一条 RawEvent);best-effort:基础设施写入失败只记 warning,
+    绝不拖垮采集主流程。
+    """
+    from src.data import bzzoiro as bz
+
+    try:
+        await bz._write_raw_event(db, "bzzoiro", source_record_id, raw_payload, batch_id)
+        await bz._write_lineage(
+            db, "bzzoiro", source_record_id,
+            "standings", league_id, "standings_ingest",
+            {"league": league_code, "season": season_label, "rows_upserted": rows_upserted},
+            batch_id,
+        )
+    except Exception:
+        logger.warning(
+            "standings Bronze 写入失败(record=%s, league=%s),不影响采集主流程",
+            source_record_id, league_code, exc_info=True,
+        )

src/data/bzzoiro_stats.py

@@ -0,0 +1,180 @@
+"""bzzoiro stats 回填管线:已完赛比赛详细统计(/events/{id}/stats/)→ match_stats 表。
+
+从 bzzoiro.py 拆出。上游限速(REQUEST_INTERVAL 秒/请求),大批量回填需分次触发;
+只 add/flush 不 commit,事务由调用方 UnitOfWork 控制。
+
+可替换协作者(_fetch_json_async / Bronze 写入助手 / REQUEST_INTERVAL)在运行期
+经聚合门面 src.data.bzzoiro 解析 —— 与拆分前的单文件 monkeypatch 语义一致。
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Iterable
+from datetime import datetime, timedelta, timezone
+
+from src.data.bzzoiro_common import _to_float_or_none, _to_int_or_none
+from src.data.config import BZZOIRO_LEAGUE_IDS
+from src.db.models import MatchStats
+from src.db.repositories import MatchRepository
+
+logger = logging.getLogger(__name__)
+
+
+# bzzoiro stats 字段 → MatchStats 字段映射(stats.home / stats.away 下)
+_STATS_FIELD_MAP = {
+    "xg": ("home_xg", "away_xg"),                    # 回退 expected_goals
+    "ball_possession": ("home_possession", None),     # 只取主队值,客队=100-home
+    "total_shots": ("home_shots", "away_shots"),
+    "shots_on_target": ("home_shots_on_target", "away_shots_on_target"),
+    "corner_kicks": ("home_corners", "away_corners"),
+    "yellow_cards": ("home_yellow_cards", "away_yellow_cards"),
+    "red_cards": ("home_red_cards", "away_red_cards"),
+    "big_chances": ("home_big_chances", "away_big_chances"),
+    "fouls": ("home_fouls", "away_fouls"),
+}
+
+
+def _pick(d: dict, *keys):
+    """按优先级取第一个非空字段值。"""
+    for k in keys:
+        v = d.get(k)
+        if v is not None:
+            return v
+    return None
+
+
+def _stats_from_payload(payload: dict) -> dict:
+    """把 /events/{id}/stats/ 响应映射成 MatchStats 字段 dict。
+
+    响应结构: {"event_id": ..., "stats": {"home": {...}, "away": {...}}}
+    """
+    stats = (payload or {}).get("stats") or {}
+    home = stats.get("home") or {}
+    away = stats.get("away") or {}
+    out: dict = {}
+
+    xg_h = _pick(home, "xg", "expected_goals")
+    xg_a = _pick(away, "xg", "expected_goals")
+    if xg_h is not None:
+        out["home_xg"] = _to_float_or_none(xg_h)
+    if xg_a is not None:
+        out["away_xg"] = _to_float_or_none(xg_a)
+
+    poss = home.get("ball_possession")
+    if poss is not None:
+        p = _to_float_or_none(poss)
+        if p is not None:
+            out["home_possession"] = p
+
+    for src, (h_fld, a_fld) in _STATS_FIELD_MAP.items():
+        if src in ("xg", "ball_possession"):
+            continue  # 已处理
+        hv = home.get(src)
+        av = away.get(src)
+        if hv is not None and h_fld:
+            out[h_fld] = _to_int_or_none(hv)
+        if av is not None and a_fld:
+            out[a_fld] = _to_int_or_none(av)
+    return out
+
+
+async def ingest_bzzoiro_event_stats(
+    db,
+    *,
+    leagues: Iterable[str],
+    limit: int = 100,
+    only_missing: bool = True,
+) -> dict:
+    """回填已完赛比赛的详细统计(逐场调 /events/{id}/stats/)。
+
+    筛选条件: match_status=finished 且 source_event_id 非空。
+    only_missing=True 时跳过已有统计的比赛(增量);False 则全量刷新。
+    limit 控制单次最多处理的比赛数(上游限速 1.2s/请求,大批量需分次触发)。
+    """
+    from src.data import bzzoiro as bz
+
+    result: dict = {"fetched": 0, "created": 0, "updated": 0, "skipped": 0, "errors": []}
+
+    league_ids = [BZZOIRO_LEAGUE_IDS[c] for c in leagues if c in BZZOIRO_LEAGUE_IDS]
+    if not league_ids:
+        result["errors"].append("无有效联赛代码")
+        return result
+
+    # D4: 候选比赛查询经 MatchRepository(含 stats 预加载,筛选/排序/limit 语义不变)
+    matches = await MatchRepository(db).find_finished_with_stats(
+        league_ids, limit=limit * 3 if only_missing else limit
+    )
+
+    now = datetime.now(timezone.utc)
+    processed = 0
+    for m in matches:
+        if processed >= limit:
+            break
+        if only_missing and m.stats is not None and m.stats.home_shots is not None:
+            result["skipped"] += 1
+            continue
+        processed += 1
+        try:
+            payload = await bz._fetch_json_async(f"/events/{m.source_event_id}/stats/")
+        except Exception as e:
+            logger.warning("stats fetch failed match=%s event=%s: %s", m.id, m.source_event_id, e)
+            result["errors"].append(f"match {m.id}: {e}")
+            await bz._safe_write_ingest_failure(
+                db,
+                entity_type="match_stats",
+                source_record_id=str(m.source_event_id),
+                error=e,
+                raw_payload={"match_id": m.id},
+            )
+            await asyncio.sleep(bz.REQUEST_INTERVAL)
+            continue
+
+        result["fetched"] += 1
+        fields = _stats_from_payload(payload)
+        if not fields:
+            result["skipped"] += 1
+            await asyncio.sleep(bz.REQUEST_INTERVAL)
+            continue
+
+        if m.stats is None:
+            available_at = m.match_date + timedelta(hours=2) if m.match_date else now
+            m.stats = MatchStats(
+                match_id=m.id,
+                source="bzzoiro",
+                source_record_id=str(m.source_event_id),
+                retrieved_at=now,
+                available_at=available_at,
+            )
+            db.add(m.stats)
+            result["created"] += 1
+        else:
+            result["updated"] += 1
+            if m.stats.source is None:
+                m.stats.source = "bzzoiro"
+                m.stats.source_record_id = str(m.source_event_id)
+            if m.stats.retrieved_at is None:
+                m.stats.retrieved_at = now
+            if m.stats.available_at is None and m.match_date:
+                m.stats.available_at = m.match_date + timedelta(hours=2)
+
+        for fld, v in fields.items():
+            if hasattr(m.stats, fld):
+                setattr(m.stats, fld, v)
+
+        # 管线基础设施:写入 RawEvent + DataLineage
+        batch_id = f"bzzoiro-stats-{m.source_event_id}-{now.strftime('%Y%m%d%H%M%S')}"
+        try:
+            await bz._write_raw_event(db, "bzzoiro", str(m.source_event_id), payload, batch_id)
+            await bz._write_lineage(db, "bzzoiro", str(m.source_event_id), "match_stats", m.stats.id if m.stats else None, "stats_backfill", {"match_id": m.id}, batch_id)
+        except Exception:
+            pass  # 基础设施写入失败不影响主流程
+
+        await asyncio.sleep(bz.REQUEST_INTERVAL)
+
+    logger.info(
+        "bzzoiro stats 回填完成: 抓取 %d, 新建 %d, 更新 %d, 跳过 %d, 错误 %d",
+        result["fetched"], result["created"], result["updated"],
+        result["skipped"], len(result["errors"]),
+    )
+    return result

src/data/pipeline_write.py

@@ -0,0 +1,80 @@
+"""管线基础设施写入助手:RawEvent(Bronze 原始载荷)/ IngestFailure(死信)/ DataLineage(血缘)。
+
+从 bzzoiro.py 拆出。约定(与拆分前一致):
+  - 只 add 不 commit —— 事务由调用方 UnitOfWork 控制,分批事务约定不变;
+  - 死信与 Bronze 写入同为 best-effort:失败只记 warning,绝不拖垮采集主流程。
+"""
+from __future__ import annotations
+
+import logging
+
+from src.db.models import DataLineage, IngestFailure, RawEvent
+
+logger = logging.getLogger(__name__)
+
+
+async def _write_raw_event(db, source_system: str, source_record_id: str, raw_payload: dict, batch_id: str | None = None) -> None:
+    """写入 Bronze 层原始事件(幂等:同 source_record_id 跳过)。"""
+    from sqlalchemy import select as _select
+    stmt = _select(RawEvent).where(
+        RawEvent.source_system == source_system,
+        RawEvent.source_record_id == source_record_id,
+    )
+    existing = (await db.execute(stmt)).scalar_one_or_none()
+    if existing is None:
+        db.add(RawEvent(
+            source_system=source_system,
+            source_record_id=source_record_id,
+            raw_payload=raw_payload,
+            ingest_batch_id=batch_id,
+        ))
+
+
+async def _write_ingest_failure(db, source_system: str, entity_type: str, source_record_id: str | None, error_type: str, error_detail: str | None, raw_payload: dict | None = None) -> None:
+    """写入采集失败死信。"""
+    db.add(IngestFailure(
+        source_system=source_system,
+        entity_type=entity_type,
+        source_record_id=source_record_id,
+        error_type=error_type,
+        error_detail=error_detail,
+        raw_payload=raw_payload,
+    ))
+
+
+async def _safe_write_ingest_failure(
+    db,
+    *,
+    entity_type: str,
+    source_record_id: str | None,
+    error: Exception,
+    raw_payload: dict | None = None,
+) -> None:
+    """抓取失败时尽力写入死信表(失败不影响主流程)。
+
+    死信是「可观测性」基础设施,与 RawEvent/Lineage 同级:写入失败只记
+    warning,绝不能让原始抓取错误之外的新异常打断采集循环。
+    """
+    try:
+        await _write_ingest_failure(
+            db, "bzzoiro", entity_type, source_record_id,
+            "fetch_error", str(error), raw_payload,
+        )
+    except Exception:
+        logger.warning(
+            "写入 ingest_failures 死信失败(entity=%s, record=%s): %s",
+            entity_type, source_record_id, error, exc_info=True,
+        )
+
+
+async def _write_lineage(db, source_system: str, source_record_id: str, target_table: str, target_id: int | None, transform_name: str, transform_detail: dict | None = None, batch_id: str | None = None) -> None:
+    """写入 ETL 血缘追踪。"""
+    db.add(DataLineage(
+        source_system=source_system,
+        source_record_id=source_record_id,
+        target_table=target_table,
+        target_id=target_id,
+        transform_name=transform_name,
+        transform_detail=transform_detail,
+        batch_id=batch_id,
+    ))

src/db/repositories.py

@@ -5,6 +5,10 @@ Repository 只负责查询,不负责事务提交。
 """
 from __future__ import annotations
 
+import logging
+
+logger = logging.getLogger(__name__)
+
 from datetime import datetime
 from sqlalchemy import select
 from sqlalchemy.orm import selectinload
@@ -108,10 +112,22 @@ class TeamRepository:
         return (await self._session.execute(stmt)).scalar_one_or_none()
 
     async def get_or_create(self, name: str, *, name_zh: str | None = None) -> Team:
-        """按名获取球队,不存在则创建(name_zh 供 bzzoiro 管线写中文名)。"""
-        team = await self.get_by_name(name)
+        """按名获取球队,不存在则创建(name_zh 供 bzzoiro 管线写中文名)。
+
+        归一化咽喉:所有入库 Team.name 必须经过 team_names.normalize,
+        此处统一收敛,避免各调用点散落归一化逻辑导致重复 Team。
+        创建新 Team 时 info 打出原始名与归一后的规范名,便于排查重名。
+        """
+        from src.data.team_names import normalize as normalize_name
+
+        normalized = normalize_name(name) or name.strip()
+        team = await self.get_by_name(normalized)
         if team is None:
-            team = Team(name=name, name_zh=name_zh)
+            logger.info(
+                "创建新 Team: %s -> %s",
+                name, normalized,
+            )
+            team = Team(name=normalized, name_zh=name_zh)
             self._session.add(team)
             await self._session.flush()
         return team

src/llm/baseline.py

@@ -12,7 +12,7 @@ from sqlalchemy import case, func, select
 
 from src.db.base import AsyncSession, AsyncSessionLocal
 from src.db.models import Match
-from src.llm.predict import PredictResult
+from src.llm.predict import PredictResult, _upsert_prediction
 
 logger = logging.getLogger(__name__)
 
@@ -58,19 +58,23 @@ async def predict_baseline(
 
     返回 PredictResult(D2 统一结果类型):
       provider=model="baseline", 不调用 LLM,latency_ms≈0。
-    prediction_id 为占位 0 —— baseline 不在服务层落库,
-    由路由层 _persist_baseline 落库后取得真实 id。
+
+    P3-2:baseline 落库下沉到服务层 —— 直接在服务层完成落库并回填真实
+    prediction_id,路由层不再需要特殊的 _persist_baseline,与 single/multi
+    路径统一(result.prediction_id 即可用)。对外 JSON 不变。
     """
+    from src.db.unit_of_work import get_uow
+
     async with AsyncSessionLocal() as db:
         match = await db.get(Match, match_id)
         if match is None:
             raise ValueError(f"match {match_id} not found")
 
         before = None
-        if backtest and match.match_dt:
+        if backtest and match.match_date:
             from datetime import timedelta
 
-            before = match.match_dt - timedelta(days=1)
+            before = match.match_date - timedelta(days=1)
         elif cutoff_at is not None:
             before = cutoff_at
 
@@ -93,8 +97,38 @@ async def predict_baseline(
     else:
         pred_1x2 = "X"
 
+    values = {
+        "prompt_version": "baseline_v1",
+        "prompt_tokens": 0,
+        "completion_tokens": 0,
+        "latency_ms": 0,
+        "pred_home_goals": float(pred_home),
+        "pred_away_goals": float(pred_away),
+        "pred_1x2": pred_1x2,
+        "subjective_confidence": 0.5,
+        "reasoning": (
+            f"基线估计(非投注建议): 主队主场场均进球 {home_avg:.2f} → 预测 {pred_home}; "
+            f"客队客场场均进球 {away_avg:.2f} → 预测 {pred_away}。"
+        ),
+        "raw_response": {"home_avg": round(home_avg, 2), "away_avg": round(away_avg, 2)},
+        "status": "success",
+    }
+
+    # P3-2:服务层落库,回填真实 prediction_id(与 single/multi 统一)。
+    async with get_uow() as session:
+        pred = await _upsert_prediction(
+            session,
+            match_id=match_id,
+            provider_name="baseline",
+            model="baseline",
+            mode="baseline",
+            run_type="live",
+            values=values,
+        )
+        prediction_id = pred.id
+
     return PredictResult(
-        prediction_id=0,  # 占位:真实 id 由路由层 _persist_baseline 落库后返回
+        prediction_id=prediction_id,
         provider="baseline",
         model="baseline",
         prompt_version="baseline_v1",
@@ -105,14 +139,11 @@ async def predict_baseline(
         alt_pred_away_goals=None,
         pred_1x2=pred_1x2,
         subjective_confidence=0.5,
-        reasoning=(
-            f"基线估计(非投注建议): 主队主场场均进球 {home_avg:.2f} → 预测 {pred_home}; "
-            f"客队客场场均进球 {away_avg:.2f} → 预测 {pred_away}。"
-        ),
+        reasoning=values["reasoning"],
         context="",  # baseline 不构建 LLM 上下文
         status="success",
         latency_ms=0,
         prompt_tokens=0,
         completion_tokens=0,
-        raw={"home_avg": round(home_avg, 2), "away_avg": round(away_avg, 2)},
+        raw=values["raw_response"],
     )

tests/test_available_at.py

@@ -79,18 +79,18 @@ class TestWriteBufferStrategy:
     def test_bzzoirot_new_match_available_at_is_two_hours_after_kickoff(self):
         """bzzoiro 新建比赛(stats 回填创建 MatchStats)时 available_at 应为开球 + 2 小时。"""
         import inspect
-        from src.data import bzzoiro
+        from src.data import bzzoiro_stats
 
-        source = inspect.getsource(bzzoiro)
+        source = inspect.getsource(bzzoiro_stats)
         assert 'timedelta(hours=2)' in source, \
             "bzzoiro 应使用 match_date + timedelta(hours=2) 作为 available_at"
 
     def test_bzzoirot_multiple_writes_use_two_hour_buffer(self):
         """bzzoiro 多处写入(创建/更新)都应使用 2 小时缓冲。"""
         import inspect
-        from src.data import bzzoiro
+        from src.data import bzzoiro_stats
 
-        source = inspect.getsource(bzzoiro)
+        source = inspect.getsource(bzzoiro_stats)
         count = source.count('timedelta(hours=2)')
         assert count >= 2, f"期望至少 2 处 timedelta(hours=2),实际 {count} 处"
 

tests/test_baseline.py

@@ -5,6 +5,7 @@
 """
 from __future__ import annotations
 
+from types import SimpleNamespace
 from unittest.mock import patch
 
 import pytest
@@ -12,6 +13,24 @@ import pytest
 from src.llm.baseline import _avg_goals, predict_baseline
 
 
+class _FakeUoW:
+    """P3-2:baseline 在服务层落库,测试需 mock get_uow。"""
+
+    async def __aenter__(self):
+        return SimpleNamespace(
+            execute=lambda *a, **k: SimpleNamespace(scalar_one_or_none=lambda: None),
+            add=lambda *a, **k: None,
+            flush=lambda *a, **k: None,
+        )
+
+    async def __aexit__(self, *a):
+        return None
+
+
+async def _fake_upsert(session, **kw):
+    return SimpleNamespace(id=1)
+
+
 @pytest.mark.asyncio
 async def test_avg_goals_no_data_returns_zero():
     """无历史数据时场均进球为 0(不抛异常)。"""
@@ -68,7 +87,9 @@ async def test_predict_baseline_no_llm():
         match_status = "scheduled"
 
     with patch("src.llm.baseline._avg_goals", fake_avg), \
-         patch("src.llm.baseline.AsyncSessionLocal") as SLC:
+         patch("src.llm.baseline.AsyncSessionLocal") as SLC, \
+         patch("src.db.unit_of_work.get_uow", _FakeUoW), \
+         patch("src.llm.baseline._upsert_prediction", _fake_upsert):
         class FakeSession:
             async def get(self, cls, mid):
                 return FakeMatch()
@@ -93,6 +114,8 @@ async def test_predict_baseline_no_llm():
     assert result.pred_1x2 == "X"
     assert result.subjective_confidence == 0.5
     assert "非投注建议" in result.reasoning
+    # P3-2:服务层落库,回填真实 prediction_id
+    assert result.prediction_id == 1
     # 确认未调用任何 LLM 相关模块
     assert "home_10" in captured and "away_20" in captured
 
@@ -112,7 +135,9 @@ async def test_predict_baseline_clamps_to_range():
         match_status = "scheduled"
 
     with patch("src.llm.baseline._avg_goals", fake_avg), \
-         patch("src.llm.baseline.AsyncSessionLocal") as SLC:
+         patch("src.llm.baseline.AsyncSessionLocal") as SLC, \
+         patch("src.db.unit_of_work.get_uow", _FakeUoW), \
+         patch("src.llm.baseline._upsert_prediction", _fake_upsert):
         class FakeSession:
             async def get(self, cls, mid):
                 return FakeMatch()
@@ -128,3 +153,5 @@ async def test_predict_baseline_clamps_to_range():
     assert result.pred_home_goals == 10.0  # clamped
     assert result.pred_away_goals == 0.0   # clamped
     assert result.pred_1x2 == "1"         # 10:0 主胜
+    # P3-2:服务层落库,回填真实 prediction_id
+    assert result.prediction_id == 1

tests/test_d2_predict_unification.py

@@ -62,12 +62,35 @@ async def test_predict_baseline_returns_predict_result():
         async def __aexit__(self, *a):
             return None
 
+    # P3-2:baseline 在服务层落库(get_uow + _upsert_prediction),需 mock 掉。
+    class FakeUoW:
+        async def __aenter__(self):
+            return _make_session()
+
+        async def __aexit__(self, *a):
+            return None
+
+    captured = {}
+
+    async def fake_upsert(session, **kw):
+        captured.update(kw)
+        return SimpleNamespace(id=77)
+
+    # baseline.py 内部 from-import get_uow / _upsert_prediction,需 patch 真实来源模块。
     with patch("src.llm.baseline._avg_goals", fake_avg), \
-         patch("src.llm.baseline.AsyncSessionLocal") as SLC:
+         patch("src.llm.baseline.AsyncSessionLocal") as SLC, \
+         patch("src.db.unit_of_work.get_uow", FakeUoW), \
+         patch("src.llm.baseline._upsert_prediction", fake_upsert):
         SLC.return_value = FakeCM()
 
         result = await predict_baseline(1)
 
+    # P3-2:验证服务层落库被调用且属性映射正确
+    assert captured["match_id"] == 1
+    assert captured["provider_name"] == "baseline"
+    assert captured["run_type"] == "live"
+    assert captured["values"]["pred_home_goals"] == 2.0
+
     assert isinstance(result, PredictResult)
     assert result.mode == "baseline"
     assert result.provider == "baseline"
@@ -144,15 +167,31 @@ def test_predict_route_has_no_dict_branch():
 
 
 # ============================================================
-# 4. _persist_baseline 属性映射(baseline 落库语义不变)
+# 4. P3-2:baseline 服务层落库属性映射(落库已从路由移到 baseline.py)
 # ============================================================
 
 
+class _FakeResult:
+    """支持 .scalar_one_or_none() 的最小假结果集。"""
+
+    def __init__(self, items):
+        self._items = list(items)
+
+    def scalars(self):
+        return self
+
+    def all(self):
+        return self._items
+
+    def scalar_one_or_none(self):
+        return self._items[0] if self._items else None
+
+
 class _FakeUoW:
-    """替代 get_uow 的最小上下文管理器。"""
+    """替代 get_uow 的最小上下文管理器(session.execute 是 async 的)。"""
 
     def __init__(self):
-        self.session = SimpleNamespace()
+        self.session = _make_session()
 
     async def __aenter__(self):
         return self.session
@@ -160,44 +199,67 @@ class _FakeUoW:
     async def __aexit__(self, *a):
         return None
 
+    def __call__(self):
+        return self
+
+
+def _make_session(existing=None):
+    """构造带 async execute / add / flush 的假 session。"""
+    sess = SimpleNamespace()
+
+    async def execute(*a, **k):
+        return _FakeResult(existing or [])
+
+    sess.execute = execute
+    sess.add = lambda *a, **k: None
+
+    async def flush(*a, **k):
+        return None
+
+    sess.flush = flush
+    return sess
+
 
 @pytest.mark.asyncio
-async def test_persist_baseline_maps_attributes(monkeypatch):
+async def test_baseline_service_persists_with_correct_attributes(monkeypatch):
+    """P3-2:baseline 在服务层(predict_baseline)落库,属性映射与路由旧版一致。"""
     captured = {}
 
     async def fake_upsert(session, **kwargs):
         captured.update(kwargs)
         return SimpleNamespace(id=77)
 
+    class FakeMatch:
+        id = 1
+        home_team_id = 10
+        away_team_id = 20
+        league_id = 1
+        match_status = "scheduled"
+
+    class FakeSession:
+        async def get(self, cls, mid):
+            return FakeMatch()
+
+    class FakeSLC:
+        async def __aenter__(self):
+            return FakeSession()
+
+        async def __aexit__(self, *a):
+            return None
+
+    async def fake_avg(db, *, team_id, side, league_id, before):
+        return 2.0 if side == "home" else 1.0
+
+    monkeypatch.setattr("src.llm.baseline._avg_goals", fake_avg)
+    monkeypatch.setattr("src.llm.baseline.AsyncSessionLocal", FakeSLC)
     monkeypatch.setattr("src.db.unit_of_work.get_uow", lambda: _FakeUoW())
-    monkeypatch.setattr("src.llm.predict._upsert_prediction", fake_upsert)
+    # baseline.py 模块级 import _upsert_prediction(第 15 行),需 patch baseline 模块属性
+    monkeypatch.setattr("src.llm.baseline._upsert_prediction", fake_upsert)
 
-    from src.api.routes.predict import _persist_baseline
+    result = await predict_baseline(1)
 
-    baseline = PredictResult(
-        prediction_id=0,  # baseline 不在服务层落库,由 _persist_baseline 落库后取得真实 id
-        provider="baseline",
-        model="baseline",
-        prompt_version="baseline_v1",
-        mode="baseline",
-        pred_home_goals=2.0,
-        pred_away_goals=1.0,
-        alt_pred_home_goals=None,
-        alt_pred_away_goals=None,
-        pred_1x2="1",
-        subjective_confidence=0.5,
-        reasoning="r",
-        context="",
-        status="success",
-        latency_ms=0,
-        prompt_tokens=0,
-        completion_tokens=0,
-        raw={"home_avg": 2.1, "away_avg": 1.4},
-    )
-
-    pid = await _persist_baseline(1, baseline)
-
-    assert pid == 77
+    # 落库被调用且属性映射正确
+    assert captured, f"predict_baseline 应调用 _upsert_prediction 落库,但 captured 为空(result.prediction_id={result.prediction_id!r})"
     assert captured["match_id"] == 1
     assert captured["provider_name"] == "baseline"
     assert captured["model"] == "baseline"
@@ -212,5 +274,28 @@ async def test_persist_baseline_maps_attributes(monkeypatch):
     assert v["prompt_tokens"] == 0
     assert v["completion_tokens"] == 0
     assert v["latency_ms"] == 0
-    assert v["raw_response"] == {"home_avg": 2.1, "away_avg": 1.4}
+    assert v["raw_response"] == {"home_avg": 2.0, "away_avg": 1.0}
     assert v["status"] == "success"
+
+    # 回填真实 prediction_id(服务层落库后取得)
+    assert result.prediction_id == 77
+    assert result.pred_1x2 == "1"
+    assert captured["match_id"] == 1
+    assert captured["provider_name"] == "baseline"
+    assert captured["model"] == "baseline"
+    assert captured["mode"] == "baseline"
+    assert captured["run_type"] == "live"
+    v = captured["values"]
+    assert v["prompt_version"] == "baseline_v1"
+    assert v["pred_home_goals"] == 2.0
+    assert v["pred_away_goals"] == 1.0
+    assert v["pred_1x2"] == "1"
+    assert v["subjective_confidence"] == 0.5
+    assert v["prompt_tokens"] == 0
+    assert v["completion_tokens"] == 0
+    assert v["latency_ms"] == 0
+    assert v["raw_response"] == {"home_avg": 2.0, "away_avg": 1.0}
+    assert v["status"] == "success"
+
+    # 回填真实 prediction_id(服务层落库后取得)
+    assert result.prediction_id == 77

tests/test_regressions.py

@@ -175,7 +175,7 @@ class TestBzzoiroLineage:
         return bad
 
     def test_normalized_matches_carries_raw(self):
-        src = _read("data/bzzoiro.py")
+        src = _read("data/bzzoiro_events.py")
         # 规范化结果必须与原始 event 成对保存
         assert "normalized_matches.append((nm, raw))" in src, (
             "normalized_matches 未携带 (nm, raw) 元组 —— raw 变量泄漏会回归 (P0-3)"
@@ -193,7 +193,7 @@ class TestBzzoiroLineage:
         它不是 `raw.get(` 同一行,但同样正确。非法写法(回归)是直接
         `existing_match.source_event_id = orphan_var`。
         """
-        src = _read("data/bzzoiro.py")
+        src = _read("data/bzzoiro_events.py")
         seg = self._consume_loop_body(src)
         bad = self._bad_assignments(seg)
         assert len(bad) == 0, (
@@ -206,7 +206,7 @@ class TestBzzoiroLineage:
         下游 `_backfill_stats` 里合法地在 ORM 对象上访问 `m.source_event_id`
         (与配对 raw 无关)。若 seg 越界,test_no_orphan_raw_use 会误报。
         """
-        src = _read("data/bzzoiro.py")
+        src = _read("data/bzzoiro_events.py")
         seg = self._consume_loop_body(src)
         assert "m.source_event_id" not in seg, (
             "循环体截取越界,扫到了下游 stats 管线 —— 会误报 P0-3"

tests/test_review_required_fixes.py

@@ -125,7 +125,7 @@ class _FakeDb:
 async def test_r2_standings_actually_upserts(monkeypatch):
     """行为测试: 喂一份积分榜 payload,断言真的构造了 Standing 且计数 > 0。"""
     import src.data.bzzoiro as bz
-    from src.db.models import League, Standing, Team
+    from src.db.models import DataLineage, League, RawEvent, Standing, Team
 
     payload = {
         "season": {"start_date": "2025-08-01", "end_date": "2026-05-31"},
@@ -166,7 +166,10 @@ async def test_r2_standings_actually_upserts(monkeypatch):
 
     standings = [o for o in db.added if isinstance(o, Standing)]
     assert len(standings) == 2, "应真的构造 Standing 行"
-    assert all(isinstance(o, (Standing, Team)) for o in db.added)
+    # standings 采集接线 Bronze 后(RawEvent + DataLineage),add 的对象类型白名单随之放宽
+    assert all(
+        isinstance(o, (Standing, Team, RawEvent, DataLineage)) for o in db.added
+    )
 
     first = standings[0]
     assert first.league_id == 42

tests/test_standings_bronze.py

@@ -0,0 +1,288 @@
+"""standings 成功路径 Bronze 层回归测试(RawEvent + DataLineage)。
+
+背景: events/stats 管线成功后均已补写 Bronze 层,唯独 standings 采集
+成功后既不留原始载荷,也不留血缘 —— 三条管线的溯源链条在积分榜一环
+缺失。本测试守护(与 test_events_bronze.py 对称):
+  1. 联赛成功 upsert → RawEvent(幂等键=standings:{league}:{season})
+     + Lineage(target_table="standings", transform_name="standings_ingest")
+  2. 更新已有快照(非插入)同样写 Bronze —— 积分榜是快照,刷新即采集
+  3. RawEvent 幂等: 同 source_record_id 已存在则跳过,血缘照写
+  4. 基础设施写入失败 → 只 warning,不拖垮采集主流程
+  5. 抓取失败路径继续走 _safe_write_ingest_failure,且不写 Bronze
+
+范式: 假 db(按查询实体分发预置数据 + 记录 add,flush 分配自增 id)
++ monkeypatch 抓取函数,不依赖真实数据库。
+"""
+from __future__ import annotations
+
+import pytest
+
+import src.data.bzzoiro as bz
+from src.db.models import DataLineage, IngestFailure, League, RawEvent, Standing, Team
+
+
+def _payload():
+    """构造一份最小合法的 bzzoiro /leagues/{id}/standings/ 原始载荷。"""
+    return {
+        "season": {"start_date": "2025-08-01", "end_date": "2026-05-31"},
+        "standings": [
+            {
+                "position": 1, "team_name": "Arsenal FC",
+                "played": 10, "won": 8, "drawn": 1, "lost": 1,
+                "gf": 22, "ga": 8, "gd": 14, "pts": 25,
+                "zone": {"key": "champions_league", "label": "Champions League"},
+            },
+            {
+                "position": 2, "team_name": "Chelsea FC",
+                "played": 10, "won": 6, "drawn": 2, "lost": 2,
+                "gf": 18, "ga": 12, "gd": 6, "pts": 20,
+            },
+        ],
+    }
+
+
+def _patch_fetch(monkeypatch, payload):
+    async def _fetch(league_code, season=None):
+        return payload
+
+    monkeypatch.setattr(bz, "fetch_bzzoiro_standings", _fetch)
+
+
+class _FakeResult:
+    """支持 .scalars().all() / .scalar_one_or_none() 的最小假结果集。"""
+
+    def __init__(self, items):
+        self._items = list(items)
+
+    def scalars(self):
+        return self
+
+    def __iter__(self):
+        return iter(self._items)
+
+    def all(self):
+        return self._items
+
+    def scalar_one_or_none(self):
+        return self._items[0] if self._items else None
+
+
+class _FakeDB:
+    """按查询实体分发预置数据;记录 add();flush 为无 id 对象分配自增主键。"""
+
+    def __init__(self, leagues=(), teams=(), standings=(), raw_events=()):
+        self.added = []
+        self._by_entity = {
+            League: list(leagues),
+            Team: list(teams),
+            Standing: list(standings),
+            RawEvent: list(raw_events),
+        }
+        self._next_id = 0
+
+    def add(self, obj):
+        self.added.append(obj)
+
+    async def execute(self, stmt):
+        entities = set()
+        for d in (stmt.column_descriptions or []):
+            entities.add(d.get("entity") or d.get("type"))
+        for entity, items in self._by_entity.items():
+            if entity in entities:
+                return _FakeResult(self._filter(entity, items, stmt))
+        return _FakeResult([])
+
+    @staticmethod
+    def _filter(entity, items, stmt):
+        """RawEvent 查询按 source_record_id 过滤 —— 幂等测试需区分不同键。"""
+        if entity is RawEvent:
+            try:
+                params = stmt.compile().params
+            except Exception:
+                return items
+            rid = next((v for k, v in params.items() if "source_record_id" in k), None)
+            if rid is not None:
+                return [i for i in items if i.source_record_id == rid]
+        return items
+
+    async def flush(self):
+        for obj in self.added:
+            if getattr(obj, "id", None) is None:
+                self._next_id += 1
+                obj.id = self._next_id
+
+
+def _preset_league():
+    lg = League(code="EPL", name="Premier League", country="England")
+    lg.id = 42
+    return lg
+
+
+def _raw_events(db):
+    return [o for o in db.added if isinstance(o, RawEvent)]
+
+
+def _lineages(db):
+    return [o for o in db.added if isinstance(o, DataLineage)]
+
+
+# ============================================================
+# 1. 成功 upsert → RawEvent + DataLineage
+# ============================================================
+
+
+class TestStandingsBronzeOnUpsert:
+    async def test_upsert_writes_raw_event_and_lineage(self, monkeypatch):
+        _patch_fetch(monkeypatch, _payload())
+        db = _FakeDB(leagues=[_preset_league()])
+
+        result = await bz.ingest_bzzoiro_standings(db, leagues=["EPL"])
+
+        assert result["errors"] == []
+        assert result["total_upserted"] == 2
+
+        raws = _raw_events(db)
+        assert len(raws) == 1
+        raw = raws[0]
+        assert raw.source_system == "bzzoiro"
+        # 幂等键: 联赛 + 实际入库的赛季标签(由载荷日期推导,与 Standing.season 同口径)
+        assert raw.source_record_id == "standings:EPL:2025-2026"
+        assert raw.ingest_batch_id.startswith("bzzoiro-standings-EPL-")
+        # 整份原始载荷完整保留
+        assert raw.raw_payload["standings"][0]["team_name"] == "Arsenal FC"
+
+        lineages = _lineages(db)
+        assert len(lineages) == 1
+        lin = lineages[0]
+        assert lin.source_system == "bzzoiro"
+        assert lin.source_record_id == "standings:EPL:2025-2026"
+        assert lin.target_table == "standings"
+        assert lin.target_id == 42  # 联赛 id
+        assert lin.transform_name == "standings_ingest"
+        assert lin.transform_detail == {
+            "league": "EPL", "season": "2025-2026", "rows_upserted": 2,
+        }
+        # RawEvent 与 Lineage 同批次,便于按批追溯
+        assert lin.batch_id == raw.ingest_batch_id
+
+    async def test_updated_snapshot_also_writes_bronze(self, monkeypatch):
+        """已有快照就地更新(非插入)同样是成功采集,必须留 Bronze 记录。"""
+        payload = _payload()
+        payload["standings"] = payload["standings"][:1]  # 单队,便于命中同一行
+        _patch_fetch(monkeypatch, payload)
+
+        team = Team(name="Arsenal FC", name_zh="阿森纳")
+        team.id = 7
+        existing = Standing(league_id=42, season="2025-2026", team_id=7, position=9)
+        existing.points = 1
+        db = _FakeDB(leagues=[_preset_league()], teams=[team], standings=[existing])
+
+        result = await bz.ingest_bzzoiro_standings(db, leagues=["EPL"])
+
+        assert result["total_upserted"] == 1
+        assert result["leagues"]["EPL"]["teams_created"] == 0
+        # 快照刷新也要留痕: RawEvent(幂等) + 血缘
+        assert len(_raw_events(db)) == 1
+        lineages = _lineages(db)
+        assert len(lineages) == 1
+        assert lineages[0].transform_name == "standings_ingest"
+        assert lineages[0].transform_detail["rows_upserted"] == 1
+
+    async def test_empty_upsert_writes_no_bronze(self, monkeypatch):
+        """载荷有行但全部队名为空 → 没有任何 upsert,不应产生 RawEvent/Lineage。"""
+        payload = {"standings": [{"position": 1, "team_name": ""}]}
+        _patch_fetch(monkeypatch, payload)
+        db = _FakeDB(leagues=[_preset_league()])
+
+        result = await bz.ingest_bzzoiro_standings(db, leagues=["EPL"])
+
+        assert result["total_upserted"] == 0
+        assert _raw_events(db) == []
+        assert _lineages(db) == []
+
+
+# ============================================================
+# 2. RawEvent 幂等: 同 source_record_id 跳过
+# ============================================================
+
+
+class TestStandingsRawEventIdempotent:
+    async def test_existing_raw_event_is_skipped(self, monkeypatch):
+        existing = RawEvent(
+            source_system="bzzoiro",
+            source_record_id="standings:EPL:2025-2026",
+            raw_payload={"old": True},
+        )
+        _patch_fetch(monkeypatch, _payload())
+        db = _FakeDB(leagues=[_preset_league()], raw_events=[existing])
+
+        await bz.ingest_bzzoiro_standings(db, leagues=["EPL"])
+
+        new_raws = [r for r in _raw_events(db) if r is not existing]
+        assert new_raws == []
+        assert len(_lineages(db)) == 1  # 血缘仍然记录本次采集
+
+    async def test_different_season_writes_new_raw_event(self, monkeypatch):
+        """幂等键含赛季: 同联赛不同赛季各留一条 RawEvent。"""
+        payload = _payload()
+        payload["season"] = {"start_date": "2024-08-01", "end_date": "2025-05-31"}
+        existing = RawEvent(
+            source_system="bzzoiro",
+            source_record_id="standings:EPL:2025-2026",
+            raw_payload={"old": True},
+        )
+        _patch_fetch(monkeypatch, payload)
+        db = _FakeDB(leagues=[_preset_league()], raw_events=[existing])
+
+        await bz.ingest_bzzoiro_standings(db, leagues=["EPL"])
+
+        new_raws = [r for r in _raw_events(db) if r is not existing]
+        assert len(new_raws) == 1
+        assert new_raws[0].source_record_id == "standings:EPL:2024-2025"
+
+
+# ============================================================
+# 3. 基础设施写入失败: 尽力而为,不拖垮主流程
+# ============================================================
+
+
+class TestStandingsBronzeIsBestEffort:
+    async def test_bronze_write_failure_does_not_break_ingest(self, monkeypatch):
+        async def _boom(*args, **kwargs):
+            raise RuntimeError("infra down")
+
+        monkeypatch.setattr(bz, "_write_raw_event", _boom)
+        monkeypatch.setattr(bz, "_write_lineage", _boom)
+        _patch_fetch(monkeypatch, _payload())
+        db = _FakeDB(leagues=[_preset_league()])
+
+        # 不应抛异常:Bronze 写不进去只记 warning
+        result = await bz.ingest_bzzoiro_standings(db, leagues=["EPL"])
+
+        assert result["total_upserted"] == 2
+        assert [o for o in db.added if isinstance(o, Standing)]
+
+
+# ============================================================
+# 4. 抓取失败: 继续写死信,且不写 Bronze
+# ============================================================
+
+
+class TestStandingsFailurePathKeepsDeadLetter:
+    async def test_fetch_failure_writes_deadletter_and_no_bronze(self, monkeypatch):
+        async def _boom(league_code, season=None):
+            raise RuntimeError("upstream 500")
+
+        monkeypatch.setattr(bz, "fetch_bzzoiro_standings", _boom)
+        db = _FakeDB()
+
+        result = await bz.ingest_bzzoiro_standings(db, leagues=["SP1"], season="2025-2026")
+
+        assert result["errors"]
+        failures = [o for o in db.added if isinstance(o, IngestFailure)]
+        assert len(failures) == 1
+        assert failures[0].entity_type == "standings"
+        assert failures[0].error_type == "fetch_error"
+        # 失败路径绝不写 Bronze(没有任何成功 upsert)
+        assert _raw_events(db) == []
+        assert _lineages(db) == []