stock-sdk 1.0.0

package/origin.md

@@ -0,0 +1,480 @@
+# qt.gtimg.cn 腾讯财经接口非官方说明文档
+
+> 重要说明：`qt.gtimg.cn` 并没有公开官方 API 文档，本文档内容均来自社区和抓包逆向整理，仅供参考和学习使用，随时可能调整或下线，使用前请自行验证。
+
+---
+
+## 1. 基本约定
+
+- **Host**：`http://qt.gtimg.cn`
+- **HTTP 方法**：`GET`
+- **基础格式**：
+
+  ```text
+  http://qt.gtimg.cn/q=<参数串>
+  ```
+
+- **多标的查询**：多个代码用英文逗号 `,` 拼接，例如：
+
+  ```text
+  http://qt.gtimg.cn/q=sh600000,sz000001,hk00001
+  ```
+
+- **返回格式**：若成功，一般为若干行 **JS 变量赋值**，例如：
+
+  ```text
+  v_sz000858="51~五 粮 液~000858~27.78~27.60~...~";
+  v_sh600000="1~浦发银行~600000~7.06~7.03~...~";
+  ```
+
+  - 变量名：`v_` + 查询参数（如 `sz000858` / `s_sz000858` / `ff_sz000858` 等）。
+  - 字段分隔符：`~`。
+  - 行分隔：`;`（英文分号）。
+
+- **编码**：响应内容通常为 GBK/GB2312，需要先按 GBK/GB2312 解码，再转 UTF-8，否则中文字段会乱码。
+
+---
+
+## 2. 市场与代码前缀
+
+常见市场前缀约定（用于 `<market+code>` 部分）：
+
+| 市场 / 类型     | 示例前缀       | 示例代码           | 说明                                   |
+|----------------|----------------|--------------------|----------------------------------------|
+| 上证 A 股/指数 | `sh`           | `sh600000`         | 浦发银行                               |
+| 深证 A 股/指数 | `sz`           | `sz000858`         | 五粮液                                 |
+| 北交所         | `bj`           | `bj899050`         | 北证 50 指数（示例）                   |
+| 港股           | `hk` / `r_hk`  | `hk00001` / `r_hk09988` | 普通 / 扩展行情（港股）         |
+| 美股           | `us` / `s_us`  | `usBABA` / `s_usBABA`   | 全量 / 简要行情（美股）         |
+| 公募基金       | `jj`           | `jj000001`         | 华夏成长混合等开放式基金              |
+
+---
+
+## 3. 接口总览
+
+### 3.1 A 股 / 指数 / 港股 / 美股 实时行情（全量字段）
+
+**用途**：获取单只或多只股票、指数的详细实时行情（含盘口、逐笔、成交额、市值等大量字段）。
+
+**参数格式**：
+
+```text
+q=<market><code>
+```
+
+**示例**：
+
+- 上证个股：
+
+  ```text
+  http://qt.gtimg.cn/q=sh600000
+  ```
+
+- 深证个股：
+
+  ```text
+  http://qt.gtimg.cn/q=sz000858
+  ```
+
+- 多标的：
+
+  ```text
+  http://qt.gtimg.cn/q=sh600000,sz000001,sz000858
+  ```
+
+**典型字段（A 股）说明**
+
+返回示例：
+
+```text
+v_sz000858="51~五 粮 液~000858~27.78~27.60~270295~142514~127781~27.77~220~27.78~144~27.76~244~27.79~146~27.75~261~27.80~74~27.74~244~27.81~41~27.73~190~27.82~127~27.72~232~27.83~96~~2025/11/26 15:00:03~27.78~0.18~0.65~27.91~27.25~27.78/270295/748632327~270295~74863~0.63~16.59~~27.91~27.25~~~1.57~27.91~2025-11-26~0.63~16.59~~~1.57~~";
+```
+
+按 `~` 分割后，下标从 0 开始，典型字段含义（仅节选，实际字段更多）：
+
+| 下标 | 含义                               |
+|------|------------------------------------|
+| 0    | 市场标识（如 51）                  |
+| 1    | 名称                               |
+| 2    | 股票代码                           |
+| 3    | 当前价格                           |
+| 4    | 昨收                               |
+| 5    | 今开                               |
+| 6    | 成交量（手）                       |
+| 7    | 外盘（手）                         |
+| 8    | 内盘（手）                         |
+| 9–18 | 买一~买五价及对应数量              |
+| 19–28| 卖一~卖五价及对应数量              |
+| 29   | 最近逐笔成交串                     |
+| 30   | 时间戳（交易日期+时间）            |
+| 31   | 涨跌额                             |
+| 32   | 涨跌幅（%）                        |
+| 33   | 当日最高                           |
+| 34   | 当日最低                           |
+| 35   | “价格/成交量/成交额” 综合字段     |
+| 36   | 成交量（手）                       |
+| 37   | 成交额（万）                       |
+| 38   | 换手率                             |
+| 39   | 市盈率                             |
+| 44   | 流通市值                           |
+| 45   | 总市值                             |
+| 46   | 市净率                             |
+| 47   | 涨停价                             |
+| 48   | 跌停价                             |
+
+> 注意：不同标的（A 股 / 港股 / 美股 / 指数等）字段数量和定义会有差异，使用前建议对照实际返回串自行确认。
+
+**支持标的类型（常见）**：
+
+- A 股个股，如：`sh600000`、`sz000858`；
+- A 股主要指数，如：`sh000001`、`sz399001` 等；
+- 港股个股，如：`hk00001`（普通）或通过扩展接口 `r_hk`（见 3.5）；
+- 美股个股，如：`usBABA`（但更推荐使用简要接口，见 3.6）。
+
+---
+
+### 3.2 简要行情接口（股票 / 指数 / 港股 / 美股）
+
+**用途**：获取精简字段的行情数据，响应体更小，适合列表展示、概览刷新。
+
+**参数格式**：
+
+```text
+q=s_<market><code>
+```
+
+**示例**：
+
+- A 股简要：
+
+  ```text
+  http://qt.gtimg.cn/q=s_sz000858
+  http://qt.gtimg.cn/q=s_sh600519
+  ```
+
+- 指数简要：
+
+  ```text
+  http://qt.gtimg.cn/q=s_sh000001    # 上证指数
+  ```
+
+- 美股简要：
+
+  ```text
+  http://qt.gtimg.cn/q=s_usBABA      # 阿里巴巴美股
+  ```
+
+- 港股指数简要：
+
+  ```text
+  http://qt.gtimg.cn/q=s_r_hkHSI     # 恒生指数
+  ```
+
+**典型字段（简要版，按 `~` 分割）**：
+
+> 以下为常见模式总结，实际字段数量及位置可能因市场而略有差异。
+
+| 下标 | 含义                                      |
+|------|-------------------------------------------|
+| 0    | 所属市场标识（如：1=大陆、100=港股、200=美股等） |
+| 1    | 名称                                      |
+| 2    | 代码                                      |
+| 3    | 当前价格                                  |
+| 4    | 涨跌额                                    |
+| 5    | 涨跌幅（%）                               |
+| 6    | 成交量（手）或成交量                      |
+| 7    | 成交额（万）或总成交额                    |
+| 8+   | 其他信息（如总市值等，因标的不同略有差异）|
+
+---
+
+### 3.3 实时资金流向接口（主力 / 散户）
+
+**用途**：获取个股的主力与散户资金流向指标。
+
+**参数格式**：
+
+```text
+q=ff_<market><code>
+```
+
+**示例**：
+
+```text
+http://qt.gtimg.cn/q=ff_sz000858
+http://qt.gtimg.cn/q=ff_sh600519
+```
+
+**典型字段含义（按 `~` 分割，节选）**：
+
+| 下标 | 含义                                |
+|------|-------------------------------------|
+| 0    | 代码                                |
+| 1    | 主力流入                            |
+| 2    | 主力流出                            |
+| 3    | 主力净流入                          |
+| 4    | 主力净流入 / 总资金流（比例）       |
+| 5    | 散户流入                            |
+| 6    | 散户流出                            |
+| 7    | 散户净流入                          |
+| 8    | 散户净流入 / 总资金流（比例）       |
+| 9    | 总资金流（1+2+5+6）                 |
+| 12   | 名称                                |
+| 13   | 日期                                |
+
+---
+
+### 3.4 盘口大单统计接口（买盘 / 卖盘）
+
+**用途**：获取该标的买卖盘中大单/小单的分布占比，常用作“主力/散户”辅助指标。
+
+**参数格式**：
+
+```text
+q=s_pk<market><code>
+```
+
+**示例**：
+
+```text
+http://qt.gtimg.cn/q=s_pksz000858
+http://qt.gtimg.cn/q=s_pksh600519
+```
+
+**字段说明**（按 `~` 分割）：
+
+| 下标 | 含义           |
+|------|----------------|
+| 0    | 买盘大单占比   |
+| 1    | 买盘小单占比   |
+| 2    | 卖盘大单占比   |
+| 3    | 卖盘小单占比   |
+
+---
+
+### 3.5 港股扩展行情接口（`r_hk`）
+
+**用途**：港股标的的较为完整行情数据（字段结构与 A 股略有区别）。
+
+**参数格式**：
+
+```text
+q=r_hk<code>    # 如港股 09988
+```
+
+**示例**：
+
+```text
+http://qt.gtimg.cn/q=r_hk09988
+```
+
+典型字段包含：当前价、昨收、今开、成交量、成交额、52 周高低、市盈率、市净率、每手股数、流通市值等，具体字段顺序和意义请以实际返回为准。
+
+---
+
+### 3.6 美股简要行情接口（`s_us`）
+
+**用途**：获取美股标的的简要行情。
+
+**参数格式**：
+
+```text
+q=s_us<代码>
+```
+
+**示例**：
+
+```text
+http://qt.gtimg.cn/?q=s_usBABA
+```
+
+典型字段包括：市场标识、名称、代码、现价、涨跌额、涨跌幅、成交量、成交额和市值等，字段位置请以实际返回为准。
+
+---
+
+### 3.7 公募基金行情接口（`jj`）
+
+**用途**：获取开放式基金（如混合型、债券型等）的净值相关数据。
+
+**参数格式**：
+
+```text
+q=jj<六位基金代码>
+```
+
+**示例**：
+
+```text
+http://qt.gtimg.cn/q=jj000001
+```
+
+基金返回串示例（节选）：
+
+```text
+v_jj000001="000001~华夏成长混合~0.0000~0.0000~~1.0270~3.6000~1.0827~2025-11-26~...";
+```
+
+典型字段大致包括：基金代码、基金名称、单位净值、累计净值、前一日净值、最新净值日期等，具体顺序和含义建议根据实际返回逐一核对。
+
+---
+
+### 3.8 指数简要接口（指数 / 港股指数 / 美股指数）
+
+**用途**：获取指数层面的简要行情信息。
+
+**参数格式**：
+
+```text
+q=s_<market><index_code>
+```
+
+**常见示例**：
+
+- 上证指数：
+
+  ```text
+  http://qt.gtimg.cn/q=s_sh000001
+  ```
+
+- 深成指、创业板等：
+
+  ```text
+  http://qt.gtimg.cn/q=s_sz399001,s_sz399006
+  ```
+
+- 道琼斯指数：
+
+  ```text
+  http://qt.gtimg.cn/q=s_usDJI
+  ```
+
+- 恒生指数：
+
+  ```text
+  http://qt.gtimg.cn/q=s_r_hkHSI
+  ```
+
+- 其他指数示例：
+
+  ```text
+  http://qt.gtimg.cn/q=s_sh000847
+  ```
+
+字段含义与 3.2 的简要行情接口类似，但具体位置会有差异，建议针对每个指数实际打印返回串。
+
+---
+
+### 3.9 期货 / 其他衍生品（经验型）
+
+部分社区经验表明，商品期货等品种也可以通过类似股票的代码与 `q=` 接口获取行情，比如使用特定字母+数字组合（如：`RB0`、`AU0` 等）作为代码。
+
+由于期货合约代码体系复杂、缺乏统一文档，建议：
+
+1. 找到腾讯行情页面对应品种；
+2. 通过浏览器 DevTools 抓包，看前端实际请求的 `qt.gtimg.cn` URL；
+3. 总结出实际使用的代码与字段含义，而不要仅凭第三方表格。
+
+---
+
+### 3.10 批量查询与组合
+
+所有上述 `q=` 形式接口都支持 **逗号分隔的批量查询**：
+
+```text
+# 同时查询 A 股、指数、港股、美股、基金
+http://qt.gtimg.cn/q=sh600000,sz000858,s_sh000001,hk00001,s_usBABA,jj000001
+```
+
+- 服务器会按顺序返回多行 `v_...="..."`；
+- 可以按 `;` 切行，再根据每行变量名前缀（`v_s_` / `v_ff_` / `v_jj` 等）决定用哪一套解析逻辑。
+
+---
+
+## 4. 返回数据解析要点
+
+### 4.1 通用解析流程（示意）
+
+建议的通用解析步骤：
+
+1. 发起 GET 请求，拿到 `bytes` 响应体；
+2. 使用 GBK/GB2312 解码为 UTF-8 字符串；
+3. 按 `;` 拆分为多行字符串；
+4. 对每行：
+   - 忽略空行；
+   - 以 `=` 拆分为左侧变量名和右侧 `"..."` 内容；
+   - 去掉右侧两端双引号；
+   - 对内容按 `~` 分割为数组；
+   - 根据变量名前缀（`v_sz...` / `v_s_sz...` / `v_ff_sz...` / `v_jj...` 等）选择对应字段映射。
+
+伪代码示例（语言无关）：
+
+```pseudo
+resp_bytes = http_get("http://qt.gtimg.cn/q=sz000858")
+text = decode_gbk(resp_bytes)
+
+for line in split(text, ';'):
+    line = trim(line)
+    if line is empty: continue
+
+    name, raw = split_once(line, '=')   # e.g. name = 'v_sz000858'
+    raw = strip_quotes(raw)             # remove leading/trailing "
+
+    fields = split(raw, '~')
+
+    if name starts_with 'v_s_':
+        parse_simple_quote(fields)
+    elif name starts_with 'v_ff_':
+        parse_fund_flow(fields)
+    elif name starts_with 'v_jj':
+        parse_fund(fields)
+    else:
+        parse_full_quote(fields)
+```
+
+### 4.2 容错与版本差异
+
+由于这些接口并非正式公开 API，存在如下风险：
+
+- 某些字段在不同时间段可能新增或废弃；
+- 不同市场（A 股 / 港股 / 美股 / 基金）字段数量与含义会有细微差异；
+- 个别字段意义在社区文章中仍存在“猜测”成分。
+
+建议：
+
+- 解析时对数组长度做判断，字段不足时设置为默认值；
+- 对暂时不需要的尾部字段，先留作原始字符串保存，方便后续升级；
+- 重要业务逻辑不要依赖尚未验证或不稳定的字段。
+
+---
+
+## 5. 与其它腾讯财经域名的关系（扩展，可选）
+
+虽然本文档只聚焦 `qt.gtimg.cn`，但实际腾讯财经生态中还有：
+
+- **K 线与分时数据**：`data.gtimg.cn/flashdata/...` 提供日 K、周 K、月 K、分时、五日分时等 JS 数据文件；
+- **逐笔成交明细/大单数据**：`stock.gtimg.cn`、`stock.finance.qq.com` 等域名提供更细粒度明细数据。
+
+如果后续需要“历史行情 / K 线 / Tick 明细”层面的数据，可以在此基础上单独整理这些域名的接口。
+
+---
+
+## 6. 小结
+
+目前社区可确认、且相对稳定使用的 `qt.gtimg.cn` 主要接口族可概括为：
+
+1. **实时全量行情**：`q=<market><code>`  
+2. **简要行情**：`q=s_<market><code>`  
+3. **资金流向**：`q=ff_<market><code>`  
+4. **盘口大单统计**：`q=s_pk<market><code>`  
+5. **港股扩展行情**：`q=r_hk<code>`  
+6. **美股简要行情**：`q=s_us<code>`  
+7. **公募基金行情**：`q=jj<code>`  
+8. **指数简要**：`q=s_<market><index>` / `q=s_r_hk<index>`  
+
+在此基础上，你可以进一步：
+
+- 封装内部 SDK / 客户端库；
+- 定义统一的 DTO / 字段映射；
+- 实现重试、限流与缓存策略；
+- 补充自己业务关心的字段说明与示例。
+

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "stock-sdk",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "stock",
+    "tencent",
+    "qt.gtimg.cn",
+    "sdk"
+  ],
+  "author": "",
+  "license": "ISC",
+  "description": "Tencent qt.gtimg.cn stock quote SDK",
+  "dependencies": {
+    "axios": "^1.13.2",
+    "iconv-lite": "^0.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.15"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "packageManager": "yarn@4.6.0+sha512.5383cc12567a95f1d668fbe762dfe0075c595b4bfff433be478dbbe24e05251a8e8c3eb992a986667c1d53b6c3a9c85b8398c35a960587fbd9fa3a0915406728"
+}

