247 lines
7.0 KiB
Markdown
247 lines
7.0 KiB
Markdown
# 企业微信客户同步功能说明
|
||
|
||
## 功能概述
|
||
|
||
自动从企业微信同步外部联系人（客户）信息，包括客户基本信息、跟进人等，用于患者信息匹配和自动关联。
|
||
|
||
同步流程：
|
||
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)
|