etf/framework_v2/config/CONFIG_DESIGN.md

V2 配置设计文档

概述

framework_v2 的配置系统基于 Pydantic Schema 验证，解决 V1 配置文件的 10 个问题。

---

核心设计原则

1. 类型安全（解决 V1 问题 #2）

# ❌ V1: 无验证
n_days: 25           # 如果是 "25"（字符串）会静默失败

# ✅ V2: Pydantic 验证
class FactorConfig(BaseModel):
    n_days: int = Field(default=25, ge=5, le=250)

验证效果：

# 错误：超出范围
factor: {n_days: 1000}
# → ValidationError: n_days 必须在 5-250 之间

# 错误：类型错误
factor: {n_days: "25"}
# → ValidationError: n_days 必须是整数

---

2. 敏感信息环境变量化（解决 V1 问题 #1）

# ❌ V1: 硬编码
flask_api:
  url: "https://k3s.tokenpluse.xyz"
ssh_tunnel:
  host: "8.218.167.69"
  key_path: "hk_ecs.pem"

# ✅ V2: 环境变量
data:
  sources:
    - type: "flask_api"
      url: "${FLASK_API_URL}"    # 从环境变量读取
    - type: "tushare"
      token: "${TUSHARE_TOKEN}"  # 从环境变量读取

环境变量替换：

# 支持格式
${VAR_NAME}                  # 必需环境变量
${VAR_NAME:default_value}    # 带默认值

# 示例
url: "${FLASK_API_URL}"                   # 必须设置
timeout: "${TIMEOUT:120}"                 # 默认 120

---

3. 资产池按类别分组（解决 V1 问题 #3）

# ❌ V1: 混合在一起
code_list:
  "399006.SZ":
    name: "创业板指"
    market: "A"
  "GC=F":
    name: "黄金"
    market: "COMMODITY"

# ✅ V2: 按类别分组
asset_pools:
  equity:                        # 股票资产
    "399006.SZ":
      name: "创业板指"
      market: "CN_EQUITY"
    "NDX":
      name: "纳指100"
      market: "US_EQUITY"
  
  commodity:                     # 商品资产
    "GC=F":
      name: "黄金"
      market: "COMMODITY"
  
  fixed_income:                  # 固定收益
    "931862.CSI":
      name: "短债指数"
      market: "FIXED_INCOME"

优势：

• ✅ 清晰的资产分类
• ✅ 支持分散化策略（每类选 Top-N）
• ✅ 易于扩展新资产类别

---

4. 精简注释 + 独立文档（解决 V1 问题 #4）

# ❌ V1: 30 行注释
# 931862.CSI = 中证0-9个月国债指数（短债指数）
# 数据范围：2007-12-31开始，约19年数据
# 久期：极短（<1年），波动极小，熊市防御效果最佳
# ...（共 30 行）
"931862.CSI":
  name: "短债指数"
  etf: null
  market: "BOND"

# ✅ V2: 精简注释 + description 字段
fixed_income:
  "931862.CSI":
    name: "短债指数"
    etf: null
    market: "FIXED_INCOME"
    description: "中证0-9个月国债指数，久期<1年，防御配置"

详细文档独立：

docs/
├── bond_analysis.md           # 债券收益归因分析
├── asset_pool_design.md       # 资产池设计说明
└── threshold_strategy.md      # 阈值策略文档

---

5. 统一阈值配置（解决 V1 问题 #6）

# ❌ V1: V2 + V3 共存，逻辑混乱
min_score: 0.0                    # V2 固定阈值

bond_threshold:                   # V3 动态阈值
  enabled: true
  bond_code: "931862.CSI"
  ratio: 1.0
  fill_bond: true

# ✅ V2: 统一配置
rotation:
  threshold:
    mode: "dynamic"               # 阈值模式: fixed / dynamic
    fixed_value: 0.0              # mode=fixed 时使用
    
    dynamic:                      # mode=dynamic 时使用
      reference: "931862.CSI"     # 参考标的
      ratio: 1.0                  # 倍数
      fallback_enabled: true      # 回退开关
      fallback_value: 0.0         # 回退值

模式切换：

# 固定阈值模式
threshold:
  mode: "fixed"
  fixed_value: 0.0

# 动态阈值模式
threshold:
  mode: "dynamic"
  dynamic:
    reference: "931862.CSI"
    ratio: 1.0

---

6. 标准化市场类型（解决 V1 问题 #8）

# ❌ V1: 随意定义
market: "A"         # A股
market: "US"        # 美股
market: "JP"        # 日本

