powerquant-cli 0.2.6__py3-none-any.whl

quant_core/app/data/schema/exchange_state_schema.py

@@ -0,0 +1,106 @@
+"""Exchange State Schema - 交易所运行状态事实契约（T4R）
+
+SSOT：DECISIONS 2026-09-07 用户裁定「Exchange Operating State」：
+- ExchangePhase：交易所运行阶段（PRE_OPEN / OPEN / BREAK / CLOSED）；
+- ExchangeStateSnapshotEvent：bounded replay 起点的**状态事实基线**——
+  表达「窗口起点交易所处于什么阶段」，不是 transition，禁止伪造
+  「request.start 发生 OPEN」；
+- ExchangeStateEvent：窗口内的**增量 transition 事实**（由 Session 边界推导）；
+- Event 只承载 phase 事实。order_entry_allowed / matching_allowed /
+  cancellation_allowed 是 ExchangeStateResolver 基于 phase 与交易所规则
+  生成的**投影**，绝不作为事件字段（phase 与 capability 不允许两套 SSOT）。
+
+排序语义（market_event_order_key）：
+- 增量 Event 继承其来源 Session 边界的优先级：进入交易类（PRE_OPEN/OPEN）
+  在市场事实前，退出交易类（BREAK/CLOSED）在市场事实后；
+- Snapshot 是市场事实层（priority=FACT）。
+"""
+
+from enum import Enum
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from quant_core.app.data.constants import MarketEventType
+from quant_core.app.data.schema.event_schema import MarketEvent
+
+
+class ExchangePhase(str, Enum):
+    """交易所运行阶段（事实枚举；capabilities 由 ExchangeStateResolver 投影）"""
+
+    PRE_OPEN = "pre_open"
+    OPEN = "open"
+    BREAK = "break"
+    CLOSED = "closed"
+
+
+class ExchangeStateSnapshotEventPayload(BaseModel):
+    """交易所状态基线快照载荷：窗口起点该交易所的完整运行阶段（状态事实）"""
+
+    model_config = ConfigDict(frozen=True)
+
+    exchange: str = Field(..., min_length=1, description="Canonical 交易所标识（XSHE/XSHG）")
+    phase: ExchangePhase = Field(..., description="窗口起点的交易所运行阶段")
+
+
+class ExchangeStateEventPayload(BaseModel):
+    """交易所状态增量事件载荷：一次 phase transition 事实"""
+
+    model_config = ConfigDict(frozen=True)
+
+    exchange: str = Field(..., min_length=1, description="Canonical 交易所标识（XSHE/XSHG）")
+    phase: ExchangePhase = Field(..., description="transition 后的交易所运行阶段")
+
+
+class ExchangeStateSnapshotEvent(MarketEvent):
+    """交易所状态基线快照事件（bounded replay 初始化；不是 transition）"""
+
+    event_type: Literal[MarketEventType.EXCHANGE_STATE_SNAPSHOT] = (
+        MarketEventType.EXCHANGE_STATE_SNAPSHOT
+    )
+    payload: ExchangeStateSnapshotEventPayload  # type: ignore[assignment]
+
+
+class ExchangeStateEvent(MarketEvent):
+    """交易所状态增量事件（窗口内 transition 事实）"""
+
+    event_type: Literal[MarketEventType.EXCHANGE_STATE_EVENT] = MarketEventType.EXCHANGE_STATE_EVENT
+    payload: ExchangeStateEventPayload  # type: ignore[assignment]
+
+
+def exchange_state_snapshot_to_event(
+    exchange: str,
+    phase: ExchangePhase,
+    event_time,
+    sequence: int,
+    source: str,
+    received_at,
+) -> ExchangeStateSnapshotEvent:
+    """把交易所状态基线包装成 ExchangeStateSnapshotEvent（Replay 统一入口）"""
+    return ExchangeStateSnapshotEvent(
+        event_type=MarketEventType.EXCHANGE_STATE_SNAPSHOT,
+        event_time=event_time,
+        received_at=received_at,
+        sequence=sequence,
+        source=source,
+        payload=ExchangeStateSnapshotEventPayload(exchange=exchange, phase=phase),
+    )
+
+
+def exchange_state_to_event(
+    exchange: str,
+    phase: ExchangePhase,
+    event_time,
+    sequence: int,
+    source: str,
+    received_at,
+) -> ExchangeStateEvent:
+    """把交易所状态推进包装成 ExchangeStateEvent（Runtime 统一入口）"""
+    return ExchangeStateEvent(
+        event_type=MarketEventType.EXCHANGE_STATE_EVENT,
+        event_time=event_time,
+        received_at=received_at,
+        sequence=sequence,
+        source=source,
+        payload=ExchangeStateEventPayload(exchange=exchange, phase=phase),
+    )

