#1078 完善企业微信外部联系人相关接口

- 完成ExternalContact基础三个接口
- 外部联系人变更事件的消息解析
- 外部联系人的属性，增加标记公司名称和标记电话号码，还有tag分类
- 企业微信API url修改优化

weixin-java-cp/src/main/java/me/chanjar/weixin/cp/api/WxCpExternalContactService.java

@@ -0,0 +1,58 @@
+package me.chanjar.weixin.cp.api;
+
+import me.chanjar.weixin.common.error.WxErrorException;
+import me.chanjar.weixin.cp.bean.WxCpUserExternalContactInfo;
+
+import java.util.List;
+
+/**
+ * <pre>
+ * 外部联系人管理接口，企业微信的外部联系人的接口和通讯录接口已经拆离
+ *  Created by Joe Cao on 2019/6/14
+ * </pre>
+ *
+ * @author <a href="https://github.com/JoeCao">JoeCao</a>
+ */
+public interface WxCpExternalContactService {
+  /**
+   * 获取外部联系人详情.
+   * <pre>
+   *   企业可通过此接口，根据外部联系人的userid，拉取外部联系人详情。权限说明：
+   * 企业需要使用外部联系人管理secret所获取的accesstoken来调用
+   * 第三方应用需拥有“企业客户”权限。
+   * 第三方应用调用时，返回的跟进人follow_user仅包含应用可见范围之内的成员。
+   * </pre>
+   *
+   * @param userId 外部联系人的userid
+   */
+  WxCpUserExternalContactInfo getExternalContact(String userId) throws WxErrorException;
+
+  /**
+   * 获取外部联系人列表.
+   * <pre>
+   *   企业可通过此接口获取指定成员添加的客户列表。
+   *   客户是指配置了客户联系功能的成员所添加的外部联系人。
+   *   没有配置客户联系功能的成员，所添加的外部联系人将不会作为客户返回。
+   * 第三方应用需拥有“企业客户”权限。
+   * 第三方应用调用时，返回的跟进人follow_user仅包含应用可见范围之内的成员。
+   * </pre>
+   *
+   * @param userId 外部联系人的userid
+   * @return List of External wx id
+   */
+  List<String> listExternalContacts(String userId) throws WxErrorException;
+
+
+  /**
+   * 企业和第三方服务商可通过此接口获取配置了客户联系功能的成员(Customer Contact)列表。
+   * <pre>
+   *   企业需要使用外部联系人管理secret所获取的accesstoken来调用（accesstoken如何获取？）；
+   *   第三方应用需拥有“企业客户”权限。
+   *   第三方应用只能获取到可见范围内的配置了客户联系功能的成员
+   * </pre>
+   *
+   * @return List of CpUser id
+   */
+  List<String> listFollowUser() throws WxErrorException;
+
+}

weixin-java-cp/src/main/java/me/chanjar/weixin/cp/api/WxCpService.java

@@ -284,7 +284,9 @@ public interface WxCpService {
    * 获取用户相关接口的服务类对象
    */
   WxCpUserService getUserService();
-  
+
+  WxCpExternalContactService getExternalContactService();
+
   /**
    * 获取群聊服务
    * 

weixin-java-cp/src/main/java/me/chanjar/weixin/cp/api/WxCpUserService.java

@@ -149,4 +149,6 @@ public interface WxCpUserService {
    * @param userId 外部联系人的userid
    */
   WxCpUserExternalContactInfo getExternalContact(String userId) throws WxErrorException;
+
+
 }

weixin-java-cp/src/main/java/me/chanjar/weixin/cp/api/impl/BaseWxCpServiceImpl.java

@@ -19,17 +19,7 @@ import me.chanjar.weixin.common.util.http.RequestExecutor;
 import me.chanjar.weixin.common.util.http.RequestHttp;
 import me.chanjar.weixin.common.util.http.SimpleGetRequestExecutor;
 import me.chanjar.weixin.common.util.http.SimplePostRequestExecutor;
