root
04947ae52d
- 修改API路径为 /open-apis/im/v1/messages (message/v4已废弃) - 添加卡片config配置 - 修复content格式(直接传卡片对象,不需要包裹) - 添加测试接口 /api/v1/test/notification 测试结果: 成功发送通知到李佳博(feishu_user_id: 481g947d) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
209 lines
6.0 KiB
Markdown
209 lines
6.0 KiB
Markdown
# 飞书通知模块使用文档
|
||
|
||
## 概述
|
||
|
||
`FeishuNotificationService` 是一个统一的飞书消息通知服务，支持多种卡片类型的消息通知，可供所有业务模块使用。
|
||
|
||
## 功能特性
|
||
|
||
- ✅ 多种卡片类型（审批通知、系统通知、提醒通知）
|
||
- ✅ 批量发送支持
|
||
- ✅ 多公司支持
|
||
- ✅ 模板化配置
|
||
- ✅ 失败重试机制
|
||
- ✅ 详细日志记录
|
||
|
||
## 使用方法
|
||
|
||
### 1. 初始化服务
|
||
|
||
```php
|
||
use app\service\FeishuNotificationService;
|
||
|
||
$notification = new FeishuNotificationService();
|
||
$notification->setCompany($companyId);
|
||
// 可选：指定应用
|
||
$notification->setApp($appId);
|
||
```
|
||
|
||
### 2. 发送审批通知
|
||
|
||
```php
|
||
$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. 发送系统通知
|
||
|
||
```php
|
||
$notification->sendSystemNotification([
|
||
// 必填
|
||
'user_ids' => [1, 2, 3], // 接收人ID数组
|
||
'title' => '系统通知', // 通知标题
|
||
'content' => '系统将于今晚维护', // 通知内容
|
||
|
||
// 可选
|
||
'url' => 'https://xxx/notice', // 跳转链接
|
||
]);
|
||
```
|
||
|
||
### 4. 发送提醒通知
|
||
|
||
```php
|
||
$notification->sendReminderNotification([
|
||
// 必填
|
||
'user_id' => $userId, // 接收人ID
|
||
'title' => '待办提醒', // 提醒标题
|
||
'content' => '您有3条待审批', // 提醒内容
|
||
'level' => 'warning', // 级别: info/warning/urgent
|
||
|
||
// 可选
|
||
'url' => 'https://xxx/todo', // 跳转链接
|
||
]);
|
||
```
|
||
|
||
**提醒级别：**
|
||
- `info` (💡 蓝色) - 普通提醒
|
||
- `warning` (⚠️ 橙色) - 警告提醒
|
||
- `urgent` (🚨 红色) - 紧急提醒
|
||
|
||
### 5. 批量发送
|
||
|
||
```php
|
||
$notification->sendBatchNotification([
|
||
'user_ids' => [1, 2, 3], // 接收人ID数组
|
||
'type' => 'approval', // 通知类型: approval/system/reminder
|
||
// ... 其他参数根据类型而定
|
||
]);
|
||
```
|
||
|
||
## 业务场景示例
|
||
|
||
### 出差申请审批通知
|
||
|
||
```php
|
||
// 在 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",
|
||
]);
|
||
}
|
||
```
|
||
|
||
### 审批结果通知
|
||
|
||
```php
|
||
// 审批通过后通知申请人
|
||
$notification->sendSystemNotification([
|
||
'user_ids' => [$trip->user_id],
|
||
'title' => '审批通过',
|
||
'content' => "您的出差申请已通过\n\n目的地: {$trip->destination}\n时间: {$trip->start_date}",
|
||
'url' => config('app.url') . "/business-trip/{$tripId}",
|
||
]);
|
||
```
|
||
|
||
### 待办提醒
|
||
|
||
```php
|
||
// 每天提醒待审批事项
|
||
$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
|
||
|
||
```php
|
||
// 批量发送示例
|
||
$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;
|
||
```
|
||
|
||
## 错误处理
|
||
|
||
服务会自动捕获异常并记录日志，不会中断业务流程：
|
||
|
||
```php
|
||
// 即使发送失败，也不会抛出异常
|
||
$result = $notification->sendApprovalNotification($params);
|
||
if (!$result) {
|
||
// 发送失败，日志已自动记录
|
||
// 可在此处添加降级处理逻辑
|
||
}
|
||
```
|
||
|
||
## 配置文件
|
||
|
||
配置文件位于 `config/feishu_notification.php`，可自定义：
|
||
- 卡片模板样式
|
||
- 重试次数和间隔
|
||
- 日志级别
|
||
|
||
## 注意事项
|
||
|
||
1. **用户必须绑定飞书**: 接收人必须已绑定飞书账号（`feishu_user_id` 不为空）
|
||
2. **公司必须配置飞书应用**: 公司需要配置有效的飞书应用
|
||
3. **链接必须可访问**: 卡片中的链接需要用户可以访问
|
||
4. **内容长度限制**: 飞书对消息内容有长度限制，建议摘要控制在 200 字以内
|
||
|
||
## 相关文档
|
||
|
||
- [飞书开放平台 - 消息卡片](https://open.feishu.cn/document/ukTMukTMukTM/uEjNwUjLxYDM14SM2ATN)
|
||
- [飞书开放平台 - 发送消息](https://open.feishu.cn/document/ukTMukTMukTM/uUjNwUjL2YDM14SN2ATN)
|