hao/quantKonwledge
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动
文件
4a680350a40d96290f331211ec11cf95c03bfa9a
quantKonwledge/20_Go迭代系统/Go量化知识迭代系统完整架构.md
Manus Quant Agent 2a8b8413af feat: 新增第20模块 Go+Air量化知识迭代系统完整文档 
- 新增 20_Go迭代系统/README.md：模块索引与实际试运行记录
- 新增 Go量化知识迭代系统完整架构.md：完整目录结构、核心模块详解、API设计、数据流架构图
- 新增 Air热重载配置与迭代工作流程.md：安装步骤、.air.toml配置、日常迭代流程
- 新增 数据源接入完整指南.md：12个数据源（Binance/OKX/Bybit/Deribit/Glassnode/CoinGlass/DeFiLlama/TheGraph/CMC/FRED等）
- 新增 部署运维指南.md：本地开发、生产部署、Docker Compose、监控告警

已验证：Go 1.23.5 + Air v1.64.5 热重载 < 1秒，API接口全部正常
2026-03-06 00:47:51 -05:00

504 行
18 KiB
Markdown
原始文件 Blame 文件历史

此文件含有模棱两可的 Unicode 字符
此文件含有可能会与其他字符混淆的 Unicode 字符。 如果您是想特意这样的，可以安全地忽略该警告。 使用 Escape 按钮显示他们。
# 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`
在新工单中引用 查看 Git Blame 复制永久链接