feat(selection): 支持选股结果服务端分页

zhixing-server/src/zhixing_server/modules/selection/application/run.py

@@ -11,6 +11,7 @@ from ..domain.models import SelectionEvaluation
 from ..domain.runs import (
     SelectionExecutionSource,
     SelectionRerunRequired,
+    SelectionResultQuery,
     SelectionRun,
     SelectionRunInProgress,
     SelectionRunItem,
@@ -135,19 +136,26 @@ class RunZhixingB1:
             except Exception:  # noqa: BLE001 - preserve the original worker failure
                 logger.exception("selection_run_failure_persist_failed run_id=%s", prepared.run.id)
 
-    def get_run(self, run_id: str) -> SelectionRun | None:
+    def get_run(
+        self,
+        run_id: str,
+        *,
+        query: SelectionResultQuery | None = None,
+    ) -> SelectionRun | None:
         """Read one persisted run for polling."""
 
-        return self.store.get_run(run_id)
+        return self.store.get_run(run_id, query=query)
 
     def get_latest(
         self,
         strategy: StrategyName,
         target_trade_date: date | None = None,
+        *,
+        query: SelectionResultQuery | None = None,
     ) -> SelectionRun | None:
         """Read the current result by date or the latest result for a strategy."""
 
-        return self.store.get_latest_run(strategy, target_trade_date)
+        return self.store.get_latest_run(strategy, target_trade_date, query=query)
 
 
 def _to_item(ts_code: str, name: str, evaluation: SelectionEvaluation) -> SelectionRunItem:

zhixing-server/src/zhixing_server/modules/selection/domain/runs.py

@@ -11,6 +11,17 @@ from .models import SelectionEvaluationStatus, SelectionSignal, StockHistory
 
 SelectionRunStatus = Literal["running", "success", "partial_success", "failed"]
 SelectionRunItemStatus = SelectionEvaluationStatus
+SelectionSignalCategoryFilter = Literal["pullback", "oversold", "original"]
+
+
+@dataclass(frozen=True, slots=True)
+class SelectionResultQuery:
+    """Validated query options for a paged selection-result read."""
+
+    page: int = 1
+    page_size: int = 10
+    search: str | None = None
+    category: SelectionSignalCategoryFilter | None = None
 
 
 @dataclass(frozen=True, slots=True)
@@ -67,6 +78,7 @@ class SelectionRun:
     finished_at: datetime | None = None
     items: tuple[SelectionRunItem, ...] = field(default_factory=tuple)
     signals: tuple[SelectionSignal, ...] = field(default_factory=tuple)
+    signals_total: int | None = None
 
 
 class SelectionRunError(RuntimeError):
@@ -112,12 +124,19 @@ class SelectionRunStore(Protocol):
         error_message: str | None = None,
     ) -> None: ...
 
-    def get_run(self, run_id: str) -> SelectionRun | None: ...
+    def get_run(
+        self,
+        run_id: str,
+        *,
+        query: SelectionResultQuery | None = None,
+    ) -> SelectionRun | None: ...
 
     def get_latest_run(
         self,
         strategy: Literal["zhixing_b1"],
         target_trade_date: date | None = None,
+        *,
+        query: SelectionResultQuery | None = None,
     ) -> SelectionRun | None: ...
 
 

zhixing-server/src/zhixing_server/modules/selection/infrastructure/postgres_runs.py

