新增
This commit is contained in:
Your Name
@@ -0,0 +1,246 @@
|
||||
# 企业微信客户同步功能说明
|
||||
|
||||
## 功能概述
|
||||
|
||||
自动从企业微信同步外部联系人（客户）信息，包括客户基本信息、跟进人等，用于患者信息匹配和自动关联。
|
||||
|
||||
同步流程：
|
||||
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)
|
||||
Reference in New Issue
Block a user