quant_core/app/data/schema/history_schema.py

@@ -0,0 +1,48 @@
+"""回放准备所需的市场事实；事件与时间片仍由量化端组织。"""
+
+from datetime import date
+from decimal import Decimal
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict
+
+from quant_core.app.data.schema.adjustment_schema import AdjustmentFactorResponse
+from quant_core.app.data.schema.corporate_action_schema import CorporateActionResponse
+from quant_core.app.data.schema.market_schema import (
+    InstrumentResponse,
+    TradingCalendarDayResponse,
+    TradingRuleResponse,
+)
+
+
+class DailyFactResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+    instrument_id: str
+    trade_date: date
+    suspension_status: Literal["none", "full_day", "intraday"] | None
+    special_type: Literal["Normal", "ST", "StarST"] | None = None
+    special_type_source: str | None = None
+    limit_up: Decimal | None = None
+    limit_dn: Decimal | None = None
+    extra: dict[str, Any] | None = None
+    source_provider: str
+
+    @property
+    def is_st(self) -> bool | None:
+        """未知保持 None，调用方不能把缺少数据当成正常。"""
+        return None if self.special_type is None else self.special_type != "Normal"
+
+    @property
+    def is_suspended(self) -> bool | None:
+        """只判断全天停牌；False 不表示全天每一分钟都可交易。"""
+        return None if self.suspension_status is None else self.suspension_status == "full_day"
+
+
+class HistoryFacts(BaseModel):
+    revision: str
+    instrument: InstrumentResponse
+    calendar: list[TradingCalendarDayResponse]
+    trading_rules: list[TradingRuleResponse]
+    daily_facts: list[DailyFactResponse]
+    adjustment_factors: list[AdjustmentFactorResponse]
+    corporate_actions: list[CorporateActionResponse]

quant_core/app/data/schema/instrument_identity.py

@@ -0,0 +1,69 @@
+"""Canonical 标的身份转换 - Provider 无关权威边界
+
+A 股代码（6 位）与 Canonical Instrument ID（{market}.{exchange}.{symbol}）
+之间的唯一权威转换。纯函数、无 IO、不依赖任何 Provider（AKShare/Tushare
+adapter 一律复用本模块，禁止各自维护第二套转换）。
+
+历史说明：本逻辑原先只存在于 app/market/adapter/akshare_mapper.py（AKShare
+私有实现），导致 Tushare 因子 adapter 跨适配器引用；R1-8 将其提升为
+market 域的 Provider 无关公共边界，akshare_mapper 改为委托复用。
+"""
+
+from quant_core.app.data.constants import (
+    INSTRUMENT_ID_SEPARATOR,
+    MARKET_CN,
+    BoardType,
+    Exchange,
+)
+
+
+def exchange_from_symbol(symbol: str) -> Exchange:
+    """按代码前缀推断交易所（覆盖 A 股全板块）"""
+    if symbol.startswith("6"):
+        return Exchange.XSHG
+    if symbol.startswith(("0", "3")):
+        return Exchange.XSHE
+    if symbol.startswith(("4", "8", "9")):
+        return Exchange.BJSE
+    raise ValueError(f"无法从代码推断交易所: {symbol}")
+
+
+def board_from_symbol(symbol: str) -> BoardType:
+    """按代码前缀推断板块"""
+    if symbol.startswith("688"):
+        return BoardType.STAR
+    if symbol.startswith("300"):
+        return BoardType.CHINEXT
+    if symbol.startswith(("4", "8", "9")):
+        return BoardType.BSE
+    return BoardType.MAIN
+
+
+def external_cn_code_to_instrument_id(external_id: str) -> str:
+    """第三方代码 → Canonical ID（权威实现）。
+
+    支持 000001.SZ / 000001.XSHE / sz000001 / 000001 等写法。
+    """
+    code = external_id.strip()
+    for sep in (".",):
+        if sep in code:
+            symbol = code.split(sep)[0]
+            break
+    else:
+        symbol = code[-6:] if len(code) > 6 and not code[:2].isalpha() else code
+    if code[:2].isalpha() and code[2:].isdigit():
+        # sz000001 / sh600519 写法
+        symbol = code[2:]
+    symbol = symbol.strip()
+    if not symbol.isdigit() or len(symbol) != 6:
+        raise ValueError(f"无法解析外部代码: {external_id}")
+    exchange = exchange_from_symbol(symbol)
+    return INSTRUMENT_ID_SEPARATOR.join((MARKET_CN, exchange.value, symbol))
+
+
+def instrument_id_to_symbol(instrument_id: str) -> str:
+    """Canonical ID → 6 位代码"""
+    parts = instrument_id.split(INSTRUMENT_ID_SEPARATOR)
+    if len(parts) != 3 or parts[0] != MARKET_CN:
+        raise ValueError(f"非法 Canonical 标的ID: {instrument_id}")
+    return parts[2]

