用途：指导构建运行在 Telegram 内的交互式网页应用（Mini App / Web App）。Telegram 会注入 window.Telegram.WebApp，应用可读取用户信息、主题与安全区，并通过原生页头页脚控件获得接近原生体验。
主要能力与使用方式：
- 本地开发：复制 assets/miniapp-mock.js 并在 head 中、Telegram SDK 之前引入，先在普通浏览器与真实 SDK 间切换调试；Telegram 要求部署地址使用 HTTPS。
- 起步模板：以 assets/miniapp-boilerplate.html 为起点，配合 theme.css 与 miniapp-native.css；保留 mock 顺序、viewport-fit=cover、tg.ready()、tg.expand()、viewportStableHeight 与 themeChanged 监听。
- 核心 API：tg.initDataUnsafe?.user 仅用于展示，授权需把 tg.initData 发到后端；颜色使用 --tg-theme-* CSS 变量。
- UI：MainButton、SecondaryButton（Bot API 7.10+）、BackButton（注意 offClick 防叠加）、SettingsButton（7.0+）、HapticFeedback 与原生弹窗。
- 回传数据：sendData() 仅在键盘按钮模式生效，其余场景用 HTTP POST 携带 initData 认证。
- 后端校验：直接使用 scripts/validate-init-data.js 或 validate_init_data.py（Go 版需改包名并移除 main），设置 BOT_TOKEN 环境变量，勿自行重写 HMAC 算法。
- 其他：SPA 用 div 页栈或 hash 路由避免整页刷新；BotFather 配置与各语言机器人处理示例；Telegram Stars（XTR）支付需在 10 秒内应答 pre_checkout_query；高级 API 与存储均需版本门控。
适用场景：需要在 Telegram 内提供表单、下单、扫码、定位、支付等交互流程的开发者与团队。
限制与注意：initDataUnsafe 不可用于授权；sendData 在非键盘按钮模式无效；BackButton 处理器会叠加；安全区需同时处理两类变量；避免 100vh；openLink 需用户手势；主题变量只读；注意 CORS 与按用户 ID 限流；全屏、加速度计等需 Bot API 8.0+；须在真实移动设备测试。实际收费与价格资料暂未提供。