# 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 等热度监测
- 只做“情绪过热 / 异常传播 / 风险提示”
- 不直接进入买卖总分