评论QQ通知插件（Qmsg）使用说明

版本：1.0.0 ｜ 作者：kuakeba.cn ｜ 适用宿主：Zsens Admin（社区版）

对接 Qmsg酱（qmsg.zendee.cn）推送接口：社区帖子产生新留言（回复）时，自动把通知推送到管理员 QQ。支持「新留言 / 待审核留言」分别开关、不推送用户过滤，以及推送失败时的前台弹窗提示。

一、功能概览

• 评论即推送：社区帖子收到新回复时，通过 Qmsg酱把留言摘要推送到管理员 QQ 单聊
• 分类开关：新留言、待审核留言可分别开启或关闭
• 用户过滤：命中「不推送的用户」名单的留言不推送（可填会员 ID / 管理员 ID）
• 推送失败弹窗（可选）：推送失败时在前台弹出原因，便于排查 KEY 或网络问题
• 零打扰主流程：推送失败静默处理，不影响用户回复操作
• 无数据表：不建表、不加后台菜单，仅使用宿主插件配置与社区回复钩子

二、运行环境

• PHP 8.0+（本机 8.0.2 实测可用），需开启 curl 扩展
• 已安装并启用「社区」（community）宿主插件（回复数据与钩子依赖）
• 一个 Qmsg酱账号与 API Key：https://qmsg.zendee.cn/user

三、安装

1. 把 plugins/Qmsg 目录整体上传到项目 plugins/ 下。
2. 后台「应用中心 → 评论QQ通知 → 安装」。
3. 安装后进入「配置」填写 Qmsg酱 KEY 即可生效。

本插件不创建数据表、不注册后台菜单；卸载仅使钩子失效，不会改动任何社区帖子与回复数据，可随时重新安装。

四、配置项

后台「应用中心 → 评论QQ通知 → 配置」：

只有「已安装」且「已填写 Qmsg酱KEY」时插件才会推送；任一条件不满足时全部静默跳过。

五、Qmsg酱 KEY 获取与绑定

1. 打开 Qmsg酱控制台，使用 QQ 登录。
2. 在控制台的「KEY 管理」中获取 API Key（推送凭证，请勿泄露或提交到公共仓库）。
3. 使用 QQ 扫码添加 Qmsg酱机器人为好友，并向机器人发送你的 API Key 完成绑定。
4. 绑定完成后，推送的消息将由该机器人发送到你的 QQ 单聊。

如需推送到 QQ 群，需先在 Qmsg酱控制台添加该群并完成群绑定；本插件固定推送单聊（不传 group 参数）。

六、触发时机与推送内容

触发时机：社区产生回复后，宿主钩子 TopicPluginHooks::afterReplySave 调用本插件。

前台提交的回复固定为 status = 1；管理员在后台把回复改为隐藏 / 待审核时才会走「待审核留言」分支。

推送内容（纯文字，多行）：

【新留言】您的社区收到一条新留言
帖子：帖子标题
用户：留言者用户名
内容：留言内容摘要（最多 80 字）

待审核分支首行替换为 【待审核留言】您的社区有新的待审核留言。

七、工作原理

用户提交回复 → community 写入 community_reply（status=1）
  → TopicPluginHooks::afterReplySave(reply_id)
    → QmsgPlugin::afterReplySave
        ① 已安装且已填 KEY？
        ② 按 status 选 notify_new / notify_pending 开关
        ③ 命中 skip_users？→ 跳过
        ④ 组装文字消息 → POST https://qmsg.zendee.cn/v3/send/{key}
    → 推送失败且开启「失败弹窗」→ 写入 Cache（120 秒）
前台页面 → 注入脚本轮询 /qmsg/notice → 读取并清除缓存 → 弹窗提示

• 接口：POST https://qmsg.zendee.cn/v3/send/{key}，表单参数 msg
• 并发保护：超时 8 秒、连接超时 5 秒；异常全部捕获，不影响回复主流程
• 失败弹窗：因回复接口固定返回成功，无法直接改写响应，故走「写缓存 + 前台轮询」方案；缓存键含会话与会员身份，只回显给触发本次回复的访客，Cache::pull 读取即清除（不会重复弹窗）

八、内容合规与限制（重要）

Qmsg酱对推送内容有强制检测，违规内容会被拒绝，严重时封禁账号：

因此本插件推送的消息只含文字（类型标记、帖子标题、用户名、内容摘要），不包含帖子链接。

但帖子标题与留言正文由用户输入，仍可能包含数字或敏感词，若频繁被判违规，建议在站点侧对留言内容做过滤，或关闭对应提醒开关。

九、常见问题

Q：回复了但没有收到 QQ 通知？

A：依次排查：① 插件是否已在「应用中心」安装并启用；② 「Qmsg酱KEY」是否已填写且正确；③ 对应开关（有新留言 / 待审核留言）是否开启；④ 该用户 ID 是否在「不推送的用户」名单中；⑤ 服务器是否已开启 curl 扩展；⑥ 是否超出 Qmsg酱每日 500 次限额或被限流（5 秒 1 次）。

Q：插件配置页在哪？

A：后台「应用中心」→ 找到「评论QQ通知」→ 点击「配置」。

Q：打开「输出推送失败弹窗」后会一直弹吗？

A：不会。失败提示写入缓存后读取即清除（Cache::pull），且只回显给当次触发推送的访客，有效期 120 秒。

Q：为什么不推送帖子链接？

A：Qmsg酱明确禁止消息中包含 URL（绝对禁止内容，可能封号），故正文不含链接。

Q：卸载插件会丢失什么？

A：不建表、不改社区数据，卸载仅停止通知；已配置的 KEY 等配置项在重新安装后需重新确认。

Q：「待审核留言提醒」怎么触发？

A：前台回复固定为正常状态，需管理员在后台把回复改为隐藏 / 待审核时才会触发该分支。

十、与其他插件的关系