# work-we-chat-kh

**Repository Path**: fantw/work-we-chat-kh

## Basic Information

- **Project Name**: work-we-chat-kh
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-22
- **Last Updated**: 2026-08-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# fantw/work-we-chat-kh

企业微信客服（WeCom KF）Laravel 集成包。

## 功能概览

| 分类 | 能力 |
|---|---|
| **消息发送** | 文本 / 图片 / 链接卡片 / 小程序卡片 / 图文 / 视频 |
| **素材管理** | 临时素材 / 永久素材（图片/视频/图文），上传/查询/删除 |
| **消息同步** | 拉取会话消息记录 |
| **客服账号** | 添加 / 删除 / 列表 |
| **会话管理** | 获取当前会话 / 变更对接客服 |
| **回调处理** | GET URL 验证 + POST 消息事件解密 + Laravel Event 分发 |

---

## 快速开始

### 1. 安装

```bash
composer require fantw/work-we-chat-kh
```

### 2. 安装插件（发布配置 + 注册 Provider）

```bash
php artisan work-we-chat-kh:install
```

`install` 命令会自动完成：
- ✅ 发布配置文件到 `config/work-we-chat-kh.php`
- ✅ 在 `config/app.php` 注册 `WorkWeChatKHServiceProvider`
- ✅ 在 `EventServiceProvider` 注册事件监听映射

> 使用 `--force` 强制覆盖已发布的配置文件  
> 使用 `--no-provider` 跳过 Provider 注册（已手动注册时）

### 3. 配置 .env

```env
# 企业凭证
WECOM_CORP_ID=wwxxxxxxxxxxxx
WECOM_CORP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
WECOM_KF_ACCOUNT=wkxxxxxxxxxxxxxx

# 回调验证（自己生成，填入企业微信管理后台）
WECOM_CALLBACK_TOKEN=your_random_44chars_token
WECOM_CALLBACK_AESKEY=your_random_43chars_aeskey

# 素材默认行为（false=临时 / true=永久）
WECOM_MEDIA_DEFAULT_PERMANENT=false
```

---

## 使用方法

### 注入使用（推荐）

```php
use Fantw\WorkWeChatKH\WorkWeChatKHClient;

// 方式1：通过 app()
$client = app('work-we-chat-kh');

// 方式2：直接 new
$client = new WorkWeChatKHClient([
    'corp_id'     => config('work-we-chat-kh.corp_id'),
    'corp_secret' => config('work-we-chat-kh.corp_secret'),
    'kf_account'  => config('work-we-chat-kh.kf_account'),
]);
```

### Facade 使用

```php
use Fantw\WorkWeChatKH\Facades\WorkWeChatKH;

WorkWeChatKH::sendText($openid, '您好，有什么可以帮您？');
```

---

## 发送消息

```php
$client = app('work-we-chat-kh');

// 文本
$client->sendText($openid, '您好！');

// 图片（先上传素材获取 media_id）
$client->sendImage($openid, $mediaId);

// 链接卡片
$client->sendLink($openid, '查看详情', '产品上新通知', 'https://example.com');

// 小程序卡片
$client->sendMiniProgram($openid, '点我打开', 'wx12345678', 'pages/index', $thumbMediaId);

// 视频
$client->sendVideo($openid, $videoMediaId, '视频标题', '视频描述');

// 指定客服账号
$client->sendText($openid, '您好！', 'wk_specific_account');
```

---

## 回调 URL 配置（企业微信后台）

1. 登录 **企业微信管理后台**
2. 进入 **应用管理** → 选择应用 → **接收消息** → **设置API接收**
3. 填写：
   - URL：`https://你的域名/api/work-we-chat-kh/callback`
   - Token：`WECOM_CALLBACK_TOKEN` 的值
   - EncodingAESKey：`WECOM_CALLBACK_AESKEY` 的值
   - 消息加密方式：选择「安全模式」或「兼容模式」
4. 点击「保存」后，企业微信会发送 GET 请求验证 URL

---

## 文件结构

```
src/
├── Config/work-we-chat-kh.php         # 配置文件
├── Commands/InstallCommand.php        # work-we-chat-kh:install 命令
├── Crypt/WXBizMsgCrypt.php            # AES 加解密
├── Client.php                         # API 客户端（主类）
├── Controllers/WorkWeChatKHController.php  # 回调入口控制器
├── Events/
│   ├── WorkWeChatKHEvent.php         # 事件基类
│   ├── KfMsgOrEvent.php              # 消息/事件事件类
│   └── KfAccountChange.php           # 账号变更事件类
├── Facades/WorkWeChatKH.php          # Facade
├── Listeners/
│   ├── RouteKfMessages.php           # 消息路由 Listener
│   └── RouteKfAccountChange.php      # 账号变更路由 Listener
├── Token/TokenManager.php            # Access Token 管理器
└── WorkWeChatKHServiceProvider.php   # Service Provider
```

---

## 许可证

MIT