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

## 问题描述

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