carrydela/cryptoHermes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
cryptoHermes/ai/specs/coinglass.md
dela 1b61541ff5
Some checks failed
ci / build + vet + guard + race (push) Has been cancelled
Details
feat: 接入 CoinGlass 清算热力图隔离链路
2026-05-25 16:57:22 +08:00

30 KiB
Raw Permalink Blame History

spec — CoinGlass V2 数据源接入（v3 phase-1）

状态：Accepted（D1–D7 全锁，§17 用户确认 2026-05-25；等 v3-PR-1 实施） 日期：2026-05-25 作者：cryptoHermes 维护者 适用范围：internal/repo/webapi/coinglass/（新）、internal/entity/coinglass.go（新）、internal/usecase/coinglass_*.go（新）、internal/controller/restapi/v1/coinglass_routes.go（新）、internal/worker/coinglass_collector.go（新）、config/config.go（扩 v3 段）

参考：

  • docs/coinglass/cg.md：V2 反混淆笔记（6 分支 dispatcher + 双阶段解密 + data= 签名）
  • docs/coinglass/coinglass_client.py：Python 参考实现（2026-05 验证可跑）
  • docs/coinglass/endpoint.json：209 endpoint 存活报告（154 ok）
  • ai/harness-health.md line 84：新数据源 → 必填本 spec
  • README.md 路线图 v3 段：CoinGlass + ETF Flow + CME gap + … 多源聚合

1. 目标

