From 4543c6bf987a32eb70a0ee50fa61372dacde4faf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E4=BD=A0=E7=9A=84=E7=94=A8=E6=88=B7=E5=90=8D?=
 <你的邮箱>
Date: Mon, 3 Nov 2025 21:02:28 +0800
Subject: [PATCH] docs: add Netts onboarding steps

---
 README.md          | 12 ++++++++++++
 docs/deployment.md | 27 +++++++++++++++++++++++++++
 2 files changed, 39 insertions(+)

diff --git a/README.md b/README.md
index 53821d5..d8eab81 100644
--- a/README.md
+++ b/README.md
@@ -90,3 +90,15 @@ CI 流程（`.github/workflows/ci.yaml`）会执行 `go fmt`, `go vet`, `go test
 - 监控：可通过 `/healthz` 结合现有 Prometheus/Consul 健康检查；同时建议订阅 Netts 提供的 webhook 以获知能量下发事件。
 
 更多架构细节、部署流程以及 CI/CD 建议请参阅 `docs/architecture.md` 与 `docs/deployment.md`。
+
+## Netts 平台接入流程
+
+在部署本服务之前，请确保完成 Netts Workspace 的账号准备（详见 `docs/deployment.md` 中的“Netts 账号准备流程”）：
+
+1. 注册并登录 [https://netts.io/workspace](https://netts.io/workspace)，生成 API Key；
+2. 在 Wallet 页面充值 TRX，保证账户余额可覆盖租赁费用；
+3. 在 API 设置中配置服务器出口 IP 白名单；
+4. 将 API Key、Real IP、回调地址写入 `config.yaml` 或环境变量；
+5. 通过 `curl https://netts.io/apiv2/userinfo`（携带 `X-API-KEY` 与 `X-Real-IP`）验证连通性。
+
+完成上述步骤后，才可由本服务调用 Netts 接口完成能量租赁。
diff --git a/docs/deployment.md b/docs/deployment.md
index a14ee5b..448da99 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -8,6 +8,33 @@
   - 配置 IP 白名单（若使用代理，可在 `config.yaml` 中设置 `netts.realIp`）；
   - 充值余额，以便购买能量周期。
 
+## Netts 账号准备流程
+
+1. **注册 Workspace 账号**  
+   - 打开 [https://netts.io/workspace](https://netts.io/workspace) 使用邮箱注册并登录；  
+   - 首次登录后系统会自动给当前账号生成一组 API Key。
+
+2. **完成余额充值**  
+   - 在 Workspace → Wallet 菜单中充值 TRX（建议先充 10–20 TRX 做验证）；  
+   - Netts 扣费直接来自账户余额，没有余额将无法下单购买能量。
+
+3. **配置 IP 白名单**  
+   - 进入 Workspace → API → IP Whitelist，将本服务所在服务器的出口 IP 填入；  
+   - 如果经由代理访问，可在配置文件 `netts.realIp` 中设置对应的公网 IP。
+
+4. **获取并保管 API Key**  
+   - 在 Workspace → API 区域复制 Key；  
+   - 设置到 `config.yaml` 的 `netts.apiKey` 字段，或通过 `NETTS_API_KEY` 环境变量注入；  
+   - 生产环境请妥善存储在 Secrets 或 Vault 中。
+
+5. **可选：配置回调地址**  
+   - 若希望接收能量下发事件，可在 Workspace → Host Mode Callback处填写统一回调 URL；  
+   - 亦可在调用本服务的 `/api/v1/energy/rent` 时传入 `callback_url` 覆盖。
+
+6. **API 验证**  
+   - 使用 cURL/ Postman 请求 `https://netts.io/apiv2/userinfo`，在 Header 中携带 `X-API-KEY` 和 `X-Real-IP`；  
+   - 当返回 `status=success` 时，说明账号、Key 与白名单均已生效。
+
 ## 构建
 
 ```bash