# 数据接口 & 数据源一览

## 架构概览

```
前端 (fetch)  →  后端 FastAPI (路由层)  →  数据源服务层  →  第三方 API
```

- 前端统一走后端代理，前端不直接调第三方
- 每个接口有主源 + 备选降级，降级对前端透明
- 后端服务层有 SQLite 缓存（6-24h）和内存缓存（60s）

---

## 1. 股票搜索 `/api/stock/search`

| 项目 | 内容 |
|------|------|
| 前端调用 | `fetchStockSearch(keyword)` → `src/lib/stock-api.ts` |
| 路由 | `GET /api/stock/search?keyword=` → `routes/stock.py:12` |
| 用途 | 模糊搜索股票（名称/代码/拼音） |

**数据源：**

| 优先级 | 源 | 方式 | 可靠性 |
|--------|----|------|--------|
| 主选 | 腾讯智能搜索 `smartbox.gtimg.cn` | HTTPS JSONP | ⭐⭐⭐⭐⭐ 稳定，覆盖全 |
| 降级 | 腾讯行情接口 `qt.gtimg.cn` | HTTPS 文本 | ⭐⭐⭐⭐ 仅当 keyword=6位代码且搜索无结果时 |

---

## 2. 实时行情 `/api/stock/quote`

| 项目 | 内容 |
|------|------|
| 前端调用 | `fetchStockQuote(code)` → `src/lib/stock-api.ts:137` |
| 路由 | `GET /api/stock/quote?code=` → `routes/stock.py:38` |
| 用途 | 获取当前实时价格、开盘价、昨收、最高最低、成交量额、盘口 |
| 前端使用 | 股票详情页基本信息区（价格、涨跌幅、内外盘） |

**数据源：**

| 优先级 | 源 | 方式 | 可靠性 |
|--------|----|------|--------|
| 主选 | 腾讯行情 `qt.gtimg.cn` | HTTPS GBK文本 | ⭐⭐⭐⭐⭐ A股全量覆盖，无IP限流 |
| 降级 | 无 | — | 无响应则返回 404 |

**字段映射：** 名称、当前价、昨收、今开、最高、最低、成交量(手)、成交额(万)、外盘、内盘、涨跌额、涨跌幅

---

## 3. 历史 K 线 / 每日行情明细 `/api/stock/history`

| 项目 | 内容 |
|------|------|
| 前端调用 | `fetchStockHistory(code, days)` → `src/lib/stock-api.ts:182` |
| 路由 | `GET /api/stock/history?code=&days=` → `routes/stock.py:49` |
| 用途 | 日K前复权 OHLCV、涨跌幅、成交额 |
| 前端使用 | K线图 + 每日行情明细表（涨跌幅列） |

**数据源：**

| 优先级 | 源 | API | 可靠性 |
|--------|----|-----|--------|
| **主选** | **东方财富 push2his** | `kline/get` (curl_cffi chrome120) | ⚠️ IP 限流严重，常被拒 |
| **备选①** | **腾讯** | `web.ifzq.gtimg.cn` HTTPS | ⭐⭐⭐⭐⭐ 稳定可靠 |
| **备选②** | **新浪** | `money.finance.sina.com.cn` HTTPS | ⭐⭐⭐ 偶有超时 |

**当前实际工作源：** 腾讯（备选①）

**增强字段（东方财富源独有，走腾讯时无）：**
- `turnover` — 成交额（元）
- `amplitude` — 振幅（%）
- `changePercent` — 涨跌幅（%）（腾讯已通过连续收盘价计算补齐）
- `turnoverRate` — 换手率（%）

> 东方财富 push2his kline/get 与 fund-flow 同域名但路径不同，kline/get 有额外反爬。
> 即使使用 curl_cffi + chrome120 指纹也无法绕过，暂不修复。

---

## 4. 资金流向 `/api/stock/fund-flow`

| 项目 | 内容 |
|------|------|
| 前端调用 | `fetchStockFundFlow(code, name, days)` → `src/lib/stock-api.ts:248` |
| 路由 | `GET /api/stock/fund-flow?code=&name=&days=` → `routes/stock.py:147` |
| 用途 | 日度主力净流入、超大单/大单/中单/小单明细、占比、累计值 |
| 前端使用 | 每日行情明细表（主力净流入列 + 成交额列），资金流向图表 |

**数据源：**

| 优先级 | 源 | API | 可靠性 |
|--------|----|-----|--------|
| **主选** | **东方财富 push2his** | `fflow/daykline/get` (httpx) | ⭐⭐⭐⭐⭐ 稳定，无 IP 限流 |
| **备选** | **MX 妙想 API** | `mkapi2.dfcfs.com` (HTTP POST + apikey) | ⚠️ 有每日配额，多 key 轮询+缓存 |

**字段映射（东方财富）：**
```
f51=日期, f52=主力净流入, f53=小单, f54=中单, f55=大单, f56=超大单
f57-f61=各占比%, f62=收盘价, f63=涨跌幅
```

> MX API 当前保留为备选。配置 `MX_APIKEY` 或 `MX_APIKEY_{1-9}` 环境变量启用。
> MX 数据只有主力净流入 + 成交额，无大/中/小单拆分（拆分的比例是估算的）。