@@ -18,6 +18,7 @@ from ..domain.models import SelectionSignal, ZhixingB1Category
 from ..domain.runs import (
     SelectionExecutionSource,
     SelectionRerunRequired,
+    SelectionResultQuery,
     SelectionRun,
     SelectionRunError,
     SelectionRunInProgress,
@@ -29,6 +30,19 @@ from ..domain.runs import (
 from ..domain.zhixing_b1 import ZHIXING_B1_SIGNAL_ORDER
 
 _SIGNAL_PRIORITY = {category: index for index, category in enumerate(ZHIXING_B1_SIGNAL_ORDER)}
+_CATEGORY_PREFIXES = {
+    "pullback": "zhixing_b1_pullback_",
+    "oversold": "zhixing_b1_oversold_",
+    "original": "zhixing_b1_original_b1",
+}
+_SIGNAL_ORDER_SQL = (
+    "CASE category "
+    + " ".join(
+        f"WHEN '{category.value}' THEN {index}"
+        for index, category in enumerate(ZHIXING_B1_SIGNAL_ORDER)
+    )
+    + f" ELSE {len(ZHIXING_B1_SIGNAL_ORDER)} END"
+)
 
 
 class PostgresSelectionRunRepository(SelectionRunStore):
@@ -224,12 +238,17 @@ class PostgresSelectionRunRepository(SelectionRunStore):
         except psycopg.Error as exc:
             raise SelectionRunStoreError(f"failed to finish selection run {run_id}") from exc
 
-    def get_run(self, run_id: str) -> SelectionRun | None:
-        """Read one run with its item failures and signal details."""
+    def get_run(
+        self,
+        run_id: str,
+        *,
+        query: SelectionResultQuery | None = None,
+    ) -> SelectionRun | None:
+        """Read one run with filtered, paged signals and item failures."""
 
         try:
             with self._connection() as connection:
-                return self._load_run(connection, run_id)
+                return self._load_run(connection, run_id, query or SelectionResultQuery())
         except psycopg.Error as exc:
             raise SelectionRunStoreError(f"failed to load selection run {run_id}") from exc
 
@@ -237,6 +256,8 @@ class PostgresSelectionRunRepository(SelectionRunStore):
         self,
         strategy: Literal["zhixing_b1"],
         target_trade_date: date | None = None,
+        *,
+        query: SelectionResultQuery | None = None,
     ) -> SelectionRun | None:
         """Read the current run for a date or the latest date for a strategy."""
 
@@ -263,12 +284,20 @@ class PostgresSelectionRunRepository(SelectionRunStore):
                         """,
                         (strategy, target_trade_date),
                     ).fetchone()
-                return self._load_run(connection, str(row[0])) if row else None
+                return (
+                    self._load_run(connection, str(row[0]), query or SelectionResultQuery())
+                    if row
+                    else None
+                )
         except psycopg.Error as exc:
             raise SelectionRunStoreError("failed to load latest selection run") from exc
 
     @staticmethod
-    def _load_run(connection: Any, run_id: str) -> SelectionRun | None:
+    def _load_run(
+        connection: Any,
+        run_id: str,
+        query: SelectionResultQuery,
+    ) -> SelectionRun | None:
         row = connection.execute(
             """
             SELECT
@@ -292,15 +321,23 @@ class PostgresSelectionRunRepository(SelectionRunStore):
             """,
             (run_id,),
         ).fetchall()
+        signal_filter, signal_parameters = _signal_filter(query, run_id)
+        signal_total_row = connection.execute(
+            f"SELECT COUNT(*) FROM selection_signal WHERE {signal_filter}",
+            tuple(signal_parameters),
+        ).fetchone()
+        signal_total = int(signal_total_row[0] or 0) if signal_total_row else 0
+        offset = (query.page - 1) * query.page_size
         signal_rows = connection.execute(
-            """
+            f"""
             SELECT
                 ts_code, name, target_trade_date, strategy, category, close, details
             FROM selection_signal
-            WHERE run_id = %s
-            ORDER BY ts_code, category
+            WHERE {signal_filter}
+            ORDER BY ts_code, {_SIGNAL_ORDER_SQL}
+            LIMIT %s OFFSET %s
             """,
-            (run_id,),
+            tuple((*signal_parameters, query.page_size, offset)),
         ).fetchall()
         signals = tuple(
             sorted(
@@ -353,6 +390,7 @@ class PostgresSelectionRunRepository(SelectionRunStore):
             finished_at=cast(datetime | None, row[15]),
             items=items,
             signals=signals,
+            signals_total=signal_total,
         )
 
     @contextmanager
@@ -380,6 +418,27 @@ def _signal_from_row(row: tuple[object, ...]) -> SelectionSignal:
     )
 
 
