使用指南
Telegram Mini App
了解 Mini App 的签名登录、角色、群组范围和可用页面。
Mini App 是从 Telegram WebView 打开的轻量管理入口。它和普通管理面板使用不同的登录边界：服务端验证 Telegram 的 initData，创建按 Bot 作用域隔离的短期会话，再根据实时授权决定用户能看到和修改什么。
启用前提
管理员需要为 Bot 启用 Mini App，并单独配置 MINI_APP_SESSION_SECRET。这个密钥不能复用 Better Auth 密钥、Bot Token 或其他 API Key；轮换后，已有 Mini App 会话会失效，但不会删除 Bot 数据。
Mini App 还需要 Telegram 能访问配置的 Bot，并让 Bot 查询所需的群成员关系。网络、Telegram WebView、Bot 权限或签名数据缺一项，都可能导致会话创建失败。
访问流程
- 从 Telegram 中打开 Bot 提供的 Mini App 链接。
- Telegram WebView 将签名初始化数据交给前端。
- 服务端校验签名、Bot 状态和用户身份，创建带 Bot 路径范围的会话 Cookie。
- 服务端实时解析管理员、操作员和已授权群组，并返回当前角色及能力。
- 前端只展示当前角色允许的页面，服务端对每个读写请求再次校验。
直接在普通浏览器访问 /mini-app/...，没有真实 Telegram initData，不能证明登录流程成功，也不应通过复制 Cookie 来绕过授权。
角色和范围
| 角色 | 默认范围 |
|---|---|
| 管理员 | 对该 Bot 的可授权范围拥有全局管理能力。 |
| 操作员 | 只操作已授予的群组。 |
| 查看者 | 只能查看自己仍是成员的已授予群组；成员状态变化会影响下一次授权检查。 |
| 无权限 | 不建立可用的 Mini App 工作区。 |
撤销授权在下一次检查中生效。Telegram API 无法确认成员身份时，服务端应按无访问处理，而不是放宽范围。
可用页面
根据角色，Mini App 可能提供：
- Groups：查看和管理已授权群组；
- Settings：调整群组启用状态、触发条件、上下文和总结相关设置；
- Access：管理聊天与操作员授权；
- Logs：查看受限的 Mini App 运行日志；
- Help：查看当前命令与使用提示。
群组设置保存使用修订版本，发生并发修改时需要重新读取最新值后再提交。Bot 生命周期、AI Provider/模型和日志能力仍受服务端角色策略限制。
安全和排错
- 生产环境应使用 HTTPS，并确保
BETTER_AUTH_URL或实例公开 origin 与 WebView 访问地址一致。 - 不要在日志中记录原始
initData、会话 Cookie 或 Bot Token。 - 若显示签名无效，重新从 Telegram 菜单打开，不要复用旧 URL 或手工拼接参数。
- 若角色是
none，检查 Bot 是否启用 Mini App、用户是否被授予群组、Bot 是否仍能查询成员关系。 - 若页面打开但保存失败，查看响应的修订冲突或权限错误，并重新加载页面。