stockbuddy/references/data-source-roadmap.md

StockBuddy 数据源升级方案（Phase 1）

目标

在不显著增加复杂度的前提下，提升 StockBuddy 对 A 股、港股、美股的：

• 数据可用性
• 数据源容错能力
• 报告可解释性
• 后续接入事件层的扩展性

当前原则：

• 先做 行情/基础面多源容错
• 再做 事件提示层
• 暂不把新闻/社媒直接并入总评分

---

已实测可用的免费数据源

行情 / K 线 / 基础字段

1. 腾讯财经

   • 适用：A 股、港股；美股实时快照也可用
   • 实测：quote 可用，K 线可用
   • 用途：主行情源

2. Yahoo Finance

   • 适用：美股
   • 实测：chart 接口可用
   • 用途：美股 K 线主源 / fallback

3. 东方财富部分行情接口

   • 适用：A 股
   • 实测：JSON 行情接口可用
   • 用途：A 股补充行情源 / fallback

公告 / 事件层

1. SEC

   • 适用：美股
   • 实测：JSON submissions 可用
   • 用途：美股公告与硬信息源

2. HKEX 披露网页

   • 适用：港股
   • 实测：搜索页可访问
   • 用途：港股公告层（需后续结构化适配）

3. 巨潮资讯

   • 适用：A 股
   • 实测：主页可访问；查询接口需单独适配
   • 用途：A 股公告层

---

不建议当前作为主源的来源

1. 新浪财经

   • 实测出现 403
   • 不适合作为稳定主源

2. 雪球 / 股吧 / 其他社区舆情

   • 可访问性和结构稳定性不如行情源
   • 更适合后续做热度/风险雷达，不适合先进入主链路

---

Phase 1 架构

1. 行情主链路

A 股 / 港股

• 主源：腾讯财经
• A 股 fallback：东方财富
• 输出：
  • 最新价
  • 涨跌幅
  • K 线
  • PE / PB / 市值 / 52 周高低点（能取则取）

美股

• 实时快照：腾讯财经可保留尝试
• K 线主源：Yahoo Finance
• fallback：后续可考虑 Finnhub / Twelve Data（若未来接受 API key）

2. 事件层（先只做扩展位，不进总分）

• A 股：巨潮资讯 / 交易所公告
• 港股：HKEX
• 美股：SEC

输出方式：

• 报告新增 “近期关键事件” 小节
• 默认只摘要 1-3 条
• 只做说明，不直接改变买卖评级

3. 社媒层（暂缓）

• 国内：雪球 / 股吧
• 海外：X / Reddit / Stocktwits

定位：

• 仅做热度、风险、情绪极端提示
• 不纳入核心评分

---

建议的代码改造顺序

Step 1：行情源抽象

将当前 analyze_stock.py 中的数据获取逻辑拆成可替换函数层：

• fetch_quote_primary()
• fetch_quote_fallback()
• fetch_kline_primary()
• fetch_kline_fallback()

建议后续拆到独立模块，例如：

• scripts/providers/tencent.py
• scripts/providers/eastmoney.py
• scripts/providers/yahoo.py
• scripts/providers/sec.py（后续事件层）

Step 2：统一数据模型

无论来源是什么，最终统一成内部字段：

• price
• change_pct
• volume
• pe
• pb
• market_cap
• 52w_high
• 52w_low
• currency
• source

并允许部分字段缺失，避免某一源缺字段时整个分析失败。

Step 3：报告补充数据来源

在最终输出中增加轻量数据源标记，例如：

• 行情源：腾讯财经
• K线源：腾讯财经 / Yahoo Finance
• 事件源：SEC / HKEX / 巨潮（未来）

用途：

• 方便排查数据异常
• 提高报告透明度

Step 4：事件层接入

在行情分析后，按市场类型追加事件抓取：

• A 股 -> 巨潮
• 港股 -> HKEX
• 美股 -> SEC

若事件抓取失败：

• 不影响主分析
• 仅在报告中省略事件小节或标注“暂无近期关键事件”

---

报告层建议

默认模板继续保持简洁，但可新增一个可选区块：

🧾 数据来源

• 行情：{quote_source}
• K线：{kline_source}
• 事件：{event_source 或 暂无}

📰 近期关键事件（后续接入）

• {事件1}
• {事件2}
• {事件3}

要求：

• 事件层不抢主体位置
• 不让报告变成资讯聚合页
• 保持 Telegram 等 IM 场景的短消息可读性

---

Phase 1 成功标准

满足以下条件即可认为第一阶段完成：

1. A 股分析：腾讯失败时可自动尝试东方财富补位
2. 美股分析：Yahoo K 线链路保持稳定
3. 输出中可看到实际使用的数据源
4. 单一来源失败不导致整份分析直接不可用
5. 事件层接口预留清晰，但暂不强耦合评分逻辑

---

后续 Phase 2 / 3

Phase 2：事件层

• 接入 SEC / HKEX / 巨潮
• 报告增加“近期关键事件”摘要

Phase 3：舆情雷达

• 接入雪球 / X / Reddit 等热度监测
• 只做“情绪过热 / 异常传播 / 风险提示”
• 不直接进入买卖总分