feat: initial Netts energy orchestrator

docs/architecture.md

@@ -0,0 +1,80 @@
+# 架构设计
+
+## 总体概览
+
+```
+┌───────────────┐        ┌────────────────┐        ┌─────────────────────┐
+│  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`，形成全自动化闭环。