quant_core/app/data/schema/market_schema.py

@@ -0,0 +1,128 @@
+"""
+Market Schema - Instrument / TradingCalendar / Bar 的请求与响应模型
+"""
+
+from datetime import date, datetime
+from decimal import Decimal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from quant_core.app.data.constants import BarFrequency, Exchange
+from quant_core.app.data.domain.trading_quantity_value import TradingQuantityRule
+
+# ========== Instrument ==========
+
+
+class InstrumentResponse(BaseModel):
+    """标的响应"""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    instrument_id: str = Field(..., description="Canonical标的ID，如CN.XSHE.000001")
+    symbol: str = Field(..., description="交易代码")
+    name: str = Field(..., description="名称")
+    instrument_type: str = Field(..., description="标的类型")
+    exchange: str = Field(..., description="交易所")
+    board: str | None = Field(None, description="板块")
+    currency: str = Field(..., description="计价货币")
+    status: str = Field(..., description="状态")
+    listed_date: date | None = Field(None, description="上市日期")
+    delisted_date: date | None = Field(None, description="退市日期")
+
+
+class TradingRuleResponse(BaseModel):
+    """某标的在一个业务日期区间内生效的交易规则。"""
+
+    model_config = ConfigDict(from_attributes=True, frozen=True)
+
+    instrument_id: str
+    effective_from: date
+    effective_to: date | None = None
+    min_buy_quantity: int = Field(..., gt=0)
+    buy_quantity_step: int = Field(..., gt=0)
+    min_sell_quantity: int = Field(..., gt=0)
+    sell_quantity_step: int = Field(..., gt=0)
+    tick_size: Decimal = Field(..., gt=0)
+    settlement_days: int = Field(..., ge=0)
+
+    @property
+    def quantity_rule(self) -> TradingQuantityRule:
+        return TradingQuantityRule(
+            min_buy_quantity=self.min_buy_quantity,
+            buy_quantity_step=self.buy_quantity_step,
+            min_sell_quantity=self.min_sell_quantity,
+            sell_quantity_step=self.sell_quantity_step,
+        )
+
+
+# ========== TradingCalendar ==========
+
+
+class TradingCalendarDayResponse(BaseModel):
+    """交易日历响应"""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    exchange: str = Field(..., description="交易所")
+    trade_date: date = Field(..., description="日期")
+    is_open: bool = Field(..., description="是否交易日")
+    previous_open_date: date | None = Field(None, description="上一个交易日")
+    next_open_date: date | None = Field(None, description="下一个交易日")
+
+
+# ========== Bar ==========
+
+
+class BarResponse(BaseModel):
+    """Bar 响应（一律 raw 价格；复权视图由下游基于 AdjustmentFactor 数据集计算）"""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    instrument_id: str = Field(..., description="Canonical标的ID")
+    timestamp: datetime = Field(..., description="Bar结束时间")
+    frequency: str = Field(..., description="频率")
+    open: Decimal = Field(..., description="开盘价")
+    high: Decimal = Field(..., description="最高价")
+    low: Decimal = Field(..., description="最低价")
+    close: Decimal = Field(..., description="收盘价")
+    volume: int = Field(..., description="成交量（share）")
+    amount: Decimal | None = Field(None, description="成交额（CNY）")
+    previous_close: Decimal | None = Field(None, description="前收盘价")
+    suspended: bool = Field(..., description="是否停牌")
+
+
+class BarQuery(BaseModel):
+    """Bar 查询参数"""
+
+    instrument_id: str = Field(..., description="Canonical标的ID")
+    frequency: BarFrequency = Field(BarFrequency.D1, description="频率")
+    start: datetime | None = Field(None, description="开始时间（含）")
+    end: datetime | None = Field(None, description="结束时间（含）")
+    limit: int = Field(1000, ge=1, le=100000, description="最大返回条数")
+
+
+# ========== Sync ==========
+
+
+class SyncRequest(BaseModel):
+    """数据同步请求"""
+
+    exchange: Exchange = Field(Exchange.XSHG, description="交易所（日历/快照类同步用）")
+    instrument_id: str | None = Field(None, description="指定标的（如CN.XSHE.000001）；None=全市场")
+    trade_date: date | None = Field(None, description="目标交易日；None=最新")
+    start: date | None = Field(None, description="范围开始（Bar增量同步用）")
+    end: date | None = Field(None, description="范围结束")
+
+
+class SyncResultResponse(BaseModel):
+    """同步结果"""
+
+    dataset: str = Field(..., description="数据集类型")
+    written: int = Field(0, description="写入条数")
+    skipped: int = Field(0, description="跳过条数")
+    rejected: int = Field(0, description="校验拒绝条数")
+    errors: list[str] = Field(default_factory=list, description="错误摘要（前若干条）")
+    quarantined_instruments: list[str] = Field(
+        default_factory=list, description="上市/退市日期缺证据，禁止进入历史股票池的标的"
+    )
+    dataset_revision: str | None = Field(None, description="本次成功同步内容的稳定摘要")

