TG Bot 手册
通道 A Telegram Bot 的命令、鉴权、后端接线与本地运行说明
角色
apps/tg-bot（包名 sharpside-tg-bot）是通道 A 的 Telegram 命令面：绑定账户、创建/管理跟随、查询交易者与绩效。
日常跟单的主入口是 Web + Deposit Wallet（见 创建与管理跟随）；Bot 适合已绑定 TG 的用户用命令操作。托管模型为平台代签（Deposit Wallet / 签名面），不是非托管。
演进方案（pause/resume、成交通知、可接线接口矩阵）见仓库 docs/TG_BOT_PLAN.md；运维细节见 docs/RUNBOOK_TG_BOT.md。
主要命令（现状）
| 命令 | 后端 | 作用 |
|---|---|---|
/start | POST /auth/tg（account） | 绑定 TG 用户与账户，换 JWT |
/follow | POST /follows（follow） | 创建跟随（channel=tg）；默认 未启动 |
/follows | GET /follows（follow） | 列出跟随（不是 /me/follows） |
/unfollow | DELETE /follows/:id | 取消跟随 |
/traders /perf | venue-hub | 浏览交易者与绩效 |
/setamount | 进程内 | 默认跟单金额（重启丢失） |
新建跟随受信号门控：active=false 时不接信号。开始/暂停应对齐 Web，调用 PATCH /follows/:id（Bot 侧 /pause /resume 规划中，见方案 P0）。在此之前请用 Web「恢复」开跑。
鉴权与拓扑
Bot 直连 account / follow / venue-hub（配置 ACCOUNT_URL / FOLLOW_URL / VENUE_HUB_URL），不经 gateway。Web 走 gateway 时路径带 /api/account 等前缀；Bot 调用服务根路径即可。
鉴权：X-TG-Bot-Secret 调 account POST /auth/tg 换 JWT，本地缓存；遇 401 自动重换。
规划中还会直连 copier（余额、成交历史）并接收内网成交通知（POST /internal/notify）。
开户边界
POST /me/deposit-wallet/provision 要求提现地址已在 user_wallets 中绑定 → 首次绑钱包须走 Web SIWE。Bot 适合展示委托状态与深链到 Web，不能独立完成首次开户。
运行
export TG_BOT_TOKEN=...
export TG_BOT_SECRET=... # 与 account 侧一致
export ACCOUNT_URL=http://127.0.0.1:8084
export FOLLOW_URL=http://127.0.0.1:8082
export VENUE_HUB_URL=http://127.0.0.1:8081
cargo run -p sharpside-tg-bot
# 或：./target/debug/sharpside-tg-bot
无 TG_BOT_TOKEN 时进程应优雅退出（exit 0）。本机若无法访问 api.telegram.org，可用 curl 等价流程验证后端契约（见仓库 docs/RUNBOOK_TG_BOT.md）。列表契约请测 GET $FOLLOW_URL/follows，勿用 /me/follows。