# 企业微信通知功能说明

## 功能概述

企业微信通知功能用于在VAT文档生成成功或失败时，自动向企业微信群发送消息通知，并可以@指定的业务顾问。

## 通知场景

### 1. 文件生成成功
当VAT文档生成成功时，系统会发送如下格式的消息：
```
{业务编码} {公司中文名} 已成功生成{文件类型}
```

示例：
```
VAT2024001 深圳测试科技有限公司 已成功生成海牙文件
```

**注意**：@提醒功能通过企业微信API的 `mentioned_mobile_list` 参数实现，不会在消息内容中显示手机号，但会在企业微信中正确@到对应的人。

### 2. 文件生成失败
当VAT文档生成失败且达到最大重试次数后，系统会发送如下格式的消息：
```
{业务编码} {公司中文名} 生成文件失败，错误原因：{错误信息}
```

示例：
```
VAT2024002 上海示例企业有限公司 生成文件失败，错误原因：营业执照文件不存在
```

**注意**：@提醒功能通过企业微信API的 `mentioned_mobile_list` 参数实现，不会在消息内容中显示手机号，但会在企业微信中正确@到对应的人。

## 技术实现

### 核心类：WeChatWorkNotifier

位置：`src/WeChatWorkNotifier.php`

#### 主要方法

1. **sendSuccessNotification($code, $companyName, $fileType, $phone = null)**
   - 发送文件生成成功通知
   - 参数：
     - `$code`: 业务编码（vb.Code）
     - `$companyName`: 公司中文名称（bc.NameCN）
     - `$fileType`: 文件类型（"海牙文件" 或 "免海牙文件"）
     - `$phone`: 手机号码（LinkedSalesContactPhone），可选

2. **sendFailureNotification($code, $companyName, $errorReason, $phone = null)**
   - 发送文件生成失败通知
   - 参数：
     - `$code`: 业务编码（vb.Code）
     - `$companyName`: 公司中文名称（bc.NameCN）
     - `$errorReason`: 错误原因
     - `$phone`: 手机号码（LinkedSalesContactPhone），可选

3. **sendTextMessage($content, $mentionedMobile = null)**
   - 发送自定义文本消息
   - 参数：
     - `$content`: 消息内容
     - `$mentionedMobile`: 需要@的手机号，可选

### 集成位置

通知功能已集成到 `VATAsyncProcessor` 类中：

- **成功通知**：在文档生成成功后自动发送
- **失败通知**：在任务失败且达到最大重试次数后发送（避免重试期间频繁发送通知）

## 配置说明

### Webhook地址

Webhook 地址通过环境变量 `WECHAT_WORK_WEBHOOK` 配置（见 `.env` / `.env.example`），优先于代码内默认值。也可以在创建 `WeChatWorkNotifier` 实例时传入自定义地址：

```php
$notifier = new WeChatWorkNotifier('https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY');
```

### 手机号获取

手机号从数据库查询中获取，对应字段：
- 表：`Base_User`
- 字段：`F_Mobile`
- 关联：通过 `VATBusinessRecord.BusinessCounselorId` 关联

SQL示例：
```sql
SELECT bu.F_Mobile as LinkedSalesContactPhone
FROM VATBusinessRecord vb
LEFT JOIN Base_User bu ON bu.F_UserId = vb.BusinessCounselorId
WHERE vb.ID = :id
```

## 测试方法

### 1. 使用测试脚本

运行失败通知测试脚本（验证查册文件等不符合要求时的企微通知）：

```bash
php scripts/test_failure_notification.php
```

### 2. 手动测试

```php
require_once 'vendor/autoload.php';
use Haiya\WeChatWorkNotifier;

$notifier = new WeChatWorkNotifier();

// 测试成功通知
$notifier->sendSuccessNotification(
    'VAT2024001',
    '测试公司',
    '海牙文件',
    '13800138000'
);

// 测试失败通知
$notifier->sendFailureNotification(
    'VAT2024002',
    '测试公司',
    '文件不存在',
    '13800138000'
);
```

## 注意事项

1. **@提醒功能**
   - 只有当手机号不为空时才会添加@提醒
   - 手机号必须是企业微信群成员绑定的手机号
   - 如果手机号不正确，消息仍会发送但不会@到人

2. **错误处理**
   - 通知发送失败不会影响主流程
   - 所有通知错误都会记录到日志中
   - 建议定期检查日志确保通知功能正常

3. **重试机制**
   - 失败通知只在达到最大重试次数后发送
   - 避免在重试期间频繁发送通知造成干扰

4. **消息长度限制**
   - 错误信息不再截断，完整发送
   - 如需截断可在代码中取消注释相关逻辑

## 日志记录

所有通知相关的操作都会记录到日志中：

- 成功发送：`logs/queue_processor_YYYYMMDD.log`
- 发送失败：同上，带有错误信息
- 日志级别：
  - 成功：`success`
  - 失败：`error`
  - 警告：`warning`

## 企业微信机器人配置

如需创建新的企业微信机器人：

1. 在企业微信群中，点击右上角 `...` → `群机器人`
2. 点击 `添加机器人`
3. 设置机器人名称和头像
4. 复制Webhook地址
5. 将地址配置到 `WeChatWorkNotifier` 中

## 故障排查

### 消息发送失败

1. 检查Webhook地址是否正确
2. 检查网络连接是否正常
3. 查看日志文件中的详细错误信息
4. 确认企业微信机器人是否被禁用

### @提醒不生效

1. 确认手机号是否正确
2. 确认手机号是否绑定到企业微信账号
3. 确认该用户是否在群中

### 测试建议

建议在正式环境使用前：
1. 先在测试群中测试通知功能
2. 验证@提醒是否正常工作
3. 确认消息格式是否符合预期
4. 检查日志记录是否完整