quant_core/app/data/schema/pit_daily_window.py

@@ -0,0 +1,16 @@
+"""Market-owned daily price windows for downstream PIT calculations."""
+
+from datetime import date
+
+from pydantic import BaseModel, ConfigDict
+
+from quant_core.app.data.schema.adjustment_schema import AdjustedBarResponse
+
+
+class PITDailyWindow(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    as_of: date
+    anchor_date: date
+    bars: tuple[AdjustedBarResponse, ...]
+    input_digest: str

quant_core/app/data/schema/quote_schema.py

@@ -0,0 +1,73 @@
+"""
+Market Schema - Quote / DailyBasic / Sector 的响应模型
+"""
+
+from datetime import date, datetime
+from decimal import Decimal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class QuoteResponse(BaseModel):
+    """最新行情快照响应"""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    instrument_id: str = Field(..., description="Canonical标的ID")
+    timestamp: datetime = Field(..., description="快照时间（事件时间）")
+    last: Decimal = Field(..., description="最新价")
+    open: Decimal | None = Field(None, description="今日开盘价")
+    high: Decimal | None = Field(None, description="今日最高价")
+    low: Decimal | None = Field(None, description="今日最低价")
+    previous_close: Decimal | None = Field(None, description="昨收价")
+    volume: int = Field(..., description="累计成交量（share）")
+    amount: Decimal | None = Field(None, description="累计成交额（CNY）")
+    bid_price_1: Decimal | None = Field(None, description="买一价")
+    bid_volume_1: int | None = Field(None, description="买一量（share）")
+    ask_price_1: Decimal | None = Field(None, description="卖一价")
+    ask_volume_1: int | None = Field(None, description="卖一量（share）")
+    status: str | None = Field(None, description="交易状态")
+
+
+class DailyBasicResponse(BaseModel):
+    """日频基础指标响应"""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    instrument_id: str = Field(..., description="Canonical标的ID")
+    trade_date: date = Field(..., description="交易日")
+    turnover_rate: Decimal | None = Field(None, description="换手率（%，1.23=1.23%）")
+    turnover_rate_free: Decimal | None = Field(None, description="自由流通换手率（%）")
+    volume_ratio: Decimal | None = Field(None, description="量比")
+    pe: Decimal | None = Field(None, description="市盈率（NULL=不可计算，如亏损）")
+    pe_ttm: Decimal | None = Field(None, description="市盈率TTM")
+    pb: Decimal | None = Field(None, description="市净率")
+    ps: Decimal | None = Field(None, description="市销率")
+    ps_ttm: Decimal | None = Field(None, description="市销率TTM")
+    dividend_yield: Decimal | None = Field(None, description="股息率（%）")
+    dividend_yield_ttm: Decimal | None = Field(None, description="股息率TTM（%）")
+    total_shares: Decimal | None = Field(None, description="总股本（share）")
+    float_shares: Decimal | None = Field(None, description="流通股本（share）")
+    free_float_shares: Decimal | None = Field(None, description="自由流通股本（share）")
+    total_market_cap: Decimal | None = Field(None, description="总市值（CNY）")
+    circulating_market_cap: Decimal | None = Field(None, description="流通市值（CNY）")
+
+
+class SectorResponse(BaseModel):
+    """板块响应"""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    sector_id: str = Field(..., description="Canonical板块ID")
+    name: str = Field(..., description="名称")
+    sector_type: str = Field(..., description="类型")
+    source: str = Field(..., description="分类体系来源")
+
+
+class SectorMembershipResponse(BaseModel):
+    """标的-板块关系响应"""
+
+    instrument_id: str = Field(..., description="Canonical标的ID")
+    sector_id: str = Field(..., description="Canonical板块ID")
+    effective_from: date = Field(..., description="生效日期（含）")
+    effective_to: date | None = Field(None, description="失效日期（含）；NULL=当前有效")

quant_core/app/data/schema/reliability_schema.py

@@ -0,0 +1,152 @@
+"""
+Market Data Reliability Schema - Sync 结果与 Dataset 健康契约
+
+SSOT 语义见 SPEC「Market Data 可靠性」与 DATA-DICTIONARY §5。
+核心原则：
+- "同步成功" != Provider 请求成功；必须 = 转换成功 + 数据合法 + 无重复 +
+  目标区间完整 + 结果可追溯（MarketSyncResult 结构化表达）。
+- Verify 只证明 "Observed Canonical Data 是否覆盖 Expected Timeline"，
+  不负责猜测 Missing 的业务原因（停牌/零成交属 Trading Status，future）。
+"""
+
+from datetime import date, datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class SyncIssueCode(str, Enum):
+    """结构化问题码（issues 摘要用，禁止只返回 "sync success" 文本）"""
+
+    INVALID_OHLC = "INVALID_OHLC"
+    NON_POSITIVE_PRICE = "NON_POSITIVE_PRICE"
+    NEGATIVE_VOLUME = "NEGATIVE_VOLUME"
+    NEGATIVE_AMOUNT = "NEGATIVE_AMOUNT"
+    INVALID_TIMESTAMP = "INVALID_TIMESTAMP"
+    INVALID_INSTRUMENT_ID = "INVALID_INSTRUMENT_ID"
+    INVALID_TRADING_DAY = "INVALID_TRADING_DAY"  # 交易日语义违反 TradingCalendar
+    MISSING_BAR = "MISSING_BAR"  # Expected Timeline 上的缺口（unexplained）
+    MISSING_ADJUSTMENT_FACTOR = "MISSING_ADJUSTMENT_FACTOR"
+    MISSING_DATASET_COVERAGE = "MISSING_DATASET_COVERAGE"
+    DUPLICATE_BAR = "DUPLICATE_BAR"  # 同批内重复（唯一键冲突，跳过）
+    PROVIDER_ERROR = "PROVIDER_ERROR"
+
+
+class SyncStatus(str, Enum):
+    """Sync 结果状态
+
+    SUCCESS = 目标同步区间成功且验证通过；
+    PARTIAL = 有数据写入，但存在缺口或非法数据；
+    FAILED  = 同步任务无法形成可用结果。
+    不因为写入了一部分数据就返回 SUCCESS。
+    """
+
+    SUCCESS = "SUCCESS"
+    PARTIAL = "PARTIAL"
+    FAILED = "FAILED"
+
+
+class SyncIssue(BaseModel):
+    """单条结构化问题摘要"""
+
+    code: SyncIssueCode
+    instrument_id: str | None = None
+    timestamp: datetime | None = None
+    detail: str | None = Field(None, description="补充说明（如失败原因原文）")
+
+
+class MarketSyncResult(BaseModel):
+    """Sync 稳定结果对象（可追溯：请求区间 + 各阶段计数 + 状态 + 问题摘要）
+
+    字段按真实实现裁剪：V1 Provider 为 ON CONFLICT DO NOTHING 幂等 upsert，
+    updated_count 恒为 0（重复数据走 skipped）。
+    """
+
+    dataset: str
+    provider: str | None = None
+    instrument_id: str | None = Field(None, description="单标的同步时有值")
+    frequency: str | None = None
+    requested_start: date | None = None
+    requested_end: date | None = None
+    fetched_count: int = Field(0, description="Provider 返回条数")
+    normalized_count: int = Field(0, description="Mapper 转换成功条数")
+    inserted_count: int = Field(0, description="新插入条数")
+    updated_count: int = Field(0, description="更新条数（V1 幂等 upsert 恒为 0）")
+    skipped_count: int = Field(0, description="重复/无需写入条数")
+    invalid_count: int = Field(0, description="校验拒绝条数")
+    missing_count: int = Field(0, description="Completeness Check 发现的缺口数")
+    started_at: datetime
+    finished_at: datetime | None = None
+    status: SyncStatus = SyncStatus.FAILED
+    issues: list[SyncIssue] = Field(default_factory=list, description="结构化问题摘要（限量）")
+
+
+class DatasetHealth(str, Enum):
+    """Dataset 健康状态（Verify 产出）
+
+    HEALTHY    = 请求区间完整且合法，可以消费；
+    PARTIAL    = 有数据但目标区间存在缺口（unexplained missing，含疑似停牌日）；
+    STALE      = 结构正确且完整，但未更新到要求的新鲜度（V1 不产出，预留枚举位）；
+    INVALID    = 存在违反 Canonical 数据规则的数据；
+    NOT_SYNCED = 请求区间基本没有本地数据。
+    """
+
+    HEALTHY = "HEALTHY"
+    PARTIAL = "PARTIAL"
+    STALE = "STALE"
+    INVALID = "INVALID"
+    NOT_SYNCED = "NOT_SYNCED"
+
+
+class DatasetHealthResult(BaseModel):
+    """Verify 结果（只检查，绝不触发 Sync）
+
+    完整性验证单位：instrument_id + frequency + requested time range。
+    missing 明细只返回限量样本（missing_count 是权威计数）。
+    """
+
+    dataset: str
+    instrument_id: str
+    frequency: str
+    requested_start: datetime
+    requested_end: datetime
+    health: DatasetHealth
+    expected_count: int = Field(0, description="Expected Timeline 应有 Bar 数")
+    actual_count: int = Field(0, description="本地实际 Bar 数")
+    missing_count: int = 0
+    invalid_count: int = 0
+    latest_timestamp: datetime | None = None
+    dataset_revision: str | None = Field(
+        None, description="本次验证所见内容版本；必须进入缓存键/回测结果"
+    )
+    issues: list[SyncIssue] = Field(default_factory=list)
+
+
+def issue_code_from_reason(reason: str) -> SyncIssueCode:
+    """Validator 失败原因字符串 → 结构化问题码（未知原因归入 INVALID_OHLC）"""
+    mapping: dict[str, SyncIssueCode] = {
+        "high_lt_max_open_close": SyncIssueCode.INVALID_OHLC,
+        "low_gt_min_open_close": SyncIssueCode.INVALID_OHLC,
+        "non_positive_price": SyncIssueCode.NON_POSITIVE_PRICE,
+        "negative_volume": SyncIssueCode.NEGATIVE_VOLUME,
+        "negative_amount": SyncIssueCode.NEGATIVE_AMOUNT,
+        "naive_timestamp": SyncIssueCode.INVALID_TIMESTAMP,
+        "invalid_instrument_id": SyncIssueCode.INVALID_INSTRUMENT_ID,
+    }
+    return mapping.get(reason, SyncIssueCode.INVALID_OHLC)
+
+
+def to_issue(reason: str, instrument_id: str, timestamp: datetime | None) -> SyncIssue:
+    """Validator 失败原因 → SyncIssue 的统一入口"""
+    return SyncIssue(
+        code=issue_code_from_reason(reason),
+        instrument_id=instrument_id,
+        timestamp=timestamp,
+        detail=reason,
+    )
+
+
+def health_payload(result: DatasetHealthResult) -> dict[str, Any]:
+    """DatasetHealthResult 的可 JSON 化视图（API/日志复用）"""
+    return result.model_dump(mode="json")

quant_core/app/data/schema/snapshot_schema.py

@@ -0,0 +1,82 @@
+"""
+Market Schema - MarketSnapshot 响应模型
+"""
+
+import json
+from datetime import date, datetime
+from decimal import Decimal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from quant_core.app.data.schema.quote_schema import QuoteResponse
+
+
+class IndexFact(BaseModel):
+    """指数事实"""
+
+    instrument_id: str = Field(..., description="Canonical指数ID")
+    name: str = Field(..., description="指数名称")
+    last: Decimal = Field(..., description="点位")
+    pct_change: Decimal | None = Field(None, description="涨跌幅（%，1.23=1.23%）")
+
+
+class SectorFact(BaseModel):
+    """板块事实"""
+
+    sector_id: str | None = Field(None, description="Canonical板块ID")
+    name: str = Field(..., description="板块名称")
+    pct_change: Decimal | None = Field(None, description="涨跌幅（%）")
+
+
+class MarketSnapshotResponse(BaseModel):
+    """市场快照响应（只有事实，没有 regime 判断）"""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    trade_date: date = Field(..., description="交易日")
+    snapshot_time: datetime = Field(..., description="快照时间")
+    major_indices: list[IndexFact] = Field(default_factory=list, description="主要指数")
+    total_turnover: Decimal | None = Field(None, description="两市总成交额（CNY）")
+    advancing_count: int | None = Field(None, description="上涨家数")
+    declining_count: int | None = Field(None, description="下跌家数")
+    unchanged_count: int | None = Field(None, description="平盘家数")
+    limit_up_count: int | None = Field(None, description="涨停家数")
+    limit_down_count: int | None = Field(None, description="跌停家数")
+    new_high_count: int | None = Field(None, description="创新高家数")
+    new_low_count: int | None = Field(None, description="创新低家数")
+    hot_sectors: list[SectorFact] = Field(default_factory=list, description="领涨板块")
+    weak_sectors: list[SectorFact] = Field(default_factory=list, description="领跌板块")
+    source_provider: str = Field(..., description="来源Provider")
+
+
+def decode_snapshot_json_fields(
+    major_indices: str | None, hot_sectors: str | None, weak_sectors: str | None
+) -> tuple[list[IndexFact], list[SectorFact], list[SectorFact]]:
+    """把快照表的 JSON 文本列解码为结构化事实（ORM → Response 转换专用）"""
+    indices = (
+        [IndexFact.model_validate(x) for x in json.loads(major_indices)] if major_indices else []
+    )
+    hot = [SectorFact.model_validate(x) for x in json.loads(hot_sectors)] if hot_sectors else []
+    weak = [SectorFact.model_validate(x) for x in json.loads(weak_sectors)] if weak_sectors else []
+    return indices, hot, weak
+
+
+def quotes_to_snapshot_facts(quotes: list[QuoteResponse]) -> dict[str, int]:
+    """从 Quote 列表聚合市场宽度事实（涨跌/平盘家数；涨停跌停需涨跌幅阈值近似，V1 不做）"""
+    advancing = declining = unchanged = 0
+    for q in quotes:
+        if q.previous_close is None or q.previous_close == 0:
+            unchanged += 1
+            continue
+        pct = (q.last - q.previous_close) / q.previous_close * 100
+        if pct > Decimal("0.001"):
+            advancing += 1
+        elif pct < Decimal("-0.001"):
+            declining += 1
+        else:
+            unchanged += 1
+    return {
+        "advancing_count": advancing,
+        "declining_count": declining,
+        "unchanged_count": unchanged,
+    }