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 无具体实现依赖，全项目
无私钥/签名字段。

internal/repo/webapi/binance/mapper.go

@@ -0,0 +1,170 @@
+package binance
+
+import (
+	"fmt"
+	"time"
+
+	"cryptoHermes/internal/entity"
+)
+
+func parseKlineRow(symbol, interval string, row []any) (entity.Kline, error) {
+	if len(row) < 12 {
+		return entity.Kline{}, fmt.Errorf("binance kline row has %d fields, expected >=12", len(row))
+	}
+	openTime, err := toInt64(row[0])
+	if err != nil {
+		return entity.Kline{}, fmt.Errorf("openTime: %w", err)
+	}
+	closeTime, err := toInt64(row[6])
+	if err != nil {
+		return entity.Kline{}, fmt.Errorf("closeTime: %w", err)
+	}
+	tradeCount, err := toInt64(row[8])
+	if err != nil {
+		return entity.Kline{}, fmt.Errorf("tradeCount: %w", err)
+	}
+
+	open, _ := row[1].(string)
+	high, _ := row[2].(string)
+	low, _ := row[3].(string)
+	closeP, _ := row[4].(string)
+	volume, _ := row[5].(string)
+	quoteVol, _ := row[7].(string)
+	takerBase, _ := row[9].(string)
+	takerQuote, _ := row[10].(string)
+
+	nowMs := time.Now().UnixMilli()
+	return entity.Kline{
+		Source:              sourceName,
+		Symbol:              symbol,
+		Interval:            interval,
+		OpenTime:            openTime,
+		CloseTime:           closeTime,
+		Open:                open,
+		High:                high,
+		Low:                 low,
+		Close:               closeP,
+		Volume:              volume,
+		QuoteVolume:         quoteVol,
+		TradeCount:          tradeCount,
+		TakerBuyBaseVolume:  takerBase,
+		TakerBuyQuoteVolume: takerQuote,
+		IsClosed:            closeTime < nowMs,
+	}, nil
+}
+
+func toInt64(v any) (int64, error) {
+	switch x := v.(type) {
+	case float64:
+		return int64(x), nil
+	case int64:
+		return x, nil
+	case int:
+		return int64(x), nil
+	default:
+		return 0, fmt.Errorf("unexpected type %T", v)
+	}
+}
+
+func mapTicker(d *tickerDTO) *entity.Ticker24h {
+	return &entity.Ticker24h{
+		Symbol:             d.Symbol,
+		LastPrice:          d.LastPrice,
+		PriceChange:        d.PriceChange,
+		PriceChangePercent: d.PriceChangePercent,
+		HighPrice:          d.HighPrice,
+		LowPrice:           d.LowPrice,
+		Volume:             d.Volume,
+		QuoteVolume:        d.QuoteVolume,
+		OpenTime:           d.OpenTime,
+		CloseTime:          d.CloseTime,
+	}
+}
+
+func mapPremiumIndex(d *premiumIndexDTO) *entity.FundingRate {
+	return &entity.FundingRate{
+		Source:      sourceName,
+		Symbol:      d.Symbol,
+		FundingTime: d.NextFundingTime,
+		FundingRate: d.LastFundingRate,
+		MarkPrice:   d.MarkPrice,
+	}
+}
+
+func mapFundingHistory(d []fundingRateDTO) []entity.FundingRate {
+	out := make([]entity.FundingRate, 0, len(d))
+	for _, x := range d {
+		out = append(out, entity.FundingRate{
+			Source:      sourceName,
+			Symbol:      x.Symbol,
+			FundingTime: x.FundingTime,
+			FundingRate: x.FundingRate,
+			MarkPrice:   x.MarkPrice,
+		})
+	}
+	return out
+}
+
+func mapOpenInterest(d *openInterestDTO, period string) *entity.OpenInterest {
+	return &entity.OpenInterest{
+		Source:       sourceName,
+		Symbol:       d.Symbol,
+		Period:       period,
+		Timestamp:    d.Time,
+		OpenInterest: d.OpenInterest,
+	}
+}
+
+func mapOpenInterestHistory(d []openInterestHistDTO, period string) []entity.OpenInterest {
+	out := make([]entity.OpenInterest, 0, len(d))
+	for _, x := range d {
+		out = append(out, entity.OpenInterest{
+			Source:            sourceName,
+			Symbol:            x.Symbol,
+			Period:            period,
+			Timestamp:         x.Timestamp,
+			OpenInterest:      x.SumOpenInterest,
+			OpenInterestValue: x.SumOpenInterestValue,
+		})
+	}
+	return out
+}
+
+func mapLongShort(d []longShortRatioDTO, period, ratioType string) []entity.LongShortRatio {
+	out := make([]entity.LongShortRatio, 0, len(d))
+	for _, x := range d {
+		longVal := x.LongAccount
+		shortVal := x.ShortAccount
+		if ratioType == entity.RatioTypeTopTraderPosition {
+			longVal = x.LongPosition
+			shortVal = x.ShortPosition
+		}
+		out = append(out, entity.LongShortRatio{
+			Source:         sourceName,
+			Symbol:         x.Symbol,
+			Period:         period,
+			RatioType:      ratioType,
+			Timestamp:      x.Timestamp,
+			LongShortRatio: x.LongShortRatio,
+			LongValue:      longVal,
+			ShortValue:     shortVal,
+		})
+	}
+	return out
+}
+
+func mapTakerVolume(d []takerVolumeDTO, symbol, period string) []entity.TakerBuySellVolume {
+	out := make([]entity.TakerBuySellVolume, 0, len(d))
+	for _, x := range d {
+		out = append(out, entity.TakerBuySellVolume{
+			Source:       sourceName,
+			Symbol:       symbol,
+			Period:       period,
+			Timestamp:    x.Timestamp,
+			BuySellRatio: x.BuySellRatio,
+			BuyVolume:    x.BuyVol,
+			SellVolume:   x.SellVol,
+		})
+	}
+	return out
+}