feat: 初始化 cryptoHermes 行情网关 v1 MVP + harness 工程文档
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 无具体实现依赖，全项目 无私钥/签名字段。
This commit is contained in:
dela
18
internal/usecase/market_collector.go
Normal file
18
internal/usecase/market_collector.go
Normal file
@@ -0,0 +1,18 @@
|
||||
package usecase
|
||||
|
||||
import (
|
||||
"context"
|
||||
"log/slog"
|
||||
)
|
||||
|
||||
type MarketCollectorUsecase struct {
|
||||
log *slog.Logger
|
||||
}
|
||||
|
||||
func NewMarketCollectorUsecase(log *slog.Logger) *MarketCollectorUsecase {
|
||||
return &MarketCollectorUsecase{log: log}
|
||||
}
|
||||
|
||||
func (u *MarketCollectorUsecase) Tick(ctx context.Context) error {
|
||||
return nil
|
||||
}
|
||||
204
internal/usecase/market_context.go
Normal file
204
internal/usecase/market_context.go
Normal file
@@ -0,0 +1,204 @@
|
||||
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
|
||||
}
|
||||
51
internal/usecase/ports.go
Normal file
51
internal/usecase/ports.go
Normal file
@@ -0,0 +1,51 @@
|
||||
package usecase
|
||||
|
||||
import (
|
||||
"context"
|
||||
|
||||
"cryptoHermes/internal/entity"
|
||||
)
|
||||
|
||||
type MarketDataProvider interface {
|
||||
GetKlines(ctx context.Context, symbol, interval string, limit int) ([]entity.Kline, error)
|
||||
GetKlinesRange(ctx context.Context, symbol, interval string, startMs, endMs int64, limit int) ([]entity.Kline, error)
|
||||
GetTicker24h(ctx context.Context, symbol string) (*entity.Ticker24h, error)
|
||||
}
|
||||
|
||||
type DerivativesProvider interface {
|
||||
GetCurrentFunding(ctx context.Context, symbol string) (*entity.FundingRate, error)
|
||||
GetFundingHistory(ctx context.Context, symbol string, limit int) ([]entity.FundingRate, error)
|
||||
|
||||
GetCurrentOpenInterest(ctx context.Context, symbol string) (*entity.OpenInterest, error)
|
||||
GetOpenInterestHistory(ctx context.Context, symbol, period string, limit int) ([]entity.OpenInterest, error)
|
||||
|
||||
GetGlobalLongShortRatio(ctx context.Context, symbol, period string, limit int) ([]entity.LongShortRatio, error)
|
||||
GetTopTraderPositionRatio(ctx context.Context, symbol, period string, limit int) ([]entity.LongShortRatio, error)
|
||||
|
||||
GetTakerBuySellVolume(ctx context.Context, symbol, period string, limit int) ([]entity.TakerBuySellVolume, error)
|
||||
}
|
||||
|
||||
type KlineRepository interface {
|
||||
UpsertMany(ctx context.Context, items []entity.Kline) error
|
||||
FindRecent(ctx context.Context, symbol, interval string, limit int) ([]entity.Kline, error)
|
||||
}
|
||||
|
||||
type FundingRepository interface {
|
||||
UpsertMany(ctx context.Context, items []entity.FundingRate) error
|
||||
FindRecent(ctx context.Context, symbol string, limit int) ([]entity.FundingRate, error)
|
||||
}
|
||||
|
||||
type OpenInterestRepository interface {
|
||||
UpsertMany(ctx context.Context, items []entity.OpenInterest) error
|
||||
FindRecent(ctx context.Context, symbol, period string, limit int) ([]entity.OpenInterest, error)
|
||||
}
|
||||
|
||||
type LongShortRatioRepository interface {
|
||||
UpsertMany(ctx context.Context, items []entity.LongShortRatio) error
|
||||
FindRecent(ctx context.Context, symbol, period, ratioType string, limit int) ([]entity.LongShortRatio, error)
|
||||
}
|
||||
|
||||
type TakerVolumeRepository interface {
|
||||
UpsertMany(ctx context.Context, items []entity.TakerBuySellVolume) error
|
||||
FindRecent(ctx context.Context, symbol, period string, limit int) ([]entity.TakerBuySellVolume, error)
|
||||
}
|
||||
Reference in New Issue
Block a user