🏗️ 项目重构：模块化清理完成

modules/documentation-suite/docs/openbb_integration/00_PROJECT_OVERVIEW.md

@@ -0,0 +1,38 @@
+# OpenBB 集成项目总览
+
+本目录构建了本项目中 OpenBB v4 集成的完整文档生态，包括架构、实现、测试、用户指南、文化融合与维护。
+
+## 目标
+- 以 OpenBB v4 作为统一市场数据路由入口（`from openbb import obb`）
+- 在未安装或不可用时，提供稳健的兜底策略（演示/合成数据）
+- 将集成能力与稷下学宫/八仙论道的产品体验深度融合
+
+## 核心组件
+- UI：`app/tabs/openbb_tab.py`（自动检测 OpenBB 可用性，提供回退）
+- 引擎：`src/jixia/engines/openbb_engine.py`、`src/jixia/engines/openbb_stock_data.py`
+- 示例/演示数据：`examples/data/*.json`
+
+## 用户旅程（摘要）
+```mermaid
+graph TD
+    A[用户启动应用] --> B[选择OpenBB标签页]
+    B --> C[查看数据可用性状态]
+    C --> D{OpenBB是否可用?}
+    D -->|是| E[选择股票符号]
+    D -->|否| F[使用演示数据]
+    E --> G[启动八仙论道]
+    F --> G
+    G --> H[查看辩论结果]
+    H --> I[导出分析报告]
+```
+
+## 快速链接
+- 实现指南（API 集成与回退策略）：[02_IMPLEMENTATION_GUIDE/api_integration_guide.md](../openbb_integration/02_IMPLEMENTATION_GUIDE/api_integration_guide.md)
+- 故障排查：[02_IMPLEMENTATION_GUIDE/troubleshooting_guide.md](../openbb_integration/02_IMPLEMENTATION_GUIDE/troubleshooting_guide.md)
+- 测试策略与报告：[03_TEST_DOCUMENTATION/](../openbb_integration/03_TEST_DOCUMENTATION/)
+- 用户指南：[04_USER_GUIDES/](../openbb_integration/04_USER_GUIDES/)
+
+## 维护与路线图
+- 版本说明与升级：见 [06_MAINTENANCE](../openbb_integration/06_MAINTENANCE/)
+
+> 注：本结构与 docs/AI_AGENT_TASKS/ROVODEV_PROJECT_INTEGRATION.md 的“文档架构”保持一致，以便多团队协作与交付。

modules/documentation-suite/docs/openbb_integration/01_ARCHITECTURE_DESIGN/data_flow_design.md

@@ -0,0 +1,3 @@
+# 数据流设计
+
+占位：将补充从 UI 输入 -> 引擎 -> OpenBB/provider -> DataFrame -> KPI/图表 的完整数据流与序列图。

modules/documentation-suite/docs/openbb_integration/01_ARCHITECTURE_DESIGN/deployment_strategy.md

@@ -0,0 +1,7 @@
+# 部署策略
+
+- OpenBB 作为可选依赖提供，默认不强制安装
+- 在需要时通过 `pip install "openbb>=4.1.0"` 启用
+- 国内网络场景建议使用镜像或代理
+
+后续将补充 CI/CD、环境矩阵与缓存策略。

modules/documentation-suite/docs/openbb_integration/01_ARCHITECTURE_DESIGN/integration_patterns.md

@@ -0,0 +1,7 @@
+# 集成模式
+
+- 路由优先：`obb.equity.price.historical`，必要时回退到 `obb.etf.price.historical`
+- 结果标准化：兼容 `.to_df()` / `.to_dataframe()` / 原始对象 -> DataFrame
+- 列规范化：Date / Close 归一化，保证后续图表与 KPI 计算稳定
+
+后续将补充更多模式（基本面/新闻/宏观等）。

modules/documentation-suite/docs/openbb_integration/01_ARCHITECTURE_DESIGN/system_architecture.md

@@ -0,0 +1,17 @@
+# 系统架构（Qwen 输出）
+
+本章描述 OpenBB 集成在系统中的位置、边界与依赖。
+
+## 组件边界
+- UI 层：`app/tabs/openbb_tab.py`
+- 引擎层：`src/jixia/engines/openbb_engine.py`、`openbb_stock_data.py`
+- 数据层：OpenBB provider（yfinance、polygon、fmp 等）与演示/合成数据
+
+## 关键架构决策
+- 使用 OpenBB v4 统一路由
+- 延迟导入（lazy import）降低对未安装环境的侵入
+- 明确回退机制，保证用户体验连续性
+
+## 后续补充
+- 数据流与上下行依赖
+- 与“八仙论道”系统的耦合点与解耦方案

