"""选股 Repository Protocol（M6.3 落库）。

业务层只依赖本 Protocol；实现位于 infrastructure/persistence。
结果按 v2 §8：selection_snapshot（一次运行的查询与统计）+ selection_result（逐候选行），
用于回答「2023-08-15 为什么选这只股票」「某日选了什么」。
"""

from __future__ import annotations

from datetime import date
from typing import Protocol

from app.domain.entities.chart import SelectionHit
from app.domain.entities.selection import SelectionMeta, SelectionResult


class SelectionRepository(Protocol):
    def save(self, selection_id: str, result: SelectionResult) -> None:
        """落库一次选股：snapshot 一行 + 候选逐行（同一事务，由调用方 commit）。"""

    def get(self, selection_id: str) -> SelectionResult | None:
        """按 id 读回完整结果（重建 SelectionResult）。"""

    def list_recent(
        self,
        as_of: date | None = None,
        method: str | None = None,
        limit: int = 20,
    ) -> list[SelectionMeta]:
        """历史选股元数据列表（按 created_at 倒序；可选 as_of/method 过滤）。"""

    def list_by_symbol(self, symbol: str, limit: int = 50) -> list[SelectionHit]:
        """该股在历史选股中的命中（Chart 标记用，含 as_of/rank/reason）。"""