cn-stock-query

# 中国 A 股/ETF/基金 实时价格查询

## 支持的标的类型

| 类型       | 代码特征                    | 数据源        | 数据类型       |
|-----------|---------------------------|--------------|---------------|
| 沪市股票   | 6 开头 6 位数字             | 新浪财经      | 实时行情       |
| 深市股票   | 0 或 3 开头 6 位数字        | 新浪财经      | 实时行情       |
| 沪市 ETF   | 5 开头 6 位数字             | 新浪财经      | 实时行情       |
| 深市 ETF   | 1 开头 6 位数字             | 新浪财经      | 实时行情       |
| 场外基金   | 排除法（见 Step 2）         | 天天基金      | 实时估值/净值  |

## 工作流程

### Step 1: 解析用户输入

从用户消息中提取所有 6 位数字代码。如果用户使用名称而非代码，尝试匹配常见标的：

常见标的速查：
- 黄金ETF → 518880（沪市）
- 红利低波ETF → 512890（沪市）
- 沪深300ETF → 510300（沪市）
- 卫星ETF → 563230（沪市）
- 创业板ETF → 159915（深市）
- 中证500ETF → 510500（沪市）

如果无法确定代码，向用户确认。

### Step 2: 识别标的市场（含防碰撞机制）

对每个代码执行以下判断逻辑：

```
第一轮：按首位数字推断市场
if code.startsWith('6'):
    market = 'sh'    # 沪市股票
    type = 'stock'
elif code.startsWith('0') or code.startsWith('3'):
    # 注意：0 开头可能是深市股票也可能是场外基金
    # 先尝试 sz 前缀查询新浪，若返回空则判定为场外基金
    market = 'sz'
    type = 'stock_or_fund'  # 待确认
elif code.startsWith('5'):
    market = 'sh'    # 沪市ETF
    type = 'etf'
elif code.startsWith('1'):
    market = 'sz'    # 深市ETF
    type = 'etf'
else:
    type = 'fund'    # 场外基金（2/4/7/8/9 开头）

第二轮：对 type='stock_or_fund' 的代码做二次确认
1. 用 sz{code} 查询新浪接口
2. 若返回空字符串("")，则判定为场外基金，转天天基金接口
3. 若返回数据，确认为深市股票

第三轮：防碰撞校验（关键！）
查询返回数据后，校验名称是否与用户预期一致。
沪深两市存在同号不同标的的情况（如 563230 在沪市是"卫星ETF"，
在深市是"山东XXXX"）。如果名称明显不符，尝试另一个市场前缀重新查询。
```

### Step 3: 查询股票/ETF 实时行情

对 type 为 stock 或 etf 的标的，使用 shell 执行：

```bash
curl -s "https://hq.sinajs.cn/list={market}{code}" \
  -H "Referer: https://finance.sina.com.cn" \
  | iconv -f GBK -t UTF-8
```

**重要：新浪接口返回 GBK 编码，必须通过 `iconv -f GBK -t UTF-8` 转码，否则中文名称会乱码。**

响应格式为逗号分隔的文本：
```
var hq_str_sh601991="大唐发电,4.240,4.250,4.310,4.440,4.230,4.310,4.320,...,2026-03-18,15:00:01,00,";
```

字段索引（0-based，引号内逗号分隔）：
- [0] 名称
- [1] 今开
- [2] 昨收
- [3] 最新价
- [4] 最高
- [5] 最低
- [8] 成交量（股）
- [9] 成交额（元）
- [30] 日期
- [31] 时间

涨跌额 = 字段[3] - 字段[2]
涨跌幅 = (字段[3] - 字段[2]) / 字段[2] × 100%

支持批量查询（逗号拼接多个代码，一次请求完成）：
```bash
curl -s "https://hq.sinajs.cn/list=sh601991,sh518880,sh563230" \
  -H "Referer: https://finance.sina.com.cn" \
  | iconv -f GBK -t UTF-8
```

### Step 4: 查询场外基金净值

对 type 为 fund 的标的，按优先级使用以下接口：

**4a. 实时估值（交易日盘中，优先使用）：**
```bash
curl -s "http://fundgz.1234567.com.cn/js/{code}.js"
```

响应格式：
```
jsonpgz({"fundcode":"014978","name":"华安纳斯达克100ETF联接(QDII)C","jzrq":"2026-03-17","dwjz":"6.9899","gsz":"6.8897","gszzl":"-1.43","gztime":"2026-03-18 15:00"});
```

字段说明：
- `fundcode`: 基金代码
- `name`: 基金名称
- `jzrq`: 最新净值日期
- `dwjz`: 上一交易日单位净值（已确认）
- `gsz`: 实时估算净值
- `gszzl`: 估算涨跌幅(%)
- `gztime`: 估值时间

