feat: add decision signal outcomes and feedback

Author: massif-01

api/v1/endpoints/decision_signals.py

@@ -4,17 +4,23 @@
 from __future__ import annotations
 
 import logging
-from typing import Optional
+from typing import List, Optional
 
 from fastapi import APIRouter, HTTPException, Query, Security
 from fastapi.security import APIKeyCookie
 
 from api.v1.schemas.common import ErrorResponse
 from api.v1.schemas.decision_signals import (
     DecisionSignalCreateRequest,
+    DecisionSignalFeedbackItem,
+    DecisionSignalFeedbackRequest,
     DecisionSignalItem,
     DecisionSignalListResponse,
     DecisionSignalMutationResponse,
+    DecisionSignalOutcomeListResponse,
+    DecisionSignalOutcomeRunRequest,
+    DecisionSignalOutcomeRunResponse,
+    DecisionSignalOutcomeStatsResponse,
     DecisionSignalStatusUpdateRequest,
 )
 from src.auth import COOKIE_NAME
@@ -23,6 +29,7 @@
     DecisionSignalService,
     DecisionSignalStorageError,
 )
+from src.services.decision_signal_outcome_service import DecisionSignalOutcomeService
 
 
 logger = logging.getLogger(__name__)
@@ -165,6 +172,121 @@ def list_signals(
         raise _internal_error("List decision signals failed", exc)
 
 
+@router.post(
+    "/outcomes/run",
+    response_model=DecisionSignalOutcomeRunResponse,
+    responses={
+        **AUTH_RESPONSE,
+        400: {"model": ErrorResponse, "description": "请求字段非法"},
+        404: {"model": ErrorResponse, "description": "信号不存在"},
+        422: {"model": ErrorResponse, "description": "请求体校验失败"},
+        500: {"model": ErrorResponse, "description": "后验计算失败"},
+    },
+    summary="触发决策信号后验评估",
+    description=(
+        "显式触发 signal-level outcome 计算；默认按当前 engine_version 幂等跳过已评估键，"
+        "force=true 会重算并覆盖同一 signal_id+horizon+engine_version。"
+    ),
+    operation_id="runDecisionSignalOutcomes",
+)
+def run_outcomes(request: DecisionSignalOutcomeRunRequest) -> DecisionSignalOutcomeRunResponse:
+    service = DecisionSignalOutcomeService()
+    try:
+        return DecisionSignalOutcomeRunResponse(
+            **service.run_outcomes(
+                signal_id=request.signal_id,
+                horizons=request.horizons,
+                force=request.force,
+                market=request.market,
+                stock_code=request.stock_code,
+                action=request.action,
+                source_type=request.source_type,
+                status=request.status,
+                limit=request.limit,
+            )
+        )
+    except DecisionSignalNotFoundError as exc:
+        raise _not_found(exc)
+    except ValueError as exc:
+        raise _bad_request(exc)
+    except Exception as exc:
+        raise _internal_error("Run decision signal outcomes failed", exc)
+
+
+@router.get(
+    "/outcomes",
+    response_model=DecisionSignalOutcomeListResponse,
+    responses={
+        **AUTH_RESPONSE,
+        400: {"model": ErrorResponse, "description": "查询参数非法"},
+        422: {"model": ErrorResponse, "description": "查询参数校验失败"},
+        500: {"model": ErrorResponse, "description": "查询失败"},
+    },
+    summary="查询决策信号后验结果",
+    description="分页查询 signal-level outcome；默认只查当前 signal 后验 engine_version。",
+    operation_id="listDecisionSignalOutcomes",
+)
+def list_outcomes(
+    signal_id: Optional[int] = Query(None, gt=0),
+    horizon: Optional[str] = Query(None),
+    engine_version: Optional[str] = Query(None),
+    eval_status: Optional[str] = Query(None),
+    outcome: Optional[str] = Query(None),
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=100),
+) -> DecisionSignalOutcomeListResponse:
+    service = DecisionSignalOutcomeService()
+    try:
+        return DecisionSignalOutcomeListResponse(
+            **service.list_outcomes(
+                signal_id=signal_id,
+                horizon=horizon,
+                engine_version=engine_version,
+                eval_status=eval_status,
+                outcome=outcome,
+                page=page,
+                page_size=page_size,
+            )
+        )
+    except ValueError as exc:
+        raise _bad_request(exc)
+    except Exception as exc:
+        raise _internal_error("List decision signal outcomes failed", exc)
+
+
+@router.get(
+    "/outcomes/stats",
+    response_model=DecisionSignalOutcomeStatsResponse,
+    responses={
+        **AUTH_RESPONSE,
+        400: {"model": ErrorResponse, "description": "查询参数非法"},
+        422: {"model": ErrorResponse, "description": "查询参数校验失败"},
+        500: {"model": ErrorResponse, "description": "统计失败"},
+    },
+    summary="查询决策信号后验统计",
+    description="默认统计当前 engine_version，且排除 archived 信号。",
+    operation_id="getDecisionSignalOutcomeStats",
+)
+def get_outcome_stats(
+    horizons: Optional[List[str]] = Query(None),
+    engine_version: Optional[str] = Query(None),
+    statuses: Optional[List[str]] = Query(None),
+) -> DecisionSignalOutcomeStatsResponse:
+    service = DecisionSignalOutcomeService()
+    try:
+        return DecisionSignalOutcomeStatsResponse(
+            **service.get_stats(
+                horizons=horizons,
+                engine_version=engine_version,
+                statuses=statuses,
+            )
+        )
+    except ValueError as exc:
+        raise _bad_request(exc)
+    except Exception as exc:
+        raise _internal_error("Get decision signal outcome stats failed", exc)
+
+
 @router.get(
     "/latest/{stock_code}",
     response_model=DecisionSignalListResponse,
@@ -225,6 +347,86 @@ def get_signal(signal_id: int) -> DecisionSignalItem:
         raise _internal_error("Get decision signal failed", exc)
 
 
+@router.get(
+    "/{signal_id}/outcomes",
+    response_model=DecisionSignalOutcomeListResponse,
+    responses={
+        **AUTH_RESPONSE,
+        404: {"model": ErrorResponse, "description": "信号不存在"},
+        422: {"model": ErrorResponse, "description": "路径参数校验失败"},
+        500: {"model": ErrorResponse, "description": "查询失败"},
+    },
+    summary="查询单个决策信号后验结果",
+    description="返回指定 signal_id 在当前 engine_version 下的后验结果。",
+    operation_id="listDecisionSignalOutcomesBySignal",
+)
+def list_signal_outcomes(signal_id: int) -> DecisionSignalOutcomeListResponse:
+    service = DecisionSignalOutcomeService()
+    try:
+        return DecisionSignalOutcomeListResponse(**service.list_signal_outcomes(signal_id))
+    except DecisionSignalNotFoundError as exc:
+        raise _not_found(exc)
+    except Exception as exc:
+        raise _internal_error("List decision signal outcomes failed", exc)
+
+
+@router.get(
+    "/{signal_id}/feedback",
+    response_model=DecisionSignalFeedbackItem,
+    responses={
+        **AUTH_RESPONSE,
+        404: {"model": ErrorResponse, "description": "信号不存在"},
+        422: {"model": ErrorResponse, "description": "路径参数校验失败"},
+        500: {"model": ErrorResponse, "description": "查询失败"},
+    },
+    summary="查询决策信号用户反馈",
+    description="没有反馈时返回 feedback_value=null；信号不存在时返回 404。",
+    operation_id="getDecisionSignalFeedback",
+)
+def get_feedback(signal_id: int) -> DecisionSignalFeedbackItem:
+    service = DecisionSignalOutcomeService()
+    try:
+        return DecisionSignalFeedbackItem(**service.get_feedback(signal_id))
+    except DecisionSignalNotFoundError as exc:
+        raise _not_found(exc)
+    except Exception as exc:
+        raise _internal_error("Get decision signal feedback failed", exc)
+
+
+@router.put(
+    "/{signal_id}/feedback",
+    response_model=DecisionSignalFeedbackItem,
+    responses={
+        **AUTH_RESPONSE,
+        400: {"model": ErrorResponse, "description": "请求字段非法"},
+        404: {"model": ErrorResponse, "description": "信号不存在"},
+        422: {"model": ErrorResponse, "description": "请求体或路径参数校验失败"},
+        500: {"model": ErrorResponse, "description": "更新失败"},
+    },
+    summary="写入决策信号用户反馈",
+    description="按 signal_id upsert 最新 useful/not_useful 反馈。",
+    operation_id="putDecisionSignalFeedback",
+)
+def put_feedback(signal_id: int, request: DecisionSignalFeedbackRequest) -> DecisionSignalFeedbackItem:
+    service = DecisionSignalOutcomeService()
+    try:
+        return DecisionSignalFeedbackItem(
+            **service.put_feedback(
+                signal_id,
+                feedback_value=request.feedback_value,
+                reason_code=request.reason_code,
+                note=request.note,
+                source=request.source,
+            )
+        )
+    except DecisionSignalNotFoundError as exc:
+        raise _not_found(exc)
+    except ValueError as exc:
+        raise _bad_request(exc)
+    except Exception as exc:
+        raise _internal_error("Put decision signal feedback failed", exc)
+
+
 @router.patch(
     "/{signal_id}/status",
     response_model=DecisionSignalItem,

api/v1/schemas/__init__.py

@@ -109,9 +109,17 @@
 )
 from api.v1.schemas.decision_signals import (
     DecisionSignalCreateRequest,
+    DecisionSignalFeedbackItem,
+    DecisionSignalFeedbackRequest,
     DecisionSignalItem,
     DecisionSignalListResponse,
     DecisionSignalMutationResponse,
+    DecisionSignalOutcomeItem,
+    DecisionSignalOutcomeListResponse,
+    DecisionSignalOutcomeRunRequest,
+    DecisionSignalOutcomeRunResponse,
+    DecisionSignalOutcomeStatsBucket,
+    DecisionSignalOutcomeStatsResponse,
     DecisionSignalStatusUpdateRequest,
 )
 
@@ -210,8 +218,16 @@
     "AlertTriggerListResponse",
     # decision signals
     "DecisionSignalCreateRequest",
+    "DecisionSignalFeedbackItem",
+    "DecisionSignalFeedbackRequest",
     "DecisionSignalItem",
     "DecisionSignalListResponse",
     "DecisionSignalMutationResponse",
+    "DecisionSignalOutcomeItem",
+    "DecisionSignalOutcomeListResponse",
+    "DecisionSignalOutcomeRunRequest",
+    "DecisionSignalOutcomeRunResponse",
+    "DecisionSignalOutcomeStatsBucket",
+    "DecisionSignalOutcomeStatsResponse",
     "DecisionSignalStatusUpdateRequest",
 ]

