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

@@ -82,6 +82,7 @@ Clean Architecture 四层。**依赖方向单向:`controller → usecase → e
- `DerivativesProvider`funding/OI/多空比/taker volume 共 7 个方法)
- `KlineRepository` / `FundingRepository` / `OpenInterestRepository` / `LongShortRatioRepository` / `TakerVolumeRepository`
- `market_context.go`:聚合 `/v1/market/context`。errgroup 并发拉 snapshot/funding/OIDB K 线不足 200 根回源 Binance 补,异步写回。
- `market_query.go``/v1/market/derivatives` 后端。`GetDerivatives(symbol, period)` 并发拉 current funding/OI + 串行查 funding/OI/多空比历史,错误降级为 warnings 返回。
**约束**grep 可验证):
```bash
@@ -98,8 +99,9 @@ usecase 不可直接 import 任何具体实现。新增业务流程 → 在 `por
**约束**
```bash
grep -r "repo/webapi/binance\|repo/persistent" internal/controller # 必须无输出
grep -rn "FundingRepo\|OIRepo\|LSRepo\|TakerRepo" internal/controller # 必须无输出G11
```
controller 只能依赖 usecase 和 entity不能直接调 binance client 或 postgres repo。
controller 只能依赖 usecase 和 entity不能直接调 binance client 或 postgres repo。衍生品多源查询必须经 usecase详见 `ai/risk-guardrails.md` G11`KlineRepo` 暂时允许直查 `/klines`,因为它现在是 thin query。
**扩展点**:新增路由 → 加 handler → 通过 `MarketDeps` 注入依赖(不要直接 import repo 包)。
@@ -191,13 +193,19 @@ cron tick
```
HTTP request
└→ internal/controller/restapi/v1/market_routes.go
→ usecase.MarketContext.Build
├→ marketData.GetTicker24h ┐
├→ derivatives.GetCurrent… ├ errgroup 并发
├→ derivatives.GetCurrent… ┘
├→ klineRepo.FindRecent × 5 周期
│ └ DB 不足 → 回源 binance.GetKlines异步写回
└→ fundingRepo / oiRepo / lsRepo.FindRecent
├→ /context → usecase.MarketContext.Build
├→ marketData.GetTicker24h ┐
├→ derivatives.GetCurrent… ├ errgroup 并发
├→ derivatives.GetCurrent… ┘
├→ klineRepo.FindRecent × 5 周期
│ └ DB 不足 → 回源 binance.GetKlines异步写回
└→ fundingRepo / oiRepo / lsRepo.FindRecent
├→ /derivatives → usecase.MarketQuery.GetDerivatives
│ ├→ derivatives.GetCurrentFunding ┐ errgroup
│ ├→ derivatives.GetCurrentOI ┘
│ └→ fundingRepo / oiRepo / lsRepo.FindRecent
├→ /klines → klineRepo.FindRecentthin query允许直查
└→ /snapshot → marketData.GetTicker24h
```
---