# 企业微信客户同步功能说明

## 功能概述

自动从企业微信同步外部联系人（客户）信息，包括客户基本信息、跟进人等，用于患者信息匹配和自动关联。

同步流程：
1. 获取企业成员列表（从指定部门开始，递归获取所有子部门成员）
2. 遍历每个成员，获取其客户列表
3. 获取客户详情并保存到数据库
4. 自动去重，避免重复处理同一客户

## 功能特性

1. **手动同步**：点击"立即同步"按钮手动触发同步
2. **自动同步**：配置定时自动同步，支持多种时间间隔
3. **客户管理**：查看客户列表、搜索、查看详情
4. **统计信息**：显示总客户数、今日新增、最后同步时间等

## 安装步骤

### 1. 数据库迁移

执行SQL文件创建数据表：

```bash
mysql -u用户名 -p密码 数据库名 < server/database/migrations/create_qywx_external_contact.sql
```

### 2. 配置企业微信

在 `server/.env` 文件中配置企业微信信息：

```env
# 企业微信配置
WECHAT_WORK_CORP_ID=你的企业ID
WECHAT_WORK_EXTERNAL_PAY_SECRET=你的应用Secret
```

在 `server/config/project.php` 文件中配置同步部门（可选，默认为1即根部门）：

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

获取方式：
- 企业ID：企业微信管理后台 → 我的企业 → 企业信息 → 企业ID
- Secret：企业微信管理后台 → 应用管理 → 选择应用 → Secret
- 部门ID：企业微信管理后台 → 通讯录 → 选择部门 → 查看部门ID（默认根部门ID为1）

### 3. 配置权限

需要在企业微信应用中开启以下权限：
- 通讯录管理 → 成员信息读取（用于获取企业成员列表）
- 客户联系 → 客户基础信息
- 客户联系 → 客户标签
- 客户联系 → 客户联系人

注意：Secret必须是对应应用的Secret，且该应用需要有上述权限。

### 4. 配置IP白名单（重要！）

企业微信API有IP白名单限制，必须将服务器IP添加到白名单：

1. 获取服务器公网IP：`curl ifconfig.me`
2. 登录企业微信管理后台 → 应用管理 → 选择应用
3. 找到"企业可信IP"设置，添加服务器IP
4. 保存并等待几分钟生效

详细说明请查看：[QYWX_IP_WHITELIST_GUIDE.md](./QYWX_IP_WHITELIST_GUIDE.md)

### 5. 配置定时任务（可选）

如果需要自动同步，配置Linux crontab：

```bash
# 编辑crontab
crontab -e

# 添加以下行（每小时执行一次）
0 * * * * cd /path/to/your/project/server && php think qywx:sync-customer >> /dev/null 2>&1
```

或者手动强制同步（忽略自动同步设置）：
```bash
php think qywx:sync-customer --force
```

## 使用说明

### 前端页面

访问路径：`/fans/qywx`

功能：
- 查看客户列表
- 搜索客户（按名称、跟进人）
- 查看客户详情
- 手动同步
- 配置自动同步

### 同步设置

1. 点击"同步设置"按钮
2. 开启"自动同步"开关
3. 选择同步间隔（1小时、2小时、4小时、6小时、12小时、24小时）
4. 点击"保存"

### API接口

#### 1. 获取客户列表
```
GET /qywx.customer/lists
参数：
- name: 客户名称（可选）
- follow_user: 跟进人（可选）
- page: 页码
- limit: 每页数量
```

#### 2. 同步客户
```
POST /qywx.customer/sync
返回：
- sync_count: 同步数量
- new_count: 新增数量
- update_count: 更新数量
```

#### 3. 获取统计信息
```
GET /qywx.customer/stats
返回：
- total: 总客户数
- today: 今日新增
- lastSync: 最后同步时间
- syncStatus: 同步状态
```

#### 4. 获取同步设置
```
GET /qywx.customer/getSyncSettings
返回：
- auto_sync: 是否自动同步
- interval: 同步间隔（秒）
- last_sync_time: 最后同步时间
```

#### 5. 保存同步设置
```
POST /qywx.customer/saveSyncSettings
参数：
- auto_sync: 是否自动同步（boolean）
- interval: 同步间隔（秒，3600-86400）
```

## 数据表结构

### zyt_qywx_external_contact（外部联系人表）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | int | 主键ID |
| external_userid | varchar(64) | 外部联系人ID（唯一） |
| name | varchar(64) | 客户名称 |
| avatar | varchar(255) | 头像URL |
| type | tinyint | 类型：1=微信用户，2=企业微信用户 |
| gender | tinyint | 性别：0=未知，1=男，2=女 |
| unionid | varchar(64) | 微信unionid |
| position | varchar(64) | 职位 |
| corp_name | varchar(128) | 企业名称 |
| corp_full_name | varchar(255) | 企业全称 |
| external_profile | text | 扩展信息JSON |
| follow_users | text | 跟进人列表JSON |
| create_time | int | 添加时间 |
| update_time | int | 更新时间 |
| delete_time | int | 删除时间 |

### zyt_qywx_sync_settings（同步设置表）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | int | 主键ID |
| setting_key | varchar(64) | 设置键（唯一） |
| setting_value | text | 设置值JSON |
| create_time | int | 创建时间 |
| update_time | int | 更新时间 |

## 注意事项

1. **API调用限制**：企业微信API有调用频率限制，建议同步间隔不要太短
2. **Secret安全**：请妥善保管企业微信Secret，不要泄露
3. **权限配置**：确保应用有足够的权限访问客户信息
4. **错误处理**：同步失败会记录日志，可在系统日志中查看详细错误信息
5. **数据更新**：同步会更新已存在的客户信息，不会删除已有数据

## 故障排查

### 1. 错误码 60020 - IP白名单限制

错误信息：`not allow to access from your ip`

解决方法：
- 将服务器IP添加到企业微信应用的"企业可信IP"白名单
- 详细说明：[QYWX_IP_WHITELIST_GUIDE.md](./QYWX_IP_WHITELIST_GUIDE.md)

### 2. 同步失败

检查：
- 企业微信配置是否正确（corp_id、secret）
- 应用权限是否开启
- IP是否在白名单中（最常见问题）
- 网络是否正常
- 查看系统日志：`server/runtime/log/`

### 3. 获取不到客户

检查：
- 应用是否有客户联系权限和通讯录读取权限
- 是否有外部联系人
- Secret是否正确（需要使用对应应用的Secret）
- 企业成员是否有添加客户
- 部门ID配置是否正确（默认1为根部门）

### 4. missing field `userid` 错误

这个错误已修复。新版本会先获取企业成员列表，然后遍历每个成员获取其客户。如果仍然出现此错误，请检查：
- 应用是否有"通讯录管理-成员信息读取"权限
- 配置的Secret是否正确

### 5. 定时任务不执行

检查：
- crontab是否配置正确
- PHP路径是否正确
- 项目路径是否正确
- 是否开启了自动同步

## 参考文档

- [企业微信API文档](https://developer.work.weixin.qq.com/document/)
- [获取部门成员](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)