# 企业微信客户同步问题修复指南

## 问题描述

同步企业微信客户时，能成功获取企业成员列表（207人），但无法获取任何客户数据，所有API调用都返回错误码 `48002: "api forbidden"`。

## 根本原因

企业微信应用未开启"客户联系"API权限。错误码 `48002` 表示API接口被禁用或未授权。

## 解决方案

### 方案一：开启API权限（推荐）

1. 登录企业微信管理后台
   - 访问：https://work.weixin.qq.com/
   - 使用管理员账号登录

2. 进入应用管理
   - 点击"应用管理"
   - 找到您正在使用的应用（使用 `external_pay_secret` 的应用）

3. 开启客户联系权限
   - 在应用详情页面，找到"客户联系"权限设置
   - 开启以下权限：
     * ✓ 客户联系 - 获取客户列表
     * ✓ 客户联系 - 获取客户详情
     * ✓ 客户联系 - 获取客户数据统计（可选）

4. 配置可信IP
   - 在应用设置中找到"企业可信IP"
   - 添加您的服务器IP地址
   - 保存配置

5. 等待生效
   - 权限修改后可能需要几分钟生效
   - 建议等待5-10分钟后再测试

### 方案二：升级企业微信版本

如果您的企业微信版本不支持客户联系API：

1. 检查当前版本是否支持"客户联系"功能
2. 如需要，升级到支持该功能的版本
3. 部分功能可能需要付费版本

### 方案三：使用替代方案

如果无法开启API权限：

1. 使用企业微信后台手动导出客户数据
2. 通过CSV导入到系统
3. 或使用企业微信的webhook回调功能（需要配置）

## 诊断工具

### 1. 运行权限检查命令

```bash
php think qywx:check-permissions
```

这个命令会：
- 检查应用配置是否正确
- 测试获取部门成员权限
- 测试获取客户列表权限
- 显示详细的错误信息和解决建议

### 2. 查看日志

日志文件位置：`runtime/log/`

关键日志信息：
```
企业微信-获取成员客户列表响应 userId=XXX: {"errcode":48002,"errmsg":"api forbidden"...}
```

如果看到 `errcode: 48002`，说明是权限问题。

## 代码改进

已对代码进行以下改进：

1. **更好的错误处理**
   - `getExternalContactList()` 方法现在会检测 `48002` 错误
   - 权限错误时返回 `false` 而不是空数组
   - 同步逻辑会捕获权限错误并抛出明确的异常

2. **新增诊断方法**
   - `WechatWorkService::checkAppPermissions()` - 检查应用权限
   - `QywxCheckPermissions` 命令 - 完整的权限诊断工具

3. **改进的日志记录**
   - 权限错误会记录更详细的信息
   - 包含解决方案提示

## 测试步骤

1. 确认已开启API权限
2. 运行诊断命令：
   ```bash
   php think qywx:check-permissions
   ```

3. 如果诊断通过，运行同步：
   ```bash
   php think qywx:sync-customer
   ```

4. 检查同步结果：
   - 查看日志文件
   - 检查数据库表 `la_qywx_external_contact`
   - 在管理后台查看客户列表

## 常见问题

### Q1: 权限已开启，但仍然报错48002
A: 
- 等待5-10分钟让权限生效
- 清除企业微信access_token缓存：删除缓存键 `qywx_access_token`
- 检查服务器IP是否在可信IP列表中

### Q2: 找不到"客户联系"权限选项
A:
- 您的企业微信版本可能不支持此功能
- 需要升级到企业版或专业版
- 联系企业微信客服确认

### Q3: 部分成员能获取客户，部分不能
A:
- 检查成员是否有"客户联系"权限
- 在企业微信后台为成员分配权限
- 确认成员确实有添加客户

### Q4: 同步速度很慢
A:
- 这是正常的，因为需要逐个成员获取客户列表
- 207个成员 × 每个成员的客户数 = 大量API调用
- 建议设置定时任务，每小时或每天同步一次

## 相关文件

- `server/app/adminapi/logic/qywx/CustomerLogic.php` - 同步逻辑
- `server/app/common/service/wechat/WechatWorkService.php` - API服务
- `server/app/command/QywxSyncCustomer.php` - 同步命令
- `server/app/command/QywxCheckPermissions.php` - 诊断命令（新增）
- `server/config/project.php` - 配置文件

## 联系支持

如果按照以上步骤仍无法解决：

1. 收集以下信息：
   - 诊断命令的完整输出
   - 最近的日志文件
   - 企业微信应用的权限截图

2. 联系企业微信技术支持
   - 官方文档：https://developer.work.weixin.qq.com/
   - 开发者社区：https://developers.weixin.qq.com/community/business

---

最后更新：2024-04-11