modules/documentation-suite/docs/openbb_integration/02_IMPLEMENTATION_GUIDE/api_integration_guide.md

@@ -0,0 +1,56 @@
+# 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 优先级与兜底策略

modules/documentation-suite/docs/openbb_integration/02_IMPLEMENTATION_GUIDE/core_engine_implementation.md

@@ -0,0 +1,10 @@
+# 核心引擎实现（Claude 输出）
+
+- 延迟导入 OpenBB
+- 统一结果转 DataFrame
+- 列/索引规范化与时间窗口裁剪
+- 失败时不影响其他功能（返回 success=False 或进入兜底路径）
+
+参考代码位置：
+- `src/jixia/engines/openbb_engine.py`
+- `src/jixia/engines/openbb_stock_data.py`

modules/documentation-suite/docs/openbb_integration/02_IMPLEMENTATION_GUIDE/troubleshooting_guide.md

@@ -0,0 +1,8 @@
+# 故障排查指南
+
+常见问题与解决方案：
+- ImportError: No module named 'openbb' → 安装 `openbb>=4.1.0`
+- 返回空数据 → 检查 symbol，尝试其他 provider 或缩短时间窗口
+- 列名/索引不匹配 → 打印原始 DataFrame，参考 UI 中的规范化逻辑
+
+更多请参考：[api_integration_guide.md](./api_integration_guide.md) 第 7 节。

modules/documentation-suite/docs/openbb_integration/02_IMPLEMENTATION_GUIDE/ui_enhancement_guide.md

@@ -0,0 +1,6 @@
+# UI 增强指南
+
+- 状态提示（OpenBB 可用/不可用）
+- 动态参数（symbol、时间窗口）
+- KPI 卡片（最新价、近30日涨幅、最大回撤）
+- 未来扩展位：基本面、新闻、情绪、宏观等

modules/documentation-suite/docs/openbb_integration/03_TEST_DOCUMENTATION/performance_benchmarks.md

@@ -0,0 +1,3 @@
+# 性能基准
+
+占位：记录不同 provider 与窗口设置下的响应时间、吞吐、内存曲线。

modules/documentation-suite/docs/openbb_integration/03_TEST_DOCUMENTATION/quality_assurance_report.md

@@ -0,0 +1,6 @@
+# 质量保证报告
+
+- 代码规范检查
+- 文档完整性
+- 测试通过率
+- 文化准确性与用户体验评估（与 05_CULTURAL_INTEGRATION 联动）

modules/documentation-suite/docs/openbb_integration/03_TEST_DOCUMENTATION/test_results_report.md

@@ -0,0 +1,3 @@
+# 测试结果报告
+
+占位：记录关键用例、环境、通过率与截图/日志摘要。

modules/documentation-suite/docs/openbb_integration/03_TEST_DOCUMENTATION/test_strategy.md

@@ -0,0 +1,6 @@
+# 测试策略（Gemini 输出）
+
+- 未安装 OpenBB：UI 能回退到演示/合成数据
+- 已安装 OpenBB：能成功调用 `obb.equity.price.historical`
+- 数据清洗后具有 Date/Close 列，KPI 计算不报错
+- 覆盖边界：空数据、异常路由、索引为日期等

modules/documentation-suite/docs/openbb_integration/04_USER_GUIDES/best_practices.md

@@ -0,0 +1,6 @@
+# 最佳实践
+
+- 将 OpenBB 作为轻依赖，必要时再安装
+- 使用统一的 DataFrame 规范化逻辑
+- 谨慎处理长时间窗口与缺失数据
+- 提供清晰的状态反馈与兜底

modules/documentation-suite/docs/openbb_integration/04_USER_GUIDES/configuration_guide.md

@@ -0,0 +1,5 @@
+# 配置指南
+
+- 默认使用公共数据（yfinance）
+- 付费 provider（polygon/fmp 等）可通过 OpenBB provider 配置或环境变量设置
+- UI 参数：symbol、时间窗口、KPI 展示

modules/documentation-suite/docs/openbb_integration/04_USER_GUIDES/getting_started.md

@@ -0,0 +1,8 @@
+# 入门指南
+
+1) 可选安装：`pip install "openbb>=4.1.0"`
+2) 运行应用，进入 OpenBB 标签页
+3) 输入股票/ETF 代码（如 AAPL），选择时间窗口
+4) 若未安装 OpenBB，将自动使用演示数据
+
+更多：见 [API 实现指南](../02_IMPLEMENTATION_GUIDE/api_integration_guide.md)。

modules/documentation-suite/docs/openbb_integration/04_USER_GUIDES/immortal_debate_tutorial.md

