# Telegram 生态开发资源索引

## 官方文档

### Bot API
**主文档:** https://core.telegram.org/bots/api  
**描述:** Telegram Bot API 完整参考文档

**核心功能：**
- 消息发送和接收
- 媒体文件处理
- 内联模式
- 支付集成
- Webhook 配置
- 游戏和投票

### Mini Apps (Web Apps)
**主文档:** https://core.telegram.org/bots/webapps  
**完整平台:** https://docs.telegram-mini-apps.com  
**描述:** Telegram 小程序开发文档

**核心功能：**
- WebApp API
- 主题和 UI 控件
- 存储（Cloud/Device/Secure）
- 生物识别认证
- 位置和传感器
- 支付集成

### Telegram API & MTProto
**主文档:** https://core.telegram.org  
**描述:** 完整的 Telegram 协议和客户端开发

**核心功能：**
- MTProto 协议
- TDLib 客户端库
- 认证和加密
- 文件操作
- Secret Chats

## 官方 GitHub 仓库

### Bot API 服务器
**仓库:** https://github.com/tdlib/telegram-bot-api  
**描述:** Telegram Bot API 服务器实现  
**特点:**
- 本地模式部署
- 支持大文件（最高 2000 MB）
- C++ 实现
- TDLib 基础

### Android 客户端
**仓库:** https://github.com/DrKLO/Telegram  
**描述:** 官方 Android 客户端源代码  
**特点:**
- 完整的 Android 实现
- Material Design
- 可自定义编译

### Desktop 客户端
**仓库:** https://github.com/telegramdesktop/tdesktop  
**描述:** 官方桌面客户端 (Windows, macOS, Linux)  
**特点:**
- Qt/C++ 实现
- 跨平台支持
- 完整功能

### 官方组织
**组织页面:** https://github.com/orgs/TelegramOfficial/repositories  
**包含:**
- Beta 版本
- 支持工具
- 示例代码

## API 方法分类

### 更新管理
- `getUpdates` - 长轮询
- `setWebhook` - 设置 Webhook
- `deleteWebhook` - 删除 Webhook  
- `getWebhookInfo` - Webhook 信息

### 消息操作
**发送消息：**
- `sendMessage` - 文本消息
- `sendPhoto` - 图片
- `sendVideo` - 视频
- `sendDocument` - 文档
- `sendAudio` - 音频
- `sendVoice` - 语音
- `sendLocation` - 位置
- `sendVenue` - 地点
- `sendContact` - 联系人
- `sendPoll` - 投票
- `sendDice` - 骰子/飞镖

**编辑消息：**
- `editMessageText` - 编辑文本
- `editMessageCaption` - 编辑标题
- `editMessageMedia` - 编辑媒体
- `editMessageReplyMarkup` - 编辑键盘
- `deleteMessage` - 删除消息

**其他操作：**
- `forwardMessage` - 转发消息
- `copyMessage` - 复制消息
- `sendChatAction` - 发送动作（输入中...）

### 文件操作
- `getFile` - 获取文件信息
- 文件下载 URL: `https://api.telegram.org/file/bot<token>/<file_path>`
- 文件上传：支持 multipart/form-data
- 最大文件：50 MB (标准), 2000 MB (本地 Bot API)

### 内联模式
- `answerInlineQuery` - 响应内联查询
- 结果类型：article, photo, gif, video, audio, voice, document, location, venue, contact, game, sticker

### 回调查询
- `answerCallbackQuery` - 响应按钮点击
- 可显示通知或警告

### 支付
- `sendInvoice` - 发送发票
- `answerPreCheckoutQuery` - 预结账
- `answerShippingQuery` - 配送查询
- 支持提供商：Stripe, Yandex.Money, Telegram Stars

### 游戏
- `sendGame` - 发送游戏
- `setGameScore` - 设置分数
- `getGameHighScores` - 获取排行榜

### 群组管理
- `kickChatMember` / `unbanChatMember` - 封禁/解封
- `restrictChatMember` - 限制权限
- `promoteChatMember` - 提升管理员
- `setChatTitle` / `setChatDescription` - 设置信息
- `setChatPhoto` - 设置头像
- `pinChatMessage` / `unpinChatMessage` - 置顶消息

