🆕 #2201【企业微信】 增加获取打卡记录日报、获取打卡记录月报、获取打卡人员排班信息接口

Author: longliveh

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

@@ -26,7 +26,7 @@ public interface WxCpOaService {
    * </pre>
    *
    * @param request 请求
-   * @return 表单提交成功后，返回的表单编号
+   * @return 表单提交成功后 ，返回的表单编号
    * @throws WxErrorException .
    */
   String apply(WxCpOaApplyEventRequest request) throws WxErrorException;
@@ -41,7 +41,7 @@ public interface WxCpOaService {
    * @param startTime           获取打卡记录的开始时间
    * @param endTime             获取打卡记录的结束时间
    * @param userIdList          需要获取打卡记录的用户列表
-   * @return 打卡数据列表
+   * @return 打卡数据列表 checkin data
    * @throws WxErrorException 异常
    */
   List<WxCpCheckinData> getCheckinData(Integer openCheckinDataType, Date startTime, Date endTime,
@@ -55,7 +55,7 @@ List<WxCpCheckinData> getCheckinData(Integer openCheckinDataType, Date startTime
    *
    * @param datetime   需要获取规则的当天日期
    * @param userIdList 需要获取打卡规则的用户列表
-   * @return 打卡规则列表
+   * @return 打卡规则列表 checkin option
    * @throws WxErrorException .
    */
   List<WxCpCheckinOption> getCheckinOption(Date datetime, List<String> userIdList) throws WxErrorException;
@@ -78,7 +78,7 @@ List<WxCpCheckinData> getCheckinData(Integer openCheckinDataType, Date startTime
    * @param cursor    分页查询游标，默认为0，后续使用返回的next_cursor进行分页拉取
    * @param size      一次请求拉取审批单数量，默认值为100，上限值为100
    * @param filters   筛选条件，可对批量拉取的审批申请设置约束条件，支持设置多个条件,nullable
-   * @return WxCpApprovalInfo
+   * @return WxCpApprovalInfo approval info
    * @throws WxErrorException .
    */
   WxCpApprovalInfo getApprovalInfo(@NonNull Date startTime, @NonNull Date endTime, Integer cursor, Integer size,
@@ -89,9 +89,9 @@ WxCpApprovalInfo getApprovalInfo(@NonNull Date startTime, @NonNull Date endTime,
    *
    * @param startTime 开始时间
    * @param endTime   结束时间
-   * @return WxCpApprovalInfo
+   * @return WxCpApprovalInfo approval info
    * @throws WxErrorException .
-   * @see me.chanjar.weixin.cp.api.WxCpOaService#getApprovalInfo
+   * @see me.chanjar.weixin.cp.api.WxCpOaService#getApprovalInfo me.chanjar.weixin.cp.api.WxCpOaService#getApprovalInfo
    */
   WxCpApprovalInfo getApprovalInfo(@NonNull Date startTime, @NonNull Date endTime) throws WxErrorException;
 
@@ -105,7 +105,7 @@ WxCpApprovalInfo getApprovalInfo(@NonNull Date startTime, @NonNull Date endTime,
    * </pre>
    *
    * @param spNo 审批单编号。
-   * @return WxCpApprovaldetail
+   * @return WxCpApprovaldetail approval detail
    * @throws WxErrorException .
    */
   WxCpApprovalDetailResult getApprovalDetail(@NonNull String spNo) throws WxErrorException;
@@ -117,7 +117,7 @@ WxCpApprovalInfo getApprovalInfo(@NonNull Date startTime, @NonNull Date endTime,
    * @param endTime   查询的结束时间戳
    * @param offset    分页查询的偏移量
    * @param limit     分页查询的每页大小,默认为100条，如该参数大于100则按100处理
-   * @return .
+   * @return . dial record
    * @throws WxErrorException .
    */
   List<WxCpDialRecord> getDialRecord(Date startTime, Date endTime, Integer offset,
@@ -127,9 +127,45 @@ List<WxCpDialRecord> getDialRecord(Date startTime, Date endTime, Integer offset,
    * 获取审批模板详情
    *
    * @param templateId 模板ID
-   * @return .
+   * @return . template detail
    * @throws WxErrorException .
    */
   WxCpTemplateResult getTemplateDetail(@NonNull String templateId) throws WxErrorException;
 
+
+  /**
+   * 获取打卡日报数据
+   *
+   * @param startTime  获取日报的开始时间
+   * @param endTime    获取日报的结束时间
+   * @param userIdList 获取日报的userid列表
+   * @return 日报数据列表 checkin day data
+   * @throws WxErrorException the wx error exception
+   */
+  List<WxCpCheckinDayData> getCheckinDayData(Date startTime, Date endTime, List<String> userIdList) throws WxErrorException;
+
+
+  /**
+   * 获取打卡月报数据
+   *
+   * @param startTime  获取月报的开始时间
+   * @param endTime    获取月报的结束时间
+   * @param userIdList 获取月报的userid列表
+   * @return 月报数据列表
+   * @throws WxErrorException the wx error exception
+   */
+  List<WxCpCheckinMonthData> getCheckinMonthData(Date startTime, Date endTime, List<String> userIdList) throws WxErrorException;
+
+  /**
+   * 获取打卡人员排班信息
+   *
+   * @param startTime  获取排班信息的开始时间。Unix时间戳
+   * @param endTime    获取排班信息的结束时间。Unix时间戳（与starttime跨度不超过一个月）
+   * @param userIdList 需要获取排班信息的用户列表（不超过100个）
+   * @return 排班表信息
+   * @throws WxErrorException the wx error exception
+   */
+  WxCpCheckinSchedule getCheckinScheduleList(Date startTime, Date endTime, List<String> userIdList) throws WxErrorException;
+
+
 }

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

@@ -212,4 +212,115 @@ public WxCpTemplateResult getTemplateDetail(@NonNull String templateId) throws W
     String responseContent = this.mainService.post(url, jsonObject.toString());
     return WxCpGsonBuilder.create().fromJson(responseContent, WxCpTemplateResult.class);
   }
+
+  @Override
+  public List<WxCpCheckinDayData> getCheckinDayData(Date startTime, Date endTime, List<String> userIdList) throws WxErrorException {
+
+    if (startTime == null || endTime == null) {
+      throw new WxRuntimeException("starttime and endtime can't be null");
+    }
+
+    if (userIdList == null || userIdList.size() > USER_IDS_LIMIT) {
+      throw new WxRuntimeException("用户列表不能为空，不超过 " + USER_IDS_LIMIT + " 个，若用户超过 " + USER_IDS_LIMIT + " 个，请分批获取");
+    }
+
+    long endTimestamp = endTime.getTime() / 1000L;
+    long startTimestamp = startTime.getTime() / 1000L;
+
+    JsonObject jsonObject = new JsonObject();
+    JsonArray jsonArray = new JsonArray();
+
+    jsonObject.addProperty("starttime", startTimestamp);
+    jsonObject.addProperty("endtime", endTimestamp);
+
+    for (String userid : userIdList) {
+      jsonArray.add(userid);
+    }
+    jsonObject.add("useridlist", jsonArray);
+
+    final String url = this.mainService.getWxCpConfigStorage().getApiUrl(GET_CHECKIN_DAY_DATA);
+    String responseContent = this.mainService.post(url, jsonObject.toString());
+    JsonObject tmpJson = GsonParser.parse(responseContent);
+    return WxCpGsonBuilder.create()
+      .fromJson(
+        tmpJson.get("datas"),
+        new TypeToken<List<WxCpCheckinDayData>>() {
+        }.getType()
+      );
+  }
+
+  @Override
+  public List<WxCpCheckinMonthData> getCheckinMonthData(Date startTime, Date endTime, List<String> userIdList) throws WxErrorException {
+    if (startTime == null || endTime == null) {
+      throw new WxRuntimeException("starttime and endtime can't be null");
+    }
+
+    if (userIdList == null || userIdList.size() > USER_IDS_LIMIT) {
+      throw new WxRuntimeException("用户列表不能为空，不超过 " + USER_IDS_LIMIT + " 个，若用户超过 " + USER_IDS_LIMIT + " 个，请分批获取");
+    }
+
+    long endTimestamp = endTime.getTime() / 1000L;
+    long startTimestamp = startTime.getTime() / 1000L;
+
+    JsonObject jsonObject = new JsonObject();
+    JsonArray jsonArray = new JsonArray();
+
+    jsonObject.addProperty("starttime", startTimestamp);
+    jsonObject.addProperty("endtime", endTimestamp);
+
+    for (String userid : userIdList) {
+      jsonArray.add(userid);
+    }
+    jsonObject.add("useridlist", jsonArray);
+
+    final String url = this.mainService.getWxCpConfigStorage().getApiUrl(GET_CHECKIN_MONTH_DATA);
+    String responseContent = this.mainService.post(url, jsonObject.toString());
+    JsonObject tmpJson = GsonParser.parse(responseContent);
+    return WxCpGsonBuilder.create()
+      .fromJson(
+        tmpJson.get("datas"),
+        new TypeToken<List<WxCpCheckinMonthData>>() {
+        }.getType()
+      );
+  }
+
+  @Override
+  public WxCpCheckinSchedule getCheckinScheduleList(Date startTime, Date endTime, List<String> userIdList) throws WxErrorException {
+    if (startTime == null || endTime == null) {
+      throw new WxRuntimeException("starttime and endtime can't be null");
+    }
+
+    if (userIdList == null || userIdList.size() > USER_IDS_LIMIT) {
+      throw new WxRuntimeException("用户列表不能为空，不超过 " + USER_IDS_LIMIT + " 个，若用户超过 " + USER_IDS_LIMIT + " 个，请分批获取");
+    }
+
+
+    long endTimestamp = endTime.getTime() / 1000L;
+    long startTimestamp = startTime.getTime() / 1000L;
+
+    if (endTimestamp - startTimestamp < 0 || endTimestamp - startTimestamp >= MONTH_SECONDS) {
+      throw new WxRuntimeException("获取记录时间跨度不超过一个月");
+    }
+
+    JsonObject jsonObject = new JsonObject();
+    JsonArray jsonArray = new JsonArray();
+
+    jsonObject.addProperty("starttime", startTimestamp);
+    jsonObject.addProperty("endtime", endTimestamp);
+
+    for (String userid : userIdList) {
+      jsonArray.add(userid);
+    }
+    jsonObject.add("useridlist", jsonArray);
+
+    final String url = this.mainService.getWxCpConfigStorage().getApiUrl(GET_CHECKIN_SCHEDULE_DATA);
+    String responseContent = this.mainService.post(url, jsonObject.toString());
+    JsonObject tmpJson = GsonParser.parse(responseContent);
+    return WxCpGsonBuilder.create()
+      .fromJson(
+        tmpJson,
+        new TypeToken<WxCpCheckinSchedule>() {
+        }.getType()
+      );
+  }
 }