powerquant-cli 0.2.6__py3-none-any.whl

quant_core/app/data/constants.py

@@ -0,0 +1,284 @@
+"""
+Market Domain 常量 - Canonical 枚举
+
+本模块是 Market Domain 全部稳定业务值的唯一定义点。
+所有枚举只描述「数据是什么」，不描述「怎么存、从谁取、怎么算」。
+
+规则：
+- 枚举存在不代表能力已实现；实现状态见 DATA-DICTIONARY.md 的 Dataset Catalog。
+- 第三方字段、单位、代码格式一律不允许进入本模块，只能在 adapter/mapper 转换。
+"""
+
+import re
+from enum import Enum
+from typing import Final
+
+# ========== 身份与格式 ==========
+
+MARKET_CN: Final[str] = "CN"
+"""中国市场的 Canonical market 前缀。"""
+
+INSTRUMENT_ID_SEPARATOR: Final[str] = "."
+"""Canonical Instrument ID 分隔符：{market}.{exchange}.{symbol}，如 CN.XSHE.000001。"""
+
+CANONICAL_INSTRUMENT_ID_PATTERN: Final[re.Pattern[str]] = re.compile(
+    r"^[A-Z]{2}\.[A-Z0-9]+\.[A-Z0-9]+$"
+)
+"""Canonical Instrument ID 格式（{market}.{exchange}.{symbol}）的唯一校验规则。
+
+域内所有需要校验 Canonical 标识的模块统一复用本模式，不允许各自复制正则。
+"""
+
+CANONICAL_PROVIDER: Final[str] = "powerquant"
+"""Canonical 数据自身的来源标识（非第三方同步的数据）。"""
+
+PROVIDER_AKSHARE: Final[str] = "akshare"
+"""AKShare 的 Provider 标识（Canonical 身份值，非 SDK 概念）。"""
+
+PROVIDER_TUSHARE: Final[str] = "tushare"
+"""Tushare Pro 的 Provider 标识（Canonical 身份值，非 SDK 概念）。"""
+
+
+class Exchange(str, Enum):
+    """Canonical 交易所枚举（第三方写法 SH/SZ/SSE/SZSE 由 mapper 转换）"""
+
+    XSHG = "XSHG"
+    XSHE = "XSHE"
+    BJSE = "BJSE"
+
+
+class BoardType(str, Enum):
+    """A股板块"""
+
+    MAIN = "main"
+    STAR = "star"
+    CHINEXT = "chinext"
+    BSE = "bse"
+
+
+class InstrumentType(str, Enum):
+    """标的类型。
+
+    注意：enum 存在不代表支持对应的交易/研究能力，实现状态见 DATA-DICTIONARY.md。
+    """
+
+    STOCK = "stock"
+    ETF = "etf"
+    INDEX = "index"
+    # reserved：仅为未来扩展保留
+    BOND = "bond"
+    FUTURE = "future"
+    OPTION = "option"
+
+
+class InstrumentStatus(str, Enum):
+    """标的状态"""
+
+    ACTIVE = "active"
+    DELISTED = "delisted"
+    SUSPENDED = "suspended"
+
+
+# ========== 数据集分类 ==========
+
+
+class MarketDataCategory(str, Enum):
+    """数据一级分类（稳定，不绑定供应商习惯）"""
+
+    REFERENCE = "reference"
+    MARKET_DATA = "market_data"
+    FUNDAMENTAL = "fundamental"
+    CORPORATE_ACTION = "corporate_action"
+    CLASSIFICATION = "classification"
+    MARKET_STATISTICS = "market_statistics"
+    FLOW = "flow"
+    ALTERNATIVE = "alternative"
+
+
+class MarketDatasetType(str, Enum):
+    """数据集类型（枚举表示 PowerQuant 认可的数据类别，不代表全部实现）"""
+
+    INSTRUMENT = "instrument"
+    TRADING_CALENDAR = "trading_calendar"
+    BAR = "bar"
+    ADJUSTMENT_FACTOR = "adjustment_factor"
+    QUOTE = "quote"
+    DAILY_BASIC = "daily_basic"
+    INSTRUMENT_DAILY_FACT = "instrument_daily_fact"
+    SECTOR = "sector"
+    SECTOR_MEMBERSHIP = "sector_membership"
+    MARKET_SNAPSHOT = "market_snapshot"
+    # reserved：仅为未来扩展保留
+    TICK = "tick"
+    CORPORATE_ACTION = "corporate_action"
+    INDEX_MEMBERSHIP = "index_membership"
+    MONEY_FLOW = "money_flow"
+    MARGIN = "margin"
+    NEWS = "news"
+    ANNOUNCEMENT = "announcement"
+
+
+class DatasetStatus(str, Enum):
+    """数据集实现状态"""
+
+    IMPLEMENTED = "implemented"
+    PLANNED = "planned"
+    RESERVED = "reserved"
+
+
+class MarketDataJobMode(str, Enum):
+    """L1 数据作业的用户意图。"""
+
+    BOOTSTRAP = "bootstrap"
+    UPDATE = "update"
+    REPAIR = "repair"
+
+
+class DatasetCheckpointStatus(str, Enum):
+    """单个同步分片的持久化状态。"""
+
+    PENDING = "pending"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+
+
+class DatasetScopeType(str, Enum):
+    """Checkpoint 作用域类型；粒度由 Provider 接口形态决定。"""
+
+    MARKET_DATE = "market_date"
+    INSTRUMENT = "instrument"
+
+
+class TemporalType(str, Enum):
+    """时间语义"""
+
+    STATIC = "static"
+    SNAPSHOT = "snapshot"
+    TIME_SERIES = "time_series"
+    INTERVAL = "interval"
+    EVENT = "event"
+
+
+class EntityScope(str, Enum):
+    """数据挂载的实体范围"""
+
+    MARKET = "market"
+    EXCHANGE = "exchange"
+    INSTRUMENT = "instrument"
+    INDEX = "index"
+    SECTOR = "sector"
+
+
+# ========== 行情语义 ==========
+
+
+class BarFrequency(str, Enum):
+    """Canonical Bar 频率（第三方 1min/D/day 等由 mapper 转换）
+
+    timestamp 语义统一为 Bar 结束时间。
+    """
+
+    M1 = "1m"
+    M5 = "5m"
+    M15 = "15m"
+    M30 = "30m"
+    H1 = "1h"
+    D1 = "1d"
+    W1 = "1w"
+
+
+class AdjustmentType(str, Enum):
+    """复权类型。
+
+    Bar 只存 Raw OHLCV，不内嵌复权因子；复权因子是独立数据集
+    AdjustmentFactor（见 DATA-DICTIONARY，Planned）。
+    V1 唯一支持 NONE；FORWARD / BACKWARD 仅为 Catalog/未来扩展保留，
+    AdjustmentFactor 数据集实现前不得假装支持。
+    """
+
+    NONE = "none"
+    # reserved：仅为未来扩展保留
+    FORWARD = "forward"
+    BACKWARD = "backward"
+
+
+class SectorType(str, Enum):
+    """板块/行业分类类型"""
+
+    INDUSTRY = "industry"
+    CONCEPT = "concept"
+    REGION = "region"
+    CUSTOM = "custom"
+
+
+# ========== 单位 ==========
+
+
+class Unit(str, Enum):
+    """Canonical 计量单位。
+
+    percent 语义固定为：1.23 表示 1.23%（ratio 型 provider 数据由 mapper *100）。
+    """
+
+    CNY = "cny"
+    CNY_PER_SHARE = "cny_per_share"
+    SHARE = "share"
+    PERCENT = "percent"
+    RATIO = "ratio"
+    COUNT = "count"
+
+
+# ========== Runtime / 事件（契约定义，Stream/Replay 归 market runtime）==========
+
+
+class MarketEventType(str, Enum):
+    """市场事件类型。
+
+    定义（见 SPEC「MarketEvent 契约」）：具有市场时间语义、会改变市场参与者
+    可观察信息集的市场事实事件。分两大类：
+
+    - Structured：Bar / Quote / Tick / Session / CorporateAction / MarketSnapshot
+    - Unstructured：News / Announcement / Policy（payload 是文本，事件协议结构化）
+
+    Live Stream 与 Historical Replay 产出同一套事件（Live/Replay 同构）。
+    枚举存在不代表已实现；实现状态见 SPEC「事件实现范围」。
+    """
+
+    # ========== Structured ==========
+    BAR = "bar"
+    QUOTE = "quote"  # planned
+    TICK = "tick"  # reserved
+    SESSION_PRE_OPEN = "session_pre_open"
+    SESSION_OPEN = "session_open"
+    SESSION_BREAK_START = "session_break_start"
+    SESSION_BREAK_END = "session_break_end"
+    SESSION_CLOSE = "session_close"
+    EXCHANGE_STATE_SNAPSHOT = "exchange_state_snapshot"  # T4R：交易所状态基线（事实）
+    EXCHANGE_STATE_EVENT = "exchange_state_event"  # T4R：交易所状态推进（transition）
+    TRADING_STATE = "trading_state"
+    PRICE_LIMIT = "price_limit"
+    DAILY_STATE_SNAPSHOT = "daily_state_snapshot"
+    CORPORATE_ACTION = "corporate_action"  # reserved
+    MARKET_SNAPSHOT = "market_snapshot"  # reserved
+    # ========== Unstructured ==========
+    NEWS = "news"  # planned
+    ANNOUNCEMENT = "announcement"  # planned
+    POLICY = "policy"  # reserved
+    # ========== Runtime 辅助 ==========
+    TIMER = "timer"
+
+
+class MarketStreamMode(str, Enum):
+    """市场事件流模式：实时流 或 历史重放"""
+
+    LIVE = "live"
+    REPLAY = "replay"
+
+
+# A股交易时段（本地时间 Asia/Shanghai）
+SESSION_PRE_OPEN_TIME: Final[str] = "09:15"
+SESSION_OPEN_TIME: Final[str] = "09:30"
+SESSION_BREAK_START_TIME: Final[str] = "11:30"
+SESSION_BREAK_END_TIME: Final[str] = "13:00"
+SESSION_CLOSE_TIME: Final[str] = "15:00"
+MARKET_TIMEZONE: Final[str] = "Asia/Shanghai"