## Mini Apps API 详解

### 初始化
```javascript
const tg = window.Telegram.WebApp;
tg.ready();
tg.expand();
```

### 主要对象
- **WebApp** - 主接口
- **MainButton** - 主按钮
- **SecondaryButton** - 次要按钮
- **BackButton** - 返回按钮
- **SettingsButton** - 设置按钮
- **HapticFeedback** - 触觉反馈
- **CloudStorage** - 云存储
- **BiometricManager** - 生物识别
- **LocationManager** - 位置服务
- **Accelerometer** - 加速度计
- **Gyroscope** - 陀螺仪
- **DeviceOrientation** - 设备方向

### 事件系统
40+ 事件包括：
- `themeChanged` - 主题改变
- `viewportChanged` - 视口改变
- `mainButtonClicked` - 主按钮点击
- `backButtonClicked` - 返回按钮点击
- `settingsButtonClicked` - 设置按钮点击
- `invoiceClosed` - 支付完成
- `popupClosed` - 弹窗关闭
- `qrTextReceived` - 扫码结果
- `clipboardTextReceived` - 剪贴板文本
- `writeAccessRequested` - 写入权限请求
- `contactRequested` - 联系人请求

### 主题参数
```javascript
tg.themeParams = {
    bg_color,           // 背景色
    text_color,         // 文本色
    hint_color,         // 提示色
    link_color,         // 链接色
    button_color,       // 按钮色
    button_text_color,  // 按钮文本色
    secondary_bg_color, // 次要背景色
    header_bg_color,    // 头部背景色
    accent_text_color,  // 强调文本色
    section_bg_color,   // 区块背景色
    section_header_text_color, // 区块头文本色
    subtitle_text_color,       // 副标题色
    destructive_text_color     // 危险操作色
}
```

## 开发工具

### @BotFather 命令
创建和管理 Bot 的核心工具：

**Bot 管理：**
- `/newbot` - 创建新 Bot
- `/mybots` - 管理我的 Bots
- `/deletebot` - 删除 Bot
- `/token` - 重新生成 token

**设置命令：**
- `/setname` - 设置名称
- `/setdescription` - 设置描述
- `/setabouttext` - 设置关于文本
- `/setuserpic` - 设置头像

**功能配置：**
- `/setcommands` - 设置命令列表
- `/setinline` - 启用内联模式
- `/setinlinefeedback` - 内联反馈
- `/setjoingroups` - 允许加入群组
- `/setprivacy` - 隐私模式

**支付和游戏：**
- `/setgamescores` - 游戏分数
- `/setpayments` - 配置支付

**Mini Apps：**
- `/newapp` - 创建 Mini App
- `/myapps` - 管理 Mini Apps
- `/setmenubutton` - 设置菜单按钮

### API ID 获取
访问 https://my.telegram.org
1. 登录账号
2. 进入 API development tools
3. 创建应用
4. 获取 API ID 和 API Hash

## 常用 Python 库

### python-telegram-bot
```bash
pip install python-telegram-bot
```

**特点：**
- 完整的 Bot API 包装
- 异步和同步支持
- 丰富的扩展
- 活跃维护

**基础示例：**
```python
from telegram import Update
from telegram.ext import Application, CommandHandler, ContextTypes

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_text('你好！')

app = Application.builder().token("TOKEN").build()
app.add_handler(CommandHandler("start", start))
app.run_polling()
```

### aiogram
```bash
pip install aiogram
```

**特点：**
- 纯异步
- 高性能
- FSM 状态机
- 中间件系统

### Telethon / Pyrogram
MTProto 客户端库：
```bash
pip install telethon
pip install pyrogram
```

**用途：**
- 自定义客户端
- 用户账号自动化
- 完整 Telegram 功能

## 常用 Node.js 库

### node-telegram-bot-api
```bash
npm install node-telegram-bot-api
```

### Telegraf
```bash
npm install telegraf
```

