cryptoHermes/ai/adr/0001-architecture-foundations.md

ADR 0001 — 架构基础决策

状态：Accepted 日期：2026-05-24 决策者：项目维护者 适用范围：cryptoHermes v1 全部代码

---

背景

cryptoHermes 是给上游 Hermes 量化分析引擎用的 Binance Futures 行情网关。在 MVP 启动前需要锁定一组基础技术决策，避免后续 PR 反复重新评估。

需求边界（来自 docs/dev.md 第 1 章）：

• 只读公共行情，不下单、不接私钥
• BTCUSDT / ETHUSDT，分钟到周级 K 线 + 衍生品（funding / OI / 多空比 / taker volume）
• 历史数据必须自存（Binance 历史 OI / 多空比官方只保留 30 天）
• Hermes 只调用 /v1/market/context 一个聚合接口
• 部署形态：单体服务 + Postgres，国内开发机通过 HTTPS_PROXY 访问 Binance

---

决策

D1. Web 框架：Fiber v2

选了 Fiber v2（而不是 net/http 标准库、Gin、Echo、Chi）。

理由：

• 性能足够（fasthttp 底层），单体网关不需要再调优
• API 与 Express/Gin 相近，团队上手快
• 内置 recover/logger/req-id 中间件
• v2 稳定，社区活跃

代价：

• 基于 fasthttp，不兼容 net/http 中间件生态
• 错误类型用 *fiber.Error，需要在 controller 包一层

何时重新评估：如果需要 HTTP/2 server push、需要复用 net/http 生态中间件、或者 v2 长期不维护——届时考虑迁回标准库。

---

D2. 数据库：TimescaleDB on PG 16

选了 TimescaleDB（而不是纯 Postgres、InfluxDB、ClickHouse）。

理由：

• 时序数据天然适合 hypertable：5 张表全部按时间分片，查询近期数据走最新 chunk，旧数据自动归档
• SQL 接口和普通 PG 完全兼容，pgx 直连，无需新驱动
• 没有引入新的运维栈（开发机用 Docker 起 timescale/timescaledb:latest-pg16 即可）
• Chunk 间隔可按表调（K 线 1 周、funding 30 天）

代价：

• 必须跑 SELECT create_hypertable(...) 才能享受时序优化，新表容易忘
• 升级 PG 大版本需要看 Timescale 兼容矩阵

何时重新评估：如果数据量进入 TB 级、需要列存压缩或者 OLAP 复杂聚合——考虑 ClickHouse。

---

D3. Architecture：Clean Architecture（4 层 + ports.go 接口边界）

4 层：controller / usecase / repo / entity。 接口边界：internal/usecase/ports.go 是唯一定义对外接口的地方。

理由：

• 上游 Hermes 只通过 REST 调用本服务，但 Binance 这个数据源大概率会扩展到 CoinGlass / ETF / CME。把数据源抽象成 MarketDataProvider / DerivativesProvider 接口，新增数据源只需要新建 internal/repo/webapi/<source>/，不动业务编排。
• 单测可以 mock 接口，不需要起真 DB / 真 Binance。
• internal/app/app.go 是唯一的组合根，DI 集中可见。

强制约束（见 ai/risk-guardrails.md G6）：

controller 不可直接 import binance/postgres
usecase 不可直接 import binance/postgres

代价：

• 多一层 ports.go，每个新接口要写两次（接口 + 实现）
• 对小型项目可能略 overkill，但本项目已经规划到 v3（多数据源），早做减少返工

何时重新评估：如果 v2 之后接口数量爆炸（> 30 个）→ 考虑按子域拆分 ports.go 为多个文件。

---

D4. 传输层：REST-only（v1 不上 gRPC / 消息队列 / WebSocket）

选了 REST（而不是 gRPC、NATS、WS 推送）。

理由：

