feat: initial Netts energy orchestrator

README.md

@@ -0,0 +1,92 @@
+# 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`。