zyt/QYWX_SYNC_FIX.md

企业微信客户同步功能修复

问题描述

调用企业微信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

新增配置项：

// 企业微信客户同步配置
// 从哪个部门开始同步（1=根部门，会递归获取所有子部门成员）
'qywx_sync_department_id' => 1,

4. QYWX_CUSTOMER_SYNC_GUIDE.md

更新文档：

• 添加同步流程说明
• 添加部门ID配置说明
• 添加通讯录权限要求
• 添加 missing field userid 错误排查说明

权限要求

企业微信应用需要开启以下权限：

• 通讯录管理 → 成员信息读取（新增）
• 客户联系 → 客户基础信息
• 客户联系 → 客户标签
• 客户联系 → 客户联系人

配置说明

必需配置（server/.env）

WECHAT_WORK_CORP_ID=你的企业ID
WECHAT_WORK_EXTERNAL_PAY_SECRET=你的应用Secret

可选配置（server/config/project.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

参考文档

• 获取部门成员
• 获取成员客户列表
• 获取客户详情