carrydela/cryptoHermes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
14 Commits 1 Branch 0 Tags
6f4e7f04cc722b5967e5441cc0112f7abd372b93
Commit Graph

14 Commits

This Branch
This Branch
All Branches
Author SHA1 Message Date
dela
6f4e7f04cc build: pass module proxy to docker builder 2026-05-24 21:40:23 +08:00
dela
542eeefdbd deploy: harden compose harness 2026-05-24 21:18:19 +08:00
dela
ea22d06dab deploy(compose): app healthcheck + 优雅停 + 日志策略 + README 部署章节 
- Dockerfile：alpine 安装 wget；加 HEALTHCHECK（/v1/health 探测，
  interval 15s、start_period 20s、retries 3）
- docker-compose.yml app：
  · stop_grace_period 30s（配合 fiber ShutdownWithContext 10s
    + cron 任务收尾，避免 SIGKILL 截断在途请求）
  · restart unless-stopped
  · json-file logging：单文件 50MB、保留 5 个滚动文件
  · 业务日志卷 ./logs:/app/logs
- docker-compose.yml postgres：同样配 restart + logging
- logs/ 目录用 .gitkeep 保留；.gitignore 加 logs/* + !logs/.gitkeep
- README 新增'一键部署（docker compose）'整章：3 步上线、启动顺序图、
  healthcheck 说明、优雅停机、日志、回填历史、生产 checklist

所有 12 条守卫保持无输出；build / vet 干净。
 2026-05-24 21:01:45 +08:00
dela
16f7f00d7b deploy(compose): 修 4 个上生产前的阻断项 
为什么：v2.0 代码侧已 ready，但 docker compose up 起来会立刻 panic
（表不存在），且密码硬编码、Binance 直连超时、无 healthcheck。

修复：

1. migrate init container（migrate/migrate:v4.18.1）
   - depends_on postgres service_healthy 后执行
   - 跑完 up 退出；app depends_on migrate service_completed_successfully
   - 表不存在的 race 彻底消除

2. postgres healthcheck（pg_isready）
   - interval 5s、retries 10、start_period 10s
   - app 不再在 init 期连接失败

3. .env + .env.example（守卫 G9）
   - 密码、端口、Binance URL 全部从环境变量读
   - POSTGRES_PASSWORD 未设置时 docker-compose 直接报错退出（${VAR:?...} 语法）
   - .env 已在 .gitignore，.env.example 留作模板

4. HTTP_PROXY/HTTPS_PROXY/NO_PROXY 透传
   - 国内直连 fapi.binance.com 不稳（AGENTS.md §7.5）
   - NO_PROXY 默认包含 postgres 容器名，避免本地代理误走

附加：config 卷只读挂载（防容器内意外写入）；ports 端口可由
.env 覆盖；postgres 容器名走 docker DNS（替换之前硬编码的
crypto-hermes-postgres）。

验证：python yaml lint 通过；依赖链 postgres healthy →
migrate completed → app start 已确认。docker 在本机不可用，
线上验证留给 commit 9 之后的人工 smoke。
 2026-05-24 20:59:09 +08:00
dela
12420c5db7 chore(milestone6): Makefile guard/test-cover/test-race + README 测试章节 
- Makefile 新增 test-race / test-cover / guard 三个 target
- guard 一次性跑所有可机械验证守卫（G1/G6/G11/G12 共 7 条 grep），
  任一非零退出即失败；CI 友好，无需 jq/yq
- README 补'测试与覆盖率'段落：列覆盖率现状、解释 pgxmock 选型、
  解释 pgxPool 接口的存在；路线图把 v2.0 标记为完成

Production gate（合并 main 前必须全绿）：
✅ go build ./...
✅ go vet ./...
✅ go test -race ./...
✅ indicator.go 12 函数平均 97.7%（≥90%）
✅ postgres 包 87.6%、mapper.go 100%（≥60%）
✅ make guard 全绿（G1/G6/G11/G12 7 条）
✅ go mod tidy 干净
✅ entity.TechnicalStructure 字段签名未改

剩余收尾留给真实环境：手动 smoke（make docker-up + migrate-up + run
+ GET /v1/market/context?symbol=BTCUSDT）在生产部署前由 ops 跑一次。
 2026-05-24 20:51:20 +08:00
dela
ee420f9c56 test(postgres): pgxmock 覆盖 5 个 repo，包级 87.6% 
为什么用 pgxmock：testcontainers 需要 docker-in-CI 而当前还没有 CI；
mock 路线 1) 零基础设施 2) 把 SQL 字符串和参数顺序作为契约锁死，
schema 漂移立刻可见——这正是上生产前最需要的信号。pgxmock 升级到
testcontainers 不阻塞 v2，留 v2.1 做 nightly 集成测试。

关键改动：
- internal/repo/persistent/postgres/pool.go：新建 pgxPool 接口，
  列出 5 repo 实际用到的 Begin/Query/Exec 三个方法。生产代码继续
  传 *pgxpool.Pool（自动满足接口），测试传 pgxmock.PgxPoolIface。
- 5 个 repo struct 字段从 *pgxpool.Pool 改为 pgxPool 接口；构造器
  签名保留 *pgxpool.Pool，app.go DI 不动。
- 5 个 *_repo_test.go：每个 repo 至少
  · UpsertMany happy path（精确 SQL + 参数）
  · UpsertMany 跳过逻辑（空字段 / 未收线）
  · UpsertMany ExecError（Rollback 路径）
  · FindRecent happy path（验证 DESC → 反序为升序）
  · FindRecent QueryError
  KlineRepo 额外加了 EmptyShortCircuits 和 BeginError 两个边界。

覆盖率：postgres 包 87.6%（UpsertMany ~86%、FindRecent ~93%）。
New*Repo 构造器为 0% 是设计选择：测试直接构造 struct 避开
*pgxpool.Pool 依赖。

所有 12 条守卫扫过无输出。
 2026-05-24 20:43:46 +08:00
dela
c478a5feb9 test(binance): mapper.go 全函数 100% 覆盖 
- parseKlineRow：正例 + 短数组 + future closeTime（G3 保护） + openTime/
  closeTime/tradeCount 各类型错误
- toInt64：float64/int64/int/未知 4 个分支
- mapLongShort：global_account 取 LongAccount/ShortAccount，
  top_trader_position 取 LongPosition/ShortPosition，空输入
- mapTicker/mapPremiumIndex/mapFundingHistory/mapOpenInterest/
  mapOpenInterestHistory/mapTakerVolume：纯字段平移，单 case 验证

mapper.go 9 函数全部 100%。包级 31.6% 是 client.go/market.go/
derivatives.go 走真实 HTTP 拉低；这部分留 v2.1 集成测试再补。
 2026-05-24 20:35:39 +08:00
dela
0dabdb29ac feat(context): 接入 IndicatorUsecase，填实 Technical 字段 
- MarketContextUsecase 增 IndicatorComputer 字段；构造器增参
- 用既有常量 derivativePeriod ("1h") 作为指标计算的 primary interval
  —— 与 LSR 采样时基对齐；未来切换 primary 改一个常量即可
- 替换原 hard-coded 空 Technical（market_context.go l.186-189）
- app.go 注入 usecase.NewIndicatorUsecase()

端到端 smoke 留给 commit 7 在所有测试就位后做（make docker-up + migrate-up + run）。
 2026-05-24 20:32:30 +08:00
dela
f47a151409 feat(indicator): 填实 pivot/cluster/percentile/LSR-crossings 算法 
- pivotHighs/pivotLows：严格大于/小于左右 5 根邻居才认 swing
- clusterLevels：按价格升序扫一遍，相对距离 <0.3% 合并到当前 cluster；
  输出按 Strength desc + Price desc 排序
- percentile：type-7 线性插值（NumPy 默认）
- rangeHighLow：P95(High) / P5(Low)，malformed 价位跳过不污染统计
- longShortCrossings：相邻 ratio (a-1)*(b-1)<0 严格穿越；用 ls 时间戳
  二分找最近 kline，取 (open+close)/2 作为穿越价位估计；保留近 N 取中位
- nearestKlineIndex：sort.Search 二分 + 邻居比距离；等距偏向 lo

数值边界严守 ADR-0002 / G12：所有 float64 仅在本文件内部，输出到
entity 前 FormatFloat('f', -1, 64) 转回 string。

补足 4 个函数的边界测试（parsePrice NaN/Inf、percentile p<=0/p>=1、
longShortCrossings keepN<=0/ratio malformed/kline parse 失败/
时间戳前置、nearestKlineIndex 全分支）。

覆盖率：indicator.go 12 个函数平均 97.7%，每个 ≥93.8%。
全部 12 条守卫 grep 无输出（含新增 G12 四条）。
 2026-05-24 20:31:10 +08:00
dela
6d412b2326 feat(indicator): ports + 骨架 + 完整测试 table（红灯） 
为什么：先把测试与骨架同时落地，让"红灯先行"作为 commit 3 实现的
靶子。骨架函数全部返回零值，所有断言失败但无编译错误也无 panic。

变更：
- ports.go 新增 IndicatorComputer 接口；接收已 fetch 的 slice、
  避免与 MarketContextUsecase 重复 IO（G1 + G12）
- internal/usecase/indicator.go：常量、pivotPoint、9 个 helper +
  Compute 全部签名就位，实现先返零值
- internal/usecase/indicator_test.go：parsePrice/formatPrice/
  percentile/medianFloat/pivot{Highs,Lows}/clusterLevels/
  rangeHighLow/longShortCrossings/Compute 全部 table-driven
  覆盖（含 V-shape、双顶 0.18%/0.45%、三聚类、N=1/2/20 percentile、
  穿越保留 N、malformed 跳过等）
- go.mod 把 stretchr/testify v1.8.1 从 indirect 提升为 direct
 2026-05-24 20:16:48 +08:00
dela
c6c25d1a45 chore(harness): ADR-0002 + G12 立指标计算的 float64 边界 
为什么：Milestone 6 引入 transient float64 用于 pivot/percentile/median
计算。G2 早已预留"统计中间过程可用 float64"的例外，但缺可机械验证
的边界。本提交把例外落地为：
- ADR-0002 记录"为什么不用 shopspring/decimal"
- G12 给出 4 条 grep 守卫（usecase float 仅限 indicator.go、
  indicator.go 不依赖 repo、不依赖 binance/postgres/pgx、entity
  仍禁 float）

代码无改动；下一 commit 开始铺 indicator.go 骨架。
 2026-05-24 20:10:13 +08:00
dela
05dc2ef0e7 refactor: 去掉 GetDerivatives 的假 error 返回 + 同步 API 文档 
GetDerivatives 签名里的 error 返回永远是 nil，controller 那段 if err != nil
是死分支，会误导调用方以为存在"全失败"语义。当前产品策略是 best-effort
response：局部失败 → warnings，bundle 永远非 nil，HTTP 永远 200。
等 Hermes 上游真要求"全失败 → 5xx"时再重新引入 error 返回。

同时把 docs/dev.md §13.5 示例补上 warnings 字段（上次重构遗漏的文档同步）。
 2026-05-24 17:57:08 +08:00
dela
f3dc4d0939 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 全绿。
 2026-05-24 17:51:11 +08:00
dela
cc7f5a4f32 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 无具体实现依赖，全项目
无私钥/签名字段。
 2026-05-24 17:20:51 +08:00