-import me.chanjar.weixin.cp.api.WxCpAgentService;
-import me.chanjar.weixin.cp.api.WxCpChatService;
-import me.chanjar.weixin.cp.api.WxCpDepartmentService;
-import me.chanjar.weixin.cp.api.WxCpMediaService;
-import me.chanjar.weixin.cp.api.WxCpMenuService;
-import me.chanjar.weixin.cp.api.WxCpOAuth2Service;
-import me.chanjar.weixin.cp.api.WxCpOaService;
-import me.chanjar.weixin.cp.api.WxCpService;
-import me.chanjar.weixin.cp.api.WxCpTagService;
-import me.chanjar.weixin.cp.api.WxCpTaskCardService;
-import me.chanjar.weixin.cp.api.WxCpUserService;
+import me.chanjar.weixin.cp.api.*;
 import me.chanjar.weixin.cp.bean.WxCpMaJsCode2SessionResult;
 import me.chanjar.weixin.cp.bean.WxCpMessage;
 import me.chanjar.weixin.cp.bean.WxCpMessageSendResult;
@@ -60,6 +50,7 @@ public abstract class BaseWxCpServiceImpl<H, P> implements WxCpService, RequestH
   private WxCpAgentService      agentService      = new WxCpAgentServiceImpl(this);
   private WxCpOaService         oaService         = new WxCpOaServiceImpl(this);
   private WxCpTaskCardService   taskCardService   = new WxCpTaskCardServiceImpl(this);
