# Go 量化知识迭代系统完整架构

> 本文档记录基于 **Go 1.23.5 + Air v1.64.5** 构建的量化知识迭代系统的完整架构设计。
> 系统已通过实际试运行验证（2026-03-06），Air 热重载功能正常，修改源码后约 **1 秒内**自动重编译并重启服务。
>
> 返回：[知识库主目录](../README.md) | [Wiki 主索引](../wiki/README.md) | [tradehk 文档](../wiki/tradehk/README.md)

---

## 一、系统定位与设计目标

本系统是 `quantKonwledge` 知识库的**后端迭代引擎**，负责：

1. **知识库 MD 文档的自动迭代更新**：通过 API 触发，自动拉取最新市场数据、arXiv 论文、链上指标，更新对应 MD 文档
2. **多数据源统一接入**：聚合 10+ 个数据源（CEX、链上、宏观、期权），标准化为统一格式
3. **指标计算引擎**：将 tradehk 的 TypeScript 指标逻辑移植为 Go 实现，支持高并发计算
4. **信号生成与通知**：复现 tradehk 的 EWO 转换检测机制，支持飞书/Telegram/Webhook 通知
5. **热重载开发体验**：使用 Air 实现无需手动重启的开发迭代流程

**核心原则**：
- 所有知识以 MD 文档形式存储，系统只负责更新内容，不替代文档
- 数据源接入层与业务逻辑层严格分离
- 每个模块独立可测试，支持逐步迭代

---

## 二、技术栈

| 组件 | 版本 | 用途 |
|------|------|------|
| Go | 1.23.5 | 主语言，高并发数据处理 |
| Air | v1.64.5 | 热重载，开发时无需手动重启 |
| Gin | v1.9.x | HTTP 框架，API 路由 |
| GORM | v2.x | ORM，MySQL/SQLite 存储 |
| gorilla/websocket | v1.5.x | WebSocket 实时数据流 |
| go-redis | v9.x | Redis 缓存层 |
| viper | v1.x | 配置管理，支持热更新 |
| zap | v1.x | 结构化日志 |
| cron | v3.x | 定时任务（定期更新 MD 文档）|
| testify | v1.x | 单元测试 |

---

## 三、完整目录结构

