109 lines
3.1 KiB
Markdown
109 lines
3.1 KiB
Markdown
# 企业微信客户同步功能修复
|
||
|
||
## 问题描述
|
||
|
||
调用企业微信API获取客户列表时报错：
|
||
```
|
||
missing field `userid`. invalid Request Parameter
|
||
```
|
||
|
||
## 问题原因
|
||
|
||
根据企业微信API文档，获取客户列表接口 `/cgi-bin/externalcontact/list` 需要传入 `userid` 参数（企业成员ID）。之前的实现直接调用该接口，没有传入必需的 `userid` 参数。
|
||
|
||
## 解决方案
|
||
|
||
修改同步逻辑，采用正确的流程：
|
||
|
||
1. 先调用 `/cgi-bin/user/list` 获取企业成员列表
|
||
2. 遍历每个成员，调用 `/cgi-bin/externalcontact/list?userid=xxx` 获取该成员的客户列表
|
||
3. 对每个客户调用 `/cgi-bin/externalcontact/get` 获取详情
|
||
4. 保存到数据库，自动去重
|
||
|
||
## 修改文件
|
||
|
||
### 1. server/app/common/service/wechat/WechatWorkService.php
|
||
|
||
新增方法：
|
||
- `getDepartmentUserList()` - 获取部门成员列表
|
||
|
||
修改方法：
|
||
- `getExternalContactList($userId)` - 添加 `$userId` 参数，获取指定成员的客户列表
|
||
|
||
### 2. server/app/adminapi/logic/qywx/CustomerLogic.php
|
||
|
||
修改 `syncCustomers()` 方法：
|
||
- 先获取企业成员列表
|
||
- 遍历成员获取其客户
|
||
- 使用 `$processedCustomers` 数组避免重复处理同一客户
|
||
|
||
### 3. server/config/project.php
|
||
|
||
新增配置项：
|
||
```php
|
||
// 企业微信客户同步配置
|
||
// 从哪个部门开始同步（1=根部门，会递归获取所有子部门成员）
|
||
'qywx_sync_department_id' => 1,
|
||
```
|
||
|
||
### 4. QYWX_CUSTOMER_SYNC_GUIDE.md
|
||
|
||
更新文档：
|
||
- 添加同步流程说明
|
||
- 添加部门ID配置说明
|
||
- 添加通讯录权限要求
|
||
- 添加 `missing field userid` 错误排查说明
|
||
|
||
## 权限要求
|
||
|
||
企业微信应用需要开启以下权限：
|
||
- 通讯录管理 → 成员信息读取（新增）
|
||
- 客户联系 → 客户基础信息
|
||
- 客户联系 → 客户标签
|
||
- 客户联系 → 客户联系人
|
||
|
||
## 配置说明
|
||
|
||
### 必需配置（server/.env）
|
||
```env
|
||
WECHAT_WORK_CORP_ID=你的企业ID
|
||
WECHAT_WORK_EXTERNAL_PAY_SECRET=你的应用Secret
|
||
```
|
||
|
||
### 可选配置（server/config/project.php）
|
||
```php
|
||
'qywx_sync_department_id' => 1, // 默认1（根部门），会递归获取所有子部门成员
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
1. 确保配置正确
|
||
2. 清除缓存：`php think clear`
|
||
3. 在前端页面点击"立即同步"按钮
|
||
4. 或运行命令：`php think qywx:sync-customer`
|
||
|
||
## 测试验证
|
||
|
||
修复后，同步功能应该能够：
|
||
- 成功获取企业成员列表
|
||
- 遍历每个成员获取其客户
|
||
- 正确保存客户信息到数据库
|
||
- 显示同步统计（总数、新增、更新）
|
||
|
||
注意：首次使用需要配置IP白名单，否则会报错 60020。
|
||
|
||
## 常见问题
|
||
|
||
### 错误码 60020 - IP白名单限制
|
||
|
||
如果遇到 `not allow to access from your ip` 错误，需要：
|
||
1. 获取服务器公网IP：`curl ifconfig.me`
|
||
2. 在企业微信管理后台添加IP到白名单
|
||
3. 详细说明：[QYWX_IP_WHITELIST_GUIDE.md](./QYWX_IP_WHITELIST_GUIDE.md)
|
||
|
||
## 参考文档
|
||
|
||
- [获取部门成员](https://developer.work.weixin.qq.com/document/path/90200)
|
||
- [获取成员客户列表](https://developer.work.weixin.qq.com/document/path/92113)
|
||
- [获取客户详情](https://developer.work.weixin.qq.com/document/path/92114)
|