+  private WxCpExternalContactService externalContactService = new WxCpExternalContactServiceImpl(this);
 
   /**
    * 全局的是否正在刷新access token的锁
@@ -396,6 +387,11 @@ public abstract class BaseWxCpServiceImpl<H, P> implements WxCpService, RequestH
     return userService;
   }
 
+  @Override
+  public WxCpExternalContactService getExternalContactService() {
+    return externalContactService;
+  }
+
   @Override
   public WxCpChatService getChatService() {
     return chatService;

weixin-java-cp/src/main/java/me/chanjar/weixin/cp/api/impl/WxCpExternalContactServiceImpl.java

@@ -0,0 +1,41 @@
+package me.chanjar.weixin.cp.api.impl;
+
+import me.chanjar.weixin.common.error.WxErrorException;
+import me.chanjar.weixin.cp.api.WxCpExternalContactService;
+import me.chanjar.weixin.cp.api.WxCpService;
+import me.chanjar.weixin.cp.bean.WxCpUserExternalContactInfo;
+import me.chanjar.weixin.cp.bean.WxCpUserExternalContactList;
+import me.chanjar.weixin.cp.bean.WxCpUserWithExternalPermission;
+
+import java.util.List;
+
+import static me.chanjar.weixin.cp.constant.WxCpApiPathConsts.ExternalContact.*;
+
+public class WxCpExternalContactServiceImpl implements WxCpExternalContactService {
+  private WxCpService mainService;
+
+  public WxCpExternalContactServiceImpl(WxCpService mainService) {
+    this.mainService = mainService;
+  }
+
+  @Override
+  public WxCpUserExternalContactInfo getExternalContact(String userId) throws WxErrorException {
+    String responseContent = this.mainService.get(this.mainService.getWxCpConfigStorage().getApiUrl(GET_EXTERNAL_CONTACT + userId), null);
+
+    return WxCpUserExternalContactInfo.fromJson(responseContent);
+  }
+
+  @Override
+  public List<String> listExternalContacts(String userId) throws WxErrorException {
+    String responseContent = this.mainService.get(this.mainService.getWxCpConfigStorage().getApiUrl(LIST_EXTERNAL_CONTACT + userId), null);
+    WxCpUserExternalContactList list = WxCpUserExternalContactList.fromJson(responseContent);
+    return list.getExternalUserId();
+  }
+
+  @Override
+  public List<String> listFollowUser() throws WxErrorException {
+    String responseContent = this.mainService.get(this.mainService.getWxCpConfigStorage().getApiUrl(GET_FOLLOW_USER_LIST), null);
+    WxCpUserWithExternalPermission list = WxCpUserWithExternalPermission.fromJson(responseContent);
+    return list.getFollowUser();
+  }
+}

weixin-java-cp/src/main/java/me/chanjar/weixin/cp/bean/WxCpUserExternalContactInfo.java

@@ -1,16 +1,11 @@
 package me.chanjar.weixin.cp.bean;
 
-import java.util.List;
-
 import com.google.gson.annotations.SerializedName;
-import lombok.AllArgsConstructor;
-import lombok.Builder;
-import lombok.Data;
-import lombok.Getter;
-import lombok.NoArgsConstructor;
-import lombok.Setter;
+import lombok.*;
 import me.chanjar.weixin.cp.util.json.WxCpGsonBuilder;
 
+import java.util.List;
+
 /**
  * <pre>
  * 外部联系人详情
@@ -118,9 +113,26 @@ public class WxCpUserExternalContactInfo {
     private String description;
     @SerializedName("createtime")
     private Long createTime;
+    private String state;
+    @SerializedName("remark_company")
+    private String remarkCompany;
+    @SerializedName("remark_mobiles")
+    private String[] remarkMobiles;
+    private Tag[] tags;
+
   }
 
   public static WxCpUserExternalContactInfo fromJson(String json) {
     return WxCpGsonBuilder.create().fromJson(json, WxCpUserExternalContactInfo.class);
   }
+
+  @Setter
+  @Getter
+  public static class Tag {
+    @SerializedName("group_name")
+    private String groupName;
+    @SerializedName("tag_name")
+    private String tagName;
+    private int type;
+  }
 }

weixin-java-cp/src/main/java/me/chanjar/weixin/cp/bean/WxCpUserExternalContactList.java

@@ -0,0 +1,58 @@
+package me.chanjar.weixin.cp.bean;
+
+import com.google.gson.annotations.Expose;
+import com.google.gson.annotations.SerializedName;
+import me.chanjar.weixin.cp.util.json.WxCpGsonBuilder;
+
+import java.util.List;
+
+/**
+ * <pre>
+ * 外部联系人列表
+ * Created by Joe Cao on 2019/6/16.
+ * 参考文档：https://work.weixin.qq.com/api/doc#90001/90143/91570
+ * </pre>
+ *
+ * @author <a href="https://github.com/JoeCao">Joe Cao</a>
+ */
+public class WxCpUserExternalContactList {
+  @SerializedName("errcode")
+  @Expose
+  private Long errcode;
+  @SerializedName("errmsg")
+  @Expose
+  private String errmsg;
+
+  @SerializedName("external_userid")
+  @Expose
+  private List<String> externalUserId = null;
+
+  public Long getErrcode() {
+    return errcode;
+  }
+
+  public void setErrcode(Long errcode) {
+    this.errcode = errcode;
+  }
+
+  public String getErrmsg() {
+    return errmsg;
+  }
+
+  public void setErrmsg(String errmsg) {
+    this.errmsg = errmsg;
+  }
+
+
+  public List<String> getExternalUserId() {
+    return externalUserId;
+  }
+
+  public void setExternalUserId(List<String> externalUserId) {
+    this.externalUserId = externalUserId;
+  }
+
+  public static WxCpUserExternalContactList fromJson(String json) {
+    return WxCpGsonBuilder.create().fromJson(json, WxCpUserExternalContactList.class);
+  }
+}

weixin-java-cp/src/main/java/me/chanjar/weixin/cp/bean/WxCpUserWithExternalPermission.java