quant_core/app/data/domain/trading_quantity_value.py

@@ -0,0 +1,57 @@
+"""交易数量的纯领域值，不依赖持久化或运行框架。"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class TradingQuantityRule:
+    min_buy_quantity: int
+    buy_quantity_step: int
+    min_sell_quantity: int
+    sell_quantity_step: int
+
+    def __post_init__(self) -> None:
+        if (
+            min(
+                self.min_buy_quantity,
+                self.buy_quantity_step,
+                self.min_sell_quantity,
+                self.sell_quantity_step,
+            )
+            <= 0
+        ):
+            raise ValueError("交易数量规则必须为正数")
+
+    def buy_quantity(self, requested: int) -> int:
+        if requested < self.min_buy_quantity:
+            return 0
+        return (
+            self.min_buy_quantity
+            + ((requested - self.min_buy_quantity) // self.buy_quantity_step)
+            * self.buy_quantity_step
+        )
+
+    def sell_quantity(self, requested: int, held: int) -> int:
+        if requested <= 0 or held <= 0:
+            return 0
+        if requested >= held:
+            return held
+        regular = 0
+        if requested >= self.min_sell_quantity:
+            regular = (
+                self.min_sell_quantity
+                + ((requested - self.min_sell_quantity) // self.sell_quantity_step)
+                * self.sell_quantity_step
+            )
+        # 整百市场持有零股时，可单次卖出零股部分并留下整手余额。
+        odd_lot = 0
+        if self.sell_quantity_step > 1 and self.min_sell_quantity == self.sell_quantity_step:
+            remainder = held % self.sell_quantity_step
+            if remainder and requested >= remainder:
+                candidate = (
+                    remainder
+                    + ((requested - remainder) // self.sell_quantity_step) * self.sell_quantity_step
+                )
+                if held - candidate >= self.min_sell_quantity:
+                    odd_lot = candidate
+        return max(regular, odd_lot)

quant_core/app/data/exceptions.py

@@ -0,0 +1,95 @@
+"""
+Market Domain 业务异常 - Domain owns semantics
+
+具体业务错误由本 Domain 自定义并继承 common 的通用异常机制（common/exceptions/base.py）。
+"""
+
+from quant_core.common.exceptions.base import AppException, NotFoundException
+
+
+class MarketDataNotSyncedException(AppException):
+    """请求数据未同步到本地。
+
+    语义：Market 域本地优先，数据缺口显式报错并提示 sync，
+    禁止隐式调用外部 Provider fallback（保证回测可复现）。
+    """
+
+    error_code = "MARKET_DATA_NOT_SYNCED"
+    http_status = 409
+
+    def __init__(self, message: str = "市场数据未同步，请先执行数据同步"):
+        super().__init__(message)
+
+
+class InstrumentNotFoundException(NotFoundException):
+    """标的不存在"""
+
+    error_code = "MARKET_INSTRUMENT_NOT_FOUND"
+    http_status = 404
+
+    def __init__(self, instrument_id: str | None = None):
+        message = f"标的不存在: {instrument_id}" if instrument_id else "标的不存在"
+        super().__init__(message)
+
+
+class MarketDataValidationError(AppException):
+    """数据校验失败（脏数据不静默入库）"""
+
+    error_code = "MARKET_DATA_VALIDATION_ERROR"
+    http_status = 422
+
+    def __init__(self, message: str = "市场数据校验失败"):
+        super().__init__(message)
+
+
+class MarketProviderException(AppException):
+    """外部 Provider 调用失败"""
+
+    error_code = "MARKET_PROVIDER_ERROR"
+    http_status = 502
+
+    def __init__(self, message: str = "外部数据源调用失败"):
+        super().__init__(message)
+
+
+class _MarketDataQualityException(AppException):
+    """数据质量类异常的公共基类：错误信息携带 dataset/instrument/range/reason"""
+
+    def __init__(
+        self,
+        dataset: str,
+        instrument_id: str | None = None,
+        start: str | None = None,
+        end: str | None = None,
+        reason: str = "",
+    ):
+        self.dataset = dataset
+        self.instrument_id = instrument_id
+        self.range = (start, end)
+        self.reason = reason
+        parts = [f"dataset={dataset}"]
+        if instrument_id:
+            parts.append(f"instrument={instrument_id}")
+        if start or end:
+            parts.append(f"range=[{start or '*'} ~ {end or '*'}]")
+        if reason:
+            parts.append(f"reason={reason}")
+        super().__init__("；".join(parts))
+
+
+class MarketDataIncompleteException(_MarketDataQualityException):
+    """数据不完整（存在无法解释的缺口），不可信可用
+
+    由 Verify / Backtest 前置检查抛出；缺口原因（停牌/零成交等）
+    V1 不推断，统一按 unexplained missing 处理。
+    """
+
+    error_code = "MARKET_DATA_INCOMPLETE"
+    http_status = 409
+
+
+class MarketDataInvalidException(_MarketDataQualityException):
+    """存在违反 Canonical 数据规则的数据，不可信可用"""
+
+    error_code = "MARKET_DATA_INVALID"
+    http_status = 409

quant_core/app/data/interface/adjustment_factor_query.py

@@ -0,0 +1,21 @@
+"""价格视图服务消费的复权因子查询能力。"""
+
+from datetime import date, datetime
+from typing import Protocol
+
+from quant_core.app.data.schema.adjustment_schema import (
+    AdjustmentFactorResponse as AdjustmentFactor,
+)
+
+
+class IAdjustmentFactorQuery(Protocol):
+    async def list_adjustment_factors(
+        self, instrument_id: str, start: date, end: date, known_at: datetime | None = None
+    ) -> list[AdjustmentFactor]: ...
+
+    async def get_adjustment_factor_on_or_before(
+        self,
+        instrument_id: str,
+        on_or_before: date | None = None,
+        known_at: datetime | None = None,
+    ) -> AdjustmentFactor | None: ...

quant_core/app/data/interface/market_data_query.py

@@ -0,0 +1,71 @@
+"""Market 的公开行情查询能力。"""
+
+from datetime import date, datetime
+from typing import Protocol
+
+from quant_core.app.data.schema.adjustment_schema import AdjustedBarSeries, BarViewRequest
+from quant_core.app.data.schema.market_schema import (
+    BarResponse,
+    InstrumentResponse,
+    TradingCalendarDayResponse,
+    TradingRuleResponse,
+)
+from quant_core.app.data.schema.pit_daily_window import PITDailyWindow
+from quant_core.app.data.schema.quote_schema import DailyBasicResponse
+
+
+class IMarketDataQuery(Protocol):
+    async def get_pit_daily_windows(
+        self,
+        instrument_id: str,
+        days: list[date],
+        next_days: list[date],
+        lookback: int,
+    ) -> tuple[PITDailyWindow, ...]: ...
+
+    async def get_instrument(self, instrument_id: str) -> InstrumentResponse: ...
+
+    async def search_instruments(
+        self,
+        keyword: str | None = None,
+        instrument_type: str | None = None,
+        exchange: str | None = None,
+        limit: int = 100,
+    ) -> list[InstrumentResponse]: ...
+
+    async def list_instruments_on(
+        self, on_date: date, limit: int = 10000
+    ) -> list[InstrumentResponse]: ...
+
+    async def list_daily_basic_at(
+        self, decision_time: datetime, limit: int = 10000
+    ) -> list[DailyBasicResponse]: ...
+
+    async def list_trading_rules(
+        self, instrument_ids: list[str], start: date, end: date
+    ) -> list[TradingRuleResponse]: ...
+
+    async def get_bars(
+        self,
+        instrument_id: str,
+        frequency: str,
+        start: datetime | None = None,
+        end: datetime | None = None,
+        limit: int = 1000,
+    ) -> list[BarResponse]: ...
+
+    async def get_adjusted_bars(
+        self,
+        instrument_id: str,
+        frequency: str,
+        view: BarViewRequest,
+        start: datetime | None = None,
+        end: datetime | None = None,
+        limit: int = 1000,
+    ) -> AdjustedBarSeries: ...
+
+    async def is_trading_day(self, exchange: str, trade_date: date) -> bool: ...
+
+    async def list_trading_days(
+        self, exchange: str, start: date, end: date
+    ) -> list[TradingCalendarDayResponse]: ...

quant_core/app/data/interface/market_data_verification.py

@@ -0,0 +1,20 @@
+"""Market 的公开数据覆盖校验能力：只读，不同步。"""
+
+from datetime import datetime
+from typing import Protocol
+
+from quant_core.app.data.schema.reliability_schema import DatasetHealthResult
+
+
+class IMarketDataVerification(Protocol):
+    async def verify_bars(
+        self, instrument_id: str, frequency: str, start: datetime, end: datetime
+    ) -> DatasetHealthResult: ...
+
+    async def verify_adjustment_factors(
+        self, instrument_id: str, frequency: str, start: datetime, end: datetime
+    ) -> DatasetHealthResult: ...
+
+    async def verify_corporate_actions(
+        self, instrument_id: str, start: datetime, end: datetime
+    ) -> DatasetHealthResult: ...

quant_core/app/data/interface/market_event_source.py

@@ -0,0 +1,11 @@
+"""Market 的公开原子事件流能力。"""
+
+from collections.abc import AsyncIterator
+from typing import Protocol, runtime_checkable
+
+from quant_core.app.data.schema.event_schema import MarketEvent, MarketStreamRequest
+
+
+@runtime_checkable
+class IMarketEventSource(Protocol):
+    def stream(self, request: MarketStreamRequest) -> AsyncIterator[MarketEvent]: ...

quant_core/app/data/interface/market_revision_query.py

@@ -0,0 +1,8 @@
+"""研究等下游读取 Market 当前同步版本的公开能力。"""
+
+from datetime import date
+from typing import Protocol
+
+
+class IMarketRevisionQuery(Protocol):
+    async def snapshot(self, start: date, end: date) -> dict[str, str]: ...

quant_core/app/data/interface/market_runtime_repository.py

@@ -0,0 +1,44 @@
+"""Market Runtime 所需的内部持久化能力。"""
+
+from datetime import date, datetime
+from typing import Protocol
+
+from quant_core.app.data.schema.corporate_action_schema import (
+    CorporateActionResponse as CorporateAction,
+)
+from quant_core.app.data.schema.history_schema import DailyFactResponse as InstrumentDailyFact
+from quant_core.app.data.schema.market_schema import BarResponse as Bar
+from quant_core.app.data.schema.market_schema import (
+    TradingCalendarDayResponse as TradingCalendarDay,
+)
+
+
+class IMarketRuntimeRepository(Protocol):
+    """Runtime 需要的持久化能力（只读历史数据）"""
+
+    async def list_bars(
+        self,
+        instrument_id: str,
+        frequency: str,
+        start: datetime | None = None,
+        end: datetime | None = None,
+        limit: int = 1000,
+    ) -> list[Bar]: ...
+
+    async def list_calendar_days(
+        self, exchange: str, start: date, end: date, only_open: bool = False
+    ) -> list[TradingCalendarDay]: ...
+
+    async def list_daily_facts(
+        self, instrument_id: str, start: date, end: date
+    ) -> list[InstrumentDailyFact]:
+        """日级官方交易事实（Q2 定案：回放状态来自日级事实的确定性展开）"""
+        ...
+
+    async def list_corporate_actions(
+        self,
+        instrument_ids: list[str],
+        start: date,
+        end: date,
+        known_at: datetime | None = None,
+    ) -> list[CorporateAction]: ...

quant_core/app/data/interface/market_time_slice_source.py

@@ -0,0 +1,11 @@
+"""Market 的公开历史时间片流能力。"""
+
+from collections.abc import AsyncIterator
+from typing import Protocol, runtime_checkable
+
+from quant_core.app.data.schema.event_schema import MarketStreamRequest, MarketTimeSlice
+
+
+@runtime_checkable
+class IMarketTimeSliceSource(Protocol):
+    def stream_slices(self, request: MarketStreamRequest) -> AsyncIterator[MarketTimeSlice]: ...

quant_core/app/data/schema/__init__.py

@@ -0,0 +1 @@
+"""Market Domain 请求/响应 Schema"""