# ✅ V2: 标准枚举
market: "CN_EQUITY"       # 中国股票
market: "US_EQUITY"       # 美国股票
market: "JP_EQUITY"       # 日本股票
market: "EU_EQUITY"       # 欧洲股票
market: "HK_EQUITY"       # 香港股票
market: "COMMODITY"       # 商品
market: "FIXED_INCOME"    # 固定收益

Python 枚举：

class MarketType(str, Enum):
    CN_EQUITY = "CN_EQUITY"
    US_EQUITY = "US_EQUITY"
    JP_EQUITY = "JP_EQUITY"
    EU_EQUITY = "EU_EQUITY"
    HK_EQUITY = "HK_EQUITY"
    COMMODITY = "COMMODITY"
    FIXED_INCOME = "FIXED_INCOME"

---

7. 多数据源降级策略（解决 V1 问题 #9）

# ❌ V1: 扁平化配置
flask_api:
  enabled: true
  url: "https://k3s.tokenpluse.xyz"

ssh_tunnel:
  enabled: true
  # ...

# ✅ V2: 优先级列表
data:
  sources:
    # 主数据源
    - type: "flask_api"
      enabled: true
      url: "${FLASK_API_URL}"
      timeout: 120
    
    # 备用数据源
    - type: "tushare"
      enabled: true
      token: "${TUSHARE_TOKEN}"
      timeout: 60
    
    # 降级数据源
    - type: "yfinance"
      enabled: false
      timeout: 120

降级逻辑：

for source in config.data.sources:
    if not source.enabled:
        continue
    
    try:
        data = fetch_from_source(source)
        return data
    except Exception as e:
        print(f"数据源 {source.type} 失败: {e}")
        continue

raise ValueError("所有数据源均失败")

---

8. 配置版本控制（解决 V1 问题 #10）

# ❌ V1: 无版本信息
# ETF轮动策略配置
# （无版本）

# ✅ V2: 元数据
metadata:
  version: "1.0.0"
  strategy: "rotation"
  description: "ETF轮动策略 V2 - 基于 framework_v2 架构"
  last_updated: "2024-04-16"

---

Schema 层次结构

RotationStrategyConfig
├── metadata: MetadataConfig
│   ├── version: str
│   ├── strategy: str
│   ├── description: str
│   └── last_updated: str
│
├── asset_pools: AssetPool
│   ├── equity: Dict[str, AssetConfig]
│   ├── commodity: Dict[str, AssetConfig]
│   └── fixed_income: Dict[str, AssetConfig]
│
├── benchmark: BenchmarkConfig
│   ├── code: str
│   └── name: str
│
├── backtest: BacktestConfig
│   ├── start_date: str
│   └── end_date: Optional[str]
│
├── factor: FactorConfig
│   ├── type: FactorType
│   ├── n_days: int (5-250)
│   ├── auto_day: bool
│   ├── min_days: int
│   └── max_days: int
│
├── rotation: RotationConfig
│   ├── select_num: int (1-10)
│   ├── diversified: bool
│   └── threshold: ThresholdConfig
│       ├── mode: ThresholdMode
│       ├── fixed_value: float
│       └── dynamic: DynamicThresholdConfig
│           ├── reference: str
│           ├── ratio: float
│           ├── fallback_enabled: bool
│           └── fallback_value: float
│
├── rebalance: RebalanceConfig
│   ├── min_hold_days: int (1-30)
│   ├── score_threshold: float (0-0.5)
│   └── trade_cost: float (0-0.01)
│
├── premium_control: PremiumControlConfig
│   ├── enabled: bool
│   ├── default_threshold: float
│   ├── mode: PremiumMode
│   ├── penalty_factor: float
│   └── market_overrides: Dict[str, MarketPremiumOverride]
│
└── data: DataConfig
    ├── sources: List[DataSourceConfig]
    ├── use_cache: bool
    └── cache_dir: str

---

使用示例

基础使用

from framework_v2.config import load_config

# 加载配置文件
config = load_config('rotation_example.yaml')

# 访问配置
print(f"动量窗口: {config.factor.n_days}")
print(f"选股数量: {config.rotation.select_num}")
print(f"数据源: {len(config.data.sources)} 个")

验证错误处理

from pydantic import ValidationError

try:
    config = load_config('invalid_config.yaml')
except ValidationError as e:
    print(f"配置验证失败: {e}")
    # 输出详细错误信息
    for error in e.errors():
        print(f"  - {error['loc']}: {error['msg']}")

