7.0 KiB
7.0 KiB
企业微信客户同步功能说明
功能概述
自动从企业微信同步外部联系人（客户）信息，包括客户基本信息、跟进人等，用于患者信息匹配和自动关联。
同步流程：
- 获取企业成员列表（从指定部门开始，递归获取所有子部门成员）
- 遍历每个成员，获取其客户列表
- 获取客户详情并保存到数据库
- 自动去重，避免重复处理同一客户
功能特性
- 手动同步：点击"立即同步"按钮手动触发同步
- 自动同步：配置定时自动同步，支持多种时间间隔
- 客户管理：查看客户列表、搜索、查看详情
- 统计信息：显示总客户数、今日新增、最后同步时间等
安装步骤
1. 数据库迁移
执行SQL文件创建数据表：
mysql -u用户名 -p密码 数据库名 < server/database/migrations/create_qywx_external_contact.sql
2. 配置企业微信
在 server/.env 文件中配置企业微信信息：
# 企业微信配置
WECHAT_WORK_CORP_ID=你的企业ID
WECHAT_WORK_EXTERNAL_PAY_SECRET=你的应用Secret
在 server/config/project.php 文件中配置同步部门（可选，默认为1即根部门）：
// 企业微信客户同步配置
// 从哪个部门开始同步（1=根部门，会递归获取所有子部门成员）
'qywx_sync_department_id' => 1,
获取方式：
- 企业ID：企业微信管理后台 → 我的企业 → 企业信息 → 企业ID
- Secret：企业微信管理后台 → 应用管理 → 选择应用 → Secret
- 部门ID：企业微信管理后台 → 通讯录 → 选择部门 → 查看部门ID（默认根部门ID为1）
3. 配置权限
需要在企业微信应用中开启以下权限：
- 通讯录管理 → 成员信息读取（用于获取企业成员列表）
- 客户联系 → 客户基础信息
- 客户联系 → 客户标签
- 客户联系 → 客户联系人
注意：Secret必须是对应应用的Secret，且该应用需要有上述权限。
4. 配置IP白名单（重要！）
企业微信API有IP白名单限制，必须将服务器IP添加到白名单：
- 获取服务器公网IP：
curl ifconfig.me - 登录企业微信管理后台 → 应用管理 → 选择应用
- 找到"企业可信IP"设置，添加服务器IP
- 保存并等待几分钟生效
详细说明请查看：QYWX_IP_WHITELIST_GUIDE.md
5. 配置定时任务（可选）
如果需要自动同步，配置Linux crontab：
# 编辑crontab
crontab -e
# 添加以下行（每小时执行一次）
0 * * * * cd /path/to/your/project/server && php think qywx:sync-customer >> /dev/null 2>&1
或者手动强制同步（忽略自动同步设置）：
php think qywx:sync-customer --force
使用说明
前端页面
访问路径：/fans/qywx
功能：
- 查看客户列表
- 搜索客户（按名称、跟进人）
- 查看客户详情
- 手动同步
- 配置自动同步
同步设置
- 点击"同步设置"按钮
- 开启"自动同步"开关
- 选择同步间隔（1小时、2小时、4小时、6小时、12小时、24小时）
- 点击"保存"
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 | 更新时间 |
注意事项
- API调用限制：企业微信API有调用频率限制，建议同步间隔不要太短
- Secret安全：请妥善保管企业微信Secret，不要泄露
- 权限配置：确保应用有足够的权限访问客户信息
- 错误处理：同步失败会记录日志，可在系统日志中查看详细错误信息
- 数据更新：同步会更新已存在的客户信息，不会删除已有数据
故障排查
1. 错误码 60020 - IP白名单限制
错误信息：not allow to access from your ip
解决方法：
- 将服务器IP添加到企业微信应用的"企业可信IP"白名单
- 详细说明：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路径是否正确
- 项目路径是否正确
- 是否开启了自动同步