Binance USDⓈ-M Futures 行情网关,给上游 Hermes 量化分析引擎提供单一聚合 接口 /v1/market/context(K 线 + funding + OI + 多空比 + taker volume)。 只读公共行情,不下单、不接私钥、不查账户。 ## v1 实现范围(Milestone 1-5) - Clean Architecture 4 层(controller/usecase/repo/entity),接口边界在 internal/usecase/ports.go - Binance Futures REST client(K 线 / ticker24h / funding / OI / 多空比 / taker volume 共 9 个接口),全链路 string 价格避免 float64 精度问题 - TimescaleDB 5 张 hypertable(market_klines / funding_rates / open_interest / long_short_ratio / taker_buy_sell_volume),主键含 时间维度,UpsertMany 幂等 - robfig/cron 定时采集(15m/1h/4h/1d/1w 多周期 K 线 + 衍生品 15 分钟 落库),未收线 K 线 (close_time > now) 由 mapper/repo 双重过滤 - pkg/httpclient 统一限流(默认 20 req/s, burst 40)+ 重试,避免触发 Binance 2400 weight/min IP 上限 - /v1/market/context 聚合接口:errgroup 并发拉 snapshot/funding/OI,DB K 线不足 200 根回源 Binance 异步补 - cmd/backfill CLI 支持指定 from/to 大段回填(Binance 历史 OI / 多空比 官方只保留 30 天,必须自己存) - Docker Compose + Makefile + golang-migrate,本地一键启 技术指标(support/resistance/Vegas/箱体)留待 v2,技术段返回空对象 + warning 占位。 ## Harness 工程文档 - AGENTS.md — AI agent 工作速查(10 个章节) - ai/project-map.md — 仓库结构、扩展点、控制流 - ai/risk-guardrails.md — G1-G10 守卫规则(每条带可机械验证命令) - ai/adr/0001-architecture-foundations.md — 9 条架构基础决策 - ai/task-templates.md — 6 种任务契约模板 - ai/harness-health.md — 当前 harness 健康度评估 3 个 grep 守卫已验证通过:controller / usecase 无具体实现依赖,全项目 无私钥/签名字段。
205 lines
4.9 KiB
Go
205 lines
4.9 KiB
Go
package usecase
|
|
|
|
import (
|
|
"context"
|
|
"errors"
|
|
"fmt"
|
|
"log/slog"
|
|
"sync"
|
|
"time"
|
|
|
|
"golang.org/x/sync/errgroup"
|
|
|
|
"cryptoHermes/internal/entity"
|
|
)
|
|
|
|
var supportedSymbols = map[string]bool{
|
|
"BTCUSDT": true,
|
|
"ETHUSDT": true,
|
|
}
|
|
|
|
var supportedIntervals = []string{"15m", "1h", "4h", "1d", "1w"}
|
|
|
|
const (
|
|
klineWindowSize = 300
|
|
klineMinForOK = 200
|
|
derivativePeriod = "1h"
|
|
fundingHistoryLen = 100
|
|
oiHistoryLen = 200
|
|
longShortLen = 200
|
|
takerHistoryLen = 200
|
|
)
|
|
|
|
type MarketContextUsecase struct {
|
|
marketData MarketDataProvider
|
|
derivatives DerivativesProvider
|
|
|
|
klineRepo KlineRepository
|
|
fundingRepo FundingRepository
|
|
oiRepo OpenInterestRepository
|
|
lsRepo LongShortRatioRepository
|
|
|
|
log *slog.Logger
|
|
}
|
|
|
|
func NewMarketContextUsecase(
|
|
marketData MarketDataProvider,
|
|
derivatives DerivativesProvider,
|
|
klineRepo KlineRepository,
|
|
fundingRepo FundingRepository,
|
|
oiRepo OpenInterestRepository,
|
|
lsRepo LongShortRatioRepository,
|
|
log *slog.Logger,
|
|
) *MarketContextUsecase {
|
|
return &MarketContextUsecase{
|
|
marketData: marketData,
|
|
derivatives: derivatives,
|
|
klineRepo: klineRepo,
|
|
fundingRepo: fundingRepo,
|
|
oiRepo: oiRepo,
|
|
lsRepo: lsRepo,
|
|
log: log,
|
|
}
|
|
}
|
|
|
|
func (u *MarketContextUsecase) Build(ctx context.Context, symbol string) (*entity.MarketContext, error) {
|
|
if !supportedSymbols[symbol] {
|
|
return nil, fmt.Errorf("unsupported symbol: %s", symbol)
|
|
}
|
|
|
|
var (
|
|
snapshot *entity.Ticker24h
|
|
currentFund *entity.FundingRate
|
|
currentOI *entity.OpenInterest
|
|
warnMu sync.Mutex
|
|
warnings []string
|
|
)
|
|
addWarn := func(w string) {
|
|
warnMu.Lock()
|
|
warnings = append(warnings, w)
|
|
warnMu.Unlock()
|
|
}
|
|
|
|
g, gctx := errgroup.WithContext(ctx)
|
|
|
|
g.Go(func() error {
|
|
s, err := u.marketData.GetTicker24h(gctx, symbol)
|
|
if err != nil {
|
|
addWarn("snapshot fetch failed: " + err.Error())
|
|
return nil
|
|
}
|
|
snapshot = s
|
|
return nil
|
|
})
|
|
g.Go(func() error {
|
|
f, err := u.derivatives.GetCurrentFunding(gctx, symbol)
|
|
if err != nil {
|
|
addWarn("current funding fetch failed: " + err.Error())
|
|
return nil
|
|
}
|
|
currentFund = f
|
|
return nil
|
|
})
|
|
g.Go(func() error {
|
|
oi, err := u.derivatives.GetCurrentOpenInterest(gctx, symbol)
|
|
if err != nil {
|
|
addWarn("current OI fetch failed: " + err.Error())
|
|
return nil
|
|
}
|
|
currentOI = oi
|
|
return nil
|
|
})
|
|
|
|
_ = g.Wait()
|
|
|
|
klines := make(map[string][]entity.Kline, len(supportedIntervals))
|
|
for _, iv := range supportedIntervals {
|
|
rows, err := u.klineRepo.FindRecent(ctx, symbol, iv, klineWindowSize)
|
|
if err != nil {
|
|
addWarn(fmt.Sprintf("klines DB query failed for %s: %v", iv, err))
|
|
rows = nil
|
|
}
|
|
if len(rows) < klineMinForOK {
|
|
addWarn(fmt.Sprintf("klines %s only %d in DB, falling back to Binance", iv, len(rows)))
|
|
fresh, ferr := u.marketData.GetKlines(ctx, symbol, iv, klineWindowSize)
|
|
if ferr != nil {
|
|
addWarn(fmt.Sprintf("klines fallback %s failed: %v", iv, ferr))
|
|
} else {
|
|
closed := make([]entity.Kline, 0, len(fresh))
|
|
for _, k := range fresh {
|
|
if k.IsClosed {
|
|
closed = append(closed, k)
|
|
}
|
|
}
|
|
go func(items []entity.Kline) {
|
|
bgCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
|
|
defer cancel()
|
|
if err := u.klineRepo.UpsertMany(bgCtx, items); err != nil {
|
|
u.log.Error("background_kline_upsert_failed", "err", err)
|
|
}
|
|
}(closed)
|
|
rows = closed
|
|
}
|
|
}
|
|
klines[iv] = rows
|
|
}
|
|
|
|
fundingHist, err := u.fundingRepo.FindRecent(ctx, symbol, fundingHistoryLen)
|
|
if err != nil {
|
|
addWarn("funding history query failed: " + err.Error())
|
|
}
|
|
|
|
oiHist, err := u.oiRepo.FindRecent(ctx, symbol, derivativePeriod, oiHistoryLen)
|
|
if err != nil {
|
|
addWarn("OI history query failed: " + err.Error())
|
|
}
|
|
|
|
globalLS, err := u.lsRepo.FindRecent(ctx, symbol, derivativePeriod, entity.RatioTypeGlobalAccount, longShortLen)
|
|
if err != nil {
|
|
addWarn("global long/short query failed: " + err.Error())
|
|
}
|
|
topLS, err := u.lsRepo.FindRecent(ctx, symbol, derivativePeriod, entity.RatioTypeTopTraderPosition, longShortLen)
|
|
if err != nil {
|
|
addWarn("top trader position long/short query failed: " + err.Error())
|
|
}
|
|
|
|
out := &entity.MarketContext{
|
|
Symbol: symbol,
|
|
GeneratedAt: time.Now().UnixMilli(),
|
|
Snapshot: snapshot,
|
|
Klines: klines,
|
|
Derivatives: entity.DerivativesBundle{
|
|
Funding: entity.FundingBundle{
|
|
Current: currentFund,
|
|
History: fundingHist,
|
|
},
|
|
OpenInterest: entity.OpenInterestBundle{
|
|
Current: currentOI,
|
|
History: oiHist,
|
|
},
|
|
LongShortRatio: entity.LongShortBundle{
|
|
Global: globalLS,
|
|
TopTraderPosition: topLS,
|
|
},
|
|
TakerBuySellVolume: nil,
|
|
},
|
|
Technical: entity.TechnicalStructure{
|
|
Support: []entity.TechnicalLevel{},
|
|
Resistance: []entity.TechnicalLevel{},
|
|
},
|
|
DataQuality: entity.DataQuality{
|
|
Source: "binance",
|
|
Warnings: warnings,
|
|
},
|
|
}
|
|
|
|
if out.DataQuality.Warnings == nil {
|
|
out.DataQuality.Warnings = []string{}
|
|
}
|
|
|
|
if snapshot == nil {
|
|
return out, errors.New("market snapshot unavailable")
|
|
}
|
|
return out, nil
|
|
}
|