环境变量

# 设置环境变量
export FLASK_API_URL="https://k3s.tokenpluse.xyz"
export TUSHARE_TOKEN="your_token_here"

# 加载配置（自动替换环境变量）
config = load_config('rotation_example.yaml')

---

文件结构

framework_v2/config/
├── __init__.py                # 导出模块
├── schemas.py                 # Pydantic Schema 定义（275 行）
├── loader.py                  # 配置加载器（237 行）
├── rotation_example.yaml      # 示例配置文件（195 行）
└── CONFIG_DESIGN.md           # 配置设计文档（本文件）

framework_v2/tests/
└── test_config.py             # 配置测试（286 行）

---

测试验证

测试结果

✓ 测试 1: 加载配置文件 - 通过
✓ 测试 2: 资产池配置 - 通过
✓ 测试 3: 阈值配置 - 通过
✓ 测试 4: 数据源配置 - 通过
✓ 测试 5: 验证错误处理 - 通过
✓ 测试 6: 环境变量替换 - 通过

总计: 6/6 通过

验证覆盖

验证项	测试内容	状态
配置加载	YAML 解析 + 环境变量替换	✅
类型验证	n_days 范围、必需字段	✅
资产池	股票/商品/债券分类	✅
阈值配置	固定/动态模式切换	✅
数据源	多源降级配置	✅
错误处理	ValidationError 捕获	✅

---

V1 vs V2 对比

特性	V1	V2	改进
类型安全	❌ 无验证	✅ Pydantic Schema	早期失败
敏感信息	❌ 硬编码	✅ 环境变量	安全性
资产分类	❌ 混合	✅ 按类别分组	可维护性
注释	❌ 冗长（30行）	✅ 精简 + 独立文档	可读性
阈值逻辑	❌ V2/V3 共存	✅ 统一配置	逻辑清晰
市场类型	❌ 随意字符串	✅ 标准枚举	一致性
数据源	❌ 扁平化	✅ 优先级列表	可靠性
版本控制	❌ 无	✅ 元数据	可追溯

---

迁移指南

从 V1 迁移到 V2

1. 更新配置文件结构

# V1
code_list:
  "399006.SZ":
    name: "创业板指"
    etf: "159915.SZ"
    market: "A"

# V2
asset_pools:
  equity:
    "399006.SZ":
      name: "创业板指"
      etf: "159915.SZ"
      market: "CN_EQUITY"

2. 更新市场类型

# V1 → V2 映射
"A" → "CN_EQUITY"
"US" → "US_EQUITY"
"HK" → "HK_EQUITY"
"COMMODITY" → "COMMODITY"
"BOND" → "FIXED_INCOME"

3. 更新阈值配置

# V1
min_score: 0.0
bond_threshold:
  enabled: true
  bond_code: "931862.CSI"
  ratio: 1.0

# V2
rotation:
  threshold:
    mode: "dynamic"
    dynamic:
      reference: "931862.CSI"
      ratio: 1.0

4. 更新数据源配置

# V1
flask_api:
  enabled: true
  url: "https://k3s.tokenpluse.xyz"

# V2
data:
  sources:
    - type: "flask_api"
      enabled: true
      url: "${FLASK_API_URL}"

---

最佳实践

1. 使用环境变量管理敏感信息

# .env 文件（不要提交到 Git）
FLASK_API_URL=https://k3s.tokenpluse.xyz
TUSHARE_TOKEN=your_token_here
SSH_HOST=8.218.167.69
SSH_KEY_PATH=/path/to/hk_ecs.pem

2. 为不同环境创建不同配置

config/
├── rotation_dev.yaml       # 开发环境
├── rotation_prod.yaml      # 生产环境
└── rotation_test.yaml      # 测试环境

3. 使用版本控制追踪配置变更

metadata:
  version: "1.0.0"
  last_updated: "2024-04-16"
  changelog:
    - "2024-04-16: 初始版本"

4. 定期验证配置

# 运行配置测试
python framework_v2/tests/test_config.py

---

未来优化

1. 配置热重载（无需重启策略）
2. 配置 diff 工具（对比版本差异）
3. 配置 UI 编辑器（可视化配置）
4. 配置模板系统（快速创建新策略）

---

版本历史

• 2024-04-16: 初始版本
  • Pydantic Schema 验证
  • 环境变量替换
  • 资产池分类
  • 统一阈值配置
  • 多数据源降级
  • 6/6 测试通过