40 lines
4.4 KiB
Markdown
40 lines
4.4 KiB
Markdown
# Telegram 工单通知与回复
|
||
|
||
## 接入范围
|
||
|
||
沿用本项目 Telegram 插件、网站机器人令牌、官方 Bot API 与原有 webhook。不接入 telegrammaster/master 项目；已有用户绑定、流量和订阅命令保留。该机器人可供用户与管理员共用，管理员工单回复需要独立权限校验。邮件仍由网站发送。
|
||
|
||
第一版仅支持管理员与机器人的私聊文字回复，不支持群聊、附件、编辑 Telegram 消息以修改已有工单回复。网站工单表与页面继续使用原有逻辑。
|
||
|
||
## 后台设置与启用
|
||
|
||
进入 /dove 的系统配置 → Telegram 设置 → 工单通知与回复。机器人令牌仍在原有字段保存。新增推送开关、回复开关和接收管理员选择；不选接收人代表全部已绑定且未禁用的管理员。
|
||
|
||
“连接机器人并启用回调”使用服务器保存的令牌，先核对 getMe 和 getWebhookInfo，拒绝覆盖其他网站/路径已有的 webhook。连接成功时启用机器人并保存随机 webhook secret；新回调通过 Telegram secret header 验证，未升级的既有回调暂兼容原 token 哈希验证。不能同时让其他服务 getUpdates 或占用同一机器人 webhook。
|
||
|
||
管理员点击“绑定我的 Telegram”，将十分钟内有效的一次性命令私聊发送给机器人。绑定码只存缓存，数据库记录管理员与 Telegram 的关联；代码不替换已有其他绑定，不允许将同一 Telegram 绑定到其他网站账号。绑定后刷新页面，并按需要开启回复。绑定码不要写入文档、日志或截图。
|
||
|
||
机器人没有绑定接收管理员前不会推送工单；回复开关默认关闭。该功能使用原有 Telegram 插件的 enable_ticket_notify 选项，若关闭该插件通知选项，仍不会推送。
|
||
|
||
## 消息处理
|
||
|
||
网站创建工单或用户追加内容后，原插件钩子排队发送通知。新增 v2_telegram_ticket_messages 保存来源工单消息、接收管理员、机器人令牌指纹和 Telegram 消息编号。正文截断过长文字，纯文本发送，减少多余个人数据披露。
|
||
|
||
管理员必须直接回复机器人发出的已关联通知。按机器人、私聊与消息编号查关联，再验证实际发送人、绑定管理员、禁用状态和接收人范围；不从转发消息或文字中的工单编号推断权限。已关闭工单拒绝回复。v2_telegram_ticket_updates 的唯一更新编号和事务锁防止 Telegram 重送导致重复写入/邮件通知。保存失败返回非成功响应，允许服务商重试；已保存回复不会因确认消息发送失败而重复写入。
|
||
|
||
回复通过 TicketService 写入原工单。有效用户邮箱才通知，仍使用 ticket_reply 的 Resend 优先/额度回退和同一用户三十分钟内不重复提醒的规则，不受自动邮件三档影响。无邮箱、邮件或其他通知钩子失败不回滚已保存回复；日志只记必要标识。
|
||
|
||
## 队列与失败处理
|
||
|
||
使用原有 send_telegram 队列。telegram:tickets:retry 每分钟恢复未发送任务；发送中断超过五分钟记为结果未知。明确 429 按 retry_after 延后，不提前重发。HTTP 超时和服务端异常可能已提交，记为 unknown，不自动重发。明确拒绝记为 failed。更换机器人令牌、撤销接收人或关闭推送后，待发送任务会取消。
|
||
|
||
## 维护与验收
|
||
|
||
迁移包含两张新表，应先备份数据库，再通过 Git 发布并执行迁移，刷新后台视图并重载队列。回滚代码时保留消息关联和去重记录，避免重复通知。
|
||
|
||
隔离测试与网页显示/保存不能替代真实验收。完整验收需管理员完成绑定，使用测试用户提交工单，管理员私聊回复，确认网站保存、邮件实际收到和重复更新不重复写入。记录结果到 STATUS.md；不得保存用户原始工单或令牌。
|
||
|
||
## 回复接收排查
|
||
|
||
按用户最新要求保留原来的回复分类：仅引用中包含 text 时进入工单回复，进入后仍按 reply_to_message.message_id 校验关联，不从原文字样推断工单或权限。对已绑定且未禁用管理员的私聊文字消息，在缓存保留最后一次接收时间、更新编号、是否使用回复、是否命中工单关联，最多一小时；不保存消息正文、账号凭据或原始请求。该记录仅供服务器维护排错，不能以收到回调代替工单写回或邮件送达验收。
|