refactor: Sprint 3 - 引入 UnitOfWork + Repository 架构

新增: - src/db/unit_of_work.py: UnitOfWork 事务封装 - src/db/repositories.py: Match/Team/League/Prediction Repository 重构: - 删除 src/data/match_lookup.py(由 Repository 替代) - 数据源(bzzoiro/understat/injuries)不再自行 commit - API 路由(ingest)改用 UnitOfWork - LLM 服务(predict/orchestrator/eval/backtest)改用 UnitOfWork 事务边界统一由调用方控制,数据层不再自行决定 commit。
2026-09-15 00:42:05 +08:00
parent cb36dc3ef9
commit 483cb956ba
11 changed files with 281 additions and 117 deletions
@@ -0,0 +1,126 @@
+"""Repository 层:封装数据访问。
+
+Repository 只负责查询,不负责事务提交。
+事务由 Application Service 通过 UnitOfWork 控制。
+"""
+from __future__ import annotations
+
+from sqlalchemy import select
+from sqlalchemy.orm import selectinload
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.db.models import League, Match, Prediction, Team
+
+
+class MatchRepository:
+    """比赛数据访问。"""
+
+    def __init__(self, session: AsyncSession) -> None:
+        self._session = session
+
+    async def get_by_id(self, match_id: int) -> Match | None:
+        return await self._session.get(Match, match_id)
+
+    async def get_with_relations(self, match_id: int) -> Match | None:
+        stmt = (
+            select(Match)
+            .options(
+                selectinload(Match.league),
+                selectinload(Match.home_team),
+                selectinload(Match.away_team),
+                selectinload(Match.stats),
+            )
+            .where(Match.id == match_id)
+        )
+        return (await self._session.execute(stmt)).scalar_one_or_none()
+
+    async def find_by_teams_and_date(
+        self, league_id: int, home_team_id: int, away_team_id: int, date
+    ) -> Match | None:
+        """按联赛+主队+客队+日期查找比赛(天级匹配)。"""
+        from sqlalchemy import func
+
+        if hasattr(date, "date"):
+            date = date.date()
+
+        stmt = (
+            select(Match)
+            .where(Match.league_id == league_id)
+            .where(Match.home_team_id == home_team_id)
+            .where(Match.away_team_id == away_team_id)
+            .where(func.date(Match.match_date) == date)
+        )
+        return (await self._session.execute(stmt)).scalar_one_or_none()
+
+    async def add(self, match: Match) -> None:
+        self._session.add(match)
+        await self._session.flush()
+
+
+class TeamRepository:
+    """球队数据访问。"""
+
+    def __init__(self, session: AsyncSession) -> None:
+        self._session = session
+
+    async def get_by_name(self, name: str) -> Team | None:
+        stmt = select(Team).where(Team.name == name)
+        return (await self._session.execute(stmt)).scalar_one_or_none()
+
+    async def get_or_create(self, name: str) -> Team:
+        """按名获取球队,不存在则创建。"""
+        team = await self.get_by_name(name)
+        if team is None:
+            team = Team(name=name)
+            self._session.add(team)
+            await self._session.flush()
+        return team
+
+    async def get_all_by_names(self, names: list[str]) -> dict[str, Team]:
+        """批量获取球队,返回 name → Team 映射。"""
+        if not names:
+            return {}
+        stmt = select(Team).where(Team.name.in_(names))
+        teams = (await self._session.execute(stmt)).scalars().all()
+        return {t.name: t for t in teams}
+
+    async def add(self, team: Team) -> None:
+        self._session.add(team)
+        await self._session.flush()
+
+
+class LeagueRepository:
+    """联赛数据访问。"""
+
+    def __init__(self, session: AsyncSession) -> None:
+        self._session = session
+
+    async def get_by_code(self, code: str) -> League | None:
+        stmt = select(League).where(League.code == code)
+        return (await self._session.execute(stmt)).scalar_one_or_none()
+
+    async def get_or_create(self, code: str, name: str, country: str | None = None) -> League:
+        league = await self.get_by_code(code)
+        if league is None:
+            league = League(code=code, name=name, country=country)
+            self._session.add(league)
+            await self._session.flush()
+        return league
+
+    async def add(self, league: League) -> None:
+        self._session.add(league)
+        await self._session.flush()
+
+
+class PredictionRepository:
+    """预测记录数据访问。"""
+
+    def __init__(self, session: AsyncSession) -> None:
+        self._session = session
+
+    async def get_by_id(self, prediction_id: int) -> Prediction | None:
+        return await self._session.get(Prediction, prediction_id)
+
+    async def add(self, prediction: Prediction) -> None:
+        self._session.add(prediction)
+        await self._session.flush()
@@ -0,0 +1,63 @@
+"""工作单元(Unit of Work):统一事务边界。
+
+使用方式:
+    async with UnitOfWork(db) as uow:
+        await uow.matches.get_by_id(1)
+        await uow.matches.add(new_match)
+        # 退出时自动 commit,异常时 rollback
+"""
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import AsyncGenerator
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.db.base import AsyncSessionLocal
+
+
+class UnitOfWork:
+    """工作单元:封装事务边界。"""
+
+    def __init__(self, session: AsyncSession) -> None:
+        self._session = session
+        self.committed = False
+
+    @property
+    def session(self) -> AsyncSession:
+        return self._session
+
+    async def commit(self) -> None:
+        await self._session.commit()
+        self.committed = True
+
+    async def rollback(self) -> None:
+        await self._session.rollback()
+
+    async def close(self) -> None:
+        await self._session.close()
+
+    async def __aenter__(self) -> "UnitOfWork":
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        if exc_type is not None:
+            await self.rollback()
+        await self.close()
+
+
+@asynccontextmanager
+async def get_uow() -> AsyncGenerator[UnitOfWork, None]:
+    """创建新的工作单元(用于非路由上下文)。"""
+    session = AsyncSessionLocal()
+    uow = UnitOfWork(session)
+    try:
+        yield uow
+        if not uow.committed:
+            await uow.commit()
+    except Exception:
+        await uow.rollback()
+        raise
+    finally:
+        await uow.close()