feat: initial Netts energy orchestrator

docs/deployment.md

@@ -0,0 +1,92 @@
+# 部署与运维指南
+
+## 环境要求
+
+- Go 1.24+
+- Netts API v2 账号，并完成：
+  - 获取 API Key；
+  - 配置 IP 白名单（若使用代理，可在 `config.yaml` 中设置 `netts.realIp`）；
+  - 充值余额，以便购买能量周期。
+
+## 构建
+
+```bash
+go build -o bin/netts-energy ./cmd/server
+```
+
+可选 Dockerfile（伪代码）：
+
+```dockerfile
+FROM golang:1.24-alpine AS builder
+WORKDIR /app
+COPY . .
+RUN go build -o /build/netts-energy ./cmd/server
+
+FROM alpine:3.20
+WORKDIR /srv/app
+COPY --from=builder /build/netts-energy /usr/local/bin/netts-energy
+COPY config.example.yaml ./config.yaml
+CMD ["netts-energy", "-config", "/srv/app/config.yaml"]
+```
+
+## 运行时配置
+
+1. 根据 `config.example.yaml` 编辑正式配置，或注入环境变量（`NETTS_API_KEY` 等）。
+2. 建议通过 systemd / Supervisor 运行，示例：
+
+   ```
+   [Unit]
+   Description=Netts Energy Orchestrator
+   After=network-online.target
+
+   [Service]
+   ExecStart=/srv/netts/netts-energy -config /srv/netts/config.yaml
+   Restart=on-failure
+   Environment=NETTS_API_KEY=***
+
+   [Install]
+   WantedBy=multi-user.target
+   ```
+
+3. 健康检查：
+   - HTTP GET `http://host:port/healthz` 返回 200。
+   - 可接入 Kubernetes / Nginx upstream 的健康探测。
+
+## CI/CD 建议
+
+仓库内置 GitHub Actions workflow (`.github/workflows/ci.yaml`)：
+
+- 安装依赖；
+- `go fmt` + `go vet`；
+- `go test ./...`。
+
+若需要自动部署服务器，可以在 CI 中加入以下步骤：
+
+1. 在 GitHub 仓库配置 Secrets：
+   - `SSH_HOST` / `SSH_USER` / `SSH_KEY`；
+   - `DEPLOY_PATH` 等自定义变量。
+2. 在 workflow 中追加 job，简例：
+
+   ```yaml
+   - name: Deploy
+     if: github.ref == 'refs/heads/main'
+     run: |
+       scp bin/netts-energy ${{ secrets.SSH_USER }}@${{ secrets.SSH_HOST }}:${{ secrets.DEPLOY_PATH }}
+       ssh ${{ secrets.SSH_USER }}@${{ secrets.SSH_HOST }} 'systemctl restart netts-energy'
+   ```
+
+> 注：部署脚本默认留空，需根据实际服务器环境完善。
+
+## 与现有自动到账系统的集成
+
+1. **地址维护**：在充值服务创建新用户地址后，触发一次 `rent` 调用，让服务自动加入 Host Mode。
+2. **归集流程**：在执行 TRC20 归集前调用 `rent` 接口，确保能量充足后再发起链上交易。
+3. **降级策略**：若 Netts API 不可用，可回退到旧的 Feee 方案；建议通过 Prometheus 指标或报警系统监控 `rent` 接口的失败率。
+4. **费用对比**：响应中的 `analysis.cost_breakdown` 与订单 `total_cost` 方便和现有成本核算系统对接。
+
+## 运维建议
+
+- **日志**：标准输出为结构化日志，建议接入 Loki / ELK 做集中采集。
+- **监控**：结合 Netts webhook 与本服务返回数据，设置周期不足、下单失败等告警。
+- **升级**：新增 Netts 接口（例如 `time/infinitystart`）时，可在 `internal/netts` 中扩展方法并追加 service 策略。
+- **安全**：谨慎保管 API Key；生产环境务必使用 HTTPS 代理或反向代理，限制访问来源。