fix(data): 自定义源比例字段单位改为显式声明 pct_unit 未声明 fail-closed

amplitude/turnover_rate 的百分制与小数制数值区间重叠(0.05 既可能是
0.05% 也可能是 5%), 截面中位数启发式不可判, 赌错即整体放大 100 倍,
违反 CONTRIBUTING §3.1 禁止启发式转换的约束。

- realtime 数据集新增 pct_unit: percent|decimal 显式声明, 声明即契约
  (percent 无条件 /100, decimal 无条件透传, 不受数值外观影响)
- 未声明时 change_pct 保留涨跌停 30% 上限的截面判定(物理可判),
  amplitude/turnover_rate 置 None 交 enriched 管道按价格/股本口径重算
  并记录 WARNING; 已配置 transforms 的列视为用户接管单位, 透传
- 配置解析/清洗/序列化全链路校验取值, 非 realtime 数据集声明即报错
- 契约测试重写覆盖声明优先、边界值、fail-closed 与 transforms 兼容

docs/custom-data-source.md

@@ -125,7 +125,23 @@ datasets:
 
 建议实时接口额外提供 `amount`、`change_pct`、`change_amount`、`amplitude`、`turnover_rate`、`name`。缺失时部分字段会由 pipeline 回算,但精度取决于可用输入。
 
-`change_pct` 和 `amplitude` 使用小数制,例如 `0.0366` 表示 `3.66%`(`turnover_rate` 同)。若接口直接返回百分数值 `3.66`,实时行情会按截面中位数自动归一为小数制,但仍建议接口直接提供小数制以避免小样本歧义。
+`change_pct`、`amplitude`、`turnover_rate` 统一使用小数制,例如 `0.0366` 表示 `3.66%`。百分制单位必须在 realtime 数据集上**显式声明**,不做数值猜测(数值无法区分两种单位:`0.05` 既可能是 0.05% 也可能是 5%):
+
+```yaml
+datasets:
+  realtime:
+    url: https://api.example.com/snapshot
+    pct_unit: percent   # 接口返回 3.66 表示 3.66%;小数制源声明 decimal 或省略
+```
+
+处理规则:
+
+| 声明 | 行为 |
+| --- | --- |
+| `pct_unit: percent` | `change_pct` / `amplitude` / `turnover_rate` 无条件 `/100` |
+| `pct_unit: decimal` | 三列原样透传 |
+| 未声明 | `change_pct` 按截面中位数归一(A 股涨跌停 30% 上限使两种单位物理可分);`amplitude` / `turnover_rate` **置 `None`** 交由 pipeline 按价格与股本口径重算,并记录 WARNING |
+| 列已配置 `transforms` | 视为用户已接管该列单位,原样透传 |
 
 ## 请求约定
 
@@ -273,8 +289,10 @@ cp docs/examples/custom-data-source/mock_source.yaml data/data_sources/mock_sour
   amount = 成交额
   change_pct = 涨跌幅 (小数, 0.0366 = 3.66%)
   change_amount = 涨跌额
-  amplitude = 振幅
-  turnover_rate = 换手率 (小数, 0.05 = 5%; 若上游返回 5 表示 5%, 配置 transforms: turnover_rate: "value / 100")
+  amplitude = 振幅 (小数, 0.024 = 2.4%)
+  turnover_rate = 换手率 (小数, 0.05 = 5%)
+  # 上游若返回百分数值 (3.66 表示 3.66%), 在 realtime 数据集声明 pct_unit: percent,
+  # 不要依赖数值自动识别; 逐列转换也可用 transforms: turnover_rate: "value / 100"
 
 分钟K (minute):
   symbol = 股票代码