```
quant-system/
├── .air.toml                    # Air 热重载配置（已验证）
├── .env                         # 环境变量（API Keys，不提交 Git）
├── .env.example                 # 环境变量示例（提交 Git）
├── go.mod                       # Go 模块定义
├── go.sum                       # 依赖锁定文件
├── Makefile                     # 常用命令快捷方式
├── docker-compose.yml           # Docker 部署配置
├── Dockerfile                   # 容器镜像定义
│
├── cmd/
│   └── server/
│       └── main.go              # 程序入口，HTTP 服务启动
│
├── internal/                    # 内部业务逻辑（不对外暴露）
│   ├── config/
│   │   ├── config.go            # 配置结构体定义
│   │   └── loader.go            # 配置加载（viper）
│   │
│   ├── datasource/              # 数据源接入层
│   │   ├── interface.go         # 数据源统一接口定义
│   │   ├── binance/
│   │   │   ├── client.go        # Binance REST + WebSocket 客户端
│   │   │   ├── klines.go        # K 线数据获取
│   │   │   └── ticker.go        # 实时行情
│   │   ├── okx/
│   │   │   └── client.go        # OKX 客户端
│   │   ├── bybit/
│   │   │   └── client.go        # Bybit 客户端
│   │   ├── deribit/
│   │   │   └── client.go        # Deribit 期权数据
│   │   ├── glassnode/
│   │   │   └── client.go        # 链上数据（MVRV/SOPR/NVT）
│   │   ├── coinglass/
│   │   │   └── client.go        # 资金费率/未平仓量/清算数据
│   │   ├── defillama/
│   │   │   └── client.go        # DeFi TVL 数据
│   │   ├── thegraph/
│   │   │   └── client.go        # The Graph GraphQL 查询
│   │   ├── coinmarketcap/
│   │   │   └── client.go        # CMC 市值/排名数据
│   │   ├── tradingview/
│   │   │   └── screener.go      # TradingView 筛选器
│   │   ├── fred/                # 美联储宏观数据
│   │   │   └── client.go        # 利率/CPI/就业数据
│   │   └── manager.go           # 数据源管理器（统一调度）
│   │
│   ├── indicators/              # 指标计算引擎（对应 tradehk/indicators.ts）
│   │   ├── ema.go               # EMA 指数移动平均
│   │   ├── ewo.go               # EWO 艾略特波浪振荡器（核心）
│   │   ├── macd.go              # MACD
│   │   ├── rsi.go               # RSI
│   │   ├── atr.go               # ATR 真实波幅
│   │   ├── supertrend.go        # SuperTrend
│   │   ├── ttm_squeeze.go       # TTM Squeeze
│   │   ├── bollinger.go         # 布林带
│   │   ├── kdj.go               # KDJ
│   │   ├── mfi.go               # MFI 资金流量指标
│   │   ├── obv.go               # OBV 能量潮
│   │   ├── stoch.go             # Stochastic
│   │   └── engine.go            # 指标计算引擎（批量计算）
│   │
│   ├── signals/                 # 信号生成层（对应 tradehk 信号评分）
│   │   ├── scorer.go            # 多指标共振评分引擎
│   │   ├── ewo_detector.go      # EWO 转换检测（对应 marketEngine.ts）
│   │   ├── bias.go              # 大周期偏向判定
│   │   ├── thresholds.go        # 各币种各周期阈值配置
│   │   └── types.go             # 信号类型定义
│   │
│   ├── notifier/                # 通知发送层
│   │   ├── feishu.go            # 飞书 Webhook 通知
│   │   ├── telegram.go          # Telegram Bot 通知
│   │   ├── webhook.go           # 通用 Webhook
│   │   └── formatter.go         # 通知格式化（对应飞书通知格式规范）
│   │
│   ├── storage/                 # 数据存储层
│   │   ├── mysql.go             # MySQL 连接与迁移
│   │   ├── redis.go             # Redis 缓存
│   │   ├── kline_repo.go        # K 线数据仓库
│   │   └── signal_repo.go       # 信号记录仓库
│   │
│   └── updater/                 # MD 文档迭代更新器（核心模块）
│       ├── md_writer.go         # MD 文档写入器
│       ├── knowledge_updater.go # 知识库内容更新调度
│       ├── arxiv_fetcher.go     # arXiv 论文自动抓取
│       └── market_reporter.go   # 市场数据自动写入 MD
│
├── api/
│   └── handlers/
│       ├── health.go            # 健康检查
│       ├── status.go            # 系统状态
│       ├── indicators.go        # 指标查询接口
│       ├── signals.go           # 信号查询接口
│       ├── datasources.go       # 数据源状态接口
│       └── knowledge.go         # 知识库更新触发接口
│
├── pkg/                         # 可复用公共包
│   ├── models/
│   │   ├── kline.go             # K 线数据模型
│   │   ├── signal.go            # 信号数据模型
│   │   └── indicator.go         # 指标数据模型
│   └── utils/
│       ├── timeutil.go          # 时间工具（时区转换）
│       ├── mathutil.go          # 数学工具（精度处理）
│       └── httputil.go          # HTTP 工具（重试/限流）
│
├── docs/
│   ├── api.md                   # API 文档
│   └── architecture.md          # 架构说明（本文档）
│
├── scripts/
│   ├── init_db.sh               # 数据库初始化脚本
│   ├── update_knowledge.sh      # 手动触发知识库更新
│   └── backfill_klines.sh       # 历史 K 线数据回填
│
└── tmp/                         # Air 编译输出目录（.gitignore）
    ├── quant-system             # 编译后的二进制文件
    └── build-errors.log         # 构建错误日志
```

---

## 四、核心模块详解

### 4.1 MD 文档迭代更新器（`internal/updater/`）

这是系统最核心的模块，负责将实时数据自动写入 `quantKonwledge` 仓库的 MD 文档。

**工作流程**：

```
定时触发（cron）
    ↓
数据源拉取（datasource/manager.go）
    ↓
数据处理与格式化
    ↓
定位目标 MD 文档（按模块/币种/日期）
    ↓
更新文档中的数据表格/价格/指标值
    ↓
Git commit + push（自动提交到 quantKonwledge）
    ↓
通知（飞书/Telegram）
```

**MD 文档更新规则**：

| 更新频率 | 目标文档 | 更新内容 |
|---------|---------|---------|
| 每 10 分钟 | `12_信号系统优化/各币种专项/*.md` | EWO 当前值、信号评分、当前阶段 |
| 每小时 | `10_链上数据分析/链上数据分析指南.md` | MVRV、SOPR、资金费率 |
| 每天 | `13_真实案例复盘/` | 当日重要信号记录 |
| 每周 | `11_参考文献/` | 新 arXiv 论文自动追加 |
| 手动触发 | 任意文档 | 通过 API `/api/v1/knowledge/update` 触发 |

### 4.2 指标计算引擎（`internal/indicators/`）

将 `tradehk/client/src/lib/indicators.ts` 的核心逻辑移植为 Go 实现。

**EWO 计算流程**（对应 `indicators.ts` L1-L44）：