---

## 5. 公司概况 `/api/stock/profile`

| 项目 | 内容 |
|------|------|
| 前端调用 | `fetchCompanyProfile(code)` → `src/lib/stock-api.ts:337` |
| 路由 | `GET /api/stock/profile?code=` → `routes/stock.py:80` |
| 用途 | 公司全名、行业、高管、联系方式、注册信息、发行信息 |
| 前端使用 | 股票详情页「公司概况」tab |

**数据源：**

| 优先级 | 源 | API | 可靠性 |
|--------|----|-----|--------|
| 主选 | 东方财富 F10 | `emweb.securities.eastmoney.com` HTTPS | ⭐⭐⭐⭐ 稳定，24h 缓存 |
| 降级 | 无 | — | — |

---

## 6. 财务指标 `/api/stock/financial`

| 项目 | 内容 |
|------|------|
| 前端调用 | `fetchFinancialData(code, years)` → `src/lib/stock-api.ts:415` |
| 路由 | `GET /api/stock/financial?code=&years=` → `routes/stock.py:91` |
| 用途 | 每股指标、盈利能力、成长能力、偿债能力、营运能力 |
| 前端使用 | 股票详情页「财务分析」tab（表格+图表） |

**数据源：**

| 优先级 | 源 | API | 可靠性 |
|--------|----|-----|--------|
| 主选 | 东方财富数据中心 | `datacenter.eastmoney.com` HTTPS | ⭐⭐⭐⭐⭐ 稳定，6h 缓存 |
| 降级 | 无 | — | — |

---

## 7. 主营构成 `/api/stock/business-segments`

| 项目 | 内容 |
|------|------|
| 前端调用 | `fetchBusinessSegments(code, byType, years)` → `src/lib/stock-api.ts:382` |
| 路由 | `GET /api/stock/business-segments?code=&by_type=&years=` → `routes/stock.py:119` |
| 用途 | 收入构成（按产品/行业/地区）、成本构成、利润占比、毛利率 |
| 前端使用 | 股票详情页「经营分析」tab（饼图） |

**数据源：**

| 优先级 | 源 | API | 可靠性 |
|--------|----|-----|--------|
| 主选 | 东方财富数据中心 | `datacenter.eastmoney.com` HTTPS | ⭐⭐⭐⭐⭐ 稳定，6h 缓存 |
| 降级 | 无 | — | — |

---

## 8. 板块资金流向 `/api/sectors`

| 项目 | 内容 |
|------|------|
| 前端调用 | `fetchSectors(type)` → `src/lib/stock-api.ts:461` |
| 路由 | `GET /api/sectors?type=` → `routes/sectors.py:9` |
| 用途 | 行业/概念板块列表，按主力净流入排序 |
| 前端使用 | `/sectors` 板块资金流向页面 |

**数据源：**

| 优先级 | 源 | API | 可靠性 |
|--------|----|-----|--------|
| **主选** | **东方财富 push2** | `push2.eastmoney.com` (curl_cffi chrome120) | ⭐⭐⭐ 有 IP 限流，60s 内存缓存 + session 重建 |
| **备选** | **AkShare** | `ak.stock_fund_flow_industry/concept` | ⭐⭐ 慢（同步调用），列名需适配 |

**字段映射（东方财富 push2）：**
```
f62=主力净流入, f184=主力净流入占比
f66/f69=超大单净流入/占比, f72/f75=大单净流入/占比
f78/f81=中单净流入/占比, f84/f87=小单净流入/占比
f70=成交额
```

> push2.eastmoney.com 有较激进的 IP 限流。通过 curl_cffi 模拟浏览器 TLS 指纹 + 持久化 session + 60s 缓存 + 自动 UT 刷新 + session 重建来缓解。

---

## 9. 估值数据（外部）

> 股票详情页「估值分析」tab 的数据从外部服务加载（landing-page），不由后端代理。

---

## 数据源总结

| 第三方源 | 域名 | 使用场景 | 限流情况 | 是否需要反爬 |
|----------|------|---------|---------|------------|
| **腾讯财经** | `qt.gtimg.cn`, `web.ifzq.gtimg.cn`, `smartbox.gtimg.cn` | 搜索、行情、K线 | 基本无限流 | ❌ |
| **新浪财经** | `money.finance.sina.com.cn` | K线降级 | 宽松 | ❌ |
| **东方财富 push2his** | `push2his.eastmoney.com` | 资金流向、K线 | **部分路径限流**（kline/get 被禁，fflow/daykline/get 正常） | ✅ 需 curl_cffi |
| **东方财富 push2** | `push2.eastmoney.com` | 板块数据 | **IP 限流严重** | ✅ 需 curl_cffi |
| **东方财富数据中心** | `datacenter.eastmoney.com` | 财务数据、主营构成 | 宽松 | ❌ |
| **东方财富 F10** | `emweb.securities.eastmoney.com` | 公司概况 | 宽松 | ❌ |
| **MX 妙想** | `mkapi2.dfcfs.com` | 资金流向备选 | 每日配额（113错误码） | ❌ |
| **AkShare** | 同花顺/东方财富 | 板块降级 | 慢但无限制 | ❌ |