目录

• 一、产品模块设计：四大 Tab 完成账号与消息任务闭环
  • 1. 账号托管模块（iPad 协议核心前置）
  • 2. 新建消息任务表单逻辑
  • 3. 会话 SOP 业务逻辑
  • 4. 执行日志、回执与失败重试
• 二、技术架构：iPad 协议长连接网关 + SpringBoot 任务调度
  • 核心后端代码片段
• 三、生产环境边界与风控避坑（重点）
• 四、完整落地开发清单
• 五、开发总结

摘要

企业微信官方开放 API 存在事件回调延迟、部分原生能力缺失、回执信息不全等痛点。本文基于生产运行的私域 SCRM 中台，讲解基于iPad 协议结合 SpringBoot+Vue 实现多账号托管、消息触达中台。实现账号会话保活、行为随机化频率控制、一次性任务、会话 SOP、消息回执、断线续跑。重点拆解产品模块、长连接架构、风控行为模拟、线上踩坑边界，适合做企微私有化 SCRM、私域自动化后台开发参考。
标签：企业微信，iPad 协议，SpringBoot,SCRM, 私域中台，消息 SOP, 多账号托管

背景：做私域 SCRM 开发，很多同学一开始直接基于企业微信官方开放 API 开发。上线后会遇到几个棘手现实问题：消息回调延迟十几秒，拿不到消息已读回执，无法捕捉撤回、好友被删除等事件；官方群发有额度约束，很多客户端原生操作没有开放接口。

iPad 协议模拟企业微信 iPad 客户端长连接通信，补齐官方 API 缺失的客户端能力，但同时带来账号保活、行为风控、协议版本迭代维护的难题。我们在自研 SCRM 中台内部实现了这套消息调度模块，统一管理多机器人账号、消息任务调度、会话 SOP、失败重试。下面分享产品设计、架构代码、生产环境真实踩坑经验。

一、产品模块设计：四大 Tab 完成账号与消息任务闭环

统一功能入口叫SCRM 消息中台，前端路由/scrm/messageCenter，一共 4 个 Tab，区分账号管理、一次性触达任务、会话 SOP 计划、执行与会话日志。不接入未完成的高级批量模块，避免演示夸大功能。

Tab 页面	前端组件	业务作用
账号托管管理	RobotAccountTab.vue	iPad 协议账号扫码登录、在线状态监控、代理配置、下线重连、设备指纹配置
一次性消息任务	OnceTaskTab.vue	临时活动触达，新建任务、任务详情、失败记录、手动重试
会话 SOP 计划	SessionSopTab.vue	客户生命周期 SOP：新客欢迎、定时回访、周期关怀；支持启用、暂停、修改规则
会话执行日志	SessionLogTab.vue	汇总一次性任务、SOP 全部执行记录；会话事件（撤回、删除好友、进群事件）统一在这里回显

1. 账号托管模块（iPad 协议核心前置）

所有消息任务必须选择已经在线的 iPad 协议机器人账号。账号列表展示：账号昵称、uuid、在线状态、设备指纹版本、代理 IP、最后心跳时间。

• 扫码登录：前端获取二维码，提交后端发起协议初始化；后端完成握手、设备指纹上报、心跳任务注册；

• 断线自动重连：检测长连接断开，按退避策略重试登录，不会无限循环重连；

• 设备指纹：支持配置模拟 iPad 硬件参数 DPI、系统版本、TLS 指纹；生产环境禁止全部账号共用同一套指纹，避免批量风控；

注意：iPad 协议底层依赖长连接会话；服务器网络抖动、企微客户端版本更新都可能导致账号掉线，离线账号不能下发任何消息任务。

2. 新建消息任务表单逻辑

任务表单机器人账号必选，账号离线时选人区域置灰提示「当前机器人已离线，请更换在线账号」。

发送对象支持外部群聊、客户好友：

1. 外部群聊：筛选群主 / 管理员 / 普通成员；区分内部群、外部客户群，读取协议拉取的实时群成员列表；

2. 客户好友：支持标签筛选、新增时间范围筛选；联系人数据来自协议实时同步本地联系人缓存，账号掉线缓存会清空。

消息类型支持全类型：文本、表情、图片、文件、小程序、名片、视频消息；单次任务支持多消息序列发送（区别官方 API），可以实现 “文本 + 图片” 连续多条消息。

调度与风控行为配置（重点）：

• 任务类型：立即发送、定点定时、周期会话 SOP；

• 发送间隔：区间 30‑300 秒，支持随机抖动，基础间隔默认 90 秒，增加 ±20s 随机偏移，避免固定 sleep 带来的机器化行为特征；页面提示风控建议：建议基础间隔不低于 90 秒；

