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/entity/funding.go

@@ -0,0 +1,9 @@
+package entity
+
+type FundingRate struct {
+	Source      string `json:"source"`
+	Symbol      string `json:"symbol"`
+	FundingTime int64  `json:"fundingTime"`
+	FundingRate string `json:"fundingRate"`
+	MarkPrice   string `json:"markPrice,omitempty"`
+}

internal/entity/kline.go

@@ -0,0 +1,19 @@
+package entity
+
+type Kline struct {
+	Source              string `json:"source"`
+	Symbol              string `json:"symbol"`
+	Interval            string `json:"interval"`
+	OpenTime            int64  `json:"openTime"`
+	CloseTime           int64  `json:"closeTime"`
+	Open                string `json:"open"`
+	High                string `json:"high"`
+	Low                 string `json:"low"`
+	Close               string `json:"close"`
+	Volume              string `json:"volume"`
+	QuoteVolume         string `json:"quoteVolume"`
+	TradeCount          int64  `json:"tradeCount"`
+	TakerBuyBaseVolume  string `json:"takerBuyBaseVolume"`
+	TakerBuyQuoteVolume string `json:"takerBuyQuoteVolume"`
+	IsClosed            bool   `json:"-"`
+}

internal/entity/long_short_ratio.go

@@ -0,0 +1,18 @@
+package entity
+
+const (
+	RatioTypeGlobalAccount     = "global_account"
+	RatioTypeTopTraderPosition = "top_trader_position"
+	RatioTypeTopTraderAccount  = "top_trader_account"
+)
+
+type LongShortRatio struct {
+	Source         string `json:"source"`
+	Symbol         string `json:"symbol"`
+	Period         string `json:"period"`
+	RatioType      string `json:"ratioType"`
+	Timestamp      int64  `json:"timestamp"`
+	LongShortRatio string `json:"longShortRatio"`
+	LongValue      string `json:"longValue,omitempty"`
+	ShortValue     string `json:"shortValue,omitempty"`
+}

internal/entity/market_context.go

@@ -0,0 +1,52 @@
+package entity
+
+type MarketContext struct {
+	Symbol      string                  `json:"symbol"`
+	GeneratedAt int64                   `json:"generatedAt"`
+	Snapshot    *Ticker24h              `json:"snapshot"`
+	Klines      map[string][]Kline      `json:"klines"`
+	Derivatives DerivativesBundle       `json:"derivatives"`
+	Technical   TechnicalStructure      `json:"technical"`
+	DataQuality DataQuality             `json:"dataQuality"`
+}
+
+type DerivativesBundle struct {
+	Funding            FundingBundle      `json:"funding"`
+	OpenInterest       OpenInterestBundle `json:"openInterest"`
+	LongShortRatio     LongShortBundle    `json:"longShortRatio"`
+	TakerBuySellVolume []TakerBuySellVolume `json:"takerBuySellVolume"`
+}
+
+type FundingBundle struct {
+	Current *FundingRate  `json:"current"`
+	History []FundingRate `json:"history"`
+}
+
+type OpenInterestBundle struct {
+	Current *OpenInterest  `json:"current"`
+	History []OpenInterest `json:"history"`
+}
+
+type LongShortBundle struct {
+	Global            []LongShortRatio `json:"global"`
+	TopTraderPosition []LongShortRatio `json:"topTraderPosition"`
+}
+
+type TechnicalStructure struct {
+	Support       []TechnicalLevel `json:"support"`
+	Resistance    []TechnicalLevel `json:"resistance"`
+	RangeHigh     *string          `json:"rangeHigh"`
+	RangeLow      *string          `json:"rangeLow"`
+	LongShortLine *string          `json:"longShortLine"`
+}
+
+type TechnicalLevel struct {
+	Price    string `json:"price"`
+	Strength string `json:"strength,omitempty"`
+	Source   string `json:"source,omitempty"`
+}
+
+type DataQuality struct {
+	Source   string   `json:"source"`
+	Warnings []string `json:"warnings"`
+}

internal/entity/open_interest.go

@@ -0,0 +1,10 @@
+package entity
+
+type OpenInterest struct {
+	Source            string `json:"source"`
+	Symbol            string `json:"symbol"`
+	Period            string `json:"period"`
+	Timestamp         int64  `json:"timestamp"`
+	OpenInterest      string `json:"openInterest"`
+	OpenInterestValue string `json:"openInterestValue,omitempty"`
+}

internal/entity/taker_volume.go

@@ -0,0 +1,11 @@
+package entity
+
+type TakerBuySellVolume struct {
+	Source        string `json:"source"`
+	Symbol        string `json:"symbol"`
+	Period        string `json:"period"`
+	Timestamp     int64  `json:"timestamp"`
+	BuySellRatio  string `json:"buySellRatio,omitempty"`
+	BuyVolume     string `json:"buyVolume,omitempty"`
+	SellVolume    string `json:"sellVolume,omitempty"`
+}

internal/entity/ticker.go

@@ -0,0 +1,14 @@
+package entity
+
+type Ticker24h struct {
+	Symbol             string `json:"symbol"`
+	LastPrice          string `json:"lastPrice"`
+	PriceChange        string `json:"priceChange"`
+	PriceChangePercent string `json:"priceChangePercent"`
+	HighPrice          string `json:"highPrice"`
+	LowPrice           string `json:"lowPrice"`
+	Volume             string `json:"volume"`
+	QuoteVolume        string `json:"quoteVolume"`
+	OpenTime           int64  `json:"openTime"`
+	CloseTime          int64  `json:"closeTime"`
+}