package/src/index.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect } from 'vitest';
+import TencentStockSDK from './index';
+
+const sdk = new TencentStockSDK();
+
+describe('TencentStockSDK', () => {
+  describe('getFullQuotes', () => {
+    it('should return A股全量行情', async () => {
+      const res = await sdk.getFullQuotes(['sz000858']);
+      expect(res.length).toBeGreaterThan(0);
+      const q = res[0];
+      expect(q.code).toBe('000858');
+      expect(q.name).toContain('粮');
+      expect(typeof q.price).toBe('number');
+      expect(q.bid.length).toBe(5);
+      expect(q.ask.length).toBe(5);
+    });
+  });
+
+  describe('getSimpleQuotes', () => {
+    it('should return 简要行情', async () => {
+      const res = await sdk.getSimpleQuotes(['s_sz000858']);
+      expect(res.length).toBeGreaterThan(0);
+      const q = res[0];
+      expect(q.code).toBe('000858');
+      expect(typeof q.price).toBe('number');
+    });
+
+    it('should return 指数简要行情', async () => {
+      const res = await sdk.getSimpleQuotes(['s_sh000001']);
+      expect(res.length).toBeGreaterThan(0);
+      const q = res[0];
+      expect(q.code).toBe('000001');
+      expect(q.name).toContain('指数');
+    });
+  });
+
+  describe('getFundFlow', () => {
+    it('should return 资金流向', async () => {
+      const res = await sdk.getFundFlow(['ff_sz000858']);
+      expect(res.length).toBeGreaterThan(0);
+      const q = res[0];
+      expect(q.code).toContain('sz000858');
+      expect(typeof q.mainInflow).toBe('number');
+    });
+  });
+
+  describe('getPanelLargeOrder', () => {
+    it('should return 盘口大单占比', async () => {
+      const res = await sdk.getPanelLargeOrder(['s_pksz000858']);
+      expect(res.length).toBeGreaterThan(0);
+      const q = res[0];
+      expect(typeof q.buyLargeRatio).toBe('number');
+      expect(typeof q.sellLargeRatio).toBe('number');
+    });
+  });
+
+  describe('getHKQuotes', () => {
+    it('should return 港股扩展行情', async () => {
+      const res = await sdk.getHKQuotes(['r_hk09988']);
+      expect(res.length).toBeGreaterThan(0);
+      const q = res[0];
+      expect(q.code).toBe('09988');
+      expect(typeof q.price).toBe('number');
+    });
+  });
+
+  describe('getUSQuotes', () => {
+    it('should return 美股简要行情', async () => {
+      const res = await sdk.getUSQuotes(['s_usBABA']);
+      expect(res.length).toBeGreaterThan(0);
+      const q = res[0];
+      expect(q.code).toContain('BABA');
+      expect(typeof q.price).toBe('number');
+    });
+  });
+
+  describe('getFundQuotes', () => {
+    it('should return 公募基金行情', async () => {
+      const res = await sdk.getFundQuotes(['jj000001']);
+      expect(res.length).toBeGreaterThan(0);
+      const q = res[0];
+      expect(q.code).toBe('000001');
+      expect(typeof q.nav).toBe('number');
+    });
+  });
+
+  describe('batchRaw', () => {
+    it('should return 批量混合查询原始结果', async () => {
+      const res = await sdk.batchRaw('sz000858,s_sh000001');
+      expect(res.length).toBe(2);
+      expect(res[0].key).toContain('sz000858');
+      expect(res[1].key).toContain('sh000001');
+    });
+  });
+});
+