x-server-mobile/docs/feishu-notification.md

飞书通知模块使用文档

概述

FeishuNotificationService 是一个统一的飞书消息通知服务，支持多种卡片类型的消息通知，可供所有业务模块使用。

功能特性

• ✅ 多种卡片类型（审批通知、系统通知、提醒通知）
• ✅ 批量发送支持
• ✅ 多公司支持
• ✅ 模板化配置
• ✅ 失败重试机制
• ✅ 详细日志记录

使用方法

1. 初始化服务

use app\service\FeishuNotificationService;

$notification = new FeishuNotificationService();
$notification->setCompany($companyId);
// 可选：指定应用
$notification->setApp($appId);

2. 发送审批通知

$notification->sendApprovalNotification([
    // 必填
    'user_id' => $approverId,          // 接收人ID
    'title' => '新的审批申请',          // 通知标题
    'applicant' => '张三',              // 申请人姓名
    'type' => '出差申请',               // 申请类型
    'content' => '前往上海参加客户会议', // 申请内容

    // 可选
    'url' => 'https://xxx/approval/123',           // 详情链接
    'approve_url' => 'https://xxx/approve/123',   // 通过按钮链接
    'reject_url' => 'https://xxx/reject/123',     // 拒绝按钮链接
]);

卡片样式：

┌─────────────────────────────┐
│ 📋 新的审批申请              │
├─────────────────────────────┤
│ 申请人: 张三  申请类型: 出差 │
│                             │
│ 申请内容:                    │
│ 前往上海参加客户会议          │
│                             │
│ [通过] [拒绝] [查看详情]     │
└─────────────────────────────┘

3. 发送系统通知

$notification->sendSystemNotification([
    // 必填
    'user_ids' => [1, 2, 3],       // 接收人ID数组
    'title' => '系统通知',           // 通知标题
    'content' => '系统将于今晚维护', // 通知内容

    // 可选
    'url' => 'https://xxx/notice',  // 跳转链接
]);

4. 发送提醒通知

$notification->sendReminderNotification([
    // 必填
    'user_id' => $userId,           // 接收人ID
    'title' => '待办提醒',           // 提醒标题
    'content' => '您有3条待审批',    // 提醒内容
    'level' => 'warning',           // 级别: info/warning/urgent

    // 可选
    'url' => 'https://xxx/todo',    // 跳转链接
]);

提醒级别：

• info (💡 蓝色) - 普通提醒
• warning (⚠️ 橙色) - 警告提醒
• urgent (🚨 红色) - 紧急提醒

5. 批量发送

$notification->sendBatchNotification([
    'user_ids' => [1, 2, 3],    // 接收人ID数组
    'type' => 'approval',       // 通知类型: approval/system/reminder
    // ... 其他参数根据类型而定
]);

业务场景示例

出差申请审批通知

// 在 BusinessTripService 中
$notification = new FeishuNotificationService();
$notification->setCompany($companyId);

// 获取审批人列表
$approvers = $this->getApprovers($tripId);

foreach ($approvers as $approver) {
    $notification->sendApprovalNotification([
        'user_id' => $approver->id,
        'title' => '新的出差申请',
        'applicant' => $trip->user->name,
        'type' => '出差申请',
        'content' => $trip->reason,
        'url' => config('app.url') . "/approval/trip/{$tripId}",
        'approve_url' => config('app.url') . "/api/approve/trip/{$tripId}/approve",
        'reject_url' => config('app.url') . "/api/approve/trip/{$tripId}/reject",
    ]);
}

审批结果通知

// 审批通过后通知申请人
$notification->sendSystemNotification([
    'user_ids' => [$trip->user_id],
    'title' => '审批通过',
    'content' => "您的出差申请已通过\n\n目的地: {$trip->destination}\n时间: {$trip->start_date}",
    'url' => config('app.url') . "/business-trip/{$tripId}",
]);

待办提醒

// 每天提醒待审批事项
$pendingApprovals = Approval::where('status', 'pending')->get();

foreach ($pendingApprovals as $approval) {
    $notification->sendReminderNotification([
        'user_id' => $approval->approver_id,
        'title' => '待办提醒',
        'content' => "您有 {$approval->count} 条待审批事项",
        'level' => 'warning',
        'url' => config('app.url') . "/approval",
    ]);
}

返回值

• 单个发送: 返回 bool - true 成功，false 失败
• 批量发送: 返回 array - key 为 user_id，value 为 bool

// 批量发送示例
$results = $notification->sendSystemNotification([
    'user_ids' => [1, 2, 3],
    'title' => '系统通知',
    'content' => '系统维护通知',
]);

// $results = [1 => true, 2 => false, 3 => true]
$successCount = count(array_filter($results));
$failCount = count($results) - $successCount;

错误处理

服务会自动捕获异常并记录日志，不会中断业务流程：

// 即使发送失败，也不会抛出异常
$result = $notification->sendApprovalNotification($params);
if (!$result) {
    // 发送失败，日志已自动记录
    // 可在此处添加降级处理逻辑
}

配置文件

配置文件位于 config/feishu_notification.php，可自定义：

• 卡片模板样式
• 重试次数和间隔
• 日志级别

注意事项

1. 用户必须绑定飞书: 接收人必须已绑定飞书账号（feishu_user_id 不为空）
2. 公司必须配置飞书应用: 公司需要配置有效的飞书应用
3. 链接必须可访问: 卡片中的链接需要用户可以访问
4. 内容长度限制: 飞书对消息内容有长度限制，建议摘要控制在 200 字以内

相关文档

• 飞书开放平台 - 消息卡片
• 飞书开放平台 - 发送消息