# OpenBB 集成指南（迁移版）

本页介绍 OpenBB v4 在本项目中的安装、配置、代码结构、回退机制、开发与测试、典型问题与后续计划。

## 1. 为什么选择 OpenBB v4
- 统一的路由接口：`from openbb import obb`
- 多数据提供商聚合（如 yfinance、polygon、fmp 等）
- 返回对象支持 `.results` 或 `.to_df()`，便于统一处理

## 2. 安装与环境准备
默认未安装 OpenBB（requirements.txt 中为可选依赖）。如需启用：

```bash
pip install "openbb>=4.1.0"
```

若你使用的是国内网络，建议配置合适的 PyPI 镜像或使用代理。

## 3. 配置说明
无需额外配置即可使用 `provider='yfinance'` 的公共数据。若你有付费数据源（如 polygon），可通过环境变量或 OpenBB 的 provider 配置进行设置。

## 4. 代码结构与调用方式
- Streamlit UI: `app/tabs/openbb_tab.py`
  - 自动检测 OpenBB 是否可用；若不可用则使用演示数据或合成数据
  - 优先路由：`obb.equity.price.historical`，ETF 回退至 `obb.etf.price.historical`
- 引擎模块: `src/jixia/engines/openbb_engine.py`
  - 延迟导入 OpenBB：首次调用时 `from openbb import obb`
  - 对 `.results` / `.to_df()` / `.to_dataframe()` 做兼容处理
- 辅助脚本: `src/jixia/engines/openbb_stock_data.py`
  - 延迟导入 `obb`
  - ETF 历史数据路径更新为 `obb.etf.price.historical`

## 5. 回退机制
- UI 层（OpenBB Tab）
  - 未安装 OpenBB 或请求失败：读取 `examples/data/*.json` 的演示数据；仍失败则生成合成数据
- 引擎层
  - 若未安装 OpenBB：返回 `success=False`，带错误消息，不影响其他功能

## 6. 开发与测试
- 单元测试建议：
  - 未安装 OpenBB 时，`_load_price_data` 能返回演示/合成数据
  - 已安装 OpenBB 时，能通过 `obb.equity.price.historical` 获取 DataFrame
- 在本仓库中新增了占位测试：`tests/test_openbb_fallback.py`

## 7. 典型问题排查
- ImportError: No module named 'openbb'
  - 未安装 OpenBB；按第2节安装。
- 返回空数据
  - 检查 symbol 是否正确；尝试更换 provider 或缩短时间窗口。
- 列名/索引不匹配
  - UI 中已对常见列/索引做了规范化处理；如仍异常，可打印原始 DataFrame 排查。

## 8. 后续计划
- 接入更多 OpenBB 路由（基本面、新闻、财报、因子）
- 与辩论系统结果联动，生成投资洞察卡片
- 支持用户自定义 provider 优先级与兜底策略