🆕 #2746 【企业微信】 增加读取学生或家长所有接口支持

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

@@ -158,6 +158,40 @@ public interface WxCpSchoolUserService {
    */
   WxCpBatchResultList batchUpdateParent(@NonNull WxCpBatchUpdateParentRequest request) throws WxErrorException;
 
+  /**
+   * 读取学生或家长
+   * 请求方式：GET（HTTPS）
+   * 请求地址：https://qyapi.weixin.qq.com/cgi-bin/school/user/get?access_token=ACCESS_TOKEN&userid=USERID
+   *
+   * @param userId
+   * @return
+   * @throws WxErrorException
+   */
+  WxCpUserResult getUser(@NonNull String userId) throws WxErrorException;
+
+  /**
+   * 获取部门成员详情
+   * 请求方式：GET（HTTPS）
+   * 请求地址：https://qyapi.weixin.qq.com/cgi-bin/school/user/list?access_token=ACCESS_TOKEN&department_id=DEPARTMENT_ID&fetch_child=FETCH_CHILD
+   *
+   * @param departmentId 获取的部门id
+   * @param fetchChild   1/0：是否递归获取子部门下面的成员
+   * @return
+   * @throws WxErrorException
+   */
+  WxCpUserListResult getUserList(@NonNull Integer departmentId, Integer fetchChild) throws WxErrorException;
+
+  /**
+   * 获取部门家长详情
+   * 请求方式：GET（HTTPS）
+   * 请求地址：https://qyapi.weixin.qq.com/cgi-bin/school/user/list_parent?access_token=ACCESS_TOKEN&department_id=DEPARTMENT_ID
+   *
+   * @param departmentId 获取的部门id
+   * @return
+   * @throws WxErrorException
+   */
+  WxCpListParentResult getUserListParent(@NonNull Integer departmentId) throws WxErrorException;
+
   /**
    * 更新家长
    * 请求方式：POST（HTTPS）

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

@@ -142,6 +142,27 @@ public class WxCpSchoolUserServiceImpl implements WxCpSchoolUserService {
     return WxCpBatchResultList.fromJson(responseContent);
   }
 
+  @Override
+  public WxCpUserResult getUser(@NonNull String userId) throws WxErrorException {
+    String apiUrl = this.cpService.getWxCpConfigStorage().getApiUrl(GET_USER) + userId;
+    String responseContent = this.cpService.get(apiUrl, null);
+    return WxCpUserResult.fromJson(responseContent);
+  }
+
+  @Override
+  public WxCpUserListResult getUserList(@NonNull Integer departmentId, Integer fetchChild) throws WxErrorException {
+    String apiUrl = String.format(this.cpService.getWxCpConfigStorage().getApiUrl(GET_USER_LIST), departmentId, fetchChild);
+    String responseContent = this.cpService.get(apiUrl, null);
+    return WxCpUserListResult.fromJson(responseContent);
+  }
+
+  @Override
+  public WxCpListParentResult getUserListParent(@NonNull Integer departmentId) throws WxErrorException {
+    String apiUrl = this.cpService.getWxCpConfigStorage().getApiUrl(GET_USER_LIST_PARENT) + departmentId;
+    String responseContent = this.cpService.get(apiUrl, null);
+    return WxCpListParentResult.fromJson(responseContent);
+  }
+
   @Override
   public WxCpBaseResp updateParent(@NonNull WxCpUpdateParentRequest request) throws WxErrorException {
     String apiUrl = this.cpService.getWxCpConfigStorage().getApiUrl(UPDATE_PARENT);

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

@@ -9,6 +9,7 @@ import java.io.Serializable;
  * <pre>
  *  使用user_ticket获取成员详情接口返回类.
  *  Created by BinaryWang on 2018/4/22.
+ *  官方文档：https://developer.work.weixin.qq.com/document/path/91122
  * </pre>
  *
  * @author <a href="https://github.com/binarywang">Binary Wang</a>

weixin-java-cp/src/main/java/me/chanjar/weixin/cp/bean/school/user/WxCpListParentResult.java

@@ -0,0 +1,95 @@
+package me.chanjar.weixin.cp.bean.school.user;
+
+import com.google.gson.annotations.SerializedName;
+import lombok.*;
+import lombok.experimental.Accessors;
+import me.chanjar.weixin.cp.bean.WxCpBaseResp;
+import me.chanjar.weixin.cp.util.json.WxCpGsonBuilder;
+
+import java.io.Serializable;
+import java.util.List;
+
+/**
+ * 获取部门家长详情返回结果.
+ *
+ * @author Wang_Wong
+ * @date 2022-07-13
+ */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+@Accessors(chain = true)
+public class WxCpListParentResult extends WxCpBaseResp implements Serializable {
+  private static final long serialVersionUID = -4960239393895754138L;
+
+  @SerializedName("parents")
+  private List<Parent> parents;
+
+  @Setter
+  @Getter
+  @Builder
+  @NoArgsConstructor
+  @AllArgsConstructor
+  public static class Parent implements Serializable {
+
+    @SerializedName("parent_userid")
+    private String parentUserId;
+
+    @SerializedName("mobile")
+    private String mobile;
+
+    @SerializedName("external_userid")
+    private String externalUserId;
+
+    @SerializedName("is_subscribe")
+    private Integer isSubscribe;
+
+    @SerializedName("children")
+    private List<Children> children;
+
+    public static Parent fromJson(String json) {
+      return WxCpGsonBuilder.create().fromJson(json, Parent.class);
+    }
+
+    public String toJson() {
+      return WxCpGsonBuilder.create().toJson(this);
+    }
+
+  }
+
+  @Setter
+  @Getter
+  @Builder
+  @NoArgsConstructor
+  @AllArgsConstructor
+  public static class Children implements Serializable {
+
+    @SerializedName("student_userid")
+    private String studentUserId;
+
+    @SerializedName("relation")
+    private String relation;
+
+    @SerializedName("name")
+    private String name;
+
+    public static Children fromJson(String json) {
+      return WxCpGsonBuilder.create().fromJson(json, Children.class);
+    }
+
+    public String toJson() {
+      return WxCpGsonBuilder.create().toJson(this);
+    }
+
+  }
+
+  public static WxCpListParentResult fromJson(String json) {
+    return WxCpGsonBuilder.create().fromJson(json, WxCpListParentResult.class);
+  }
+
+  public String toJson() {
+    return WxCpGsonBuilder.create().toJson(this);
+  }
+
+}

weixin-java-cp/src/main/java/me/chanjar/weixin/cp/bean/school/user/WxCpUserListResult.java

@@ -0,0 +1,98 @@
+package me.chanjar.weixin.cp.bean.school.user;
+
+import com.google.gson.annotations.SerializedName;
+import lombok.*;
+import lombok.experimental.Accessors;
+import me.chanjar.weixin.cp.bean.WxCpBaseResp;
+import me.chanjar.weixin.cp.util.json.WxCpGsonBuilder;
+
+import java.io.Serializable;
+import java.util.List;
+
+/**
+ * 获取部门成员详情返回结果.
+ *
+ * @author Wang_Wong
+ * @date 2022-07-13
+ */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+@Accessors(chain = true)
+public class WxCpUserListResult extends WxCpBaseResp implements Serializable {
+  private static final long serialVersionUID = -4960239393895754138L;
+
+  @SerializedName("students")
+  private List<Student> students;
+
+  @Setter
+  @Getter
+  @Builder
+  @NoArgsConstructor
+  @AllArgsConstructor
+  public static class Parent implements Serializable {
+
+    @SerializedName("parent_userid")
+    private String parentUserId;
+
+    @SerializedName("relation")
+    private String relation;
+
+    @SerializedName("mobile")
+    private String mobile;
+
+    @SerializedName("external_userid")
+    private String externalUserId;
+
+    @SerializedName("is_subscribe")
+    private Integer isSubscribe;
+
+    public static Parent fromJson(String json) {
+      return WxCpGsonBuilder.create().fromJson(json, Parent.class);
+    }
+
+    public String toJson() {
+      return WxCpGsonBuilder.create().toJson(this);
+    }
+
+  }
+
+  @Setter
+  @Getter
+  @Builder
+  @NoArgsConstructor
+  @AllArgsConstructor
+  public static class Student implements Serializable {
+
+    @SerializedName("student_userid")
+    private String studentUserId;
+
+    @SerializedName("name")
+    private String name;
+
+    @SerializedName("department")
+    private List<Integer> department;
+
+    @SerializedName("parents")
+    private List<Parent> parents;
+
+    public static Student fromJson(String json) {
+      return WxCpGsonBuilder.create().fromJson(json, Student.class);
+    }
+
+    public String toJson() {
+      return WxCpGsonBuilder.create().toJson(this);
+    }
+
+  }
+
+  public static WxCpUserListResult fromJson(String json) {
+    return WxCpGsonBuilder.create().fromJson(json, WxCpUserListResult.class);
+  }
+
+  public String toJson() {
+    return WxCpGsonBuilder.create().toJson(this);
+  }
+
+}

weixin-java-cp/src/main/java/me/chanjar/weixin/cp/bean/school/user/WxCpUserResult.java

@@ -0,0 +1,130 @@
+package me.chanjar.weixin.cp.bean.school.user;
+
+import com.google.gson.annotations.SerializedName;
+import lombok.*;
+import lombok.experimental.Accessors;
+import me.chanjar.weixin.cp.bean.WxCpBaseResp;
+import me.chanjar.weixin.cp.util.json.WxCpGsonBuilder;
+
+import java.io.Serializable;
+import java.util.List;
+
+/**
+ * 读取学生或家长返回结果.
+ *
+ * @author Wang_Wong
+ * @date 2022-07-13
+ */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+@Accessors(chain = true)
+public class WxCpUserResult extends WxCpBaseResp implements Serializable {
+  private static final long serialVersionUID = -4960239393895754138L;
+
+  @SerializedName("student")
+  private Student student;
+
+  @SerializedName("parent")
+  private Parent parent;
+
+  @SerializedName("user_type")
+  private Integer userType;
+
+  @Setter
+  @Getter
+  @Builder
+  @NoArgsConstructor
+  @AllArgsConstructor
+  public static class Parent implements Serializable {
+
+    @SerializedName("parent_userid")
+    private String parentUserId;
+
+    @SerializedName("relation")
+    private String relation;
+
+    @SerializedName("mobile")
+    private String mobile;
+
+    @SerializedName("external_userid")
+    private String externalUserId;
+
+    @SerializedName("is_subscribe")
+    private Integer isSubscribe;
+
+    @SerializedName("children")
+    private List<Children> children;
+
+    public static Parent fromJson(String json) {
+      return WxCpGsonBuilder.create().fromJson(json, Parent.class);
+    }
+
+    public String toJson() {
+      return WxCpGsonBuilder.create().toJson(this);
+    }
+
+  }
+
+  @Setter
+  @Getter
+  @Builder
+  @NoArgsConstructor
+  @AllArgsConstructor
+  public static class Student implements Serializable {
+
+    @SerializedName("student_userid")
+    private String studentUserId;
+
+    @SerializedName("department")
+    private List<Integer> department;
+
+    @SerializedName("parents")
+    private List<Parent> parents;
+
+    @SerializedName("name")
+    private String name;
+
+    public static Student fromJson(String json) {
+      return WxCpGsonBuilder.create().fromJson(json, Student.class);
+    }
+
+    public String toJson() {
+      return WxCpGsonBuilder.create().toJson(this);
+    }
+
+  }
+
+  @Setter
+  @Getter
+  @Builder
+  @NoArgsConstructor
+  @AllArgsConstructor
+  public static class Children implements Serializable {
+
+    @SerializedName("student_userid")
+    private String studentUserId;
+
+    @SerializedName("relation")
+    private String relation;
+
+    public static Children fromJson(String json) {
+      return WxCpGsonBuilder.create().fromJson(json, Children.class);
+    }
+
+    public String toJson() {
+      return WxCpGsonBuilder.create().toJson(this);
+    }
+
+  }
+
+  public static WxCpUserResult fromJson(String json) {
+    return WxCpGsonBuilder.create().fromJson(json, WxCpUserResult.class);
+  }
+
+  public String toJson() {
+    return WxCpGsonBuilder.create().toJson(this);
+  }
+
+}

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

@@ -206,6 +206,9 @@ public interface WxCpApiPathConsts {
     String CREATE_PARENT = "/cgi-bin/school/user/create_parent";
     String UPDATE_PARENT = "/cgi-bin/school/user/update_parent";
     String DELETE_PARENT = "/cgi-bin/school/user/delete_parent?userid=";
+    String GET_USER = "/cgi-bin/school/user/get?userid=";
+    String GET_USER_LIST = "/cgi-bin/school/user/list?department_id=%s&fetch_child=%d";
+    String GET_USER_LIST_PARENT = "/cgi-bin/school/user/list_parent?department_id=";
     String SET_ARCH_SYNC_MODE = "/cgi-bin/school/set_arch_sync_mode";
     String SET_UPGRADE_INFO = "/cgi-bin/school/set_upgrade_info";
 

weixin-java-cp/src/test/java/me/chanjar/weixin/cp/api/WxCpSchoolUserTest.java

@@ -56,6 +56,160 @@ public class WxCpSchoolUserTest {
     final String exUserId = "wmOQpTDwAAJFHrryZ8I8ALLEZuLHIUKA";
 
 
+    /**
+     * 获取部门家长详情
+     *
+     * https://developer.work.weixin.qq.com/document/path/92446
+     */
+    WxCpListParentResult userListParent = cpService.getSchoolUserService().getUserListParent(1);
+
+    String jsonUserListParentResult = "{\n" +
+      "    \"errcode\": 0,\n" +
+      "    \"errmsg\": \"ok\",\n" +
+      "    \"parents\": [\n" +
+      "        {\n" +
+      "            \"parent_userid\": \"zhangsan_parent\",\n" +
+      "            \"mobile\": \"18900000000\",\n" +
+      "            \"is_subscribe\": 1,\n" +
+      "\t\t\t\"external_userid\":\"xxx\",\n" +
+      "            \"children\": [\n" +
+      "                {\n" +
+      "                    \"student_userid\": \"zhangsan\",\n" +
+      "                    \"relation\": \"爸爸\",\n" +
+      "                    \"name\": \"张三\"\n" +
+      "                }\n" +
+      "            ]\n" +
+      "        },\n" +
+      "\t\t{\n" +
+      "            \"parent_userid\": \"lisi_parent\",\n" +
+      "            \"mobile\": \"18900000001\",\n" +
+      "            \"is_subscribe\": 0,\n" +
+      "            \"children\": [\n" +
+      "                {\n" +
+      "                    \"student_userid\": \"lisi\",\n" +
+      "                    \"relation\": \"妈妈\",\n" +
+      "                    \"name\": \"李四\"\n" +
+      "                }\n" +
+      "            ]\n" +
+      "        }\n" +
+      "    ]\n" +
+      "}";
+
+    WxCpListParentResult wxCpListParentResult = WxCpListParentResult.fromJson(jsonUserListParentResult);
+    assertThat(wxCpListParentResult.toJson()).isEqualTo(GsonParser.parse(jsonUserListParentResult).toString());
+
+
+    /**
+     * 获取部门成员详情
+     *
+     * https://developer.work.weixin.qq.com/document/path/92043
+     */
+    WxCpUserListResult userList = cpService.getSchoolUserService().getUserList(1, 0);
+
+    String jsonUserListResult = "{\n" +
+      "\t\"errcode\": 0,\n" +
+      "\t\"errmsg\": \"ok\",\n" +
+      "\t\"students\":[\n" +
+      "\t\t{\n" +
+      "\t\t\t\"student_userid\": \"zhangsan\",\n" +
+      "\t\t\t\"name\": \"张三\",\n" +
+      "\t\t\t\"department\": [1, 2],\n" +
+      "\t\t\t\"parents\": [\n" +
+      "\t\t\t\t{\n" +
+      "\t\t\t\t\t\"parent_userid\": \"zhangsan_parent1\",\n" +
+      "\t\t\t\t\t\"relation\": \"爸爸\",\n" +
+      "\t\t\t\t\t\"mobile\": \"18000000001\",\n" +
+      "\t\t\t\t\t\"is_subscribe\": 1,\n" +
+      "\t\t\t\t\t\"external_userid\":\"xxx\"\n" +
+      "\t\t\t\t},\n" +
+      "\t\t\t\t{\n" +
+      "\t\t\t\t\t\"parent_userid\": \"zhangsan_parent2\",\n" +
+      "\t\t\t\t\t\"relation\": \"妈妈\",\n" +
+      "\t\t\t\t\t\"mobile\": \"18000000002\",\n" +
+      "\t\t\t\t\t\"is_subscribe\": 0\n" +
+      "\t\t\t\t}\n" +
+      "\t\t\t]\n" +
+      "\t\t},\n" +
+      "\t\t{\n" +
+      "\t\t\t\"student_userid\": \"lisi\",\n" +
+      "\t\t\t\"name\": \"李四\",\n" +
+      "\t\t\t\"department\": [4, 5],\n" +
+      "\t\t\t\"parents\": [\n" +
+      "\t\t\t\t{\n" +
+      "\t\t\t\t\t\"parent_userid\": \"lisi_parent1\",\n" +
+      "\t\t\t\t\t\"relation\": \"爷爷\",\n" +
+      "\t\t\t\t\t\"mobile\": \"18000000003\",\n" +
+      "\t\t\t\t\t\"is_subscribe\": 1,\n" +
+      "\t\t\t\t\t\"external_userid\":\"xxx\"\n" +
+      "\t\t\t\t},\n" +
+      "\t\t\t\t{\n" +
+      "\t\t\t\t\t\"parent_userid\": \"lisi_parent2\",\n" +
+      "\t\t\t\t\t\"relation\": \"妈妈\",\n" +
+      "\t\t\t\t\t\"mobile\": \"18000000004\",\n" +
+      "\t\t\t\t\t\"is_subscribe\": 1,\n" +
+      "\t\t\t\t\t\"external_userid\":\"xxx\"\n" +
+      "\t\t\t\t}\n" +
+      "\t\t\t]\n" +
+      "\t\t}\n" +
+      "\t]\n" +
+      "}";
+
+    WxCpUserListResult wxCpUserListResult = WxCpUserListResult.fromJson(jsonUserListResult);
+    assertThat(wxCpUserListResult.toJson()).isEqualTo(GsonParser.parse(jsonUserListResult).toString());
+
+    /**
+     * 读取学生或家长
+     *
+     * https://developer.work.weixin.qq.com/document/path/92337
+     */
+    WxCpUserResult userResult = cpService.getSchoolUserService().getUser(userId);
+
+    String jsonUserResult = "{\n" +
+      "\t\"errcode\": 0,\n" +
+      "\t\"errmsg\": \"ok\",\n" +
+      "\t\"user_type\": 1,\n" +
+      "\t\"student\":{\n" +
+      "\t\t\"student_userid\": \"zhangsan\",\n" +
+      "\t\t\"name\": \"张三\",\n" +
+      "\t\t\"department\": [1, 2],\n" +
+      "\t\t\"parents\":[\n" +
+      "\t\t\t{\n" +
+      "\t\t\t\t\"parent_userid\": \"zhangsan_parent1\",\n" +
+      "\t\t\t\t\"relation\": \"爸爸\",\n" +
+      "\t\t\t\t\"mobile\":\"18000000000\",\n" +
+      "\t\t\t\t\"is_subscribe\": 1,\n" +
+      "\t\t\t\t\"external_userid\":\"xxxxx\"\n" +
+      "\t\t\t},\n" +
+      "\t\t\t{\n" +
+      "\t\t\t\t\"parent_userid\": \"zhangsan_parent2\",\n" +
+      "\t\t\t\t\"relation\": \"妈妈\",\n" +
+      "\t\t\t\t\"mobile\": \"18000000001\",\n" +
+      "\t\t\t\t\"is_subscribe\": 0\n" +
+      "\t\t\t}\n" +
+      "\t\t]\n" +
+      "    },\n" +
+      "\t\"parent\":{\n" +
+      "\t\t\"parent_userid\": \"zhangsan_parent2\",\n" +
+      "\t\t\"mobile\": \"18000000003\",\n" +
+      "\t\t\"is_subscribe\": 1,\n" +
+      "\t\t\"external_userid\":\"xxxxx\",\n" +
+      "\t\t\"children\":[\n" +
+      "\t\t\t{\n" +
+      "\t\t\t\t\"student_userid\": \"zhangsan\",\n" +
+      "\t\t\t\t\"relation\": \"妈妈\"\n" +
+      "\t\t\t},\n" +
+      "\t\t\t{\n" +
+      "\t\t\t\t\"student_userid\": \"lisi\",\n" +
+      "\t\t\t\t\"relation\": \"伯母\"\n" +
+      "\t\t\t}\n" +
+      "\t\t]\n" +
+      "\t}\n" +
+      "}";
+
+    WxCpUserResult wxCpUserResult = WxCpUserResult.fromJson(jsonUserResult);
+    assertThat(wxCpUserResult.toJson()).isEqualTo(GsonParser.parse(jsonUserResult).toString());
+
+
     /**
      * 批量更新家长
      *