refactor: 把 /derivatives 的多源编排从 controller 搬进 usecase

为什么:原 controller handler 在 HTTP 层同时承担了 4 项 usecase 职责
(多源拼装、错误降级策略、limit 硬编码、响应结构组装),违反了
"controller 只做参数解析 + 调用 + 序列化" 的边界。等后续给衍生品加
缓存 / taker volume / 数据质量字段时,HTTP 层会持续变厚。

改动:
- 新增 internal/usecase/market_query.go: MarketQueryUsecase.GetDerivatives()
  并发拉 current funding/OI + 串行查历史 + 错误聚合为 warnings 返回
- /derivatives handler 退化到 4 行;MarketDeps / restapi.Deps 同步收窄
- /klines 保持直查 KlineRepo(thin query,G11 例外)
- 新增 G11 守卫:grep "FundingRepo|OIRepo|LSRepo|TakerRepo" internal/controller

破坏性 API 变更(/derivatives 响应):
- 删除 funding.error / openInterest.error
- 新增顶层 warnings: []string
顶层 symbol / funding / openInterest / longShortRatio / takerBuySellVolume 保持。

harness 同步:
- AGENTS.md §6 加 G11 grep
- ai/project-map.md 加 market_query.go + /derivatives 数据流分支
- ai/task-templates.md T6 加"破坏性变体"分支(本次重构暴露了原假设过严)
- ai/harness-health.md W1 记一次轻量验证 + 守卫数 10→11

验收: go build / go vet / G6 grep / G11 grep 全绿。
This commit is contained in:
dela
2026-05-24 17:51:11 +08:00
parent cc7f5a4f32
commit f3dc4d0939
9 changed files with 185 additions and 67 deletions

View File

@@ -177,6 +177,22 @@ grep -rn --include="*.go" "websocket\|fstream.binance" .
---
## G11. Controller 不编排 derivatives 多源查询
**规则**`internal/controller/**` 不得直接持有或调用 `FundingRepository` / `OpenInterestRepository` / `LongShortRatioRepository` / `TakerVolumeRepository`。这类衍生品历史数据的"查哪些表 + 多源拼装 + 错误降级 → warnings"必须在 `internal/usecase/` 完成controller 只做参数解析、调用 usecase、返回 JSON。
**为什么**:曾经 `/derivatives` handler 一次性编排了 6 处查询、4 个静默吞错的 `_`、硬编码的 limit 和响应结构——HTTP 层在替业务层做决定。要给衍生品加 taker volume、缓存、降级策略、数据质量 warnings 时,应该只动 usecase不该让 HTTP handler 跟着变厚。
**例外**`KlineRepository` 暂时允许 controller 直查,因为 `/klines` 现在就是 thin query。一旦它要加缓存 / live fallback / interval 聚合,就同样要搬进 usecase。
**怎么验证**
```bash
grep -rn "FundingRepo\|OIRepo\|LSRepo\|TakerRepo" internal/controller
# 期望:无输出
```
---
## 升级守护规则的时机
同一类错误第二次出现 → 写一条新规则进来。修改本文件 = 改动了项目契约,需要在 PR 描述里说明原因并 @ 维护者。