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/controller/restapi/middleware.go

@@ -0,0 +1,38 @@
+package restapi
+
+import (
+	"log/slog"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+)
+
+func RequestLogger(log *slog.Logger) fiber.Handler {
+	return func(c *fiber.Ctx) error {
+		start := time.Now()
+		err := c.Next()
+		log.Info("http_request",
+			"method", c.Method(),
+			"path", c.Path(),
+			"status", c.Response().StatusCode(),
+			"duration_ms", time.Since(start).Milliseconds(),
+			"ip", c.IP(),
+		)
+		return err
+	}
+}
+
+func ErrorHandler(c *fiber.Ctx, err error) error {
+	code := fiber.StatusInternalServerError
+	msg := "internal error"
+	if fe, ok := err.(*fiber.Error); ok {
+		code = fe.Code
+		msg = fe.Message
+	}
+	return c.Status(code).JSON(fiber.Map{
+		"error": fiber.Map{
+			"code":    code,
+			"message": msg,
+		},
+	})
+}

internal/controller/restapi/router.go

@@ -0,0 +1,39 @@
+package restapi
+
+import (
+	"log/slog"
+
+	"github.com/gofiber/fiber/v2"
+	"github.com/gofiber/fiber/v2/middleware/recover"
+
+	v1 "cryptoHermes/internal/controller/restapi/v1"
+	"cryptoHermes/internal/usecase"
+)
+
+type Deps struct {
+	Logger         *slog.Logger
+	MarketContext  *usecase.MarketContextUsecase
+	MarketData     usecase.MarketDataProvider
+	Derivatives    usecase.DerivativesProvider
+	KlineRepo      usecase.KlineRepository
+	FundingRepo    usecase.FundingRepository
+	OIRepo         usecase.OpenInterestRepository
+	LSRepo         usecase.LongShortRatioRepository
+}
+
+func Register(app *fiber.App, deps Deps) {
+	app.Use(recover.New())
+	app.Use(RequestLogger(deps.Logger))
+
+	api := app.Group("/v1")
+	v1.RegisterHealth(api)
+	v1.RegisterMarket(api, v1.MarketDeps{
+		MarketContext: deps.MarketContext,
+		MarketData:    deps.MarketData,
+		Derivatives:   deps.Derivatives,
+		KlineRepo:     deps.KlineRepo,
+		FundingRepo:   deps.FundingRepo,
+		OIRepo:        deps.OIRepo,
+		LSRepo:        deps.LSRepo,
+	})
+}

internal/controller/restapi/v1/health_routes.go

@@ -0,0 +1,16 @@
+package v1
+
+import (
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+)
+
+func RegisterHealth(r fiber.Router) {
+	r.Get("/health", func(c *fiber.Ctx) error {
+		return c.JSON(fiber.Map{
+			"status": "ok",
+			"time":   time.Now().UnixMilli(),
+		})
+	})
+}

internal/controller/restapi/v1/market_routes.go

@@ -0,0 +1,118 @@
+package v1
+
+import (
+	"strconv"
+	"strings"
+
+	"github.com/gofiber/fiber/v2"
+
+	"cryptoHermes/internal/entity"
+	"cryptoHermes/internal/usecase"
+)
+
+type MarketDeps struct {
+	MarketContext *usecase.MarketContextUsecase
+	MarketData    usecase.MarketDataProvider
+	Derivatives   usecase.DerivativesProvider
+	KlineRepo     usecase.KlineRepository
+	FundingRepo   usecase.FundingRepository
+	OIRepo        usecase.OpenInterestRepository
+	LSRepo        usecase.LongShortRatioRepository
+}
+
+var allowedIntervals = map[string]bool{
+	"15m": true, "1h": true, "4h": true, "1d": true, "1w": true,
+}
+
+func RegisterMarket(r fiber.Router, d MarketDeps) {
+	g := r.Group("/market")
+
+	g.Get("/context", func(c *fiber.Ctx) error {
+		symbol := strings.ToUpper(c.Query("symbol"))
+		if symbol == "" {
+			return fiber.NewError(fiber.StatusBadRequest, "symbol is required")
+		}
+		out, err := d.MarketContext.Build(c.UserContext(), symbol)
+		if err != nil && out == nil {
+			return fiber.NewError(fiber.StatusBadRequest, err.Error())
+		}
+		return c.JSON(out)
+	})
+
+	g.Get("/klines", func(c *fiber.Ctx) error {
+		symbol := strings.ToUpper(c.Query("symbol"))
+		interval := c.Query("interval")
+		if symbol == "" || interval == "" {
+			return fiber.NewError(fiber.StatusBadRequest, "symbol and interval are required")
+		}
+		if !allowedIntervals[interval] {
+			return fiber.NewError(fiber.StatusBadRequest, "interval must be one of 15m/1h/4h/1d/1w")
+		}
+		limit := 300
+		if l := c.Query("limit"); l != "" {
+			if v, err := strconv.Atoi(l); err == nil && v > 0 && v <= 1000 {
+				limit = v
+			}
+		}
+		rows, err := d.KlineRepo.FindRecent(c.UserContext(), symbol, interval, limit)
+		if err != nil {
+			return fiber.NewError(fiber.StatusInternalServerError, err.Error())
+		}
+		return c.JSON(rows)
+	})
+
+	g.Get("/snapshot", func(c *fiber.Ctx) error {
+		symbol := strings.ToUpper(c.Query("symbol"))
+		if symbol == "" {
+			return fiber.NewError(fiber.StatusBadRequest, "symbol is required")
+		}
+		t, err := d.MarketData.GetTicker24h(c.UserContext(), symbol)
+		if err != nil {
+			return fiber.NewError(fiber.StatusBadGateway, err.Error())
+		}
+		return c.JSON(t)
+	})
+
+	g.Get("/derivatives", func(c *fiber.Ctx) error {
+		symbol := strings.ToUpper(c.Query("symbol"))
+		period := c.Query("period", "1h")
+		if symbol == "" {
+			return fiber.NewError(fiber.StatusBadRequest, "symbol is required")
+		}
+
+		fundCur, ferr := d.Derivatives.GetCurrentFunding(c.UserContext(), symbol)
+		oiCur, oerr := d.Derivatives.GetCurrentOpenInterest(c.UserContext(), symbol)
+
+		fundHist, _ := d.FundingRepo.FindRecent(c.UserContext(), symbol, 100)
+		oiHist, _ := d.OIRepo.FindRecent(c.UserContext(), symbol, period, 200)
+		globalLS, _ := d.LSRepo.FindRecent(c.UserContext(), symbol, period, entity.RatioTypeGlobalAccount, 200)
+		topLS, _ := d.LSRepo.FindRecent(c.UserContext(), symbol, period, entity.RatioTypeTopTraderPosition, 200)
+
+		resp := fiber.Map{
+			"symbol": symbol,
+			"funding": fiber.Map{
+				"current": fundCur,
+				"history": fundHist,
+				"error":   errString(ferr),
+			},
+			"openInterest": fiber.Map{
+				"current": oiCur,
+				"history": oiHist,
+				"error":   errString(oerr),
+			},
+			"longShortRatio": fiber.Map{
+				"global":            globalLS,
+				"topTraderPosition": topLS,
+			},
+			"takerBuySellVolume": []any{},
+		}
+		return c.JSON(resp)
+	})
+}
+
+func errString(e error) string {
+	if e == nil {
+		return ""
+	}
+	return e.Error()
+}