@@ -0,0 +1,3 @@
+# 八仙论道教程（占位）
+
+将补充如何基于市场数据触发与解读“八仙论道”的步骤与最佳实践。

modules/documentation-suite/docs/openbb_integration/05_CULTURAL_INTEGRATION/cultural_accuracy_guidelines.md

@@ -0,0 +1,3 @@
+# 文化准确性指南（占位）
+
+将补充文化审核检查点、示例与注意事项。

modules/documentation-suite/docs/openbb_integration/05_CULTURAL_INTEGRATION/immortal_characteristics.md

@@ -0,0 +1,3 @@
+# 八仙特质（占位）
+
+将列举八仙角色特性，并映射到数据分析风格/观点生成策略。

modules/documentation-suite/docs/openbb_integration/05_CULTURAL_INTEGRATION/jixia_philosophy_in_code.md

@@ -0,0 +1,4 @@
+# 稷下学宫哲学在代码中的体现（占位）
+
+- 开放包容、百家争鸣 → 多 provider 聚合与辩论系统
+- 求同存异、理性决策 → 数据驱动 + 观点对齐

modules/documentation-suite/docs/openbb_integration/06_MAINTENANCE/future_roadmap.md

@@ -0,0 +1,5 @@
+# 路线图
+
+- v1.x：路由扩展、稳定性增强
+- v2.x：高级分析与移动端适配
+- v3.x：企业级能力与治理

modules/documentation-suite/docs/openbb_integration/06_MAINTENANCE/known_issues.md

@@ -0,0 +1,4 @@
+# 已知问题
+
+- 某些 symbol 在特定 provider 下返回为空或字段不齐
+- 长窗口数据清洗后为空的边界情况

modules/documentation-suite/docs/openbb_integration/06_MAINTENANCE/release_notes.md

@@ -0,0 +1,4 @@
+# 发布说明
+
+- 参考：`docs/development/RELEASE_v2.0.0.md`
+- 在此记录 OpenBB 集成相关的变更、修复与新增功能。

modules/documentation-suite/docs/openbb_integration/06_MAINTENANCE/upgrade_guide.md

@@ -0,0 +1,5 @@
+# 升级指南
+
+- OpenBB 版本升级注意事项
+- provider 配置兼容性
+- 本项目接口变化记录

modules/documentation-suite/docs/openbb_integration/README.md

@@ -0,0 +1,36 @@
+# OpenBB 集成文档索引
+
+本目录提供 OpenBB v4 在本项目中的完整集成文档。
+
+- 00 项目总览：./00_PROJECT_OVERVIEW.md
+- 01 架构设计（Qwen 输出）：
+  - ./01_ARCHITECTURE_DESIGN/system_architecture.md
+  - ./01_ARCHITECTURE_DESIGN/data_flow_design.md
+  - ./01_ARCHITECTURE_DESIGN/integration_patterns.md
+  - ./01_ARCHITECTURE_DESIGN/deployment_strategy.md
+- 02 实现指南（Claude 输出）：
+  - ./02_IMPLEMENTATION_GUIDE/core_engine_implementation.md
+  - ./02_IMPLEMENTATION_GUIDE/api_integration_guide.md
+  - ./02_IMPLEMENTATION_GUIDE/ui_enhancement_guide.md
+  - ./02_IMPLEMENTATION_GUIDE/troubleshooting_guide.md
+- 03 测试文档（Gemini 输出）：
+  - ./03_TEST_DOCUMENTATION/test_strategy.md
+  - ./03_TEST_DOCUMENTATION/test_results_report.md
+  - ./03_TEST_DOCUMENTATION/performance_benchmarks.md
+  - ./03_TEST_DOCUMENTATION/quality_assurance_report.md
+- 04 用户指南：
+  - ./04_USER_GUIDES/getting_started.md
+  - ./04_USER_GUIDES/immortal_debate_tutorial.md
+  - ./04_USER_GUIDES/configuration_guide.md
+  - ./04_USER_GUIDES/best_practices.md
+- 05 文化融合文档：
+  - ./05_CULTURAL_INTEGRATION/immortal_characteristics.md
+  - ./05_CULTURAL_INTEGRATION/jixia_philosophy_in_code.md
+  - ./05_CULTURAL_INTEGRATION/cultural_accuracy_guidelines.md
+- 06 维护：
+  - ./06_MAINTENANCE/release_notes.md
+  - ./06_MAINTENANCE/upgrade_guide.md
+  - ./06_MAINTENANCE/known_issues.md
+  - ./06_MAINTENANCE/future_roadmap.md
+
+快速入口：API 实现指南 → ./02_IMPLEMENTATION_GUIDE/api_integration_guide.md