新增

2026-04-11 18:06:02 +08:00
parent 4909ec6daa
commit abcecf66e7
325 changed files with 4199 additions and 633 deletions
@@ -0,0 +1,108 @@
+# 企业微信客户同步功能修复
+
+## 问题描述
+
+调用企业微信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)