# MoFin / TDX-Relay 协作文档

> 最后更新：2026-06-12
> 维护人：知微 + 小小莫(xxm)
> 铁律：任何 relay 相关改动必须先读本文档，改完必须同步更新

---

## 一、什么是 tdx-relay

tdx-relay 是小小莫（xxm）开发的 Windows 端通达信中继程序。
作用：通过 opentdx 协议直连招商证券 7727 扩展行情服务器，
为 MoFin 系统提供港股低延迟实时行情。

### 为什么需要它

原本 MoFin 的港股行情来源是腾讯 API（qt.gtimg.cn），
存在约 15 分钟延迟，对于盘中决策不够及时。
tdx-relay 将港股行情延迟从约 15 分钟降到接近实时（1~3 秒）。

---

## 二、系统架构

```
Windows 端（小小莫负责）
┌─────────────────────────────────────────┐
│  tdx-relay 项目                          │
│                                          │
│  tdx_client.py                           │
│  └─ opentdx MacExtendedClient            │
│     └─ 直连 招商证券 7727 扩展行情服务器  │
│         → 拉取 17 只港股实时行情          │
│                                          │
│  run_relay.py                            │
│  └─ 断线自动重连(5s/15s/30s 三次退避)    │
│  └─ 推送 → POST /api/update/realtime     │
│                                          │
│  start_tdx_relay.bat                     │
│  └─ 一键启动脚本                         │
└───────────────┬─────────────────────────┘
                │ HTTP POST (JSON)
                ▼
Linux 端（知微负责）
┌─────────────────────────────────────────┐
│  MoFin 系统 (web-dashboard)              │
│                                          │
│  server.py                               │
│  ├─ /api/update/realtime (POST)          │
│  │   ← 接收 tdx-relay 推送的实时行情     │
│  │   → 更新 portfolio.json + watchlist   │
│  │   → 写入 data_source = "tdx_relay"    │
│  │                                        │
│  ├─ /api/relay/status (GET)              │
│  │   ← 查询 relay 状态（在线/离线/时间） │
│  │                                        │
│  price_monitor.py                        │
│  └─ relay_active 检测                    │
│     ├─ relay 在线 → 跳过港股腾讯API拉取  │
│     │   （保留 tdx-relay 的实时价不覆盖） │
│     └─ relay 掉线 → 回退腾讯 API 兜底    │
│                                          │
│  数据文件                                │
│  ├─ data/portfolio.json                  │
│  │   └─ 每只港股: data_source=txton/tdx  │
│  ├─ data/watchlist.json                  │
│  └─ data/relay_state.json (新增)         │
│      └─ online: true/false               │
│      └─ last_ping: 时间戳                │
└─────────────────────────────────────────┘
```

## 三、职责边界

### 小小莫（xxm）— Windows 端

负责：
1. tdx_client.py 的开发维护
   - 直连券商行情服务器的稳定性
   - 港股代码列表的维护（当前 17 只）
   - 行情数据的正确性验证
2. run_relay.py 的重连机制
   - 断线自动恢复（3 次退避重连）
   - relan 状态上报
3. 行情推送的稳定性
   - 每 X 秒推送一次实时行情
   - 推送失败的处理
4. Windows 端部署维护
   - 开机自启动
   - 日志管理
   - 异常告警

不负责：
- MoFin API 的修改（但需要配合 server.py 新增端点）
- Linux 端 price_monitor 的回退逻辑
- 持仓分析和策略制定

### 知微（zhiwei）— Linux 端（MoFin）

负责：
1. MoFin API 的 relay 兼容
   - /api/update/realtime 端点（已实现）
   - /api/relay/status 端点（待实现）
   - relay_state 持久化（待实现）
2. price_monitor 的 relay 检测（待实现）
   - relay 在线 → 跳过港股腾讯 API 拉取
   - relay 掉线 → 回退腾讯 API 兜底
3. tdx-relay 接入后的数据一致性保障
   - 腾讯 API 和 tdx-relay 的数据源标记区分
   - 价格更新不互相覆盖
4. 行情来源对分析层的透明化
   - 分析层（cron prompt）不需要关心行情来源
   - 直接读 portfolio.json 即可
   - 数据源标记在 data_source 字段中

不负责：
- Windows 端程序的开发和部署
- 通达信协议的细节
- 券商行情服务器的维护

### 共同维护

1. 港股代码列表 — 两边保持一致
2. 数据格式 — tdx-relay 推送的 JSON 格式与 MoFin 期望的格式
3. 接口联调 — 新端点上线后的验证

---

## 四、数据流详解

### 正常流程（relay 在线）