**4b. 备用：最新确认净值**
```bash
curl -s "https://api.fund.eastmoney.com/f10/lsjz?fundCode={code}&pageIndex=1&pageSize=1" \
  -H "Referer: https://fund.eastmoney.com"
```

若 4a 返回 `jsonpgz()` 空值，则使用 4b 获取最新确认净值。

**QDII 基金特殊处理：**
若基金名称包含"QDII""纳斯达克""标普""海外""美国""全球"等关键词，
且净值日期（jzrq）落后当前日期超过 2 天，属于正常现象——QDII 基金净值公布有 T+2 至 T+7 的系统性延迟。
需在输出中附加提示：`⏳ QDII基金，净值公布有 T+2~T+7 延迟`

### Step 5: 格式化输出

以 Markdown 表格输出，格式如下：

```
| 代码   | 名称            | 类型  | 最新价  | 涨跌幅          | 更新时间            |
|--------|----------------|-------|--------|----------------|-------------------|
| 601991 | 大唐发电        | stock | 4.310  | 🔴 +1.41%      | 2026-03-18 15:00  |
| 518880 | 黄金ETF华安     | etf   | 10.606 | 🟢 -0.29%      | 2026-03-18 15:00  |
| 014978 | 华安纳指100联接C | fund  | 6.8897 | 🟢 -1.43%（估） | 2026-03-18 15:00  |
| 600995 | 南网储能        | stock | 14.980 | ⚪ 0.00%        | 2026-03-18 15:00  |
```

涨跌标识规则（遵循 A 股红涨绿跌惯例）：
- 上涨：🔴 红色圆点 + `+` 前缀，涨跌幅文字用 **红色** 显示
- 下跌：🟢 绿色圆点 + `-` 前缀，涨跌幅文字用 **绿色** 显示
- 平盘：⚪ 白色圆点，显示 `0.00%`

如果输出环境支持 HTML 或富文本，使用颜色标签增强显示：
- 上涨：`<span style="color:#e54d42">🔴 +1.41%</span>`
- 下跌：`<span style="color:#39b54a">🟢 -0.29%</span>`
- 平盘：`⚪ 0.00%`

如果输出环境仅支持纯 Markdown，退回到 emoji + 文字方案（不使用 HTML 标签）。

其他输出规则：
- 涨跌幅为正数前面加 `+`，为负数自带 `-`
- 价格保留与原始数据相同的小数位数
- 场外基金盘中显示估算净值，在涨跌幅后标注 `（估）`
- 非交易时段在表格下方注明：`⏸ 非交易时段，显示上一交易日收盘数据`
- QDII 基金在表格下方注明：`⏳ QDII基金，净值公布有 T+2~T+7 延迟`

### Step 6: 持仓市值计算（可选）

如果用户同时提供了持仓份额/股数，额外输出市值表：

```
| 代码   | 名称      | 持仓   | 成本价  | 最新价  | 市值       | 浮盈/亏         | 盈亏比          |
|--------|----------|--------|--------|--------|-----------|----------------|----------------|
| 601991 | 大唐发电  | 500股  | 3.725  | 4.310  | 2,155.00  | 🔴 +292.50     | 🔴 +15.70%    |
| 518880 | 黄金ETF  | 200股  | 10.925 | 10.606 | 2,121.20  | 🟢 -63.80      | 🟢 -2.92%     |
```

汇总行：
```
📊 持仓合计：市值 4,276.20 | 总成本 4,047.50 | 浮盈 🔴 +228.70（+5.65%）
```

计算公式：
- 市值 = 持仓数 × 最新价
- 浮盈/亏 = 市值 - (持仓数 × 成本价)
- 盈亏比 = 浮盈/亏 ÷ (持仓数 × 成本价) × 100%
- 盈亏颜色规则与涨跌幅一致：盈利 🔴 红色，亏损 🟢 绿色

## 错误处理

| 场景              | 处理方式                                                     |
|------------------|--------------------------------------------------------------|
| 代码无法识别       | 提示 "未找到标的 {code}，请确认代码是否正确"                      |
| 接口返回空值       | 股票接口返回 `=""` 或基金接口返回 `jsonpgz()` 时提示未找到         |
| 接口超时(>5s)     | 重试 1 次，仍失败则提示 "数据源暂时不可用，请稍后重试"              |
| 场外基金无估值数据  | 回退到确认净值接口，标注 `（净值，非估值）`                        |
| 用户输入非6位代码  | 提示正确的代码格式                                              |
| 市场前缀碰撞       | 校验返回名称与用户预期是否一致，不一致时尝试另一市场前缀             |
| 中文乱码          | 检查是否遗漏 iconv 转码步骤                                     |

## 交易时间参考

- A 股/ETF 交易时段：工作日 09:30-11:30, 13:00-15:00
- 场外基金估值时段：工作日 09:30-15:00（确认净值 T+1 日晚间公布）
- QDII 基金净值：T+2 至 T+7 公布（因海外市场时差和结算流程）
- 节假日、周末无交易