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 无具体实现依赖，全项目无私钥/签名字段。
2026-05-24 17:20:51 +08:00
commit cc7f5a4f32
58 changed files with 5356 additions and 0 deletions
--- a/internal/repo/persistent/postgres/funding_repo.go
+++ b/internal/repo/persistent/postgres/funding_repo.go
@@ -0,0 +1,86 @@
+package postgres
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"cryptoHermes/internal/entity"
+)
+
+type FundingRepo struct {
+	pool *pgxpool.Pool
+}
+
+func NewFundingRepo(pool *pgxpool.Pool) *FundingRepo {
+	return &FundingRepo{pool: pool}
+}
+
+const fundingUpsertSQL = `
+INSERT INTO funding_rates (source, symbol, funding_time, funding_rate, mark_price)
+VALUES ($1, $2, $3, $4, NULLIF($5, '')::NUMERIC)
+ON CONFLICT (source, symbol, funding_time) DO UPDATE SET
+  funding_rate = EXCLUDED.funding_rate,
+  mark_price = EXCLUDED.mark_price
+`
+
+func (r *FundingRepo) UpsertMany(ctx context.Context, items []entity.FundingRate) error {
+	if len(items) == 0 {
+		return nil
+	}
+	tx, err := r.pool.Begin(ctx)
+	if err != nil {
+		return err
+	}
+	defer tx.Rollback(ctx)
+
+	for _, f := range items {
+		if f.FundingRate == "" || f.FundingTime == 0 {
+			continue
+		}
+		if _, err := tx.Exec(ctx, fundingUpsertSQL,
+			f.Source, f.Symbol, f.FundingTime, f.FundingRate, f.MarkPrice,
+		); err != nil {
+			return fmt.Errorf("upsert funding %s@%d: %w", f.Symbol, f.FundingTime, err)
+		}
+	}
+	return tx.Commit(ctx)
+}
+
+const fundingFindSQL = `
+SELECT source, symbol, funding_time, funding_rate::text, COALESCE(mark_price::text, '')
+FROM funding_rates
+WHERE symbol = $1
+ORDER BY funding_time DESC
+LIMIT $2
+`
+
+func (r *FundingRepo) FindRecent(ctx context.Context, symbol string, limit int) ([]entity.FundingRate, error) {
+	if limit <= 0 {
+		limit = 100
+	}
+	rows, err := r.pool.Query(ctx, fundingFindSQL, symbol, limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	out := make([]entity.FundingRate, 0, limit)
+	for rows.Next() {
+		var f entity.FundingRate
+		var mark sql.NullString
+		if err := rows.Scan(&f.Source, &f.Symbol, &f.FundingTime, &f.FundingRate, &mark); err != nil {
+			return nil, err
+		}
+		if mark.Valid {
+			f.MarkPrice = mark.String
+		}
+		out = append(out, f)
+	}
+	for i, j := 0, len(out)-1; i < j; i, j = i+1, j-1 {
+		out[i], out[j] = out[j], out[i]
+	}
+	return out, rows.Err()
+}
--- a/internal/repo/persistent/postgres/kline_repo.go
+++ b/internal/repo/persistent/postgres/kline_repo.go
@@ -0,0 +1,114 @@
+package postgres
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"cryptoHermes/internal/entity"
+)
+
+type KlineRepo struct {
+	pool *pgxpool.Pool
+}
+
+func NewKlineRepo(pool *pgxpool.Pool) *KlineRepo {
+	return &KlineRepo{pool: pool}
+}
+
+const klineUpsertSQL = `
+INSERT INTO market_klines (
+  source, symbol, interval, open_time, close_time,
+  open, high, low, close,
+  volume, quote_volume,
+  trade_count, taker_buy_base_volume, taker_buy_quote_volume,
+  updated_at
+) VALUES (
+  $1, $2, $3, $4, $5,
+  $6, $7, $8, $9,
+  $10, $11,
+  $12, $13, $14,
+  now()
+)
+ON CONFLICT (source, symbol, interval, open_time) DO UPDATE SET
+  close_time = EXCLUDED.close_time,
+  open = EXCLUDED.open,
+  high = EXCLUDED.high,
+  low = EXCLUDED.low,
+  close = EXCLUDED.close,
+  volume = EXCLUDED.volume,
+  quote_volume = EXCLUDED.quote_volume,
+  trade_count = EXCLUDED.trade_count,
+  taker_buy_base_volume = EXCLUDED.taker_buy_base_volume,
+  taker_buy_quote_volume = EXCLUDED.taker_buy_quote_volume,
+  updated_at = now()
+`
+
+func (r *KlineRepo) UpsertMany(ctx context.Context, items []entity.Kline) error {
+	if len(items) == 0 {
+		return nil
+	}
+	tx, err := r.pool.Begin(ctx)
+	if err != nil {
+		return fmt.Errorf("begin: %w", err)
+	}
+	defer tx.Rollback(ctx)
+
+	for _, k := range items {
+		if !k.IsClosed {
+			continue
+		}
+		_, err := tx.Exec(ctx, klineUpsertSQL,
+			k.Source, k.Symbol, k.Interval, k.OpenTime, k.CloseTime,
+			k.Open, k.High, k.Low, k.Close,
+			k.Volume, k.QuoteVolume,
+			k.TradeCount, k.TakerBuyBaseVolume, k.TakerBuyQuoteVolume,
+		)
+		if err != nil {
+			return fmt.Errorf("upsert kline %s/%s@%d: %w", k.Symbol, k.Interval, k.OpenTime, err)
+		}
+	}
+	return tx.Commit(ctx)
+}
+
+const klineFindSQL = `
+SELECT source, symbol, interval, open_time, close_time,
+  open::text, high::text, low::text, close::text,
+  volume::text, quote_volume::text,
+  trade_count, taker_buy_base_volume::text, taker_buy_quote_volume::text
+FROM market_klines
+WHERE symbol = $1 AND interval = $2
+ORDER BY open_time DESC
+LIMIT $3
+`
+
+func (r *KlineRepo) FindRecent(ctx context.Context, symbol, interval string, limit int) ([]entity.Kline, error) {
+	if limit <= 0 {
+		limit = 300
+	}
+	rows, err := r.pool.Query(ctx, klineFindSQL, symbol, interval, limit)
+	if err != nil {
+		return nil, fmt.Errorf("query: %w", err)
+	}
+	defer rows.Close()
+
+	out := make([]entity.Kline, 0, limit)
+	for rows.Next() {
+		var k entity.Kline
+		if err := rows.Scan(
+			&k.Source, &k.Symbol, &k.Interval, &k.OpenTime, &k.CloseTime,
+			&k.Open, &k.High, &k.Low, &k.Close,
+			&k.Volume, &k.QuoteVolume,
+			&k.TradeCount, &k.TakerBuyBaseVolume, &k.TakerBuyQuoteVolume,
+		); err != nil {
+			return nil, fmt.Errorf("scan: %w", err)
+		}
+		k.IsClosed = true
+		out = append(out, k)
+	}
+	for i, j := 0, len(out)-1; i < j; i, j = i+1, j-1 {
+		out[i], out[j] = out[j], out[i]
+	}
+	return out, rows.Err()
+}
--- a/internal/repo/persistent/postgres/long_short_ratio_repo.go
+++ b/internal/repo/persistent/postgres/long_short_ratio_repo.go
@@ -0,0 +1,94 @@
+package postgres
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"cryptoHermes/internal/entity"
+)
+
+type LongShortRatioRepo struct {
+	pool *pgxpool.Pool
+}
+
+func NewLongShortRatioRepo(pool *pgxpool.Pool) *LongShortRatioRepo {
+	return &LongShortRatioRepo{pool: pool}
+}
+
+const lsUpsertSQL = `
+INSERT INTO long_short_ratio (
+  source, symbol, period, ratio_type, timestamp,
+  long_short_ratio, long_value, short_value
+) VALUES (
+  $1, $2, $3, $4, $5,
+  $6,
+  NULLIF($7, '')::NUMERIC,
+  NULLIF($8, '')::NUMERIC
+)
+ON CONFLICT (source, symbol, period, ratio_type, timestamp) DO UPDATE SET
+  long_short_ratio = EXCLUDED.long_short_ratio,
+  long_value = EXCLUDED.long_value,
+  short_value = EXCLUDED.short_value
+`
+
+func (r *LongShortRatioRepo) UpsertMany(ctx context.Context, items []entity.LongShortRatio) error {
+	if len(items) == 0 {
+		return nil
+	}
+	tx, err := r.pool.Begin(ctx)
+	if err != nil {
+		return err
+	}
+	defer tx.Rollback(ctx)
+
+	for _, ls := range items {
+		if ls.LongShortRatio == "" || ls.Timestamp == 0 {
+			continue
+		}
+		if _, err := tx.Exec(ctx, lsUpsertSQL,
+			ls.Source, ls.Symbol, ls.Period, ls.RatioType, ls.Timestamp,
+			ls.LongShortRatio, ls.LongValue, ls.ShortValue,
+		); err != nil {
+			return fmt.Errorf("upsert ls %s/%s/%s@%d: %w", ls.Symbol, ls.Period, ls.RatioType, ls.Timestamp, err)
+		}
+	}
+	return tx.Commit(ctx)
+}
+
+const lsFindSQL = `
+SELECT source, symbol, period, ratio_type, timestamp,
+       long_short_ratio::text,
+       COALESCE(long_value::text, ''),
+       COALESCE(short_value::text, '')
+FROM long_short_ratio
+WHERE symbol = $1 AND period = $2 AND ratio_type = $3
+ORDER BY timestamp DESC
+LIMIT $4
+`
+
+func (r *LongShortRatioRepo) FindRecent(ctx context.Context, symbol, period, ratioType string, limit int) ([]entity.LongShortRatio, error) {
+	if limit <= 0 {
+		limit = 100
+	}
+	rows, err := r.pool.Query(ctx, lsFindSQL, symbol, period, ratioType, limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	out := make([]entity.LongShortRatio, 0, limit)
+	for rows.Next() {
+		var ls entity.LongShortRatio
+		if err := rows.Scan(&ls.Source, &ls.Symbol, &ls.Period, &ls.RatioType, &ls.Timestamp,
+			&ls.LongShortRatio, &ls.LongValue, &ls.ShortValue); err != nil {
+			return nil, err
+		}
+		out = append(out, ls)
+	}
+	for i, j := 0, len(out)-1; i < j; i, j = i+1, j-1 {
+		out[i], out[j] = out[j], out[i]
+	}
+	return out, rows.Err()
+}
--- a/internal/repo/persistent/postgres/open_interest_repo.go
+++ b/internal/repo/persistent/postgres/open_interest_repo.go
@@ -0,0 +1,82 @@
+package postgres
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"cryptoHermes/internal/entity"
+)
+
+type OpenInterestRepo struct {
+	pool *pgxpool.Pool
+}
+
+func NewOpenInterestRepo(pool *pgxpool.Pool) *OpenInterestRepo {
+	return &OpenInterestRepo{pool: pool}
+}
+
+const oiUpsertSQL = `
+INSERT INTO open_interest (source, symbol, period, timestamp, open_interest, open_interest_value)
+VALUES ($1, $2, $3, $4, $5, NULLIF($6, '')::NUMERIC)
+ON CONFLICT (source, symbol, period, timestamp) DO UPDATE SET
+  open_interest = EXCLUDED.open_interest,
+  open_interest_value = EXCLUDED.open_interest_value
+`
+
+func (r *OpenInterestRepo) UpsertMany(ctx context.Context, items []entity.OpenInterest) error {
+	if len(items) == 0 {
+		return nil
+	}
+	tx, err := r.pool.Begin(ctx)
+	if err != nil {
+		return err
+	}
+	defer tx.Rollback(ctx)
+
+	for _, o := range items {
+		if o.OpenInterest == "" || o.Timestamp == 0 {
+			continue
+		}
+		if _, err := tx.Exec(ctx, oiUpsertSQL,
+			o.Source, o.Symbol, o.Period, o.Timestamp, o.OpenInterest, o.OpenInterestValue,
+		); err != nil {
+			return fmt.Errorf("upsert oi %s/%s@%d: %w", o.Symbol, o.Period, o.Timestamp, err)
+		}
+	}
+	return tx.Commit(ctx)
+}
+
+const oiFindSQL = `
+SELECT source, symbol, period, timestamp,
+       open_interest::text, COALESCE(open_interest_value::text, '')
+FROM open_interest
+WHERE symbol = $1 AND period = $2
+ORDER BY timestamp DESC
+LIMIT $3
+`
+
+func (r *OpenInterestRepo) FindRecent(ctx context.Context, symbol, period string, limit int) ([]entity.OpenInterest, error) {
+	if limit <= 0 {
+		limit = 100
+	}
+	rows, err := r.pool.Query(ctx, oiFindSQL, symbol, period, limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	out := make([]entity.OpenInterest, 0, limit)
+	for rows.Next() {
+		var o entity.OpenInterest
+		if err := rows.Scan(&o.Source, &o.Symbol, &o.Period, &o.Timestamp, &o.OpenInterest, &o.OpenInterestValue); err != nil {
+			return nil, err
+		}
+		out = append(out, o)
+	}
+	for i, j := 0, len(out)-1; i < j; i, j = i+1, j-1 {
+		out[i], out[j] = out[j], out[i]
+	}
+	return out, rows.Err()
+}
--- a/internal/repo/persistent/postgres/taker_volume_repo.go
+++ b/internal/repo/persistent/postgres/taker_volume_repo.go
@@ -0,0 +1,90 @@
+package postgres
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"cryptoHermes/internal/entity"
+)
+
+type TakerVolumeRepo struct {
+	pool *pgxpool.Pool
+}
+
+func NewTakerVolumeRepo(pool *pgxpool.Pool) *TakerVolumeRepo {
+	return &TakerVolumeRepo{pool: pool}
+}
+
+const takerUpsertSQL = `
+INSERT INTO taker_buy_sell_volume (source, symbol, period, timestamp, buy_sell_ratio, buy_volume, sell_volume)
+VALUES ($1, $2, $3, $4,
+  NULLIF($5, '')::NUMERIC,
+  NULLIF($6, '')::NUMERIC,
+  NULLIF($7, '')::NUMERIC)
+ON CONFLICT (source, symbol, period, timestamp) DO UPDATE SET
+  buy_sell_ratio = EXCLUDED.buy_sell_ratio,
+  buy_volume = EXCLUDED.buy_volume,
+  sell_volume = EXCLUDED.sell_volume
+`
+
+func (r *TakerVolumeRepo) UpsertMany(ctx context.Context, items []entity.TakerBuySellVolume) error {
+	if len(items) == 0 {
+		return nil
+	}
+	tx, err := r.pool.Begin(ctx)
+	if err != nil {
+		return err
+	}
+	defer tx.Rollback(ctx)
+
+	for _, t := range items {
+		if t.Timestamp == 0 {
+			continue
+		}
+		if _, err := tx.Exec(ctx, takerUpsertSQL,
+			t.Source, t.Symbol, t.Period, t.Timestamp,
+			t.BuySellRatio, t.BuyVolume, t.SellVolume,
+		); err != nil {
+			return fmt.Errorf("upsert taker %s/%s@%d: %w", t.Symbol, t.Period, t.Timestamp, err)
+		}
+	}
+	return tx.Commit(ctx)
+}
+
+const takerFindSQL = `
+SELECT source, symbol, period, timestamp,
+       COALESCE(buy_sell_ratio::text, ''),
+       COALESCE(buy_volume::text, ''),
+       COALESCE(sell_volume::text, '')
+FROM taker_buy_sell_volume
+WHERE symbol = $1 AND period = $2
+ORDER BY timestamp DESC
+LIMIT $3
+`
+
+func (r *TakerVolumeRepo) FindRecent(ctx context.Context, symbol, period string, limit int) ([]entity.TakerBuySellVolume, error) {
+	if limit <= 0 {
+		limit = 100
+	}
+	rows, err := r.pool.Query(ctx, takerFindSQL, symbol, period, limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	out := make([]entity.TakerBuySellVolume, 0, limit)
+	for rows.Next() {
+		var t entity.TakerBuySellVolume
+		if err := rows.Scan(&t.Source, &t.Symbol, &t.Period, &t.Timestamp,
+			&t.BuySellRatio, &t.BuyVolume, &t.SellVolume); err != nil {
+			return nil, err
+		}
+		out = append(out, t)
+	}
+	for i, j := 0, len(out)-1; i < j; i, j = i+1, j-1 {
+		out[i], out[j] = out[j], out[i]
+	}
+	return out, rows.Err()
+}