```
tdx-relay (Windows)
  │ 每 X 秒推送 {stocks: [{code, price, change_pct, ...}]}
  │ POST → http://192.168.1.246:8899/api/update/realtime
  ▼
server.py 接收
  ├─ 更新 portfolio.json（港股 data_source = "tdx_relay"）
  ├─ 更新 watchlist.json（港股 data_source = "tdx_relay"）
  └─ 更新 relay_state.json（online=true, last_ping=now）
      │
      ▼
  price_monitor.py（每分钟运行）
    ├─ A股 → 腾讯 API（不变）
    ├─ 港股 → 检查 relay_state
    │   ├─ relay 在线 → 跳过（保留 tdx-relay 的实时价）
    │   └─ relay 离线（>60秒无推送）→ 回退腾讯 API
    └─ 数据源标记 → 写入 portfolio/watchlist
```

### 异常流程（relay 离线）

```
tdx-relay 断线
  │ 60秒内无推送
  ▼
price_monitor.py 检测到 relay_state.online=false
  │ 或 last_ping > 60秒前
  ├─ 港股 → 回退腾讯 API 拉取
  ├─ 写入时 data_source = "tencent"
  └─ 记录日志 "relay offline, fallback to tencent"

tdx-relay 恢复
  │ 推送到达 /api/update/realtime
  ▼
server.py 接收更新
  ├─ 更新 relay_state.json（online=true）
  └─ 正常接收行情
```

---

## 五、接口规范

### POST /api/update/realtime （已实现）

接收 tdx-relay 推送的实时行情。

请求格式：
```json
{
  "stocks": [
    {
      "code": "00700",
      "price": 467.20,
      "change_pct": 3.09,
      "high": 470.00,
      "low": 460.00,
      "open": 462.00,
      "volume": 15000000
    }
  ],
  "source": "tdx_relay"
}
```

响应：
```json
{
  "status": "ok",
  "updated": 15,
  "source": "tdx_relay",
  "timestamp": "2026-06-12T14:30:00"
}
```

### GET /api/relay/status （待实现）

查询 tdx-relay 当前状态。

响应：
```json
{
  "online": true,
  "source": "tdx_relay",
  "last_ping": "2026-06-12T14:29:55",
  "age_seconds": 5,
  "stocks_count": 15,
  "fallback_active": false
}
```

---

## 六、当前实现状态

### 已完成
- server.py `/api/update/realtime` 端点 ✅（v1.0）
- portfolio.json 写入 data_source 字段 ✅

### 待实现（知微负责）
1. relay_state.json 持久化 — 记录 relay 在线状态
2. /api/relay/status GET 端点 — 中继状态查询
3. price_monitor.py relay_active 检测 — 在线/离线判断
4. price_monitor 回退逻辑 — relay 离线时用腾讯 API 兜底

### 待实现（小小莫负责）
1. tdx-relay 心跳上报 — 定期推送到 /api/update/realtime
2. 断线自动重连验证 — Windows 端长期稳定运行
3. 行情覆盖检查 — 确保 17 只港股全量推送

---

## 七、港股代码列表（双方保持一致）

当前 17 只港股（来自 portfolio.json + watchlist.json）：

| 代码 | 名称 | 持仓/自选 |
|------|------|----------|
| 00700 | 腾讯控股 | 持仓 |
| 00981 | 中芯国际 | 持仓 |
| 01211 | 比亚迪股份 | 持仓 |
| 09988 | 阿里巴巴 | 持仓 |
| 02202 | 万科企业 | 持仓 |
| 02388 | 中银香港 | 持仓 |
| 01478 | 丘钛科技 | 持仓 |
| 09868 | 小鹏集团 | 自选(已清仓) |
| 01088 | 中国神华 | 持仓 |
| 02359 | 药明康德 | 自选 |
| 01888 | 建滔积层板 | 自选 |
| 00968 | 信义光能 | 自选 |
| 01070 | TCL电子 | 自选 |
| 02318 | 中国平安 | 自选 |
| 02628 | 中国人寿 | 自选 |
| 06160 | 百济神州 | 自选(已清仓) |
| 06869 | 长飞光纤 | 自选 |

---

## 八、故障处理

| 现象 | 可能原因 | 处理方式 |
|------|---------|---------|
| relay 显示离线 | Windows 端掉线 | 检查 Windows 端运行状态，双击 start_tdx_relay.bat |
| relay 在线但数据不更新 | 推送异常 | 查 Windows 端日志，重启 tdx-relay |
| 港股价格异常 | 数据源错乱 | 检查 data_source 字段，确认 relay 是否覆盖了错误数据 |
| 港股价格用腾讯旧数据 | relay 离线超过 60s 自动回退 | 正常行为，relay 恢复后自动切回 |