```
输入：K 线数组（close 价格序列）
    ↓
计算 EMA(5)  → 快线
计算 EMA(34) → 慢线
    ↓
EWO = EMA(5) - EMA(34)
    ↓
归一化：EWO_pct = EWO / close * 100  （相对阈值，解决 SOL 绝对值问题）
    ↓
输出：{value: float64, pct: float64, direction: "red"|"green"}
```

**各币种 EWO 阈值配置**（`internal/signals/thresholds.go`）：

| 币种 | 绝对阈值 | 相对阈值 | 备注 |
|------|---------|---------|------|
| BTC | ≥ 15.0 | ≥ 0.015% | 主要用绝对阈值 |
| ETH | ≥ 12.0 | ≥ 0.020% | 主要用绝对阈值 |
| SOL | — | ≥ 0.025% | **只用相对阈值**（绝对值太小）|
| BNB | ≥ 10.0 | ≥ 0.018% | 主要用绝对阈值 |
| DOGE | — | ≥ 0.080% | **只用相对阈值** |
| XAUT | ≥ 8.0 | ≥ 0.004% | 黄金波动率低，阈值小 |

### 4.3 信号评分引擎（`internal/signals/scorer.go`）

复现 `tradehk/client/src/lib/indicators.ts` L454-L747 的多指标共振评分逻辑。

**评分权重表**（与 tradehk 保持一致）：

| 指标 | 多头 +分 | 空头 -分 | 权重说明 |
|------|---------|---------|---------|
| EWO 方向 | +2 | -2 | 核心指标，权重最高 |
| EWO 强力穿越 | +1 | -1 | 幅度超阈值 2 倍时额外加分 |
| MACD 方向 | +1 | -1 | 趋势确认 |
| RSI 区间 | +1 | -1 | >50 多头，<50 空头 |
| SuperTrend 方向 | +1 | -1 | 趋势跟踪 |
| TTM Squeeze 动量 | +1 | -1 | 动量方向 |
| 大周期偏向 | +1 | -1 | 4h 偏向过滤 |
| **满分** | **+8** | **-8** | — |

**信号触发阈值**：
- `≥ +5`：强多头信号，触发通知
- `≤ -5`：强空头信号，触发通知
- `+3 ~ +4`：弱多头，仅记录
- `-3 ~ -4`：弱空头，仅记录

---

## 五、API 接口设计

### 5.1 基础接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/health` | 健康检查 |
| GET | `/info` | 系统基本信息 |
| GET | `/api/v1/status` | 知识库状态（文档数/术语数/最后更新）|

### 5.2 指标接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/indicators` | 所有指标列表 |
| GET | `/api/v1/indicators/:name` | 单个指标详情 |
| POST | `/api/v1/indicators/calculate` | 计算指定币种/周期的指标值 |

**请求示例**：
```json
POST /api/v1/indicators/calculate
{
  "symbol": "BTCUSDT",
  "timeframe": "10m",
  "indicators": ["EWO", "MACD", "RSI"],
  "limit": 100
}
```

**响应示例**：
```json
{
  "symbol": "BTCUSDT",
  "timeframe": "10m",
  "timestamp": "2026-03-06T10:10:00+08:00",
  "indicators": {
    "EWO": {
      "value": 33.320837,
      "pct": 0.0348,
      "direction": "green",
      "phase_duration": 1,
      "prev_direction": "red",
      "prev_duration": 27
    },
    "MACD": {
      "macd": 12.5,
      "signal": 10.2,
      "histogram": 2.3,
      "direction": "bullish"
    },
    "RSI": {
      "value": 58.4,
      "zone": "neutral_bullish"
    }
  },
  "signal_score": 5,
  "signal_type": "strong_long"
}
```

### 5.3 信号接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/signals` | 最近信号列表 |
| GET | `/api/v1/signals/:symbol` | 指定币种信号历史 |
| POST | `/api/v1/signals/detect` | 手动触发信号检测 |

### 5.4 知识库更新接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/knowledge/update` | 触发知识库 MD 文档更新 |
| GET | `/api/v1/knowledge/status` | 查看更新状态 |
| GET | `/api/v1/datasources` | 数据源状态列表 |

---

## 六、数据流架构图

```
外部数据源
┌─────────────────────────────────────────────────────────┐
│  Binance  OKX  Bybit  Deribit  Glassnode  CoinGlass     │
│  DeFiLlama  The Graph  CMC  FRED  TradingView           │
└──────────────────────┬──────────────────────────────────┘
                       │ REST API / WebSocket
                       ▼
              datasource/manager.go
              （统一接入层，限流/重试/缓存）
                       │
          ┌────────────┼────────────┐
          ▼            ▼            ▼
    Redis 缓存    MySQL 存储    内存计算
    （实时数据）  （历史数据）  （指标计算）
          │            │            │
          └────────────┼────────────┘
                       │
              indicators/engine.go
              （EWO/MACD/RSI/ATR 等计算）
                       │
              signals/scorer.go
              （多指标共振评分）
                       │
          ┌────────────┼────────────┐
          ▼            ▼            ▼
    notifier/       storage/     updater/
    （飞书通知）   （信号存储）  （MD 文档更新）
                                    │
                              quantKonwledge/
                              （Git 仓库）
```