• Hermes 是同语言 Go 服务，但跨服务调用频率是分钟级（拿一次 context），REST + JSON 完全够
• gRPC 多一份 proto 维护负担，团队/工具收益不明显
• WebSocket 推送是独立工程量（重连、消息丢失、订阅状态机），v1 不进入
• Cron + REST 拉取模型对运维友好（任何 HTTP 监控就够）

代价：

• 如果未来 Hermes 需要 sub-second 行情，REST 拉模型撑不住

何时重新评估：Hermes 接入实盘策略后，如果发现"分钟级"延迟成为瓶颈 → 写新 ADR 引入 WS。

---

D5. 价格 / 成交量：全链路 string

所有金额字段端到端用 string：Binance DTO 是 string、entity 是 string、JSON 响应是 string。落库时由 PG 转 NUMERIC(36,18)。

理由：

• Binance 原样返回字符串，避免 float64 转换丢精度
• 108000.12 这种数 float64 表示就会丢尾数；累积统计后偏差更大
• 上游量化分析对价格精度敏感，宁可让 Hermes 自己决定怎么解析

代价：

• 加减乘除需要 PG 端做或者引入 decimal 库
• JSON 响应里 price 是字符串，前端/客户端要适配

强制约束：见 ai/risk-guardrails.md G2。

---

D6. 数据源边界：只用 Binance USDⓈ-M Futures 公共 API

v1 不引入 CoinGlass、Glassnode、ETF Flow、CME、链上数据。

理由：

• Binance 一家覆盖 80% 的需求（K 线 / 衍生品 / 多空比）
• 引入新数据源等于引入新的鉴权、限流、错误模式、SLA——v1 优先把一条链路打通
• 路线图 v2 / v3 才扩展数据源（README "路线图" 段）

强制约束：

• 新增数据源前必须先写 ai/specs/<source>.md（见 AGENTS.md §10）
• 不可使用 Binance 的私有签名接口（见 G1）

---

D7. 配置层：cleanenv（yaml + env override）

选了 cleanenv（而不是 viper、koanf、env-only）。

理由：

• 一份 yaml 默认值 + 环境变量覆盖，开发和部署都方便
• 比 viper 轻，没有多余抽象
• env-default: tag 让默认值跟字段定义放在一起，可读性好

代价：无明显缺点。如果后续需要热重载（不需要）才会考虑换。

---

D8. 限流：golang.org/x/time/rate token bucket

挂在 pkg/httpclient/client.go 里，默认 RPS=20 / Burst=40，从配置读。

理由：

• 标准库附属，零外部依赖
• token bucket 适合突发场景
• Binance IP 限 2400 weight/min，20 req/s × 60s = 1200 req/min，留出一半余量给重试和 backfill

强制约束：所有外部 HTTP 调用走 pkg/httpclient，见 G5。

---

D9. Scheduler：robfig/cron v3

选了 robfig/cron v3（而不是自己写 ticker、go-co-op/gocron）。

理由：

• cron 表达式所有人都看得懂，schedule 修改是配置而非代码
• 稳定老牌，3.0 之后无破坏性变化
• 和 Fiber 在同一进程内运行，graceful shutdown 容易做

代价：

• 没有分布式锁——但本服务 v1 是单实例，不需要

---

不在本 ADR 范围

• 下单 / 账户 / 私钥：永久禁止（G1）。要做必须新仓库。
• 多交易所聚合：v3 才考虑，届时再写 ADR。
• WS / 实时推送：见 D4，需要单独写 ADR。
• 观测性（metrics / tracing）：MVP 阶段只用 slog 结构化日志，Prometheus / OTel 留待生产部署前评估。

---

后续 ADR 的触发条件（来自 AGENTS.md §10）

• 换 HTTP 框架 → 新 ADR
• 引入消息队列 / WS → 新 ADR
• 跨服务通信改 gRPC → 新 ADR
• 数据库换型（PG → ClickHouse）→ 新 ADR
• 引入新数据源 → ai/specs/<source>.md（不一定要 ADR，除非影响整体架构）