+def _signal_filter(query: SelectionResultQuery, run_id: str) -> tuple[str, list[object]]:
+    """Build the parameterized WHERE clause shared by count and page reads."""
+
+    clauses = ["run_id = %s"]
+    parameters: list[object] = [run_id]
+    if query.search:
+        pattern = f"%{_escape_like(query.search)}%"
+        clauses.append("(name ILIKE %s ESCAPE '\\' OR ts_code ILIKE %s ESCAPE '\\')")
+        parameters.extend((pattern, pattern))
+    if query.category:
+        clauses.append("category LIKE %s")
+        parameters.append(f"{_CATEGORY_PREFIXES[query.category]}%")
+    return " AND ".join(clauses), parameters
+
+
+def _escape_like(value: str) -> str:
+    """Escape user wildcards before placing text inside a SQL LIKE pattern."""
+
+    return value.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+
+
 def _details(value: object) -> dict[str, float | str | None]:
     """Normalize JSONB details into the domain's scalar-only mapping."""
 

zhixing-server/src/zhixing_server/modules/selection/presentation/http.py

@@ -3,7 +3,7 @@
 from datetime import date, datetime
 from typing import Annotated, Literal
 
-from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, status
+from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Query, status
 from pydantic import BaseModel, Field
 
 from zhixing_server.bootstrap.config import Settings, get_settings