@@ -0,0 +1,49 @@
+package me.chanjar.weixin.cp.bean;
+
+import com.google.gson.annotations.Expose;
+import com.google.gson.annotations.SerializedName;
+import me.chanjar.weixin.cp.util.json.WxCpGsonBuilder;
+
+import java.util.List;
+
+public class WxCpUserWithExternalPermission {
+  @SerializedName("errcode")
+  @Expose
+  private Long errcode;
+  @SerializedName("errmsg")
+  @Expose
+  private String errmsg;
+
+  @SerializedName("follow_user")
+  @Expose
+  private List<String> followUser = null;
+
+  public Long getErrcode() {
+    return errcode;
+  }
+
+  public void setErrcode(Long errcode) {
+    this.errcode = errcode;
+  }
+
+  public String getErrmsg() {
+    return errmsg;
+  }
+
+  public void setErrmsg(String errmsg) {
+    this.errmsg = errmsg;
+  }
+
+  public List<String> getFollowUser() {
+    return followUser;
+  }
+
+  public void setFollowUser(List<String> followUser) {
+    this.followUser = followUser;
+  }
+
+
+  public static WxCpUserWithExternalPermission fromJson(String json) {
+    return WxCpGsonBuilder.create().fromJson(json, WxCpUserWithExternalPermission.class);
+  }
+}

weixin-java-cp/src/main/java/me/chanjar/weixin/cp/bean/WxCpXmlMessage.java

@@ -175,6 +175,26 @@ public class WxCpXmlMessage implements Serializable {
   @XStreamConverter(value = XStreamCDataConverter.class)
   private String userId;
 
+  /**
+   * 变更信息的外部联系人的userid，注意不是企业成员的帐号.
+   */
+  @XStreamAlias("ExternalUserID")
+  @XStreamConverter(value = XStreamCDataConverter.class)
+  private String externalUserID;
+
+  /**
+   * 添加此用户的「联系我」方式配置的state参数，可用于识别添加此用户的渠道
+   */
+  @XStreamAlias("State")
+  @XStreamConverter(value = XStreamCDataConverter.class)
+  private String state;
+
+  /**
+   * 欢迎语code，可用于发送欢迎语
+   */
+  @XStreamAlias("WelcomeCode")
+  @XStreamConverter(value = XStreamCDataConverter.class)
+  private String welcomeCode;
   /**
    * 新的UserID，变更时推送（userid由系统生成时可更改一次）.
    */

weixin-java-cp/src/main/java/me/chanjar/weixin/cp/constant/WxCpApiPathConsts.java

@@ -103,4 +103,10 @@ public final class WxCpApiPathConsts {
     public static final String USER_CONVERT_TO_USERID = "/cgi-bin/user/convert_to_userid";
     public static final String GET_EXTERNAL_CONTACT = "/cgi-bin/crm/get_external_contact?external_userid=";
   }
+
+  public static class ExternalContact {
+    public static final String GET_EXTERNAL_CONTACT = "/cgi-bin/crm/get_external_contact?external_userid=";
+    public static final String LIST_EXTERNAL_CONTACT = "/cgi-bin/externalcontact/list?userid=";
+    public static final String GET_FOLLOW_USER_LIST = "/cgi-bin/externalcontact/get_follow_user_list";
+  }
 }

weixin-java-cp/src/main/java/me/chanjar/weixin/cp/constant/WxCpConsts.java

@@ -89,6 +89,26 @@ public class WxCpConsts {
      */
     public static final String TASKCARD_CLICK = "taskcard_click";
 
+    /**
+     * 企业成员添加外部联系人事件推送
+     */
+    public static final String CHANGE_EXTERNAL_CONTACT = "change_external_contact";
+
+
+  }
+
+  /**
+   * 企业外部联系人变更事件的CHANGE_TYPE
+   */
+  public static class ExternalContactChangeType {
+    /**
+     * 新增外部联系人
+     */
+    public static final String ADD_EXTERNAL_CONTACT = "add_external_contact";
+    /**
+     * 删除外部联系人
+     */
+    public static final String DEL_EXTERNAL_CONTACT = "del_external_contact";
   }
 
   /**