feat: 接入同花顺官方SDK，新增v2数据接口，股票详情K线改用v2(前复权日K)

- vendor 同花顺官方 SDK 到 backend/sdk（含K线>10年自动切片、重试、拼音首字母检索兜底） - 新增 /api/v2 路由：行情/估值/财务/日历/指数/K线/标的检索 - 股票详情页K线改用 v2 同花顺接口（前复权日K+总手+按昨收涨跌幅） - 密钥仅后端持有，响应/日志无泄露 - 新增 run_local.sh 本地直接拉起（不再依赖 docker）
2026-08-28 02:09:49 +08:00
parent 82006f7cf9
commit d5516b72d7
13 changed files with 2465 additions and 5 deletions
@@ -1,5 +1,7 @@
 # 数据接口 & 数据源一览

+> 📖 同花顺官方金融数据 API 能力整理见 [hithink-financial-api.md](./hithink-financial-api.md)
+
 ## 架构概览

 ```
@@ -0,0 +1,188 @@
+# 同花顺金融数据 API（HiThink Financial API）接口能力整理
+
+> 数据源参考：https://github.com/HiThink-Tech/Financial-API · 文档：https://fuyao.aicubes.cn/docs/quickstart/
+> 本文档整理官方 REST / MCP / CLI / Python / 本地库 各接入方式的能力清单，供后续开发评估使用。
+
+## 一句话概览
+
+同花顺官方维护的 **A 股金融数据服务**，面向 AI Agent、量化研究和应用开发者。
+一个 API Key 即可访问数据，提供 **六种接入方式**：REST API、托管 MCP、Node.js CLI、Python SDK、
+本地 DuckDB 数据库（marketdb）和 Agent Skill。MIT 许可，约 1.9k stars。
+
+**支持**：A股股票、指数与板块、公募基金（含 ETF/LOF）、衍生特色数据（涨跌停/连板/异动/热榜/龙虎榜）、全市场数据导出。
+**暂不支持**：期货、分钟K、tick、海外市场、宏观数据、新闻公告原文、研报原文。
+
+---
+
+## 认证与调用
+
+| 项目 | 内容 |
+|------|------|
+| Base URL | `https://fuyao.aicubes.cn` |
+| 认证 | 请求头 `X-api-key: <your-key>`（与同花顺账号绑定） |
+| Key 获取 | 官网注册 → 「API Key 管理」创建；关闭弹窗后无法再看完整 Key，需妥善保存 |
+| 响应信封 | `{ code, message, request_id, data }`，`code=0` 表示成功（HTTP 恒为 200） |
+| 环境变量 | `HITHINK_FINANCE_API_KEY` |
+| 常见错误 | `2001` Key 缺失/无效；`2003` 无权限需开通 |
+
+**Agent 集成（推荐）**：`npx skills add HiThink-Tech/Financial-API --skill hithink-finance -g --yes`
+Agent 会在 API / MCP / CLI / Python 间自动选择合适方式，并对大结果自动落盘。
+
+---
+
+## 接入方式一览
+
+| 方式 | 说明 |
+|------|------|
+| **REST API** | `GET` + `X-api-key`，最通用 |
+| **MCP** | 4 个服务端点，供 AI Agent 直接调用 |
+| **Node.js CLI** | npm 包 `@hithink-tech/hithink-finance-cli` |
+| **Python SDK** | `pip install -e ./python` |
+| **本地 DuckDB** | `marketdb` 本地库，支持增量同步 + SQL + 复权 |
+| **Agent Skill** | 一键安装，自动选择最优接入 |
+
+---
+
+## REST API 能力清单（GET + X-api-key）
+
+### 基础 / 元信息
+
+| 接口路径 | 功能 | 主要参数 |
+|----------|------|---------|
+| `/api/meta/tickers/search` | 跨市场标的检索（代码/名称/拼音） | `q`*、`exchange`、`asset_type`、`limit`(≤50) |
+| `/api/meta/tickers/list` | 分页获取代码表 | `asset_type`、`limit`(≤10000)、`offset` |
+
+### A股行情
+
+| 接口路径 | 功能 | 主要参数 |
+|----------|------|---------|
+| `/api/a-share/prices/snapshot` | 行情快照（单只/多只/全市场） | `thscodes`、`limit`、`offset` |
+| `/api/a-share/prices/historical` | 单只标的日K（窗口≤10年） | `thscode`*、`interval`(1d)、`start`*、`end`*、`adjust`(none/forward/backward)、`offset` |
+| `/api/a-share/auction/snapshot` | 集合竞价快照 | `thscodes`*、`stage`(live/final) |
+| `/api/a-share/auction/short-term-benchmark` | 短线风向标竞价基准 | `date`(yyyy-MM-dd) |
+| `/api/a-share/calendar/trading-days` | 近一年交易日序列 | 无 |
+
+### A股财务 / 复权 / 估值
+
+| 接口路径 | 功能 | 主要参数 |
+|----------|------|---------|
+| `/api/a-share/financials/income-statements` | 合并利润表多期序列 | `thscode`*、`period`(annual/quarterly)*、`limit`(1-20) 或 `start`+`end` |
+| `/api/a-share/financials/balance-sheets` | 合并资产负债表 | 同上 |
+| `/api/a-share/financials/cash-flow-statements` | 合并现金流量表 | 同上 |
+| `/api/a-share/financials/indicators` | 五类财务指标 | `thscode`*、`report`*(yyyy-1~yyyy-4) |
+| `/api/a-share/corporate-actions/adjustment-factors` | 分红/送股/配股事件流 | `thscode`*、`from`、`to` |
+| `/api/a-share/valuations/snapshot` | 估值快照（PE TTM/MRQ、PB、PS、PCF） | 批量查询 |
+
+### 指数与板块
+
+| 接口路径 | 功能 | 主要参数 |
+|----------|------|---------|
+| `/api/a-share-index/catalog/ths-index-list` | 同花顺指数清单 | `tag`(cn_concept/region/tszs/industry) |
+| `/api/a-share-index/constituents/ths-stock-list` | 指数成分股 | `thscode`* |
+| `/api/a-share-index/prices/snapshot` | 指数行情快照 | `thscodes`* |
+| `/api/a-share-index/prices/historical` | 指数历史K线（无复权参数） | `thscode`*、`interval`、`start`*、`end`* |
+
+### 特色数据（`/api/a-share/special-data/…`）
+
+| 接口路径后缀 | 功能 |
+|------|------|
+| `limit-up-pool` | 涨停池（涨停/连板股） |
+| `limit-down-pool` | 跌停池 |
+| `limit-break-pool` | 涨停炸板池 |
+| `limit-up-ladder` | 近30日连板天梯 |
+| `skyrocket-list` | 热度飙升榜 Top30（日榜/小时榜） |
+| `hot-stock-list` | A股热股榜 Top30（24h/小时） |
+| `hot-stock-list-history` | 按自然日历史热股排行 |
+| `hot-stock-rank-trend` | 单股热榜排名走势 |
+| `anomaly-analysis-list` | 当日个股异动原因列表（`tag_codes` 如 `LIMIT_UP,SHARP_FALL`）※仅 REST |
+| `anomaly-analysis-stock` | 按股票批量查异动原因（`thscodes`* ≤50） |
+| `dragon-tiger-list` | 龙虎榜（`board_type` all/org/hot_money、`date`） |
+
+### 公募基金（21 项，仅列核心）
+
+| 接口路径 | 功能 |
+|----------|------|
+| `/api/fund/profile/**` | 基金基本资料 |
+| `/api/fund/portfolio/holdings` | 定期披露重仓持仓 |
+| `/api/fund/performance/nav` / `returns` / `indicators-historical` | 净值 / 区间收益与同类排名 / 历史业绩指标 |
+| `/api/fund/holders/detail` / `top` | 持有人结构 / 前十大持有人 |
+| `/api/fund/corporate-actions/dividends` | 基金分红记录 |
+| `/api/fund/managers/investment-style` / `performance` / `experience` / `detail` | 经理投资风格 / 业绩 / 经历 / 详情 |
+| `/api/fund/companies/detail` | 基金公司详情 |
+| `/api/fund/diagnostics/detail` | 基金诊断 |
+| `/api/fund/offerings/list` | 新发基金募集列表 |
+| `/api/fund/news/article-list` | 基金资讯（游标分页） |
+| `/api/fund/financials/indicators` / `income-statements` / `balance-sheets` | 基金财务指标 / 利润表 / 资产负债表 |
+| `/api/fund/market/snapshot` / `historical` | ETF 行情快照 / 历史日线（窗口≤5年） |
+
+### 全市场数据导出（Market Dumps）
+
+| 接口路径 | 功能 |
+|----------|------|
+| `/api/dump/market-dumps/daily-k/download-url` | 全市场 10 年日K Parquet 下载链接 |
+| `/api/dump/market-dumps/daily-k-10d/download-url` | 最近 10 交易日日K Parquet |
+| `/api/dump/market-dumps/adjustment-factors/download-url` | 全量复权因子 Parquet |
+
+---
+
+## MCP 服务端点（4 个）
+
+| 服务 | 端点 |
+|------|------|
+| `hithink-finance-a-share` | `/mcp/a-share` |
+| `hithink-finance-a-share-index` | `/mcp/a-share-index` |
+| `hithink-finance-meta` | `/mcp/meta` |
+| `hithink-finance-fund` | `/mcp/fund` |
+
+鉴权：环境变量 `API_KEY` 注入，与 REST 同一 Key。
+
+---
+
+## CLI（`@hithink-tech/hithink-finance-cli`）
+
+| 命令 | 功能 |
+|------|------|
+| `auth login` | 录入 API Key |
+| `capabilities` | 能力目录 |
+| `symbol search --q <代码>` | 标的检索 |
+| `market snapshot --thscodes 600519.SH` | 行情快照 |
+| `financials income --thscode ... --limit 4` | 利润表 |
+| `data init` / `db query --sql "..."` | 初始化本地库 / SQL 查询（视图如 `v_daily_qfq`） |
+
+---
+
+## Python SDK 与本地 DuckDB
+
+```bash
+pip install -e ./python
+python python/bootstrap.py   # 初始化本地 DuckDB（marketdb）
+```
+
+常用脚本：`fuyao.py tickers-search --q "贵州茅台"`、`fuyao.py prices-snapshot ...`
+marketdb 支持增量同步、SQL 查询、复权计算、数据导出。
+
+---
+
+## 合规要求
+
+- 输出需注明数据源、时间范围与复权口径，标注"非投资建议"
+- 真实数据不可用时不得用模拟数据冒充
+- API Key 不可写入代码、日志或 Git 仓库
+
+---
+
+## 与我们现有系统的潜在结合点（供后续评估）
+
+> 现有数据源依赖腾讯/东方财富/新浪/AkShare，均为非官方抓取，存在限流与反爬问题。
+> 同花顺官方 API 可作**更稳定、结构化的权威数据源**，或补充新能力。
+
+| 现有模块 | 同花顺对应能力 | 潜在价值 |
+|----------|--------------|---------|
+| 实时行情 `/api/stock/quote`（腾讯） | `a-share/prices/snapshot` | 官方行情快照，避免腾讯兼容性/抓取风险 |
+| 历史K线 `/api/stock/history`（东财/腾讯） | `a-share/prices/historical`（10年、复权可选） | 权威日K + 明确复权口径，替代被反爬的东财 kline |
+| 财务指标 `/api/stock/financial`（东财） | `a-share/financials/*` + `valuations/snapshot` | 官方三大报表、五类指标、估值快照 |
+| 题材热点 / 热点穿透（东财） | `a-share/special-data/*` 热榜、涨停池、连板天梯 | 官方热榜/涨停/连板数据，可增强题材热度判断 |
+| 核心股追踪 / 每日采集 | `a-share/special-data/dragon-tiger-list`、`hot-stock-*` | 龙虎榜、热股榜可作为核心股采样的补充来源 |
+| 新增能力 | `a-share-index/*`（指数/板块成分）、`fund/*`（基金）、Market Dumps（全市场导出） | 指数行情、基金筛选、本地 marketdb 全市场回测 |
+
+> 注意：特色数据（涨停池等）tag_codes 语义、thscode 与现有 code 体系的映射，接入前需先做字段对齐验证。