把 CoinGlass V2 私有 API 中跨交易所聚合的 4 个核心信号接入 cryptoHermes，作为 v3 的第一波交付。结束后下游 Hermes 量化引擎能从 /v1/coinglass/* 拿到 Binance 单交易所视角看不到的数据（清算热力图 + 多交易所 OI / 多空比 / funding 聚合）。

为什么是 CoinGlass 而不是 ETF Flow / CME / 链上：

  • 反混淆窗口期已开（cg.md + Python ref 都已在 2026-05 验证），错过这窗口下次 CoinGlass 版本号变（V3）又要重新逆向。
  • 4 个 endpoint 一次拿下，覆盖 README v3 段里的"多交易所聚合"子项；ETF Flow / CME gap 在 CoinGlass 自己的 endpoint 里也有，phase-2 直接复用本 phase 的 client 即可。
  • 链上 / 宏观日历是不同性质的数据源（不需要 TLS 指纹绕过、不需要私有解密），独立铺设更经济。

2. Phase 1 endpoint 范围（用户锁定 2026-05-25）

Path 用途 参考 params
/api/index/v2/liqHeatMap 清算热力图（价格 × 时间 × 清算量） merge=true symbol=Binance_BTCUSDT interval=5 limit=288
/api/openInterest/v3/chart 多交易所 OI 历史 symbol=BTC interval=h1 timeType=1 type=0
/api/futures/longShortRate 跨交易所多空比 symbol=BTC interval=h1 timeType=1
/api/fundingRate/v2/home 多交易所 funding 聚合 (空)

非目标（phase 2+）：ETF Flow、CVD、CME gap、宏观日历、链上稳定币流动性、其它 200 个 CoinGlass endpoint 中的 150 个。

3. 决策锁定

ID 决策 锁定时间 备注
D1 TLS 指纹库用 github.com/enetx/surf v1.0.144 2026-05-25（用户，后经 surf spike 修订） surf Firefox profile 已真打 CoinGlass liqHeatMap：能拿到 v/user/data 并解出 plaintext；pin v1.0.144，避免 latest 抬 Go 1.25
D2 Phase 1 = 4 个 endpoint（见 §2） 2026-05-25（用户） 全部对应 Python ref __main__ smoke test
D3 TOTP_SECRET 走 config 注入，env COINGLASS_TOTP_SECRET，enabled=true 时必填 2026-05-25（作者） 公开 bundle 里能抠出 → 不算账户 secret；但 CoinGlass 可能旋转，env 化保旋转友好；Go client 不提供代码默认值
D4 新增 /v1/coinglass/* namespace，不折进 /v1/market/context 2026-05-25（作者） CoinGlass 故障模式（fake-success / 密钥旋转 / TLS 失效）独立，要求物理隔离；下游 Hermes 可独立降级
D5 每个 endpoint 独立 PG 表 + 独立 cron 周期 2026-05-25（作者） 热力图频次需要更细（5min）、funding 聚合更粗（30min）；schema 形状差异大
D6 解密管线产生的 float64 数值字段，在 repo 出口处全部 strconv.FormatFloat 转 string 进 entity 2026-05-25（作者） 沿用 ADR-0001 D5 全链 string + ADR-0002 数值边界白名单语义。详见 §6.3
D7 新增独立 CoinglassProvider interface，不扩 DerivativesProvider 2026-05-25（作者） 失败语义不同（fake-success retry），返回类型不同（聚合后的 list 不是单 symbol）

D1 / D2 由用户锁定，D3-D7 由作者基于现有架构推断；任何一条用户不同意都可单点回旋。

4. 架构

4.1 分层（Clean Arch 边界沿用）

controller/restapi/v1/coinglass_routes.go
        │
        ▼
usecase/coinglass_query.go        ← 只读路径：repo 拉历史
usecase/coinglass_signal.go       ← 纯函数：聚合多交易所 OI/funding → 语义信号
        │
        ▼
repo/persistent/postgres/coinglass_*.go   ← 5 个新表的 UpsertMany + FindRecent
repo/webapi/coinglass/                    ← V2 client + 4 个 endpoint mapper
        │
        ▼
worker/coinglass_collector.go     ← cron：周期性 fetch → upsert

G6（边界）守卫不变：usecase 不导入 repo/webapi/coinglass 或 repo/persistent/postgres，只对 ports。 G12（数值边界）守卫扩白名单：coinglass_signal.go 类比 derivatives_signal.go，允许 float64；其余 usecase 文件仍禁。

4.2 ports（新）

// internal/usecase/ports.go 追加
type CoinglassProvider interface {
    GetLiqHeatMap(ctx context.Context, symbol string, intervalMin int, limit int) (*entity.CGLiqHeatMap, error)
    GetOpenInterestChart(ctx context.Context, symbol, interval string) (*entity.CGOpenInterestChart, error)
    GetLongShortRate(ctx context.Context, symbol, interval string) (*entity.CGLongShortRate, error)
    GetFundingRateHome(ctx context.Context) (*entity.CGFundingHome, error)
}

type CoinglassRepository interface {
    UpsertLiqHeatMap(ctx context.Context, m *entity.CGLiqHeatMap) error
    FindRecentLiqHeatMap(ctx context.Context, symbol string, limit int) ([]entity.CGLiqHeatMap, error)
    UpsertOpenInterestChart(ctx context.Context, m *entity.CGOpenInterestChart) error
    FindRecentOpenInterestChart(ctx context.Context, symbol, interval string, limit int) ([]entity.CGOpenInterestChart, error)
    UpsertLongShortRate(ctx context.Context, m *entity.CGLongShortRate) error
    FindRecentLongShortRate(ctx context.Context, symbol, interval string, limit int) ([]entity.CGLongShortRate, error)
    UpsertFundingHome(ctx context.Context, m *entity.CGFundingHome) error
    FindRecentFundingHome(ctx context.Context, limit int) ([]entity.CGFundingHome, error)
}

4 endpoint × (Upsert + FindRecent) = 8 repo 方法。每个独立表（D5）。

4.3 V2 dispatcher 6 分支 — 必须全实现

cg.md §"Known branches (2026-05)" 写得很清楚：服务器per-response挑 v，同一 endpoint 连续两次调用 v 可能不同。客户端必须能处理所有 6 个分支，不能 pin。

v seed 来源 已确认
"0" base64("coinglass"+path+"coinglass")[:16] V1-compat，需要时再启
"1" path（待验证派生形状） cg.md 标"shape — verify"
"2" response.headers.time V2 实战出现
"55" "170b070da9654622" bundle 常量
"66" "d6537d845a964081" bundle 常量
"77" "863f08689c97435b" bundle 常量

实现要点（沿用 Python ref _resolve_seed）：

func resolveSeed(v, path, reqCacheTsV2, respTime string) (string, error) {
    switch v {
    case "0": return reqCacheTsV2, nil
    case "1": return path, nil
    case "2": return respTime, nil
    case "55": return "170b070da9654622", nil
    case "66": return "d6537d845a964081", nil
    case "77": return "863f08689c97435b", nil
    default:  return "", fmt.Errorf("unknown coinglass v=%q (bundle may have changed)", v)
    }
}

未知 v → 返回错误（不重试不降级），让 collector log 一行 warn，等人工 review bundle。这是已知"以后会出现的故障模式"，预先把 hook 留好。

4.4 双阶段解密（universal pipeline）

Stage 1: user_key = base64(seed)[:16]                              （16 字节 ASCII）
         token    = strip_quotes(gunzip(unpad(aes_ecb_decrypt(b64dec(headers["user"]), user_key))))
Stage 2: body_key = token[:16]（**原 ASCII**，**不再 base64**）
         plain    = strip_quotes(gunzip(unpad(aes_ecb_decrypt(b64dec(body["data"]), body_key))))
         result   = json.Unmarshal(plain)

Go 实现位置：internal/repo/webapi/coinglass/crypto.go，纯函数，与 fetch 解耦，方便单测喂样本。 依赖：stdlib crypto/aes + crypto/cipher（ECB 自己拼 block 循环，stdlib 没有 ECB 模式）+ compress/gzip + encoding/base64。零第三方。

PKCS#7 unpad 自己写 8 行；ECB decrypt 自己写 ~15 行（cipher.Block.Decrypt(dst, src) 一块一块走）。

4.5 请求侧 data= 签名（TOTP）

ts        = unix_seconds_now()
totp_code = TOTP(secret=COINGLASS_TOTP_SECRET, period=30s, digits=6).At(ts)
plaintext = fmt.Sprintf("%d,%s", ts, totp_code)
cipher    = AES-256-ECB-PKCS7(DATA_AES_KEY)
data_b64  = base64(cipher.Encrypt(pad(plaintext)))
url      ?= ...&data=<data_b64>

依赖：github.com/pquerna/otp/totp（Go TOTP 事实标准）。 DATA_AES_KEY = "1f68efd73f8d4921acc0dead41dd39bc"（32 字节 ASCII，AES-256），从 bundle 抠出，作为代码常量；与 TOTP_SECRET 不同 — DATA_AES_KEY 旋转概率显著低，且即便旋转也是同步换的。仍保留 env override COINGLASS_DATA_AES_KEY 作为 escape hatch。

4.6 TLS 指纹（D1 = github.com/enetx/surf v1.0.144）

client := surf.NewClient().Builder().
    Impersonate().FireFox(). // v1.0.144 Firefox/144 profile
    Timeout(15 * time.Second).
    Build()

请求头按 coinglass_client.py _base_headers 复写，但 User-Agent 由 surf Firefox profile 负责，避免 UA 与 TLS 指纹版本脱节。Origin / Referer = https://www.coinglass.com，Encryption: true，Cache-Ts-V2: <ms ts>。

2026-05-25 spike 结果：surf@v1.0.144 在 Go 1.24.1 下真打 /api/index/v2/liqHeatMap?merge=true&symbol=Binance_BTCUSDT&interval=5&limit=288，返回 status=200、v=0、user header、非空 data，并可用 §4.4 双阶段解密得到 plaintext。surf@latest v1.0.200 也可用，但会把模块 go 版本抬到 1.25.0，PR-1 不采用。

Fake-success 检测（cg.md §"fake success trap"）：

判定（在 client 层，先于解密）：

resp.status == 200 AND body.success == true AND body.data IS empty/null
  → fake-success → 等 2s 重试 1 次 → 仍 fake → 抛 ErrFakeSuccess

不区分"业务 error（success=false + 明确 msg）"与"fake-success"，因为业务 error 调 retry 没用。两者必须明确分类。

4.7 配置（config/config.go 扩段）

coinglass:
  enabled: false                                 # 默认关，老 v1/v2 用户零侵入
  base_url: "https://capi.coinglass.com"
  totp_secret: "${COINGLASS_TOTP_SECRET}"        # env 注入，必填（enabled=true 时）
  data_aes_key: "${COINGLASS_DATA_AES_KEY:-1f68efd73f8d4921acc0dead41dd39bc}"
  tls_profile: "surf_firefox"                    # 当前实现固定 surf v1.0.144 Firefox/144 profile
  request_timeout_sec: 15
  fake_success_retry: 1
  fake_success_retry_wait_ms: 2000
  collectors:
    liq_heatmap_interval_sec: 300   # 5 min
    oi_chart_interval_sec: 600      # 10 min
    long_short_rate_interval_sec: 600
    funding_home_interval_sec: 1800 # 30 min
    startup_jitter_max_sec: 30      # 启动时随机延迟 [0, max)，避免整点齐打
    backoff_initial_sec: 30         # 失败后退避起点
    backoff_max_sec: 600            # 退避上限
    single_flight: true             # 任一 endpoint 不允许并发 fetch

cron 行为硬约束（§9 Collector 实现必须满足）：

  1. 不重叠（single-flight）：同一 endpoint 上一次 fetch 未结束前，下一次 tick 跳过（log skip 一行），不堆积。
  2. 失败退避：fetch 失败（任意错误类）后按 backoff_initial_sec 起步 ×2 增长到 backoff_max_sec 封顶；成功一次后重置回 interval。
  3. 启动 jitter：每个 collector 启动时 sleep rand.Intn(startup_jitter_max_sec) 秒再开始第一次 tick，避免 4 endpoint 在整点齐打 CoinGlass。

PR-1 范围内：只启 liqHeatMap 的 cron（其它 3 个 endpoint cron 留到 v3-PR-2 接入时一起启）。但 §4.7 的 config schema 与 §9 的 backoff/jitter/single-flight 框架必须在 PR-1 落地，避免 PR-2 还要回头改 config 结构。

enabled: false 默认保护：未配置 TOTP_SECRET 时 cron 不启动、controller 路由 503。G1（无私钥）守卫不变：TOTP_SECRET 不是账户级签名，是 CoinGlass 站点级的反爬密钥，不签账户行为，不需要进 G1 灰名单。但 spec 内对此事实必须记下来：

CoinGlass TOTP_SECRET 是站点反爬签名密钥（用于 data= 参数），与"账户级 API 签名"性质不同，不在 G1 守卫范围内。其唯一暴露面是 CoinGlass 反爬规则，泄露不影响用户资产。AGENTS.md §"绝不做"不变。

5. 数据模型（internal/entity/coinglass.go）

ADR-0001 D5：所有数值字段全链 string。下文 type 都是 string 除非显式标注。

package entity

// CGLiqHeatMap — /api/index/v2/liqHeatMap 响应建模。
// 注意：CoinGlass 返回的 prices/volumes 是 2D 网格，要展平成行存或保 JSONB；
// 这里建议保 JSONB（一次拉一帧，按 Symbol+Timestamp 单行）。
type CGLiqHeatMap struct {
    Symbol    string `json:"symbol"`       // "Binance_BTCUSDT"
    Interval  string `json:"interval"`     // "5"（分钟）
    Timestamp int64  `json:"timestamp"`    // 拉取时间（ms）
    PriceMin  string `json:"priceMin"`
    PriceMax  string `json:"priceMax"`
    // RawGrid 是 CoinGlass 原 JSON 序列化字节；下游需要时再解析。
    // 不在 Go entity 层重建价格×时间二维网格，避免不必要 schema 锁定。
    RawGrid []byte `json:"rawGrid"`
}

// CGOpenInterestChart — 多交易所 OI 时序。一帧多交易所。
type CGOpenInterestChart struct {
    Symbol    string                 `json:"symbol"`   // "BTC"
    Interval  string                 `json:"interval"` // "h1"
    Timestamp int64                  `json:"timestamp"`
    Exchanges []CGExchangeOIPoint    `json:"exchanges"`
}

type CGExchangeOIPoint struct {
    Exchange string `json:"exchange"`  // "Binance" / "OKX" / "Bybit" ...
    OI       string `json:"oi"`        // USD value
}

// CGLongShortRate — 多交易所多空比。
type CGLongShortRate struct {
    Symbol    string                       `json:"symbol"`
    Interval  string                       `json:"interval"`
    Timestamp int64                        `json:"timestamp"`
    Exchanges []CGExchangeLongShortPoint   `json:"exchanges"`
}

type CGExchangeLongShortPoint struct {
    Exchange  string `json:"exchange"`
    LongRate  string `json:"longRate"`   // 百分比，如 "55.32"
    ShortRate string `json:"shortRate"`  // 百分比
    Ratio     string `json:"ratio"`      // long/short
}

// CGFundingHome — 多交易所 funding 聚合（home page format）。
type CGFundingHome struct {
    Timestamp int64               `json:"timestamp"`
    Items     []CGFundingHomeItem `json:"items"`
}

type CGFundingHomeItem struct {
    Symbol         string `json:"symbol"`        // "BTCUSDT"
    Exchange       string `json:"exchange"`      // "Binance"
    FundingRate    string `json:"fundingRate"`   // e.g. "0.0001"
    NextFundingTs  int64  `json:"nextFundingTs"`
    Interval       string `json:"interval"`      // "8h" / "4h"
}

确认前提：上面字段名是基于 Python ref 4 个 smoke endpoint 的"预期形状"。真 schema 必须等 Go 端跑通 client + dump 一次解密后的 JSON 才能定。spec 阶段先占位；PR-1 spike 跑通后回填本节并把 spec 标 Accepted。

5.1 JSONB 字段使用纪律（强约束）

CGLiqHeatMap.RawGrid 是本 spec 唯一允许的 JSONB 字段。约束如下：

  1. JSONB 只承载供应商原始网格 / 元信息：CoinGlass 返回的 2D 价格×时间×清算量网格因 schema 频繁微调且行数爆炸（一帧 288 × N 价位），关系化得不偿失，故保 JSONB。
  2. usecase 层禁止直接解析 RawGrid 任意 JSON 结构：如 coinglass_signal.go 需要"清算密集价位"等派生字段，必须先在 mapper.go 里展开成 entity 字段（如未来加 LiqCluster []CGLiqLevel），再由 usecase 消费。json.Unmarshal(RawGrid, &map[string]any{}) 这种 ad-hoc 解析禁止出现在 usecase。
  3. JSONB → 稳定 entity 字段的演进路径：当某个派生指标稳定（≥2 个 PR 反复用）时，mapper 加一个显式字段；不要让 RawGrid 的形状沿伸到 controller / 下游 Hermes 合约。
  4. 其它 3 个 entity（OI / LSR / Funding）保持拍平结构，不引入新 JSONB 字段。新增 JSONB 字段需开 ADR 锁定。

6. Repo 层（internal/repo/webapi/coinglass/）

6.1 目录结构

internal/repo/webapi/coinglass/
├── client.go        # surf wrapper + data= TOTP signing + dispatch GET + retry
├── crypto.go        # AES-ECB + PKCS7 + gzip，零外部依赖
├── crypto_test.go   # 喂 fixed ciphertext + key → 解出已知 plaintext
├── dispatcher.go    # resolveSeed 6 分支
├── mapper.go        # CoinGlass JSON → entity（per endpoint）
├── mapper_test.go   # table-driven
├── liq_heatmap.go   # GetLiqHeatMap
├── oi_chart.go      # GetOpenInterestChart
├── long_short.go    # GetLongShortRate
└── funding_home.go  # GetFundingRateHome

6.2 错误分类（client 层导出）

var (
    ErrFakeSuccess  = errors.New("coinglass fake-success (TLS fingerprint suspected)")
    ErrUnknownV     = errors.New("coinglass unknown v branch")
    ErrDecryptFail  = errors.New("coinglass decrypt pipeline failed")
    ErrAPIBusiness  = errors.New("coinglass API business error") // success=false + msg
)

Collector 见到 ErrFakeSuccess 连发 3 次 → 全局 disable 1 小时 + log alert（避免 IP 进黑名单）。

6.3 数值边界（G12 白名单扩张）

internal/repo/webapi/coinglass/mapper.go 内部允许 transient float64（解 JSON 时 number 默认 float64），但 mapper 出口（写入 entity）前必须 strconv.FormatFloat(f, 'f', -1, 64) 回 string。

G12 守卫扩白名单：Makefile guard 目标的 G12.1 规则增加 coinglass 排除：

@echo "G12.1 (usecase float)..." && ! { grep -rn --include="*.go" "float64\|float32" internal/usecase | grep -vE "indicator|derivatives_signal|coinglass" | grep -q . ; }

同时新增 G12.7 / G12.8 覆盖：coinglass_signal.go 与 derivatives_signal.go 同款（no repo / no DB import）。

G12.4（entity 不能含 float）：CoinGlass entity 全 string，G12.4 不破。

6.4 测试策略

文件 测试范围 工具
crypto_test.go 喂 fixed (key, ciphertext) → 期望 plaintext；PKCS7 unpad 边界（0/16 块大小） table-driven + testify
dispatcher_test.go 6 个 v 分支各一例 + unknown v → ErrUnknownV table-driven
mapper_test.go 喂 fixed JSON（从 Python ref dump 出来）→ 期望 entity 字段；NaN/Inf/缺字段处理 table-driven，fixture 放 testdata/
client_test.go 用 httptest.NewServer 起 fake CoinGlass，验证 data= TOTP 签名、retry / fake-success 分类 httptest（不需要 surf 真起 Firefox 指纹，测的是上层逻辑）
integration_test.go（build tag integration_coinglass，默认关） 真打 CoinGlass，仅在手动 + nightly 跑；不进 push CI CGO=0 即可

PR-C 已经被跳，但 CoinGlass integration test 因为打外部服务，必须有 build tag 隔离。这是 D7 顺带的硬约束。

7. Usecase（internal/usecase/coinglass_*.go）

7.1 coinglass_query.go（薄）

只读路径：给 controller 调，从 repo 拉历史，组装 response，不做计算。

type CoinglassQueryUsecase struct {
    repo CoinglassRepository
    log  *slog.Logger
}

func (u *CoinglassQueryUsecase) GetLiqHeatMap(ctx context.Context, symbol string, limit int) ([]entity.CGLiqHeatMap, error) { ... }
// ... 4 个 endpoint 各一个 Get

7.2 coinglass_signal.go（厚，纯函数）

类比 derivatives_signal.go：把多交易所原始数据翻译成可读语义。

// CoinglassSignal 把 4 个 endpoint 的原始数据聚合成上游 Hermes 直接消费的语义字段。
type CoinglassSignal struct {
    OIDominance     string `json:"oiDominance"`     // e.g. "binance:0.42,okx:0.28,bybit:0.18"
    OIShiftBias     string `json:"oiShiftBias"`     // accumulating_binance / fleeing_to_okx / balanced
    LSRDispersion   string `json:"lsrDispersion"`   // narrow / wide — 交易所间多空比方差
    FundingExtreme  string `json:"fundingExtreme"`  // 哪个 exchange funding 是 outlier
    LiqClusterPrice string `json:"liqClusterPrice"` // 清算热力图里最密集的价位（中位数）
}

type CoinglassSignalComputer interface {
    Compute(
        heat *entity.CGLiqHeatMap,
        oi *entity.CGOpenInterestChart,
        lsr *entity.CGLongShortRate,
        fund *entity.CGFundingHome,
    ) (*CoinglassSignal, []string) // signal + warnings
}

这是 phase 1 真正的"算法增量"。前面 4 个 endpoint 是底料；这里把"7 个交易所 OI 谁在涨"翻成"oi_shift_bias=accumulating_binance"才是给 Hermes 看的成品。

7.3 MarketContextUsecase 增强（可选 phase-1.5）

ADR-0003 的 mirror 思路可以借用：/v1/market/context 增一个 coinglass *CGSummary 字段（可选，omitempty），把 CoinglassSignal 嵌入。不在 phase-1 必做范围；phase-1 先把 /v1/coinglass/* 独立起来，跑稳了再考虑要不要折回 context。

8. Controller（internal/controller/restapi/v1/coinglass_routes.go）

GET /v1/coinglass/liq-heatmap?symbol=BTCUSDT&limit=288
GET /v1/coinglass/open-interest?symbol=BTC&interval=h1&limit=200
GET /v1/coinglass/long-short?symbol=BTC&interval=h1&limit=200
GET /v1/coinglass/funding-home
GET /v1/coinglass/signal?symbol=BTC                ← 聚合 4 endpoint 的 latest，调 CoinglassSignalComputer

coinglass.enabled=false 时全部返 503 service-unavailable: coinglass disabled in config。 G11（controller 不直依 derivatives repo）类比：controller 不直依 CoinglassRepository，只调 CoinglassQueryUsecase。新增 G11.2 守卫覆盖：

@echo "G11.2 (ctrl coinglass)..." && ! grep -rqn "CoinglassRepo\|coinglassRepo" internal/controller

9. Worker / Collector

internal/worker/coinglass_collector.go：4 个独立 cron（间隔见 §4.7 config）。复用 internal/worker/collector.go 的 ticker 模式。

每个 endpoint 错误隔离 — 一个 endpoint 持续 fake-success 不影响其它 3 个的轮询。ErrFakeSuccess 连 3 次 → 该 endpoint disable 1h + log error。

10. 迁移与回滚

10.1 schema 迁移

新增 4 个表 + 0 个旧表改动：

migrations/00XX_create_coinglass_liq_heatmap.up.sql
migrations/00XX_create_coinglass_open_interest_chart.up.sql
migrations/00XX_create_coinglass_long_short_rate.up.sql
migrations/00XX_create_coinglass_funding_home.up.sql

每个表对应一个 down.sql。migrations/ 已有 5 张 Binance 表；编号顺延。

10.2 回滚策略

  • 配置层关：coinglass.enabled=false → cron 不跑、路由 503，但表保留。运维零代码回滚。
  • 代码层关：revert PR-1 起的 4 个 commit；表保留（下次启用时重新 collect 填）。

11. 失败模式 & 检测

症状 含义 处置
持续 HTTP 200 + success:true + 无 data TLS 指纹漂移 / IP 进灰名单 该 endpoint disable 1h + log alert；运维换 IP / 升级 surf profile
ErrUnknownV CoinGlass bundle 出了新 v 分支 log + alert；人工 re-read bundle + 加分支；spec §4.3 表追加
ErrDecryptFail（gzip / unpad / utf-8 任一失败） 密钥派生错 / 算法变 log + alert；先重试 1 次（可能是网络截断）；仍失败 → human inspect dump
业务 success:false code=40001 params 错（如缺 symbol） 不重试，直接 propagate 出错（编码 bug）
业务 success:false code=40000 之前 fake-success 后被风控 同 fake-success 处置
静默 schema 变（新字段 / 字段重命名） CoinGlass 后端微调 mapper 容忍（按 key 选字段，不依顺序）；新字段 phase-2 决定要不要接

监控 metric（phase-1.5 落地，不阻塞 phase-1）：

  • coinglass_request_total{endpoint, outcome=ok|fake_success|business_err|unknown_v|decrypt_fail}
  • coinglass_endpoint_last_success_age_seconds{endpoint}

12. 守卫扩张总结

守卫 改动
G1（无账户签名） 不变。TOTP_SECRET 不在范围（站点反爬密钥 ≠ 账户签名密钥），spec §4.7 已记
G6（边界） 不变。新 repo 仍只被 usecase 通过接口调
G11（controller 不直依 repo） 新增 G11.2 = controller 不见 CoinglassRepo
G12.1（usecase float 白名单） 扩 coinglass：grep -vE "indicator|derivatives_signal|coinglass"
G12.7（新） coinglass_signal.go 不 import internal/repo
G12.8（新） coinglass_signal.go 不 import binance/postgres/pgx
G12.9（新） internal/repo/webapi/coinglass/mapper.go 出口前必须 formatPrice/FormatFloat（grep 模式：mapper.go 内 float64 必须与 FormatFloat 共现） — 可选，phase-1 先靠 mapper_test 覆盖
G13.x 不变

13. PR 切分（建议，可调）

PR 范围 验收
v3-PR-1 TLS spike + crypto.go + dispatcher.go + 1 endpoint（liqHeatMap）vertical slice：client / repo / usecase / controller / migration / 单 cron + §4.7 config 全骨架（含 jitter/backoff/single-flight） 硬门槛：(a) TLS fake-success 能被正确识别并抛 ErrFakeSuccess（fake-success unit test 必过）；(b) curl /v1/coinglass/liq-heatmap?symbol=BTCUSDT 返回非空真实响应；(c) 不触碰 /v1/market/context 任何字段（v2 合约不动）
v3-PR-2 剩 3 endpoint（OI / longShort / fundingHome）+ 各自 mapper + 表 + cron 4 个 endpoint 都能 curl 出数据；4 个 cron 都遵守 single-flight / backoff / jitter
v3-PR-3 CoinglassSignalComputer 实现 + /v1/coinglass/signal + signal 单测；如需 RawGrid 派生指标，新增显式 entity 字段（§5.1 纪律） signal 字段语义稳，单测覆盖 ≥95%；usecase 层零 RawGrid 直接解析
v3-PR-4 守卫扩张落 Makefile + 文档对齐（AGENTS §2、harness-health 复评、README v3 ✅）+ spec 标 Accepted make guard 全过；README v3 段第一项 ✅

/v1/market/context 折回机制：phase-1 内绝不讨论；CoinglassSignalComputer 稳定后（≥2 周连续运行 + signal 字段被下游 Hermes 实际消费），再开 ADR 评估是否扩 MarketContext schema。PR-1/2/3 路径上任何 PR 都不能改 /v1/market/context 响应体。

14. 非目标（明确写下来）

  • ETF Flow / CME gap / CVD / 链上 / 宏观日历 — phase 2+。
  • WebSocket 推送 — 仍在 README "绝不做（v1 范围外）" 范围，v3 也不开。
  • CoinGlass 账户级私有接口（如 portfolio）— 不接。CoinGlass 没有"账户级"概念，所有数据都是聚合公开；不存在 G1 violations 风险。
  • 历史回填 — Python ref 没做，CoinGlass V2 也没标 history backfill endpoint；phase-1 起从启动那刻开始 collect。
  • TLS profile 自定义（构造非常用浏览器指纹） — phase-1 沿用 firefox_133；profile 调优留 phase-2。

15. 复评触发器

  • firefox_133 失效（CoinGlass 升级反爬）→ 评估升级 profile 或换 client。
  • 4 个 endpoint 任一持续 7 天 ≥10% fake-success 率 → 评估 IP 池 / 代理策略。
  • CoinGlass 出 V3 dispatcher（即出现 7+ 个 v 分支）→ 整段 §4.3 重做。
  • 下游 Hermes 要求把 CoinGlass 折回 /v1/market/context → phase-1.5 启动。

16. 关联 ADR / 文档

  • ADR-0001（架构基础）：D5 全链 string，本 spec 严格沿用。
  • ADR-0002（数值边界）：本 spec §6.3 扩白名单到 coinglass，需要新 ADR（暂列 ADR-0004 — 等 PR-1 落地前写定）。
  • ADR-0003（per-interval 技术结构）：无直接冲突；CoinGlass 数据可未来作为新 interval/source 接入 TechnicalStructure 但本 phase 不做。
  • ai/risk-guardrails.md：G11/G12 扩张要同步更新（v3-PR-4）。
  • docs/coinglass/cg.md：本 spec 的协议事实底稿，保持单一来源；本 spec 引用而非复述。
  • docs/coinglass/coinglass_client.py：本 spec 的算法参考实现，Go 端是 1:1 移植。

17. 决策记录（2026-05-25 用户确认，全部 Accepted）

# 决策 内容
Q1 namespace 独立 锁 /v1/coinglass/... 单独 namespace。/v1/market/context 继续 Binance-only，PR-1/2/3 路径上绝不碰 v2 合约；后续融合需 CoinglassSignalComputer 稳定后通过显式版本/字段扩展开 ADR 讨论，不在 phase-1 范围。
Q2 cron cadence 接受 5/10/10/30 min（liqHeatMap / OI / LSR / Funding）采用。强制三条实现约束：single-flight 不重叠 + 失败指数退避 + 启动 jitter。详见 §4.7 / §9。PR-1 范围内仅启 liqHeatMap 的 cron。
Q3 entity 形状方向 OK RawGrid JSONB 适用于 liqHeatMap（避免行爆炸）；其它 3 个 entity 拍平。string-numeric 全链路保持，零 float64 出 mapper 边界。新增强约束：JSONB 仅供应商原始网格 / 元信息，usecase 不允许直接解析任意 JSON 结构，需要稳定字段时由 mapper 展开成 entity 字段（§5.1）。
Q4 保持 4 PR 不合并 PR-2 进 PR-1。PR-1 已含 TLS spike + 解密 + 1 endpoint + repo/usecase/controller/cron，风险足够大；额外 3 endpoint 塞入会模糊失败归因。按 §13 4 PR 切分推进。

v3-PR-1 硬门槛（再强调，对应 §13 PR-1 验收）：

  1. TLS fake-success 识别通过（ErrFakeSuccess 单测覆盖 + 真打 CoinGlass 时能正确分类）。
  2. liqHeatMap vertical slice 打通（client → repo → usecase → controller → cron 全链，curl /v1/coinglass/liq-heatmap 出真实非空数据）。
  3. v2 合约零变更（/v1/market/context 响应体 diff = 0）。

任一未达标，PR-1 不合。

Reference in New Issue View Git Blame Copy Permalink