• 单批次最大数量：每发送 N 个对象，插入一段休眠，避免短时间大量操作；

• 结束时间：到达截止时间，任务直接终止，记录断点下标；

• 行为模拟开关：开启后，消息之间插入随机阅读等待，模拟人工操作；

• 自动重试：默认关闭；失败仅重试 1 次，不会无限重试。

一次性任务底部按钮「立即执行」；周期 SOP 任务按钮为「保存 SOP 规则」。

3. 会话 SOP 业务逻辑

会话 SOP 和一次性消息任务复用任务提交接口，通过taskCategory字段区分：普通任务normal，会话周期 SOPsop_session。
SOP 支持按天 / 周 / 月执行，也支持入群触发、新增好友触发的事件型 SOP。

操作区分两种场景：

1. SOP 计划处于暂停状态：点击执行，走断点续跑，从上次中断下标继续发送；

2. SOP 处于运行状态：手动执行，生成独立执行记录，任务名称追加(手动触发)，全新一轮消息推送。

⚠️演示环境不要对暂停状态 SOP 点击执行，会真实调用 iPad 协议下发消息。

4. 执行日志、回执与失败重试

日志页面展示：总数量、成功数、失败数；并且展示 iPad 协议返回的msgId 消息回执，可以确认消息是否投递到达。
只有failCount>0，手动重试按钮激活；失败记录落库，记录错误码、错误描述（会话失效、风控限流、对方已删除等）。
协议推送的会话事件（消息撤回、被客户删除、成员进群退群）也统一写入会话日志，工作台可以读取展示完整会话轨迹。

二、技术架构：iPad 协议长连接网关 + SpringBoot 任务调度

下面是消息任务从提交到下发的完整时序流程：

核心思路：iPad 协议服务对外输出 HTTP/WebSocket 接口；SpringBoot 业务层不直接处理底层二进制 TLV 协议帧，调用协议网关完成消息下发；业务层负责任务入库、频率抖动计算、调度、断点续跑、失败记录。
整体流程：Vue 提交任务 → SpringBoot 任务落库 → 调度器接管任务 → 遍历接收人 vid，计算带随机抖动的 sleep 时间 → HTTP 调用 iPad 协议网关下发消息 → 获取 msgId 回执；保存发送结果、失败记录；WebSocket 接收协议推送的会话事件落库。

核心后端代码片段

接收前端任务接口：

@PostMapping("/scrm/message/submitTask")
public AjaxResult createScrmTask(@RequestBody Map<String,Object> params){
    ScrmMassTask task = scrmMessageService.saveScrmTask(params);
    return AjaxResult.success(task);
}

间隔处理：基础间隔加上随机抖动，规避固定间隔被风控识别。

//基础间隔
Integer baseSec = params.get("frequency")!=null
        ? Integer.parseInt(params.get("frequency").toString())
        :90;
//增加±20秒随机抖动
int randomOffset = new Random().nextInt(41)-20;
int realSleepSec = Math.max(30,baseSec + randomOffset);

//过滤机器人自己vid，避免给自己发消息
List<String> targetVids = filterRobotSelfVid(params.get("robotUuid"),params.get("vids"));

boolean isSessionSop = "sop_session".equals(params.get("taskCategory"));
if(isSessionSop){
    task.setTaskStatus("periodic_active");
}else{
    scrmTaskDispatcher.dispatchTask(task);
    task.setTaskStatus("waiting");
}

周期 SOP 定时扫描：

//每分钟扫描全部启用状态会话SOP
@Scheduled(cron = "0 * * * * ?")
public void scanSessionSopTask(){
    scrmMessageService.checkAndRunSessionSop();
}

消息发送循环，断点续跑、随机休眠、截止时间判断：

//从断点下标resumeIndex开始遍历
for(int i=resumeIndex;i<vidList.size();i++){
    if(i>0){
        //带随机抖动休眠
        Thread.sleep(realSleepSec *1000L);
    }
    //调用iPad协议网关发送消息
    JSONObject resp = ipadGatewayUtil.sendMsg(robotUuid,vidList.get(i),isRoom,msgSequence);
    String msgId = resp.getString("msgId");
    String errcode = resp.getString("errcode");
    if("0".equals(errcode)){
        saveSuccessRecord(taskId,vidList.get(i),msgSequence,msgId);
    }else{
        saveFailRecord(taskId,vidList.get(i),resp);
        //开启自动重试，重试一次
        if(task.getAutoRetry()){
            ipadGatewayUtil.sendMsg(robotUuid,vidList.get(i),isRoom,msgSequence);
        }
    }
    //到达结束时间直接终止任务，保存断点
    if(LocalDateTime.now().isAfter(task.getEndTime())){
        task.setResumeFromIndex(i);
        taskMapper.updateById(task);
        break;
    }
}

