Files
cryptoHermes/internal/repo/persistent/postgres/kline_repo.go
dela cc7f5a4f32 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

115 lines
2.8 KiB
Go

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()
}