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

pkg/httpclient/client.go

@@ -0,0 +1,120 @@
+package httpclient
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"time"
+
+	"golang.org/x/time/rate"
+)
+
+type Client struct {
+	httpClient *http.Client
+	baseURL    string
+	limiter    *rate.Limiter
+	retryCount int
+}
+
+type Options struct {
+	BaseURL    string
+	Timeout    time.Duration
+	RetryCount int
+	RPS        float64
+	Burst      int
+}
+
+func New(opts Options) *Client {
+	if opts.Timeout == 0 {
+		opts.Timeout = 10 * time.Second
+	}
+	if opts.RPS <= 0 {
+		opts.RPS = 20
+	}
+	if opts.Burst <= 0 {
+		opts.Burst = 40
+	}
+	return &Client{
+		httpClient: &http.Client{Timeout: opts.Timeout},
+		baseURL:    opts.BaseURL,
+		retryCount: opts.RetryCount,
+		limiter:    rate.NewLimiter(rate.Limit(opts.RPS), opts.Burst),
+	}
+}
+
+type Request struct {
+	Method string
+	Path   string
+	Query  url.Values
+	Header http.Header
+}
+
+func (c *Client) Do(ctx context.Context, req Request) (int, []byte, http.Header, error) {
+	if err := c.limiter.Wait(ctx); err != nil {
+		return 0, nil, nil, err
+	}
+
+	fullURL := c.baseURL + req.Path
+	if len(req.Query) > 0 {
+		fullURL += "?" + req.Query.Encode()
+	}
+
+	var lastErr error
+	for attempt := 0; attempt <= c.retryCount; attempt++ {
+		if attempt > 0 {
+			select {
+			case <-ctx.Done():
+				return 0, nil, nil, ctx.Err()
+			case <-time.After(time.Duration(attempt) * 500 * time.Millisecond):
+			}
+		}
+
+		httpReq, err := http.NewRequestWithContext(ctx, req.Method, fullURL, nil)
+		if err != nil {
+			return 0, nil, nil, err
+		}
+		for k, vs := range req.Header {
+			for _, v := range vs {
+				httpReq.Header.Add(k, v)
+			}
+		}
+
+		resp, err := c.httpClient.Do(httpReq)
+		if err != nil {
+			lastErr = err
+			continue
+		}
+		body, readErr := io.ReadAll(resp.Body)
+		resp.Body.Close()
+		if readErr != nil {
+			lastErr = readErr
+			continue
+		}
+
+		if shouldRetry(resp.StatusCode) && attempt < c.retryCount {
+			lastErr = fmt.Errorf("retryable status %d", resp.StatusCode)
+			continue
+		}
+		return resp.StatusCode, body, resp.Header, nil
+	}
+
+	if lastErr == nil {
+		lastErr = errors.New("unknown http error")
+	}
+	return 0, nil, nil, lastErr
+}
+
+func shouldRetry(status int) bool {
+	switch status {
+	case http.StatusTooManyRequests,
+		http.StatusInternalServerError,
+		http.StatusBadGateway,
+		http.StatusServiceUnavailable,
+		http.StatusGatewayTimeout:
+		return true
+	}
+	return false
+}

pkg/logger/logger.go

@@ -0,0 +1,17 @@
+package logger
+
+import (
+	"log/slog"
+	"os"
+)
+
+func New(env string) *slog.Logger {
+	var handler slog.Handler
+	opts := &slog.HandlerOptions{Level: slog.LevelInfo}
+	if env == "local" || env == "dev" {
+		handler = slog.NewTextHandler(os.Stdout, opts)
+	} else {
+		handler = slog.NewJSONHandler(os.Stdout, opts)
+	}
+	return slog.New(handler)
+}

pkg/postgres/postgres.go

@@ -0,0 +1,36 @@
+package postgres
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+type Options struct {
+	DSN      string
+	MaxConns int32
+	MinConns int32
+}
+
+func NewPool(ctx context.Context, opts Options) (*pgxpool.Pool, error) {
+	cfg, err := pgxpool.ParseConfig(opts.DSN)
+	if err != nil {
+		return nil, fmt.Errorf("parse dsn: %w", err)
+	}
+	if opts.MaxConns > 0 {
+		cfg.MaxConns = opts.MaxConns
+	}
+	if opts.MinConns > 0 {
+		cfg.MinConns = opts.MinConns
+	}
+	pool, err := pgxpool.NewWithConfig(ctx, cfg)
+	if err != nil {
+		return nil, fmt.Errorf("pool: %w", err)
+	}
+	if err := pool.Ping(ctx); err != nil {
+		pool.Close()
+		return nil, fmt.Errorf("ping: %w", err)
+	}
+	return pool, nil
+}