pfinal_notify

统一通知网关 — webman 插件，聚合飞书、钉钉、企业微信机器人消息推送。

通过一个 API 即可向所有平台发送文本、Markdown、卡片消息，支持失败自动重试、异步队列、广播发送、通用卡片格式自动转换。

特性

• 三合一 — 一套接口同时对接飞书、钉钉、企业微信
• 消息类型 — text / markdown / card（平台原生卡片）
• 通用卡片 — 传入统一格式，自动转换为各平台原生卡片（飞书 interactive、钉钉 actionCard、企微 template_card）
• 广播 — 一条消息同时发送给所有已启用的机器人
• 异步队列 — 支持消息入队异步发送，失败自动重试（指数退避）
• 失败重试 — 内置重试机制 + 定时消费进程
• 完备的管理后台 — 配置管理 / 发送日志 / 失败队列（Layui 界面）
• 全局辅助函数 — 一行代码即可发送，无需手动实例化
• DB 连接可配置 — 自定义数据库，默认 plugin.admin.mysql

支持的平台

安装

通过 webman 应用市场安装，或手动拷贝插件目录到 plugin/pfinal_notify 后运行：

php webman plugin:install pfinal_notify

数据库

安装过程会自动创建三张表：

• pfinal_notify_config — 机器人配置
• pfinal_notify_log — 发送日志
• pfinal_notify_queue — 失败重试队列

配置

机器人管理

访问管理后台 消息通知 → 配置管理，添加机器人配置：

配置文件 config/notify.php

return [
    // 默认配置 ID（可选）
    'default' => [
        'feishu'   => 1,
        'dingtalk' => 2,
        'wework'   => 3,
    ],
    'timeout'       => 10,       // HTTP 超时（秒）
    'log_enabled'   => true,     // 是否记录发送日志
    'retry_count'   => 2,        // 失败重试次数
    'retry_delay'   => 1000,     // 重试间隔（毫秒）
    'auto_retry'    => true,     // 发送失败自动入队重试
    'max_retry'     => 3,        // 队列最大重试次数
    'queue_interval'=> 60,       // 队列消费间隔（秒）
    'queue_limit'   => 10,       // 每次消费数量
    'db_connection' => 'plugin.admin.mysql', // 数据库连接名
];

使用方式

全局辅助函数（推荐）

直接在任意代码中调用：

// 发送文本
notify_feishu('hello world');
notify_dingtalk('hello world');
notify_wework('hello world');
notify_send('feishu', 'hello world');

// 发送 Markdown
notify_feishu_markdown('标题', '**加粗** 正文');
notify_dingtalk_markdown('标题', '# 一级标题');
notify_wework_markdown('标题', '> 引用文本');
notify_send_markdown('feishu', '标题', '正文内容');

// 异步发送（入队后立即返回）
notify_feishu_async('hello world');
notify_dingtalk_async('hello world');
notify_wework_async('hello world');
notify_send_async('feishu', 'hello world');
notify_send_markdown_async('feishu', '标题', '正文');

完整辅助函数列表

Service 调用

use plugin\pfinal_notify\app\service\NotifyService;

NotifyService::sendText('feishu', '你好', [], $configId);
NotifyService::sendMarkdown('dingtalk', '标题', '# 正文', []);
NotifyService::sendCard('wework', $cardArray, []);
NotifyService::sendTextAsync('feishu', '异步消息', [], $configId);
NotifyService::sendBroadcast('全员通知', 'markdown', '公告');
NotifyService::sendSimple('feishu', '部署通知', '前端已发布', [
    ['key' => '环境', 'value' => '生产'],
    ['key' => '版本', 'value' => 'v2.1.0'],
], 'success', 'https://example.com');
NotifyService::sendSimpleBroadcast('全局通知', '所有人', [], 'warning');

HTTP API

所有接口路径：POST /notify/send/*

发送消息

配置管理

日志管理

队列管理

通用卡片（send/simple）参数

POST /notify/send/simple

{
    "type": "feishu",        // 不传则广播给所有类型
    "title": "部署通知",
    "content": "前端已发布到生产环境",
    "fields": [
        {"key": "环境", "value": "生产"},
        {"key": "版本", "value": "v2.1.0"}
    ],
    "status": "success",     // info | success | warning | error
    "url": "https://..."
}

自动转换为各平台原生卡片格式：

通用响应格式

{
    "code": 0,
    "message": "发送成功",
    "data": { ... }
}

管理后台

插件安装后，在 webman admin 左侧菜单可见：

数据库

pfinal_notify_config     -- 机器人配置（名称 / 类型 / webhook / 密钥 / 启用）
pfinal_notify_log        -- 发送日志（配置ID / 类型 / 标题 / 内容 / 状态 / 错误信息）
pfinal_notify_queue      -- 失败重试队列（配置ID / 消息类型 / 内容 / 状态 / 重试次数 / 下次重试时间）

架构

client/         平台适配层
├── BaseClient.php          —— HTTP 客户端基类（签名、请求）
├── ClientInterface.php     —— 接口契约
├── FeishuClient.php        —— 飞书适配
├── DingTalkClient.php      —— 钉钉适配
└── WeWorkClient.php        —— 企业微信适配

service/        业务逻辑层
├── NotifyService.php       —— 核心服务（发送、日志、配置管理、广播、通用卡片）
└── FailQueueService.php    —— 队列服务（入队、统计、重试）

task/           异步任务
└── AsyncNotifyTask.php     —— 队列消费任务（processQueue）

process/        常驻进程
└── NotifyQueueProcess.php  —— 定时消费进程（基于 Timer）

controller/     控制器
└── NotifyController.php    —— HTTP API 控制器

发送流程

请求 → Controller → NotifyService → Client（Feishu/DingTalk/WeWork）→ HTTP POST → 平台
                                        │
                                        ├─ 失败 → 自动重试（配置次数）
                                        ├─ 仍失败 → 入队（FailQueue）
                                        └─ 记录日志 → pfinal_notify_log

队列消费流程

NotifyQueueProcess（Timer 定时）
    → AsyncNotifyTask::processQueue()
        → 读取 pending 记录
        → NotifyService::send*()（设置 $processingFromQueue 防止循环入队）
            → 成功 → 标记 success
            → 失败 → 更新 retry_count，指数退避计算 next_retry_at