# 飞书通知模块使用文档

## 概述

`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)