add resilient CN market fallbacks and source metadata

references/data-source-roadmap.md

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

references/output_templates.md

@@ -12,6 +12,11 @@
 - **分析时间**：{时间}
 - **数据周期**：{周期}
 
+### 🧾 数据来源
+- **行情**：{行情源}
+- **K线**：{K线源}
+- **事件**：{事件源}
+
 ---
 
 ### {建议图标} 操作建议：{操作建议}
@@ -116,6 +121,7 @@
 ## 模板使用说明
 
 - 所有 `{占位符}` 根据脚本返回的 JSON 数据填充。
+- `{行情源}` / `{K线源}` 使用 `data_sources` 中的实际来源；若事件层尚未接入，`{事件源}` 填 `暂无`。
 - 最终输出必须是标准 Markdown 正文，不要放进 ``` 代码块。
 - 优先使用短段落、项目符号、卡片式结构；除非用户明确要求，否则尽量不要使用宽表格。
 - Telegram 等 IM 场景下，优先保证手机端可读性，避免一行承载过多字段。