虚拟通讯录数据增量同步接入

1 接入流程说明

1.1 配置流程

1. 对接方提供虚拟通讯录数据接收接口（支持 Basic 认证）
2. 在 UAA 管理端配置应用信息及推送地址
3. 将应用授权给对应虚拟通讯录（通讯录关联应用）
4. 虚拟通讯录下的节点新增/修改/删除时，UAA 自动向已配置的接口推送数据

1.2 数据推送流程

虚拟通讯录节点变更（新增/修改/删除）
    ↓
UAA 按通讯录关联的应用列表查找推送配置
    ↓
对每个已配置 PUSH_TYPE_VIRTUAL_ORG 的应用
    ↓
HTTP POST 至对接方提供的接收接口

说明 ：仅当应用已关联该虚拟通讯录、且已配置虚拟组织推送时，才会收到推送。

---

2 开始接入

2.1 对接方准备工作

1. 提供接收虚拟通讯录数据推送接口 ：
   • 请求方式：POST
   • 认证方式：Basic 认证
   • 提供 Basic 认证的用户名和密码
   • 消息体：request body，Content-Type 为 application/json
2. 填写应用信息，并在 UAA 管理端完成：
   • 应用注册
   • 推送配置（推送类型选择「虚拟组织」）
   • 虚拟通讯录与应用关联

2.2 与组织/用户推送的区别

维度	组织推送	用户推送	虚拟通讯录推送
数据来源	uaa_org（真实组织）	用户账户	uaa_virtual_org（虚拟组织节点）
推送配置类型	ORG	ACCOUNT	VIRTUAL_ORG
关联方式	应用-组织授权	应用-组织授权	通讯录-应用关联
接收接口	组织同步接口	账户同步接口	虚拟组织同步接口（独立）

---

3 推送数据结构

说明 ：虚拟组织相关的数据推送需写到专门的接收接口中，虚拟通讯录节点新增/修改/删除时会向已关联且已配置推送的应用推送。

3.1 虚拟组织新增、修改

{
  "event": "add_update",
  "data": {
    "orgId": "19225462452373831690246943335",
    "displayName": "海南省",
    "addressBookId": "19175158246038364188738020442",
    "parentOrgId": "0",
    "realOrgId": "1495910062532149250",
    "nodeType": "AREA",
    "enable": true,
    "sortNum": 2,
    "fullNamePath": "-/海南省",
    "parentIdPath": "0,19225462452373831690246943335",
    "leaf": false,
    "remark": "",
    "createTime": "2024-01-01 00:00:00",
    "updateTime": "2024-01-01 00:00:00"
  }
}

字段说明 ：

字段	类型	说明
event	String	固定为 add_update，表示新增或修改
data	Object	虚拟组织节点数据
data.orgId	String	节点 ID
data.displayName	String	显示名称（通讯录中展示的名称）
data.addressBookId	String	所属通讯录 ID
data.parentOrgId	String	父节点 ID，根节点为 “0”
data.realOrgId	String	关联的真实组织 ID
data.nodeType	String	节点类型：AREA-行政区划节点；LINE-条线节点
data.enable	Boolean	是否启用
data.sortNum	Integer	排序
data.fullNamePath	String	全路径名称，如 “-/海南省/xx部门”
data.parentIdPath	String	父节点 ID 路径，逗号分隔
data.leaf	Boolean	是否叶子节点
data.remark	String	备注
data.createTime	String	创建时间，格式 yyyy-MM-dd HH:mm:ss
data.updateTime	String	更新时间，格式 yyyy-MM-dd HH:mm:ss

3.2 虚拟组织删除

{
  "event": "delete",
  "data": {
    "orgId": "19225462452373831690246943335",
    "addressBookId": "19175158246038364188738020442"
  }
}

字段说明 ：

字段	类型	说明
event	String	固定为 delete，表示删除
data.orgId	String	被删除的节点 ID
data.addressBookId	String	所属通讯录 ID

说明 ：删除为级联删除，子节点会一并删除，UAA 会按删除顺序推送（先子后父），对接方可按需处理。

---

4 代码样例

4.1 curl 结构样例

curl --location --request POST 'https://对接方接口地址' \
--header 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
--header 'Content-Type: application/json' \
-d '{
  "event": "add_update",
  "data": {
    "orgId": "19225462452373831690246943335",
    "displayName": "海南省",
    "addressBookId": "19175158246038364188738020442",
    "parentOrgId": "0",
    "realOrgId": "1495910062532149250",
    "nodeType": "AREA",
    "enable": true,
    "sortNum": 2,
    "fullNamePath": "-/海南省",
    "parentIdPath": "0,19225462452373831690246943335",
    "leaf": false,
    "remark": "",
    "createTime": "2024-01-01 00:00:00",
    "updateTime": "2024-01-01 00:00:00"
  }
}'

4.2 对接方接收数据样例

/**
 * 接收虚拟通讯录数据推送
 * ReceiveVirtualOrg 根据 UAA 推送的 JSON 格式定义
 */
@PostMapping("receive/virtual-org")
public BaseResponse receiveVirtualOrg(@RequestBody ReceiveVirtualOrg receiveVirtualOrg) {
    String event = receiveVirtualOrg.getEvent();
    if ("add_update".equals(event)) {
        // 新增或修改：落库/更新本地虚拟组织树
        VirtualOrgData data = receiveVirtualOrg.getData();
        // ... 业务处理
    } else if ("delete".equals(event)) {
        // 删除：从本地移除（data 仅含 orgId、addressBookId）
        VirtualOrgData data = receiveVirtualOrg.getData();
        // ... 业务处理
    }
    return BaseResponse.success();
}

// 请求体 DTO 示例（add_update 与 delete 共用，delete 时 data 仅含 orgId、addressBookId）
@Data
public class ReceiveVirtualOrg {
    private String event;  // "add_update" 或 "delete"
    private VirtualOrgData data;
}

@Data
public class VirtualOrgData {
    private String orgId;           // 节点 ID（add_update/delete 均有）
    private String addressBookId;    // 通讯录 ID（add_update/delete 均有）
    private String displayName;     // add_update 时有值
    private String parentOrgId;
    private String realOrgId;
    private String nodeType;
    private Boolean enable;
    private Integer sortNum;
    private String fullNamePath;
    private String parentIdPath;
    private Boolean leaf;
    private String remark;
    private String createTime;
    private String updateTime;
}

4.3 统一响应结构

{
  "success": true,
  "message": null
}

字段	类型	说明
success	Boolean	true 表示处理成功，false 表示失败
message	String	失败时的提示信息，成功可为 null

说明 ：UAA 以该结构判断推送是否成功，若 success 为 false 或接口异常，可能触发重试。

---

5 注意事项

1. 接口幂等 ：同一条数据可能因重试被多次推送，对接方需保证幂等处理。
2. Basic 认证 ：用户名密码需与 UAA 管理端配置一致，UAA 会在请求头中携带 Authorization: Basic xxx。
3. 虚拟组织与真实组织 ：两者为不同数据源，虚拟组织的 realOrgId 指向真实组织，对接方可据此做关联。
4. 全量初始化 ：若需全量同步，请联系 UAA 侧提供虚拟通讯录导出或全量查询接口，增量推送仅覆盖变更数据。