# 通达信行情中继 — 开发指南

> 写给小小莫。在 Windows 上用 Python 直连招商证券的通达信行情主站，获取实时港股行情，推送到知微的 MoFin Dashboard。

---

## 一、背景

知微的 MoFin 系统目前用腾讯免费 API 获取行情。A 股是实时的，但港股有 **15 分钟延迟**。

你在 Windows 上的招商证券客户端（通达信内核）是买了港股实时数据的。我们可以通过 Python 直连招商证券的行情主站，拿到**真正实时的港股行情**，然后推送到知微的 Dashboard。

## 二、技术方案

```
招商证券客户端 (通信设置里的IP:7709)
        │
        ▼
   opentdx (Python库)
        │
        ▼
   tdx_relay.py (你写)
        │  POST /api/update/realtime
        ▼
   MoFin Dashboard (192.168.1.246:8899)
```

推荐用 **opentdx**（pytdx 的升级版）：

```bash
pip install opentdx requests
```

## 三、第一步：拿行情主站IP

打开招商证券 PC 客户端：

1. **菜单 → 选项 → 通信设置**
2. 你会看到一列行情主站，类似：`招商证券深圳主站 113.105.73.88:7709`
3. 记下来，填到 `src/relay/config.py` 里

或者在命令行找：

```cmd
tasklist | findstr "zhsh"       # 找招商证券进程PID
netstat -ano | findstr "7709"   # 看连接的IP
```

## 四、CLI 验证连通性

装好 opentdx 后，先用命令行测试：

```bash
# 测试 A 股
opentdx quote "SZ 000001"

# 测试港股（用你的服务器IP替换）
opentdx g-quote "HK_MAIN_BOARD 00700" --server 113.105.73.88:7709
```

> opentdx 的完整命令列表：`opentdx doc`（交互式文档）

## 五、Python 代码示例

### 连接 + 获取港股行情

```python
from opentdx.tdxClient import TdxClient
from opentdx.const import EX_MARKET

# 方式一：自动选最快服务器
with TdxClient() as client:
    # A股
    a_quotes = client.stock_quotes([(0, '000001')])

    # 港股 ⭐
    hk_quotes = client.goods_quotes([
        (EX_MARKET.HK_MAIN_BOARD, '00700'),  # 腾讯
        (EX_MARKET.HK_MAIN_BOARD, '09988'),  # 阿里
    ])
    for q in hk_quotes:
        print(f"{q['code']}: {q['price']} {q['change_pct']}%")
```

> ⚠️ `opentdx` 的具体 API 以 `opentdx doc` 为准。
> GitHub: https://github.com/acb6104/opentdx

### 推送到 MoFin

用现成的工具类：

```python
from relay.pusher import MoFinPusher

pusher = MoFinPusher("http://192.168.1.246:8899")
result = pusher.push([
    {
        "code": "00700",
        "name": "腾讯控股",
        "price": 463.6,
        "change_pct": 1.55,
        "high": 468.0,
        "low": 460.2,
        "open": 462.0,
        "volume": 25000000,
        "timestamp": "2026-06-12 14:30:00"
    }
])
print(result)  # {"status": "ok", "updated": 1}
```

## 六、你的任务清单

### 阶段一：环境 + 连通性
- [ ] 装 Python 3.10+（如果没有的话）
- [ ] `pip install opentdx requests`
- [ ] 运行 `opentdx doc` 看看接口
- [ ] 从招商证券通信设置拿到行情主站IP
- [ ] 用 CLI 测试港股：`opentdx g-quote "HK_MAIN_BOARD 00700" --server <IP>:7709`

### 阶段二：港股行情获取
- [ ] 实现 `tdx_client.py` 的连接和港股查询
- [ ] 验证单只港股（腾讯00700）数据正确
- [ ] 验证批量港股（持仓列表）
- [ ] ⚠️ **对比招商证券客户端价格，确认数据准确**（红线）

### 阶段三：数据推送
- [ ] 实现 `run_relay.py` 主循环
- [ ] 测试推送一条数据到 MoFin Dashboard
- [ ] 全量推送所有持仓港股

### 阶段四：自动化
- [ ] 设置 Windows 定时任务（每15~30秒运行一次）

## 七、注意事项

### 数据准确性（⚠️红线）
```python
# 从通达信拿到的价格 和 招商证券客户端显示的现价
# 两者必须一致！
tdx_price = 463.6
assert abs(tdx_price - 招商证券_显示价格) < 0.01
```

### A股不要动
A 股继续走腾讯 API，已经是实时的。**本项目只解决港股延迟。**

### 字段映射

| 含义 | 腾讯API索引 | 通达信字段 |
|------|------------|-----------|
| 当前价 | fields[3] | price |
| 昨收 | fields[4] | last_close |
| 今开 | fields[5] | open |
| 最高 | fields[33] | high |
| 最低 | fields[34] | low |
| 涨跌幅 | fields[32] | change_pct |

### 回退方案
通达信连不上时自动回退腾讯 API（当前方案），不中断行情更新。

```python
try:
    data = tdx_client.get_quotes(codes)
except Exception:
    data = tencent_api.get_quotes(codes)  # 回退
```

### 连接稳定性
opentdx 内置心跳，但网络不稳时需要重连：

```python
def safe_get(client, codes, retries=3):
    for i in range(retries):
        try:
            return client.goods_quotes(codes)
        except (ConnectionError, TimeoutError):
            client.disconnect()
            time.sleep(2)
            client.connect(ip, port)
    return None  # 回退腾讯API
```

## 八、参考

| 资源 | 地址 |
|------|------|
| opentdx GitHub | https://github.com/acb6104/opentdx |
| opentdx PyPI | `pip install opentdx` |
| MoFin Dashboard | http://192.168.1.246:8899 |
| 架构文档 | 见本目录上级 `docs/` |