refactor: 重构目录结构以支持 i18n

创建 'i18n' 目录以存放多语言内容。将所有现有的中文内容（文档、提示词、技能、README）移动到 'i18n/zh/' 中。添加了新的根 README 作为语言入口，并为英文（'en'）翻译创建了占位符结构。
2026-08-12 18:38:04 +00:00 · 2025-12-16 21:30:13 +08:00
parent 1b235161ec
commit 624ef8d5f9
199 changed files with 674 additions and 654 deletions
@@ -1,404 +0,0 @@
-# Telegram Bot 按钮与键盘实现指南
-
-> 完整的 Telegram Bot 交互式功能开发参考
-
---
-
-## 📋 目录
-
-1. [按钮和键盘类型](#按钮和键盘类型)
-2. [实现方式对比](#实现方式对比)
-3. [核心代码示例](#核心代码示例)
-4. [最佳实践](#最佳实践)
-
---
-
-## 按钮和键盘类型
-
-### 1. Inline Keyboard（内联键盘）
-
-**特点**：
- 显示在消息下方
- 点击后触发回调，不发送消息
- 支持回调数据、URL、切换查询等
-
-**应用场景**：确认/取消、菜单导航、分页控制、设置选项
-
-### 2. Reply Keyboard（底部虚拟键盘）
-
-**特点**：
- 显示在输入框上方
- 点击后发送文本消息
- 可设置持久化或一次性
-
-**应用场景**：快捷命令、常用操作、表单输入、主菜单
-
-### 3. Bot Command Menu（命令菜单）
-
-**特点**：
- 显示在输入框左侧 "/" 按钮
- 通过 BotFather 或 API 设置
- 提供命令列表和描述
-
-**应用场景**：功能索引、新用户引导、快速命令访问
-
-### 4. 类型对比
-
-| 特性 | Inline | Reply | Command Menu |
-|------|--------|-------|--------------|
-| 位置 | 消息下方 | 输入框上方 | "/" 菜单 |
-| 触发 | 回调查询 | 文本消息 | 命令 |
-| 持久化 | 随消息 | 可配置 | 始终存在 |
-| 场景 | 临时交互 | 常驻功能 | 命令索引 |
-
---
-
-## 实现方式对比
-
-### python-telegram-bot（推荐 Bot 开发）
-
-**优点**：
- 官方推荐，完整的 Handler 系统
- 丰富的按钮和键盘支持
- 异步版本性能优异
-
-**安装**：
-```bash
-pip install python-telegram-bot==20.7
-```
-
-### Telethon（适合用户账号自动化）
-
-**优点**：
- 完整的 MTProto API 访问
- 可使用用户账号和 Bot
- 强大的消息监听能力
-
-**安装**：
-```bash
-pip install telethon cryptg
-```
-
---
-
-## 核心代码示例
-
-### 1. Inline Keyboard 实现
-
-**python-telegram-bot：**
-```python
-from telegram import Update, InlineKeyboardButton, InlineKeyboardMarkup
-from telegram.ext import Application, CommandHandler, CallbackQueryHandler, ContextTypes
-
-async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
-    """显示内联键盘"""
-    keyboard = [
-        [
-            InlineKeyboardButton("📊 查看数据", callback_data="view_data"),
-            InlineKeyboardButton("⚙️ 设置", callback_data="settings"),
-        ],
-        [
-            InlineKeyboardButton("🔗 访问网站", url="https://example.com"),
-        ],
-    ]
-    reply_markup = InlineKeyboardMarkup(keyboard)
-    await update.message.reply_text("请选择：", reply_markup=reply_markup)
-
-async def button_callback(update: Update, context: ContextTypes.DEFAULT_TYPE):
-    """处理按钮点击"""
-    query = update.callback_query
-    await query.answer()  # 必须调用
-
-    if query.data == "view_data":
-        await query.edit_message_text("显示数据...")
-    elif query.data == "settings":
-        await query.edit_message_text("设置选项...")
-
-# 注册处理器
-app = Application.builder().token("TOKEN").build()
-app.add_handler(CommandHandler("start", start))
-app.add_handler(CallbackQueryHandler(button_callback))
-app.run_polling()
-```
-
-**Telethon：**
-```python
-from telethon import TelegramClient, events, Button
-
-client = TelegramClient('bot', api_id, api_hash).start(bot_token=BOT_TOKEN)
-
-@client.on(events.NewMessage(pattern='/start'))
-async def start(event):
-    buttons = [
-        [Button.inline("📊 查看数据", b"view_data"), Button.inline("⚙️ 设置", b"settings")],
-        [Button.url("🔗 访问网站", "https://example.com")]
-    ]
-    await event.respond("请选择：", buttons=buttons)
-
-@client.on(events.CallbackQuery)
-async def callback(event):
-    if event.data == b"view_data":
-        await event.edit("显示数据...")
-    elif event.data == b"settings":
-        await event.edit("设置选项...")
-
-client.run_until_disconnected()
-```
-
-### 2. Reply Keyboard 实现
-
-**python-telegram-bot：**
-```python
-from telegram import KeyboardButton, ReplyKeyboardMarkup, ReplyKeyboardRemove
-
-async def menu(update: Update, context: ContextTypes.DEFAULT_TYPE):
-    """显示底部键盘"""
-    keyboard = [
-        [KeyboardButton("📊 查看数据"), KeyboardButton("⚙️ 设置")],
-        [KeyboardButton("📚 帮助"), KeyboardButton("❌ 隐藏键盘")],
-    ]
-    reply_markup = ReplyKeyboardMarkup(
-        keyboard,
-        resize_keyboard=True,
-        one_time_keyboard=False
-    )
-    await update.message.reply_text("菜单已激活", reply_markup=reply_markup)
-
-async def handle_text(update: Update, context: ContextTypes.DEFAULT_TYPE):
-    """处理文本消息"""
-    text = update.message.text
-    if text == "📊 查看数据":
-        await update.message.reply_text("显示数据...")
-    elif text == "❌ 隐藏键盘":
-        await update.message.reply_text("已隐藏", reply_markup=ReplyKeyboardRemove())
-```
-
-**Telethon：**
-```python
-@client.on(events.NewMessage(pattern='/menu'))
-async def menu(event):
-    buttons = [
-        [Button.text("📊 查看数据"), Button.text("⚙️ 设置")],
-        [Button.text("📚 帮助"), Button.text("❌ 隐藏键盘")]
-    ]
-    await event.respond("菜单已激活", buttons=buttons)
-
-@client.on(events.NewMessage)
-async def handle_text(event):
-    if event.text == "📊 查看数据":
-        await event.respond("显示数据...")
-```
-
-### 3. Bot Command Menu 设置
-
-**通过 BotFather：**
-```
-1. 发送 /setcommands 到 @BotFather
-2. 选择你的 Bot
-3. 输入命令列表（每行格式：command - description）
-
-start - 启动机器人
-help - 获取帮助
-menu - 显示主菜单
-settings - 配置设置
-```
-
-**通过 API（python-telegram-bot）：**
-```python
-from telegram import BotCommand
-
-async def set_commands(app: Application):
-    """设置命令菜单"""
-    commands = [
-        BotCommand("start", "启动机器人"),
-        BotCommand("help", "获取帮助"),
-        BotCommand("menu", "显示主菜单"),
-        BotCommand("settings", "配置设置"),
-    ]
-    await app.bot.set_my_commands(commands)
-
-# 在启动时调用
-app.post_init = set_commands
-```
-
-### 4. 项目结构示例
-
-```
-telegram_bot/
-├── bot.py                    # 主程序
-├── config.py                 # 配置管理
-├── requirements.txt
-├── .env
-├── handlers/
-│   ├── command_handlers.py   # 命令处理器
-│   ├── callback_handlers.py  # 回调处理器
-│   └── message_handlers.py   # 消息处理器
-├── keyboards/
-│   ├── inline_keyboards.py   # 内联键盘布局
-│   └── reply_keyboards.py    # 回复键盘布局
-└── utils/
-    ├── logger.py             # 日志
-    └── database.py           # 数据库
-```
-
-**模块化示例（keyboards/inline_keyboards.py）：**
-```python
-from telegram import InlineKeyboardButton, InlineKeyboardMarkup
-
-def get_main_menu():
-    """主菜单键盘"""
-    return InlineKeyboardMarkup([
-        [
-            InlineKeyboardButton("📊 数据", callback_data="data"),
-            InlineKeyboardButton("⚙️ 设置", callback_data="settings"),
-        ],
-        [InlineKeyboardButton("📚 帮助", callback_data="help")],
-    ])
-
-def get_data_menu():
-    """数据菜单键盘"""
-    return InlineKeyboardMarkup([
-        [
-            InlineKeyboardButton("📈 实时", callback_data="data_realtime"),
-            InlineKeyboardButton("📊 历史", callback_data="data_history"),
-        ],
-        [InlineKeyboardButton("⬅️ 返回", callback_data="back")],
-    ])
-```
-
---
-
-## 最佳实践
-
-### 1. Handler 优先级
-
-```python
-# 先注册先匹配，按从特殊到通用的顺序
-app.add_handler(CommandHandler("start", start))           # 1. 特定命令
-app.add_handler(CallbackQueryHandler(callback))           # 2. 回调查询
-app.add_handler(ConversationHandler(...))                 # 3. 对话流程
-app.add_handler(MessageHandler(filters.TEXT, text_msg))   # 4. 通用消息（最后）
-```
-
-### 2. 错误处理
-
-```python
-async def error_handler(update: Update, context: ContextTypes.DEFAULT_TYPE):
-    """全局错误处理"""
-    logger.error(f"更新 {update} 引起错误", exc_info=context.error)
-
-    # 通知用户
-    if update and update.effective_message:
-        await update.effective_message.reply_text("操作失败，请重试")
-
-app.add_error_handler(error_handler)
-```
-
-### 3. 回调数据管理
-
-```python
-# 使用结构化的 callback_data
-callback_data = "action:page:item"  # 例如 "view:1:product_123"
-
-# 解析回调数据
-async def callback(update: Update, context: ContextTypes.DEFAULT_TYPE):
-    query = update.callback_query
-    parts = query.data.split(":")
-    action, page, item = parts
-
-    if action == "view":
-        await show_item(query, page, item)
-```
-
-### 4. 键盘设计原则
-
- **简洁**：每行最多 2-3 个按钮
- **清晰**：使用 emoji 增强识别度
- **一致**：保持统一的布局风格
- **响应**：及时反馈用户操作
-
-### 5. 安全考虑
-
-```python
-# 验证用户权限
-ADMIN_IDS = [123456789]
-
-async def admin_only(update: Update, context: ContextTypes.DEFAULT_TYPE):
-    user_id = update.effective_user.id
-    if user_id not in ADMIN_IDS:
-        await update.message.reply_text("无权限")
-        return
-
-    # 执行管理员操作
-```
-
-### 6. 部署方案
-
-**Webhook（推荐生产环境）：**
-```python
-from flask import Flask, request
-
-app_flask = Flask(__name__)
-
-@app_flask.route('/webhook', methods=['POST'])
-def webhook():
-    update = Update.de_json(request.get_json(), bot)
-    application.update_queue.put(update)
-    return "OK"
-
-# 设置 webhook
-bot.set_webhook(f"https://yourdomain.com/webhook")
-```
-
-**Systemd Service（Linux）：**
-```ini
-[Unit]
-Description=Telegram Bot
-After=network.target
-
-[Service]
-Type=simple
-User=your_user
-WorkingDirectory=/path/to/bot
-ExecStart=/path/to/venv/bin/python bot.py
-Restart=always
-
-[Install]
-WantedBy=multi-user.target
-```
-
-### 7. 常用库版本
-
-```txt
-# requirements.txt
-python-telegram-bot==20.7
-python-dotenv==1.0.0
-aiosqlite==0.19.0
-httpx==0.25.2
-```
-
---
-
-## 快速参考
-
-### Inline Keyboard 按钮类型
-
-```python
-InlineKeyboardButton("文本", callback_data="data")     # 回调按钮
-InlineKeyboardButton("链接", url="https://...")        # URL按钮
-InlineKeyboardButton("切换", switch_inline_query="")   # 内联查询
-InlineKeyboardButton("登录", login_url=...)            # 登录按钮
-InlineKeyboardButton("支付", pay=True)                 # 支付按钮
-InlineKeyboardButton("应用", web_app=WebAppInfo(...))  # Mini App
-```
-
-### 常用事件类型
-
- `events.NewMessage` - 新消息
- `events.CallbackQuery` - 回调查询
- `events.InlineQuery` - 内联查询
- `events.ChatAction` - 群组动作
-
---
-
-**这份指南涵盖了 Telegram Bot 按钮和键盘的所有核心实现！**
@@ -1,470 +0,0 @@
-# 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 开发解决方案！**
@@ -1,407 +0,0 @@
-# 📊 动态视图对齐 - Telegram 数据展示指南
-
-> 专业的等宽字体数据对齐和格式化方案
-
---
-
-## 📑 目录
-
- [核心原理](#核心原理)
- [实现代码](#实现代码)
- [格式化系统](#格式化系统)
- [应用示例](#应用示例)
- [最佳实践](#最佳实践)
-
---
-
-## 核心原理
-
-### 问题场景
-
-在 Telegram Bot 中展示排行榜、数据表格时，需要在等宽字体环境（代码块）中实现完美对齐：
-
-**❌ 未对齐：**
-```
-1. BTC $1.23B $45000 +5.23%
-10. DOGE $123.4M $0.0789 -1.45%
-```
-
-**✅ 动态对齐：**
-```
-1.   BTC      $1.23B    $45,000   +5.23%
-10.  DOGE   $123.4M   $0.0789   -1.45%
-```
-
-### 三步对齐算法
-
-```
-步骤 1: 扫描数据，计算每列最大宽度
-步骤 2: 根据列类型应用对齐规则（文本左对齐，数字右对齐）
-步骤 3: 拼接成最终文本
-```
-
-### 对齐规则
-
-| 列索引 | 数据类型 | 对齐方式 | 示例 |
-|--------|----------|----------|------|
-| 列 0 | 序号 | 左对齐 | `1.  `, `10. ` |
-| 列 1 | 符号 | 左对齐 | `BTC  `, `DOGE ` |
-| 列 2+ | 数值 | 右对齐 | `  $1.23B`, `$123.4M` |
-
---
-
-## 实现代码
-
-### 核心函数
-
-```python
-def dynamic_align_format(data_rows):
-    """
-    动态视图对齐格式化
-
-    参数:
-        data_rows: 二维列表 [["1.", "BTC", "$1.23B", ...], ...]
-
-    返回:
-        对齐后的文本字符串
-    """
-    if not data_rows:
-        return "暂无数据"
-
-    # ========== 步骤 1: 计算每列最大宽度 ==========
-    max_widths = []
-    for row in data_rows:
-        for i, cell in enumerate(row):
-            # 动态扩展列表
-            if i >= len(max_widths):
-                max_widths.append(0)
-            # 更新最大宽度
-            max_widths[i] = max(max_widths[i], len(str(cell)))
-
-    # ========== 步骤 2: 格式化每一行 ==========
-    formatted_rows = []
-    for row in data_rows:
-        formatted_cells = []
-        for i, cell in enumerate(row):
-            cell_str = str(cell)
-
-            if i == 0 or i == 1:
-                # 序号列和符号列 - 左对齐
-                formatted_cells.append(cell_str.ljust(max_widths[i]))
-            else:
-                # 数值列 - 右对齐
-                formatted_cells.append(cell_str.rjust(max_widths[i]))
-
-        # 用空格连接所有单元格
-        formatted_line = ' '.join(formatted_cells)
-        formatted_rows.append(formatted_line)
-
-    # ========== 步骤 3: 拼接成最终文本 ==========
-    return '\n'.join(formatted_rows)
-```
-
-### 使用示例
-
-```python
-# 准备数据
-data_rows = [
-    ["1.", "BTC", "$1.23B", "$45,000", "+5.23%"],
-    ["2.", "ETH", "$890.5M", "$2,500", "+3.12%"],
-    ["10.", "DOGE", "$123.4M", "$0.0789", "-1.45%"]
-]
-
-# 调用对齐函数
-aligned_text = dynamic_align_format(data_rows)
-
-# 输出到 Telegram
-text = f"""📊 排行榜
-```
-{aligned_text}
-```
-💡 说明文字"""
-```
-
---
-
-## 格式化系统
-
-### 1. 交易量智能缩写
-
-```python
-def format_volume(volume: float) -> str:
-    """智能格式化交易量"""
-    if volume >= 1e9:
-        return f"${volume/1e9:.2f}B"    # 十亿 → $1.23B
-    elif volume >= 1e6:
-        return f"${volume/1e6:.2f}M"    # 百万 → $890.5M
-    elif volume >= 1e3:
-        return f"${volume/1e3:.2f}K"    # 千 → $123.4K
-    else:
-        return f"${volume:.2f}"          # 小数 → $45.67
-```
-
-**示例：**
-```python
-format_volume(1234567890)  # → "$1.23B"
-format_volume(890500000)   # → "$890.5M"
-format_volume(123400)      # → "$123.4K"
-```
-
-### 2. 价格智能精度
-
-```python
-def format_price(price: float) -> str:
-    """智能格式化价格 - 根据大小自动调整小数位"""
-    if price >= 1000:
-        return f"${price:,.0f}"      # 千元以上 → $45,000
-    elif price >= 1:
-        return f"${price:.3f}"       # 1-1000 → $2.500
-    elif price >= 0.01:
-        return f"${price:.4f}"       # 0.01-1 → $0.0789
-    else:
-        return f"${price:.6f}"       # <0.01 → $0.000123
-```
-
-### 3. 涨跌幅格式化
-
-```python
-def format_change(change_percent: float) -> str:
-    """格式化涨跌幅 - 正数添加+号"""
-    if change_percent >= 0:
-        return f"+{change_percent:.2f}%"
-    else:
-        return f"{change_percent:.2f}%"
-```
-
-**示例：**
-```python
-format_change(5.234)   # → "+5.23%"
-format_change(-1.456)  # → "-1.46%"
-format_change(0)       # → "+0.00%"
-```
-
-### 4. 资金流向智能显示
-
-```python
-def format_flow(net_flow: float) -> str:
-    """格式化资金净流向"""
-    sign = "+" if net_flow >= 0 else ""
-    abs_flow = abs(net_flow)
-
-    if abs_flow >= 1e9:
-        return f"{sign}{net_flow/1e9:.2f}B"
-    elif abs_flow >= 1e6:
-        return f"{sign}{net_flow/1e6:.2f}M"
-    elif abs_flow >= 1e3:
-        return f"{sign}{net_flow/1e3:.2f}K"
-    else:
-        return f"{sign}{net_flow:.0f}"
-```
-
---
-
-## 应用示例
-
-### 完整排行榜实现
-
-```python
-def get_volume_ranking(data, limit=10):
-    """获取交易量排行榜"""
-
-    # 1. 数据处理和排序
-    sorted_data = sorted(data, key=lambda x: x['volume'], reverse=True)[:limit]
-
-    # 2. 准备数据行
-    data_rows = []
-    for i, item in enumerate(sorted_data, 1):
-        symbol = item['symbol']
-        volume = item['volume']
-        price = item['price']
-        change = item['change_percent']
-
-        # 格式化各列
-        volume_str = format_volume(volume)
-        price_str = format_price(price)
-        change_str = format_change(change)
-
-        # 添加到数据行
-        data_rows.append([
-            f"{i}.",      # 序号
-            symbol,       # 币种
-            volume_str,   # 交易量
-            price_str,    # 价格
-            change_str    # 涨跌幅
-        ])
-
-    # 3. 动态对齐格式化
-    aligned_data = dynamic_align_format(data_rows)
-
-    # 4. 构建最终消息
-    text = f"""🎪 热币排行 - 交易量榜 🎪
-⏰ 更新 {datetime.now().strftime('%Y-%m-%d %H:%M')}
-📊 排序 24小时交易量(USDT) / 降序
-排名/币种/24h交易量/价格/24h涨跌
-```
-{aligned_data}
-```
-💡 交易量反映市场活跃度和流动性"""
-
-    return text
-```
-
-### 输出效果
-
-```
-🎪 热币排行 - 交易量榜 🎪
-⏰ 更新 2025-10-29 14:30
-📊 排序 24小时交易量(USDT) / 降序
-排名/币种/24h交易量/价格/24h涨跌
-
-1.   BTC      $1.23B    $45,000   +5.23%
-2.   ETH    $890.5M     $2,500   +3.12%
-3.   SOL    $567.8M       $101   +8.45%
-4.   BNB    $432.1M       $315   +2.67%
-5.   XRP    $345.6M     $0.589   -1.23%
-
-💡 交易量反映市场活跃度和流动性
-```
-
---
-
-## 最佳实践
-
-### 1. 数据准备规范
-
-```python
-# ✅ 推荐：使用列表嵌套结构
-data_rows = [
-    ["1.", "BTC", "$1.23B", "$45,000", "+5.23%"],
-    ["2.", "ETH", "$890.5M", "$2,500", "+3.12%"]
-]
-
-# ❌ 不推荐：使用字典（需要额外转换）
-data_rows = [
-    {"rank": 1, "symbol": "BTC", ...},
-]
-```
-
-### 2. 格式化顺序
-
-```python
-# ✅ 推荐：先格式化，再对齐
-for i, item in enumerate(data, 1):
-    volume_str = format_volume(item['volume'])      # 格式化
-    price_str = format_price(item['price'])         # 格式化
-    change_str = format_change(item['change'])      # 格式化
-
-    data_rows.append([f"{i}.", symbol, volume_str, price_str, change_str])
-
-aligned_data = dynamic_align_format(data_rows)  # 对齐
-```
-
-### 3. Telegram 消息嵌入
-
-```python
-# ✅ 推荐：使用代码块包裹对齐数据
-text = f"""📊 排行榜标题
-⏰ 更新时间 {time}
-```
-{aligned_data}
-```
-💡 说明文字"""
-
-# ❌ 不推荐：直接输出（Telegram会自动换行，破坏对齐）
-text = f"""📊 排行榜标题
-{aligned_data}
-💡 说明文字"""
-```
-
-### 4. 空数据处理
-
-```python
-# ✅ 推荐：在函数开头检查
-def dynamic_align_format(data_rows):
-    if not data_rows:
-        return "暂无数据"
-    # ... 正常处理逻辑 ...
-```
-
-### 5. 性能优化
-
-```python
-# ✅ 推荐：限制数据量
-sorted_data = sorted(data, key=lambda x: x['volume'], reverse=True)[:limit]
-aligned_data = dynamic_align_format(data_rows)
-
-# ❌ 不推荐：处理全量后截取（浪费资源）
-aligned_data = dynamic_align_format(all_data_rows)
-final_data = aligned_data.split('\n')[:limit]
-```
-
-### 6. 中文字符支持（可选）
-
-```python
-def get_display_width(text):
-    """计算文本显示宽度（中文=2，英文=1）"""
-    width = 0
-    for char in text:
-        if ord(char) > 127:  # 非ASCII字符
-            width += 2
-        else:
-            width += 1
-    return width
-
-# 在 dynamic_align_format 中使用
-max_widths[i] = max(max_widths[i], get_display_width(str(cell)))
-```
-
---
-
-## 设计优势
-
-### 与硬编码方式对比
-
-| 特性 | 传统硬编码 | 动态对齐 |
-|------|-----------|---------|
-| 列宽适配 | 手动指定 | 自动计算 |
-| 维护成本 | 高（需多处修改） | 低（一次编写） |
-| 对齐精度 | 易出偏差 | 字符级精确 |
-| 扩展性 | 需重构 | 自动支持任意列 |
-| 性能 | O(n) | O(n×m) |
-
-### 技术亮点
-
- **自适应宽度**: 无论数据如何变化，始终完美对齐
- **智能对齐规则**: 符合人类阅读习惯（文本左，数字右）
- **等宽字体完美支持**: 空格填充确保对齐效果
- **高复用性**: 一个函数适用所有排行榜场景
-
---
-
-## 快速参考
-
-### 函数签名
-
-```python
-dynamic_align_format(data_rows: list[list]) -> str
-format_volume(volume: float) -> str
-format_price(price: float) -> str
-format_change(change_percent: float) -> str
-format_flow(net_flow: float) -> str
-```
-
-### 时间复杂度
-
- 宽度计算: O(n × m)
- 格式化输出: O(n × m)
- 总复杂度: O(n × m) - 线性时间，高效实用
-
-### 性能基准
-
- 处理 100 行 × 5 列: ~1ms
- 处理 1000 行 × 5 列: ~5-10ms
- 内存占用: 最小
-
---
-
-**这份指南提供了 Telegram Bot 专业数据展示的完整解决方案！**