企业微信通讯录同步服务的增量更新算法与冲突解决策略

企业微信提供全量与增量两种通讯录变更通知机制。全量同步成本高，仅适用于初始化；日常同步应基于/cgi-bin/sync/get_change_data接口拉取增量变更（包括成员、部门、标签的增删改）。然而，网络抖动、回调丢失或本地处理失败可能导致状态不一致。本文设计一套基于版本号（cursor）和时间戳的增量同步算法，并结合乐观锁与最后写入胜出（LWW）策略解决数据冲突。

1. 增量同步主流程

使用企业微信返回的next_cursor实现断点续传：

java 复制代码

package wlkankan.cn.wecom.sync;

import wlkankan.cn.wecom.client.WxApiClient;
import wlkankan.cn.wecom.model.SyncChange;
import wlkankan.cn.wecom.repo.SyncStateRepository;
import com.fasterxml.jackson.databind.JsonNode;

public class IncrementalSyncService {
    private final WxApiClient wxClient;
    private final SyncStateRepository stateRepo;
    private final UserEventHandler userHandler;
    private final DeptEventHandler deptHandler;

    public void syncOnce(String corpId) {
        String currentCursor = stateRepo.findCursorByCorp(corpId);
        JsonNode response = wxClient.getChangeData(corpId, currentCursor);

        // 处理变更项
        for (JsonNode item : response.get("items")) {
            SyncChange change = parseChange(item);
            applyChange(change);
        }

        // 更新游标（仅当全部成功）
        String nextCursor = response.get("next_cursor").asText();
        stateRepo.updateCursor(corpId, nextCursor);
    }

    private SyncChange parseChange(JsonNode item) {
        return new SyncChange(
            item.get("type").asText(),
            item.get("id").asText(),
            item.get("action").asText(),
            item.get("timestamp").asLong()
        );
    }
}

2. 本地数据模型与版本控制

为每条记录添加sync_version字段，用于冲突检测：

java 复制代码

package wlkankan.cn.wecom.entity;

import javax.persistence.*;

@Entity
@Table(name = "wx_user")
public class WxUser {
    @Id
    private String userId;

    private String name;
    private String email;
    private Long syncVersion; // 企业微信变更时间戳
    private Long localModifiedAt; // 本地修改时间

    // getters/setters
}

3. 冲突检测与解决策略

当本地修改时间晚于企业微信变更时间，视为"本地优先"；否则采用远程数据：

java 复制代码

package wlkankan.cn.wecom.handler;

import wlkankan.cn.wecom.entity.WxUser;
import wlkankan.cn.wecom.repo.WxUserRepository;
import java.util.Optional;

public class UserEventHandler {
    private final WxUserRepository userRepository;

    public void handleUpdate(SyncChange change, JsonNode userData) {
        String userId = change.getId();
        Long remoteTs = change.getTimestamp();
        Optional<WxUser> existingOpt = userRepository.findById(userId);

        if (existingOpt.isEmpty()) {
            // 新增
            WxUser user = buildUserFromJson(userData);
            user.setSyncVersion(remoteTs);
            userRepository.save(user);
            return;
        }

        WxUser local = existingOpt.get();
        Long localModifyTs = local.getLocalModifiedAt() != null ? local.getLocalModifiedAt() : 0L;

        // 冲突：本地修改时间 > 远程变更时间 → 保留本地，暂不覆盖
        if (localModifyTs > remoteTs) {
            // 可选：记录冲突日志，或触发人工审核
            logConflict(userId, localModifyTs, remoteTs);
            return;
        }

        // 无冲突或远程更新更晚：应用变更
        updateUserFromJson(local, userData);
        local.setSyncVersion(remoteTs);
        local.setLocalModifiedAt(null); // 清除本地修改标记
        userRepository.save(local);
    }

    private void logConflict(String userId, Long localTs, Long remoteTs) {
        // 写入冲突表，供后台处理
        conflictLogRepo.save(new ConflictLog(userId, localTs, remoteTs, "USER"));
    }
}

4. 本地修改标记机制

当业务系统主动修改用户信息（如HR系统更新邮箱），需标记localModifiedAt：

java 复制代码

public void updateEmailLocally(String userId, String newEmail) {
    WxUser user = userRepository.findById(userId)
        .orElseThrow(() -> new IllegalArgumentException("User not found"));

    user.setEmail(newEmail);
    user.setLocalModifiedAt(System.currentTimeMillis()); // 标记本地修改
    userRepository.save(user);
}

5. 安全回溯与补偿机制

若因异常导致游标未更新，下次同步将重复拉取部分数据。通过幂等处理避免重复：

java 复制代码

public void applyChange(SyncChange change) {
    // 检查是否已处理（基于change.id + change.timestamp）
    if (changeLogService.exists(change.getId(), change.getTimestamp())) {
        return; // 幂等跳过
    }

    switch (change.getType()) {
        case "user":
            if ("delete".equals(change.getAction())) {
                handleUserDelete(change.getId());
            } else {
                handleUserUpdate(change, fetchUserData(change.getId()));
            }
            break;
        case "dept":
            handleDeptChange(change);
            break;
    }

    // 记录已处理
    changeLogService.markProcessed(change.getId(), change.getTimestamp());
}

6. 部门树结构一致性保障

部门变更需维护父子关系完整性。删除部门前校验子部门：

java 复制代码

private void handleDeptDelete(String deptId) {
    if (deptRepository.countByParentId(deptId) > 0) {
        // 企业微信保证先删子部门，若仍有子部门，说明同步乱序
        // 暂存待重试队列
        retryQueue.offer(new RetryTask("dept", deptId, System.currentTimeMillis() + 30_000));
        return;
    }
    deptRepository.deleteById(deptId);
}

通过游标驱动的增量拉取、时间戳版本比对、本地修改标记与幂等处理，该方案在保证最终一致性的同时，有效应对网络异常、并发修改与数据冲突，适用于大规模企业微信组织架构同步场景。