"""Signal Repository Protocol（M8.1 落库）。"""

from __future__ import annotations

from datetime import date
from typing import Protocol

from app.domain.entities.signal import SignalHit, SignalMeta, SignalResult


class SignalRepository(Protocol):
    def save(self, signal_id: str, result: SignalResult) -> None:
        """snapshot 一行 + 事件逐行（同事务，调用方 commit）。"""

    def get(self, signal_id: str) -> SignalResult | None: ...

    def list_recent(
        self, as_of: date | None = None, limit: int = 20
    ) -> list[SignalMeta]: ...

    def list_by_symbol(self, symbol: str, limit: int = 50) -> list[SignalHit]:
        """该股在历史信号中的命中（Chart 标记用，含 signal_id 溯源）。"""