# 架构设计

## 总体概览

```
┌───────────────┐        ┌────────────────┐        ┌─────────────────────┐
│  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`，形成全自动化闭环。