bc-netts-energy/docs/architecture.md

架构设计

总体概览

┌───────────────┐        ┌────────────────┐        ┌─────────────────────┐
│  Client/BC系统 │  --->  │ Netts Energy API│  --->  │ Netts.io (Host Mode) │
└───────────────┘        └────────────────┘        └─────────────────────┘
          │                         │
          │ REST /api/v1/energy/rent│
          ▼                         ▼
┌──────────────────────────────────────────────────────────────────────────┐
│                            Netts Energy Orchestrator                     │
│ ┌────────────┐  ┌──────────────────┐  ┌──────────────────────────────┐   │
│ │ HTTP Server│→│ Energy Service    │→│ Netts Client (API v2)         │   │
│ │ (chi)      │  │ - 业务规则       │  │ - usdt/analyze               │   │
│ │            │  │ - Host Mode判断  │  │ - time/status/add/order      │   │
│ └────────────┘  └──────────────────┘  └──────────────────────────────┘   │
│                     ▲                                   │               │
│                     └──────────── config/logger ────────┘               │
└──────────────────────────────────────────────────────────────────────────┘

模块分解

1. cmd/server

• 应用入口，解析 -config 参数。
• 初始化配置、日志、Netts Client、业务服务与 HTTP Server。

2. internal/config

• 负责加载 YAML 配置与环境变量覆盖。
• 内置默认值、校验逻辑，确保 API Key 与阈值正确。

3. internal/logger

• 基于 log/slog 的结构化日志工厂。
• 支持 text / json 输出格式。

4. internal/netts

• 轻量封装 Netts API。
• 具备重试、User-Agent、X-Real-IP 注入、错误码处理等。
• 在 GetAddressStatus 中把 “Address not found” 映射为可识别的 ErrAddressNotFound。

5. internal/service

• 业务编排核心：
  1. 调用 usdt/analyze 计算推荐能量；
  2. 检查 Host Mode 状态，必要时自动 time/add；
  3. 当周期低于阈值时，根据配置 targetCycles 自动下单；
  4. 返回分析详情、周期变化、下单记录。
• 通过接口解耦，便于单元测试和未来 mock。

6. internal/http

• 使用 chi 构建 REST API。
• 提供健康检查与 POST /api/v1/energy/rent 主入口。
• 响应中包含分析、Host Mode 状态以及订单结果，方便上游系统直接使用。

关键流程

1. 租赁请求：上游在归集前发送 from_address 与 to_address，可附带金额。
2. 能量分析：调用 Netts usdt/analyze 获取推荐能量。
3. Host Mode 确认：
   • 如果地址未加入，且配置允许自动加入 ⇒ 调用 time/add。
   • 否则直接报错，交由上游处理。
4. 周期管理：
   • 读取 time/status。
   • 若 cycles_remaining < minCycles ⇒ 计算补足数量并调用 time/order。
   • 下单后可选等待 postOrderWait 秒，再次查询状态。
5. 响应汇总：返回推荐能量、是否新增 Host Mode、下单详情、剩余周期、分析数据等。

与既有系统的协作

• 触发时机：在归集执行前（或按周期任务）调用本服务，确保地址有足够能量。
• 地址生命周期：推荐在创建新充值地址时即调用 rent 接口，让服务负责 Host Mode 注册；现有地址可批量调用 time/add 或逐次触发。
• 成本监控：可据 analysis.cost_breakdown 与 OrderResult 中的 total_cost 统计能量开销，并和旧的 Feee 系统成本对比。
• 告警策略：根据 cycles_after、status.cycles_remaining 制定阈值告警；Netts 自带 webhook 可配合使用。

扩展点

• 多币种支持：Netts 文档提供更多接口（如 prices、usdt-public），可按需扩展。
• 持久化缓存：目前状态全由 Netts API 提供，如需本地缓存可在 service 层引入数据库或 Redis。
• 批量调度：可增加定时任务扫描地址列表并调用 EnsureEnergy，形成全自动化闭环。