行情、历史规则与公司行动¶
本页定义 MarketData 的输入、时点和验证规则。分红送转见权益模型，沪深预设见市场支持矩阵。
面向使用者的入口¶
分钟入口为 MarketData.from_minutes：日期日历仍只含交易日，行提供带 +08:00 的 timestamp 及 phase，frequency 为 1min／5min。每个日期／证券必须覆盖完整时段网格，详见分钟数据与时间契约。以下日线契约适用于 from_records／from_csv。
MarketData.from_records(rows, calendar=..., instruments=..., rules=..., source=..., actions=..., adjustments=...) 接受字典行；MarketData.from_csv(path, ...) 接受相同字段的 UTF-8 CSV（允许 BOM）。构造后数据不可修改，行自动按交易日和声明的证券顺序排列。交易日、证券、规则和来源由数据提供层组织一次，策略只接收验证后的对象，不重复填写规则。
完整可执行的人工数据示例见 examples/market_data.py。示例中的规则是测试输入，不是官方市场规则预设；来源版本只是标识，不代表引擎已经核验外部来源的真实性。
价格和状态¶
每个交易日、每个证券恰有一行，字段全部必需：
字段 |
契约 |
|---|---|
|
严格的日期和证券标识；不从文件名或列位置猜测 |
|
|
|
人民币元、原始未复权 OHLC；交易及停牌日必须明确提供估值，不隐式前填 |
|
股／份，非负整数；停牌、上市前及退市后为零 |
|
当日真实价格边界，两个值一起提供；确认无限制时两个字段均为空，不能缺列 |
上市前和退市后必须有显式行，价格及边界为空；它们在 prices("close") 等只读矩阵中返回 NaN。证券不能从已上市回到未上市，也不能在退市后重新交易。交易日历必须非空、严格递增，缺行、重复行、日历外数据和未知证券全部报错。引擎校验日历的一致性，不声称能够仅凭这些输入判断供应商是否遗漏了真实交易日。
报价内部按万分之一元精确存储，随后按当期最小价位检查。不支持的精度和非有限数值直接报错，不自动四舍五入行情。指标层获得元为单位的浮点数组；此数组不会被用于反向修正账本。复权研究价单独定义时点和用途，不作为记账价格输入。
按决策时点复权的研究视图¶
data.prices("close") 默认仍是整个输入的原始价矩阵；传 as_of="2025-01-06" 只返回截至该输入交易日的行。data.prices("close", adjustment="asof", as_of=...) 要求显式时点；策略可直接使用 ctx.history(symbol, adjustment="asof", bars=20)，其时点固定为当前回调收盘，无须手工传日期。OHLC 四个字段遵循同一规则，输出为只读浮点副本。
数据准备时通过 adjustments 提供 PriceAdjustment(action_id=..., factor=..., known_on=..., source=...)：
action_id必须对应输入中的公司行动，除权日和证券沿用该事件；不能重复或引用未知事件。factor是单次事件把除权日前价格换算到事件后价格口径的乘法系数，非供应商截至今天的累计复权因子。它必须正且有限，当前数值范围为1e-100至1e100。known_on为该因子可被研究者获知的日期，不早于事件公告。只有除权日已到、因子也已知时才能用于该历史视图。未来事件即便提前公告也不会提前调整。视图每跨过一次事件，就把该事件之前的行乘相应因子；事件日及之后不乘这个因子。多个日期事件按顺序组合，不跨事件的短窗口无须因子。请求的证券不会被其他证券缺失因子阻断。
已跨过事件而当时没有可用因子时明确失败，不退回原始价，不偷用后来补齐的值。复权计算出现数值溢出或下溢也明确失败。数据提供层必须完整声明相关事件；引擎不能从价格缺口证明供应商是否遗漏事件。
普通现金分红／送转的理论参考比例可由 ((前收盘价-每股参考现金额)/(1+参考送转比例))/前收盘价 得到。但参考现金额不一定等于账户应得现金，例如差异化分派中不参与分配的回购股份会改变摊薄口径，因此引擎不从账户 cash_per_share 自动猜复权因子。参考深交所公式说明与差异化分派公告示例。事件因子由提供层根据适用规则、行情或有来源的供应商数据准备，并记录口径；不同供应商的舍入与累计方式可能不同。
这是一种截至当前时点归一化的乘法前复权研究价，不是税后分红再投资净值、真实成交价或可直接代替账户收益的全收益指数。账户分红、税款及送转仍只在权益账本中处理一次。示例 historical_rules.py 将人工原始收盘价 [18.5, 18.5, 10] 换算为除权日视图 [10, 10, 10]，并独立保持原始成交和税务结果。
历史规则¶
Instrument 明确 symbol 和 stock／etf 分类。证券代码是标识，引擎不根据前缀推断市场制度。RuleBook 包含有起止日期（两端含）、来源与版本的 RulePeriod，禁止区间重叠，活动行情对应的日期必须存在规则。
TradingRule 表达价位、买卖最小量和增量、单笔数量上限、交易日交收延迟、是否允许零股清仓，以及卖出印花税率与双向过户费率。比例使用小数（例如 0.0005），最多六位小数。佣金、滑点和成交策略属于执行配置，不混入历史市场事实。买入数量满足最小量后按增量增加，交收延迟按后续交易日计数。规则可附 instrument_kind 约束，防止股票与 ETF 规则误用；自定义中性规则可留空。
历史规则查询按证券建立索引，不在每根行情上扫描整个市场的规则集合。过期和缺口不能退回最新规则。china_rules 可为显式市场分类构建 2020–2025 年普通股票／境内股票 ETF 的基础规则；每段保留来源和核验版本，不推断每日特殊状态或价格边界。
公司行动¶
CorporateAction 保留唯一事件标识、证券、公告／登记／除权日期和来源。cash_per_share 按每股税前金额填写并附 pay_date；bonus_per_share 按每股增加数量填写，附 share_credit_date 和 share_listing_date，分别表示入账和上市可卖。现金及送转应税金额支持六位小数；股票送转必须显式提供 taxable_bonus_amount_per_share，免税转增填零，不从送转比例猜税基。
distribution 至少包含现金或送转；登记必须早于除权，到账和上市不得早于除权，股份入账不能晚于上市。样本范围内的登记、除权、股份入账和上市日必须在输入日历中；现金到账落在非输入交易日时，在之后首个输入交易日开盘处理。允许样本结束后的到账／上市日期，结果保留未到账权益或未解锁股份。
配股、合并、退市作为其他显式事件保留，不暗中转换成分红。未支持行动影响持仓、登记权益、未到账权益或活动委托时明确失败。完全未持有且无相关权益、委托的证券发生该事件，不自动使整个组合失败。
同一证券同一除权日目前只接受一个综合公司行动。现金和送转应放在同一个分配事件中；不能用不同事件 ID 重复表示同一权益，也不猜测多个事件之间的股份计算基数。数据准备层须合并可确定的同日分派事实，不能合并的复合行动不在当前执行支持范围内。此限制避免持续目标在同日被重复复合调整。
复现标识与边界¶
fingerprint 覆盖交易日、证券顺序、原始行情、状态／价格边界、历史规则、公司行动、研究复权因子及其可知日期和来源。等价的 CSV 行顺序与规则输入顺序得到相同标识；声明的证券顺序则保留，因为后续共同现金的订单处理需要确定顺序。它用于识别输入变化，不替代供应商授权、来源核验或策略代码与参数的记录。
公开测试和示例只含人工行情。权益、税务及基础历史规则已有独立账本和政策依据，支持矩阵明确排除范围；真实 ETF 历史行情在授权本地环境完成案例对账，公开的是工具、汇总证据与输入标识，不附原始数据。不将通过字段校验或单个市场案例描述为所有市场情况都已正确覆盖。