**特点：**
- 现代化
- 中间件架构
- TypeScript 支持

### grammY
```bash
npm install grammy
```

**特点：**
- 轻量级
- 类型安全
- 插件生态

## 部署选项

### Webhook 托管
**推荐平台：**
- Heroku
- AWS Lambda
- Google Cloud Functions
- Azure Functions
- Vercel
- Railway
- Render

**要求：**
- HTTPS 支持
- 公网可访问
- 支持的端口：443, 80, 88, 8443

### 长轮询托管
**推荐平台：**
- VPS (Vultr, DigitalOcean, Linode)
- Raspberry Pi
- 本地服务器

**优点：**
- 无需 HTTPS
- 简单配置
- 适合开发测试

## 安全最佳实践

1. **Token 安全**
   - 不要提交到 Git
   - 使用环境变量
   - 定期轮换

2. **数据验证**
   - 验证 initData
   - 服务器端验证
   - 不信任客户端

3. **权限控制**
   - 检查用户权限
   - 管理员验证
   - 群组权限

4. **速率限制**
   - 实现请求限制
   - 防止滥用
   - 监控异常

## 调试技巧

### Bot 调试
```python
import logging
logging.basicConfig(level=logging.DEBUG)
```

### Mini App 调试
```javascript
// 开启调试模式
tg.showAlert(JSON.stringify(tg.initDataUnsafe, null, 2));

// 控制台日志
console.log('WebApp version:', tg.version);
console.log('Platform:', tg.platform);
console.log('Theme:', tg.colorScheme);
```

### Webhook 测试
使用 ngrok 本地测试：
```bash
ngrok http 5000
# 将生成的 https URL 设置为 webhook
```

## 社区资源

- **Telegram 开发者群组**: @BotDevelopers
- **Telegram API 讨论**: @TelegramBots
- **Mini Apps 讨论**: @WebAppChat

## 更新日志

**最新功能：**
- Paid Media (付费媒体)
- Checklist Tasks (检查列表任务)
- Gift Conversion (礼物转换)
- Business Features (商业功能)
- Poll 选项增加到 12 个
- Story 发布和编辑

---

## 完整实现模板 (新增)

### Telegram Bot 按钮和键盘实现指南
**文件:** `Telegram_Bot_按钮和键盘实现模板.md`
**行数:** 404 行
**大小:** 12 KB
**语言:** 中文

精简实用的 Telegram Bot 交互式功能实现指南：

**核心内容：**
- 三种按钮类型详解（Inline/Reply/Command Menu）
- python-telegram-bot 和 Telethon 双实现对比
- 完整的代码示例（即拿即用）
- 项目结构和模块化设计
- Handler 优先级和事件处理
- 生产环境部署方案
- 安全和错误处理最佳实践

**特色：**
- 核心代码精简，去除冗余示例
- 聚焦常用场景和实用技巧
- 完整的快速参考表

---

### 动态视图对齐 - 数据展示指南
**文件:** `动态视图对齐实现文档.md`
**行数:** 407 行
**大小:** 12 KB
**语言:** 中文

专业的等宽字体数据对齐和格式化方案：

**核心功能：**
- 智能动态视图对齐算法（三步法）
- 自动计算列宽，无需硬编码
- 智能对齐规则（文本左，数字右）
- 完整的格式化系统：
  - 交易量智能缩写（B/M/K）
  - 价格智能精度（自适应小数位）
  - 涨跌幅格式化（+/- 符号）
  - 资金流向智能显示

**应用场景：**
- 排行榜、数据表格、实时行情
- 任何需要专业数据展示的 Telegram Bot

**技术特点：**
- O(n×m) 线性复杂度，高效实用
- 1000 行数据处理仅需 5-10ms
- 支持中文字符宽度扩展

**视觉效果示例：**
```
1.   BTC      $1.23B    $45,000   +5.23%
2.   ETH    $890.5M     $2,500   +3.12%
3.   SOL    $567.8M       $101   +8.45%
```

---

**这些模板提供了从基础到生产级别的完整 Telegram Bot 开发解决方案！**