---

## 七、Air 热重载开发流程

### 7.1 启动开发环境

```bash
# 1. 克隆项目
git clone ssh://git@git.hk.hao.work:2222/hao/quant-system.git
cd quant-system

# 2. 复制环境变量
cp .env.example .env
# 编辑 .env，填入各数据源 API Key

# 3. 启动 Air（热重载模式）
air

# 输出示例：
# [00:40:04] watching cmd/server
# [00:40:04] building...
# [00:40:04] running...
# === QuantSystem v0.1.1 ===
# Air 热重载模式启动中...
# 服务地址: http://localhost:9090
```

### 7.2 迭代开发流程

```
修改任意 .go 文件
    ↓（Air 自动检测文件变化，约 1 秒）
Air 自动重新编译
    ↓（编译成功）
Air 自动重启服务
    ↓
curl http://localhost:9090/health 验证
    ↓
功能正常 → git commit → git push
```

### 7.3 知识库 MD 文档迭代流程

```
触发条件（定时 / API 调用 / 手动）
    ↓
updater/knowledge_updater.go 调度
    ↓
拉取最新数据（datasource）
    ↓
格式化为 MD 表格/段落
    ↓
定位 quantKonwledge 仓库对应文档
    ↓
更新文档中的数据区块（<!-- AUTO_UPDATE --> 标记之间）
    ↓
git add + commit + push
    ↓
通知（飞书）：「知识库已更新：BTC EWO 当前值 +33.32」
```

---

## 八、Makefile 常用命令

```makefile
# 开发模式（Air 热重载）
make dev

# 编译
make build

# 运行测试
make test

# 触发知识库更新
make update-knowledge

# 查看 API 状态
make status

# 数据库迁移
make migrate

# Docker 部署
make docker-up
```

---

## 九、实际试运行记录（2026-03-06）

| 步骤 | 结果 | 耗时 |
|------|------|------|
| Go 1.23.5 安装 | ✅ 成功 | ~30s |
| Air v1.64.5 安装 | ✅ 成功（自动升级到 Go 1.25.8）| ~90s |
| 项目目录初始化 | ✅ 成功（15 个目录）| <1s |
| 首次编译 | ✅ 成功（7.7MB 二进制）| ~1s |
| 服务启动 | ✅ 成功（端口 9090）| <1s |
| `/health` 接口 | ✅ 返回 `{"status":"ok","version":"0.1.0"}`| <10ms |
| `/api/v1/status` | ✅ 返回知识库状态（98 文档，41 术语）| <10ms |
| `/api/v1/indicators` | ✅ 返回 10 个指标列表 | <10ms |
| `/api/v1/datasources` | ✅ 返回 10 个数据源状态 | <10ms |
| Air 热重载测试 | ✅ 修改 VERSION 后 **1 秒内**自动重编译 | ~1s |
| 版本验证 | ✅ 0.1.0 → 0.1.1 自动更新 | — |

---

## 十、下一步迭代计划

| 优先级 | 功能 | 预计工作量 |
|--------|------|-----------|
| P0 | 接入 Binance WebSocket，实时 K 线推送 | 2 天 |
| P0 | EWO 转换检测完整实现（对应 marketEngine.ts）| 2 天 |
| P1 | 飞书通知发送（对应现有通知格式）| 1 天 |
| P1 | Redis 缓存层接入 | 1 天 |
| P1 | MySQL 历史数据存储 | 2 天 |
| P2 | MD 文档自动更新器 | 3 天 |
| P2 | arXiv 论文自动抓取 | 1 天 |
| P3 | 所有 10 个数据源完整接入 | 5 天 |
| P3 | Docker Compose 完整部署 | 1 天 |

---

## 参考资料

- [1] Air 框架 GitHub 仓库：https://github.com/air-verse/air（v1.64.5，23.1k Stars）
- [2] tradehk 指标引擎：`../wiki/tradehk/指标引擎详解.md`
- [3] tradehk 信号评分引擎：`../wiki/tradehk/信号评分引擎.md`
- [4] tradehk EWO 转换检测：`../wiki/tradehk/EWO转换检测机制.md`
- [5] EWO 阈值过滤完整流程：`../12_信号系统优化/EWO阈值过滤完整落地流程.md`
- [6] 各币种专项优化：`../12_信号系统优化/各币种专项/`
- [7] 数据源接入文档：`./数据源接入完整指南.md`