@@ -12,6 +12,7 @@ from zhixing_server.modules.selection.application.run import (
 )
 from zhixing_server.modules.selection.domain.runs import (
     SelectionRerunRequired,
+    SelectionResultQuery,
     SelectionRun,
     SelectionRunInProgress,
     SelectionRunStoreError,
@@ -88,7 +89,7 @@ def _empty_signals() -> list[SelectionSignalResponse]:
 
 
 class SelectionResultsResponse(BaseModel):
-    """Batch summary and materialized signals consumed by the Web feature."""
+    """Batch summary and one filtered page of signals consumed by the Web feature."""
 
     strategy: StrategyValue
     target_trade_date: date | None
@@ -106,6 +107,9 @@ class SelectionResultsResponse(BaseModel):
     error_message: str | None = None
     created_at: datetime | None = None
     finished_at: datetime | None = None
+    page: int = Field(default=1, ge=1)
+    page_size: int = Field(default=10, ge=1, le=100)
+    signals_total: int = Field(default=0, ge=0)
     failures: list[SelectionFailureResponse] = Field(default_factory=_empty_failures)
     signals: list[SelectionSignalResponse] = Field(default_factory=_empty_signals)
 
@@ -160,16 +164,21 @@ def trigger_selection_run(
 def get_selection_run(
     run_id: str,
     service: Annotated[RunZhixingB1, Depends(get_selection_service)],
+    page: Annotated[int, Query(ge=1)] = 1,
+    page_size: Annotated[int, Query(ge=1, le=100)] = 10,
+    search: Annotated[str | None, Query(max_length=100)] = None,
+    category: Literal["pullback", "oversold", "original"] | None = None,
 ) -> SelectionResultsResponse:
     """Return one run for asynchronous polling."""
 
     try:
-        run = service.get_run(run_id)
+        query = _result_query(page, page_size, search, category)
+        run = service.get_run(run_id, query=query)
     except SelectionRunStoreError as exc:
         raise _http_error(503, "selection_storage_unavailable", str(exc)) from exc
     if run is None:
         raise _http_error(404, "run_not_found", f"selection run not found: {run_id}")
-    return _run_response(run)
+    return _run_response(run, query=query)
 
 
 @selection_router.get("/results", response_model=SelectionResultsResponse)
@@ -177,11 +186,16 @@ def get_selection_results(
     service: Annotated[RunZhixingB1, Depends(get_selection_service)],
     strategy: StrategyValue = "zhixing_b1",
     target_trade_date: date | None = None,
+    page: Annotated[int, Query(ge=1)] = 1,
+    page_size: Annotated[int, Query(ge=1, le=100)] = 10,
+    search: Annotated[str | None, Query(max_length=100)] = None,
+    category: Literal["pullback", "oversold", "original"] | None = None,
 ) -> SelectionResultsResponse:
     """Return the current persisted result for a strategy and optional date."""
 
     try:
-        run = service.get_latest(strategy, target_trade_date)
+        query = _result_query(page, page_size, search, category)
+        run = service.get_latest(strategy, target_trade_date, query=query)
     except SelectionRunStoreError as exc:
         raise _http_error(503, "selection_storage_unavailable", str(exc)) from exc
     if run is None:
@@ -192,11 +206,14 @@ def get_selection_results(
             market_sync_batch_id=None,
             status="no_data",
             coverage=0,
+            page=query.page,
+            page_size=query.page_size,
+            signals_total=0,
         )
-    return _run_response(run)
+    return _run_response(run, query=query)
 
 
-def _run_response(run: SelectionRun) -> SelectionResultsResponse:
+def _run_response(run: SelectionRun, *, query: SelectionResultQuery) -> SelectionResultsResponse:
     """Translate a domain run without exposing storage-specific fields."""
 
     return SelectionResultsResponse(
@@ -216,6 +233,9 @@ def _run_response(run: SelectionRun) -> SelectionResultsResponse:
         error_message=run.error_message,
         created_at=run.created_at,
         finished_at=run.finished_at,
+        page=query.page,
+        page_size=query.page_size,
+        signals_total=run.signals_total if run.signals_total is not None else run.signal_count,
         failures=[
             SelectionFailureResponse(
                 ts_code=item.ts_code,
@@ -241,6 +261,23 @@ def _run_response(run: SelectionRun) -> SelectionResultsResponse:
     )
 
 
+def _result_query(
+    page: int,
+    page_size: int,
+    search: str | None,
+    category: Literal["pullback", "oversold", "original"] | None,
+) -> SelectionResultQuery:
+    """Normalize HTTP query values before handing them to the selection port."""
+
+    normalized_search = search.strip() if search else None
+    return SelectionResultQuery(
+        page=page,
+        page_size=page_size,
+        search=normalized_search or None,
+        category=category,
+    )
+
+
 def _http_error(code: int, error_type: str, message: str) -> HTTPException:
     """Create the project's explicit, safe error envelope."""
 

zhixing-server/tests/test_selection_http.py

@@ -11,6 +11,7 @@ from zhixing_server.modules.selection.domain.models import SelectionSignal, Zhix
 from zhixing_server.modules.selection.domain.runs import (
     SelectionExecutionSource,
     SelectionRerunRequired,
+    SelectionResultQuery,
     SelectionRun,
     SelectionRunInProgress,
     SelectionStock,
@@ -28,6 +29,7 @@ class FakeSelectionService:
         self.run = run
         self.executed = False
         self.mode = "ok"
+        self.last_query: SelectionResultQuery | None = None
 
     def prepare(
         self,
@@ -58,14 +60,23 @@ class FakeSelectionService:
     def execute(self, prepared: PreparedSelectionRun) -> None:
         self.executed = True
 
-    def get_run(self, run_id: str) -> SelectionRun | None:
+    def get_run(
+        self,
+        run_id: str,
+        *,
+        query: SelectionResultQuery | None = None,
+    ) -> SelectionRun | None:
+        self.last_query = query
         return self.run if self.run and self.run.id == run_id else None
 
     def get_latest(
         self,
         strategy: str,
         target_trade_date: date | None = None,
+        *,
+        query: SelectionResultQuery | None = None,
     ) -> SelectionRun | None:
+        self.last_query = query
         if self.run is None:
             return None
         if target_trade_date is not None and self.run.target_trade_date != target_trade_date:
@@ -193,10 +204,47 @@ def test_query_returns_persisted_signal_details() -> None:
     body = response.json()
     assert body["run_id"] == "run-http"
     assert body["signal_count"] == 1
+    assert body["page"] == 1
+    assert body["page_size"] == 10
+    assert body["signals_total"] == 1
     assert body["signals"][0]["category"] == "zhixing_b1_original_b1"
     assert body["signals"][0]["details"] == {"j": 12.0}
 
 
+def test_query_forwards_pagination_and_filters() -> None:
+    service = FakeSelectionService(_run("run-http", "success"))
+
+    response = _client(service).get(
+        "/api/v1/selection/results",
+        params={
+            "strategy": "zhixing_b1",
+            "page": 2,
+            "page_size": 5,
+            "search": "  平安银行 ",
+            "category": "original",
+        },
+    )
+
+    assert response.status_code == 200
+    assert service.last_query == SelectionResultQuery(
+        page=2,
+        page_size=5,
+        search="平安银行",
+        category="original",
+    )
+    assert response.json()["page"] == 2
+    assert response.json()["page_size"] == 5
+
+
+def test_query_rejects_invalid_page_size() -> None:
+    response = _client(FakeSelectionService()).get(
+        "/api/v1/selection/results",
+        params={"strategy": "zhixing_b1", "page_size": 101},
+    )
+
+    assert response.status_code == 422
+
+
 def test_run_polling_returns_the_persisted_terminal_result() -> None:
     response = _client(FakeSelectionService(_run("run-http", "success"))).get(
         "/api/v1/selection/runs/run-http"

zhixing-server/tests/unit/selection/test_postgres_runs.py

@@ -11,6 +11,7 @@ from zhixing_server.modules.selection.domain.models import SelectionSignal, Zhix
 from zhixing_server.modules.selection.domain.runs import (
     SelectionExecutionSource,
     SelectionRerunRequired,
+    SelectionResultQuery,
     SelectionRunInProgress,
     SelectionRunItem,
     SelectionStock,
@@ -163,6 +164,9 @@ def test_record_item_persists_independent_signals_as_jsonb(monkeypatch: pytest.M
 
 
 class LoadConnection:
+    def __init__(self) -> None:
+        self.statements: list[tuple[str, tuple[object, ...]]] = []
+
     def __enter__(self) -> "LoadConnection":
         return self
 
@@ -170,6 +174,7 @@ class LoadConnection:
         return None
 
     def execute(self, query: str, parameters: tuple[object, ...]) -> "LoadResult":
+        self.statements.append((query, parameters))
         if "FROM selection_run\n" in query:
             return LoadResult(
                 row=(
@@ -193,6 +198,8 @@ class LoadConnection:
             )
         if "FROM selection_run_item" in query:
             return LoadResult(rows=[("000001.SZ", "平安银行", "selected", 2, None)])
+        if "COUNT(*) FROM selection_signal" in query:
+            return LoadResult(row=(2,))
         return LoadResult(
             rows=[
                 (
@@ -242,10 +249,32 @@ def test_get_run_orders_signals_by_formula_priority(monkeypatch: pytest.MonkeyPa
         return connection
 
     monkeypatch.setattr(psycopg, "connect", connect)
-    run = PostgresSelectionRunRepository("postgresql://test").get_run("run-1")
+    run = PostgresSelectionRunRepository("postgresql://test").get_run(
+        "run-1",
+        query=SelectionResultQuery(
+            page=2,
+            page_size=1,
+            search="100%",
+            category="pullback",
+        ),
+    )
 
     assert run is not None
     assert [signal.category for signal in run.signals] == [
         ZHIXING_B1_SIGNAL_ORDER[0],
         ZHIXING_B1_SIGNAL_ORDER[-1],
     ]
+    count_query, count_parameters = next(
+        (query, parameters)
+        for query, parameters in connection.statements
+        if "COUNT(*) FROM selection_signal" in query
+    )
+    assert "name ILIKE %s ESCAPE" in count_query
+    assert count_parameters == ("run-1", "%100\\%%", "%100\\%%", "zhixing_b1_pullback_%")
+    page_query, page_parameters = next(
+        (query, parameters)
+        for query, parameters in connection.statements
+        if "LIMIT %s OFFSET %s" in query
+    )
+    assert "ORDER BY ts_code, CASE category" in page_query
+    assert page_parameters[-2:] == (1, 1)

zhixing-server/tests/unit/selection/test_run.py

@@ -15,6 +15,7 @@ from zhixing_server.modules.selection.domain.models import (
 )
 from zhixing_server.modules.selection.domain.runs import (
     SelectionExecutionSource,
+    SelectionResultQuery,
     SelectionRun,
     SelectionRunItem,
     SelectionRunStatus,
@@ -100,10 +101,16 @@ class FakeStore:
             kwargs["error_message"] = error_message
         self.finished = (run_id, status, kwargs)
 
-    def get_run(self, run_id: str):
+    def get_run(self, run_id: str, *, query: SelectionResultQuery | None = None):
         return None
 
-    def get_latest_run(self, strategy: str, target_trade_date: date | None = None):
+    def get_latest_run(
+        self,
+        strategy: str,
+        target_trade_date: date | None = None,
+        *,
+        query: SelectionResultQuery | None = None,
+    ):
         return None