api/v1/schemas/decision_signals.py

@@ -17,6 +17,10 @@
 DecisionSignalPlanQuality = Literal["complete", "partial", "minimal", "unknown"]
 DecisionSignalHorizon = Literal["intraday", "1d", "3d", "5d", "10d", "swing", "long"]
 DecisionSignalMarket = Literal["cn", "hk", "us"]
+DecisionSignalOutcomeStatus = Literal["completed", "unable"]
+DecisionSignalOutcomeValue = Literal["hit", "miss", "neutral"]
+DecisionSignalFeedbackValue = Literal["useful", "not_useful"]
+DecisionSignalFeedbackSource = Literal["web", "api"]
 
 
 class DecisionSignalCreateRequest(BaseModel):
@@ -57,6 +61,110 @@ class DecisionSignalStatusUpdateRequest(BaseModel):
     metadata: Optional[Dict[str, Any]] = None
 
 
+class DecisionSignalOutcomeRunRequest(BaseModel):
+    signal_id: Optional[int] = Field(None, gt=0)
+    horizons: Optional[List[DecisionSignalHorizon]] = None
+    force: bool = False
+    market: Optional[DecisionSignalMarket] = None
+    stock_code: Optional[str] = Field(None, json_schema_extra={"maxLength": 32})
+    action: Optional[DecisionAction] = None
+    source_type: Optional[DecisionSignalSourceType] = None
+    status: Optional[DecisionSignalStatus] = None
+    limit: int = Field(100, ge=1, le=500)
+
+
+class DecisionSignalOutcomeItem(BaseModel):
+    id: int
+    signal_id: int
+    horizon: str
+    engine_version: str
+    eval_status: str
+    outcome: Optional[str] = None
+    direction_expected: Optional[str] = None
+    direction_correct: Optional[bool] = None
+    unable_reason: Optional[str] = None
+    anchor_date: Optional[str] = None
+    eval_window_days: Optional[int] = None
+    start_price: Optional[float] = None
+    end_close: Optional[float] = None
+    max_high: Optional[float] = None
+    min_low: Optional[float] = None
+    stock_return_pct: Optional[float] = None
+    action: Optional[str] = None
+    market: Optional[str] = None
+    market_phase: Optional[str] = None
+    source_type: Optional[str] = None
+    source_agent: Optional[str] = None
+    plan_quality: Optional[str] = None
+    data_quality_level: Optional[str] = None
+    holding_state: str
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+
+
+class DecisionSignalOutcomeRunResponse(BaseModel):
+    items: List[DecisionSignalOutcomeItem] = Field(default_factory=list)
+    evaluated: int
+    created: int
+    updated: int
+    skipped: int
+    engine_version: str
+
+
+class DecisionSignalOutcomeListResponse(BaseModel):
+    items: List[DecisionSignalOutcomeItem] = Field(default_factory=list)
+    total: int
+    page: int
+    page_size: int
+
+
+class DecisionSignalOutcomeStatsBucket(BaseModel):
+    dimension: str
+    value: str
+    total: int
+    completed: int
+    unable: int
+    hit: int
+    miss: int
+    neutral: int
+    hit_rate_pct: Optional[float] = None
+    avg_stock_return_pct: Optional[float] = None
+    unable_reasons: Dict[str, int] = Field(default_factory=dict)
+
+
+class DecisionSignalOutcomeStatsResponse(BaseModel):
+    engine_version: str
+    horizons: Optional[List[str]] = None
+    statuses: List[str] = Field(default_factory=list)
+    total: int
+    completed: int
+    unable: int
+    hit: int
+    miss: int
+    neutral: int
+    hit_rate_pct: Optional[float] = None
+    avg_stock_return_pct: Optional[float] = None
+    unable_reasons: Dict[str, int] = Field(default_factory=dict)
+    breakdowns: Dict[str, List[DecisionSignalOutcomeStatsBucket]] = Field(default_factory=dict)
+
+
+class DecisionSignalFeedbackRequest(BaseModel):
+    feedback_value: DecisionSignalFeedbackValue
+    reason_code: Optional[str] = Field(None, json_schema_extra={"maxLength": 64})
+    note: Optional[str] = Field(None, json_schema_extra={"maxLength": 1000})
+    source: DecisionSignalFeedbackSource = "api"
+
+
+class DecisionSignalFeedbackItem(BaseModel):
+    signal_id: int
+    feedback_value: Optional[DecisionSignalFeedbackValue] = None
+    reason_code: Optional[str] = None
+    note: Optional[str] = None
+    source: Optional[DecisionSignalFeedbackSource] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+
+
 class DecisionSignalItem(BaseModel):
     id: int
     stock_code: str