81 lines
4.8 KiB
Markdown
81 lines
4.8 KiB
Markdown
# 架构设计
|
||
|
||
## 总体概览
|
||
|
||
```
|
||
┌───────────────┐ ┌────────────────┐ ┌─────────────────────┐
|
||
│ 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`，形成全自动化闭环。
|