补充说明：iPad 协议网关层负责底层 TCP 长连接、TLV 二进制帧封装、ECDH 密钥协商、心跳保活；业务 SpringBoot 层不触碰底层协议，只调用网关输出的 HTTP 接口。
图片视频文件：前端限制图片 10MB，视频 20MB；发送前调用协议网关 CDN 上传接口拿到 mediaId 再下发消息。
WebSocket 监听网关推送事件：解析撤回、删除好友、进群退群事件，存入会话日志表。

三、生产环境边界与风控避坑（重点）

iPad 协议属于模拟客户端行为，和官方开放 API 有本质区别，开发阶段必须梳理清楚能力边界，避免售前预期和实际能力不符。

✅系统可实现能力：

1. 多账号 iPad 协议托管、扫码登录、断线退避重连、设备指纹管理；

2. 一次性消息任务、周期 SOP、事件触发 SOP，支持断点续跑；

3. 支持文本、表情、图片、文件、小程序、视频，支持多消息序列发送；

4. 发送间隔支持随机抖动模拟人工行为，任务超时终止；

5. 获取 msgId 消息投递回执；捕获撤回、被删好友、群成员变更事件；

6. 失败落库，手动重试；会话事件统一日志；结果写入 Redis 工作台展示。

❌明确不具备 & 风险点：

1. iPad 协议非官方开放 API，属于模拟 iPad 客户端通信；企微客户端版本更新，底层 TLV 协议帧可能变动，需要持续维护协议网关；存在账号限流、封禁风险，业务需要自行评估风险。

2. 虽然支持间隔配置，业务层不能完全保证账号不触发风控；随机抖动只是降低被识别概率，不能杜绝风控。

3. 设备指纹不能多账号复用同一套硬件参数，大量账号共用指纹极易批量下线。

4. 长连接网络抖动、服务器 IP 变更会造成账号会话失效掉线；掉线中任务会暂停，等待重连之后才可以续跑。

5. 没有全局限流面板；每个任务独立线程，大批量并发任务会占用线程资源，业务层需要自己做任务并发数控制。

6. 联系人、群聊列表依赖协议同步缓存；账号掉线之后缓存清空，无法选择接收对象。

7. 事件型 SOP（新增好友、入群触发）依赖 WebSocket 事件推送，如果网络断连会丢失部分事件。

8. 不直接对接企业微信官方群发额度；消息以客户端私聊 / 群聊形式发出，手机端显示和真人发送消息样式一致。

四、完整落地开发清单

1. 前端搭建 SCRM 消息中台 4 个 Tab 页面；账号托管页面管理 iPad 协议账号扫码登录、在线状态、设备指纹；离线账号禁止新建消息任务。

2. 接口/scrm/message/submitTask接收参数，任务落库；普通任务交给调度器；周期 SOP 标记状态，交给每分钟定时扫描。

3. 发送间隔增加随机抖动逻辑，禁止固定 sleep；循环中保存断点下标，支持暂停恢复续跑；到达结束时间终止任务。

4. SpringBoot 业务层只调用 iPad 协议网关 HTTP 接口，不实现底层二进制协议；图片视频调用网关 CDN 上传接口。

5. 发送前过滤机器人自身 vid；成功记录保存协议返回 msgId 回执，写入 Redis 给客服工作台读取。

6. 失败消息落库；手动重试按钮由失败条数控制；自动重试只执行一次，禁止无限重试。

7. WebSocket 消费协议网关推送的会话事件，解析撤回、删好友、群变更事件，存入会话日志。

8. SOP 区分断点续跑、手动执行两套逻辑；演示环境禁止对暂停 SOP 直接点执行按钮。

9. 账号断线重连实现指数退避策略；禁止无限循环重连；多账号隔离设备指纹参数。

五、开发总结

很多开发者误以为 iPad 协议就是 “万能接口”，拿到接口就可以无限制批量发消息。真正做生产 SCRM 中台会发现，难点不在于调用协议发送消息，而在于账号托管保活、行为风控模拟、任务调度断点续跑、会话事件消费整套业务闭环。

官方 API 和 iPad 协议各有取舍：官方 API 稳定、维护成本低，但部分原生能力缺失；iPad 协议补齐客户端能力，但是会带来协议迭代维护、账号风控风险。实际项目需要结合业务场景做选型。

如果你正在做企微私有化 SCRM 开发，欢迎评论区交流你的业务场景：账号规模、触达客户量级，SOP 类型，以及风控踩过哪些坑。