# Netts Energy Orchestrator

Netts Energy Orchestrator 是一个使用 Go 实现的独立服务，用于为自动到账系统中的 TRON 地址自动租赁能量。它集成了 [Netts API v2](https://doc.netts.io/api/v2/)，支持地址自动加入 Host Mode、轮询剩余能量周期并按需购买能量租赁周期，从而显著降低 TRC20 归集的手续费。

## 功能亮点

- ✅ **Netts API 集成**：封装 `usdt/analyze`、`time/add`、`time/status`、`time/order` 等核心接口。
- 🔁 **自动周期管理**：当剩余周期低于阈值时自动补充，可选自动 Host Mode 注册。
- 🧩 **独立微服务**：提供 REST API (`POST /api/v1/energy/rent`)，便于与现有到账平台对接。
- ⚙️ **可配置化**：通过 `config.yaml` 或环境变量管理 API Key、阈值、重试策略等。
- 📈 **可观察性**：结构化日志、健康检查接口，易于纳入现有监控体系。

## 快速开始

1. 复制配置模板：

   ```bash
   cp config.example.yaml config.yaml
   ```

2. 编辑 `config.yaml`，填入 Netts API Key、白名单 IP、Host Mode 回调地址等；或通过环境变量覆盖：

   ```bash
   export NETTS_API_KEY=your-key
   export NETTS_REAL_IP=1.2.3.4
   ```

3. 运行服务：

   ```bash
   go run ./cmd/server -config config.yaml
   ```

4. 调用接口租赁能量：

   ```bash
   curl -X POST http://localhost:8080/api/v1/energy/rent \
     -H "Content-Type: application/json" \
     -d '{
       "from_address": "Txxx", 
       "to_address": "Tyyy",
       "amount": "200.0"
     }'
   ```

   返回值包含分析结果、是否新增 Host Mode、下单详情以及最新剩余周期。

## 配置说明

参见 `config.example.yaml`，主要段落如下：

- `server`：HTTP 服务监听地址、超时等。
- `netts`：Netts API 参数（`apiKey` 可通过 `NETTS_API_KEY` 覆盖）。
- `energy`：
  - `autoAddHost`：是否自动调用 `time/add` 把地址加入 Host Mode。
  - `minCycles` / `targetCycles`：低于最小阈值时补足到目标阈值。
  - `postOrderWait`：下单后等待能量生效的时间。
- `logging`：日志级别与输出格式（text/json）。

更多环境变量详见 `internal/config/config.go` 中的 `envPrefix` 定义。

## REST API

`POST /api/v1/energy/rent`

```json
{
  "from_address": "源地址（监控地址）",
  "to_address": "归集地址",
  "amount": "USDT 数量，可选，默认 100",
  "callback_url": "可选，覆盖 config 默认回调"
}
```

响应字段包括推荐能量、下单情况、当前 Host Mode 状态等，详细 schema 请见 `docs/api.md`。

## 测试与质量

```bash
go test ./...
golangci-lint run        # 若本地已安装，可执行静态检查
```

CI 流程（`.github/workflows/ci.yaml`）会执行 `go fmt`, `go vet`, `go test`。

## 与自动到账系统的集成

- 对接点：在归集服务中，当检测到能量不足（或计划归集）时调用本服务接口即可。
- 配置建议：将主系统的数据库中保存的地址同步到 Netts Host Mode，或在首次归集前调用 `rent` 接口，由服务自动注册/购买能量。
- 监控：可通过 `/healthz` 结合现有 Prometheus/Consul 健康检查；同时建议订阅 Netts 提供的 webhook 以获知能量下发事件。

更多架构细节、部署流程以及 CI/CD 建议请参阅 `docs/architecture.md` 与 `docs/deployment.md`。