订阅模块

订阅模块允许用户将钱包绑定至 Telegram 并接收通知（清算预警、借款利率提醒）。它对客户端应用暴露一套 REST API，并通过 Telegram Bot 完成绑定与订阅管理。

Base URL： /api/v2/subscription

---

绑定流程

1. 客户端应用调用 POST /api/v2/subscription/:user/otp（带钱包签名）-> 服务返回一个 6 位 OTP，有效期 5 分钟。

2. 用户打开 Telegram Bot 并在聊天中发送该 OTP。

3. Bot 校验 OTP，并将钱包地址与用户的 Telegram ID 绑定。

4. 绑定完成后，用户即可接收清算预警与借款利率提醒。

---

REST API

1. 查询订阅状态

GET /api/v2/subscription/:user

返回指定钱包是否已绑定 Telegram，以及相关的订阅状态。

路径参数	说明
user	钱包地址（例如 0x…）

2. 生成 OTP

POST /api/v2/subscription/:user/otp

生成一个一次性 6 位验证码，供用户在 Telegram Bot 中发送以完成绑定。需要钱包签名以证明所有权。

路径参数	说明
user	钱包地址

请求体： signature、message（或等效字段）。服务端从签名与消息中恢复地址；该地址必须与路径中的 user 一致。

响应： 例如 { "otp": "123456" } 或类似结构（OTP 有效期 5 分钟）。

3. 取消订阅（解绑）

PUT /api/v2/subscription/:user/unsubscribe

解除钱包与 Telegram 的绑定并停止所有通知。会向用户的 Telegram 发送解绑确认。需要钱包签名。

路径参数	说明
user	钱包地址

请求体： signature、message（或等效字段）。

---

Telegram Bot

Bot 通过 Webhook（内部端点）接收消息。支持的交互如下：

命令 / 操作	说明
OTP（纯文本）	用户发送由 API 生成的 6 位 OTP → Bot 将钱包绑定至 Telegram。
/unbind	显示已绑定钱包列表（内联按钮）；用户选择其一进行解绑。
/subscribe	列出用户持有借款仓位的市场；用户回复市场编号（例如 1,4）以订阅借款利率提醒。每日 UTC 02:00 推送。
/cancel	列出已订阅的市场；用户回复编号以停止利率提醒。
静音（内联）	预警消息上的内联按钮，可静音清算预警或借款通知（CDP 与 lending 可分别设置）。
/change_language	在中文与英文之间切换 Bot 语言。

---

通知类型

类型	触发时机 / 内容
清算预警	仓位达到或超过清算阈值；可能附带静音按钮。
借款利率提醒	针对通过 /subscribe 订阅的市场，每日推送（例如 UTC 02:00）。
解绑确认	解绑成功后发送至 Telegram。

---

安全与隐私

• 对 OTP 与取消订阅请求校验钱包签名；在未经过 Bot OTP 流程的情况下，不要信任客户端提交的 Telegram ID。

• 消息中只包含该订阅用户本人的仓位/金库信息。

• 只存储最小必要数据（例如 Telegram ID、订阅状态、静音标记）；并考虑数据保留与删除策略。