🎨 #3977 【企业微信】修复「人事助手」相关接口在响应反序列化时字段结构与实际 API 返回不一致导致的解析问题

2026-10-17 04:46:10 +08:00 · 2026-05-09 10:22:10 +08:00
parent 63e8291248
commit 7a4204a6c2
7 changed files with 380 additions and 46 deletions
--- a/weixin-java-cp/src/main/java/me/chanjar/weixin/cp/bean/hr/WxCpHrEmployeeFieldData.java
+++ b/weixin-java-cp/src/main/java/me/chanjar/weixin/cp/bean/hr/WxCpHrEmployeeFieldData.java
@@ -5,10 +5,9 @@ import lombok.Data;
 import lombok.NoArgsConstructor;

 import java.io.Serializable;
-import java.util.List;

 /**
- * 人事助手-员工档案数据（单个员工）.
+ * 人事助手-员工档案数据（单个字段）.
 *
 * @author <a href="https://github.com/leejoker">leejoker</a> created on  2024-01-01
 */
@@ -18,19 +17,98 @@ public class WxCpHrEmployeeFieldData implements Serializable {
  private static final long serialVersionUID = 4593693598671765396L;

  /**
-   * 员工userid.
+   * 字段ID.
   */
+  @SerializedName("fieldid")
+  private Integer fieldId;
+
+  /**
+   * 子字段索引.
+   */
+  @SerializedName("sub_idx")
+  private Integer subIdx;
+
+  /**
+   * 结果状态，1表示成功.
+   */
+  @SerializedName("result")
+  private Integer result;
+
+  /**
+   * 值类型：1-字符串，2-uint64，3-uint32，4-int64，5-mobile.
+   */
+  @SerializedName("value_type")
+  private Integer valueType;
+
+  /**
+   * 字符串值（value_type=1时使用）.
+   */
+  @SerializedName("value_string")
+  private String valueString;
+
+  /**
+   * 无符号32位整数值（value_type=3时使用）.
+   */
+  @SerializedName("value_uint32")
+  private Long valueUint32;
+
+  /**
+   * 有符号64位整数值（value_type=4时使用）.
+   */
+  @SerializedName("value_int64")
+  private Long valueInt64;
+
+  /**
+   * 无符号64位整数值（value_type=2时使用）.
+   */
+  @SerializedName("value_uint64")
+  private Long valueUint64;
+
+  /**
+   * 手机号值（value_type=5时使用）.
+   */
+  @SerializedName("value_mobile")
+  private MobileValue valueMobile;
+
+  /**
+   * 手机号值.
+   */
+  @Data
+  @NoArgsConstructor
+  public static class MobileValue implements Serializable {
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * 国家代码.
+     */
+    @SerializedName("value_country_code")
+    private String valueCountryCode;
+
+    /**
+     * 手机号.
+     */
+    @SerializedName("value_mobile")
+    private String valueMobile;
+  }
+
+  /**
+   * 员工userid（兼容旧版本，实际API不返回此字段）.
+   * @deprecated 此字段在API响应中不存在
+   */
+  @Deprecated
  @SerializedName("userid")
  private String userid;

  /**
-   * 字段数据列表.
+   * 字段数据列表（兼容旧版本，实际API不返回此字段）.
+   * @deprecated 此字段在API响应中不存在
   */
+  @Deprecated
  @SerializedName("field_list")
-  private List<FieldItem> fieldList;
+  private java.util.List<FieldItem> fieldList;

  /**
-   * 字段数据项.
+   * 字段数据项（用于更新员工档案）.
   */
  @Data
  @NoArgsConstructor
@@ -38,15 +116,21 @@ public class WxCpHrEmployeeFieldData implements Serializable {
    private static final long serialVersionUID = 1L;

    /**
-     * 字段key.
+     * 字段ID.
     */
-    @SerializedName("field_key")
-    private String fieldKey;
+    @SerializedName("fieldid")
+    private Integer fieldId;

    /**
-     * 字段值.
+     * 字段值对象（推荐使用，支持多种类型）.
     */
    @SerializedName("field_value")
    private WxCpHrEmployeeFieldValue fieldValue;
+
+    /**
+     * 字符串值（简化用法，适用于文本类型字段）.
+     */
+    @SerializedName("value_string")
+    private String valueString;
  }
 }
--- a/weixin-java-cp/src/main/java/me/chanjar/weixin/cp/bean/hr/WxCpHrEmployeeFieldDataResp.java
+++ b/weixin-java-cp/src/main/java/me/chanjar/weixin/cp/bean/hr/WxCpHrEmployeeFieldDataResp.java
@@ -21,10 +21,28 @@ public class WxCpHrEmployeeFieldDataResp extends WxCpBaseResp {
  private static final long serialVersionUID = 6593693598671765396L;

  /**
-   * 员工档案数据列表.
+   * 字段数据列表（API实际返回field_info）.
   */
-  @SerializedName("employee_field_list")
-  private List<WxCpHrEmployeeFieldData> employeeFieldList;
+  @SerializedName("field_info")
+  private List<WxCpHrEmployeeFieldData> fieldInfoList;
+
+  /**
+   * 员工档案数据列表（兼容旧版本方法名）.
+   * @deprecated 请使用 getFieldInfoList()
+   */
+  @Deprecated
+  public List<WxCpHrEmployeeFieldData> getEmployeeFieldList() {
+    return this.fieldInfoList;
+  }
+
+  /**
+   * 员工档案数据列表（兼容旧版本方法名）.
+   * @deprecated 请使用 setFieldInfoList()
+   */
+  @Deprecated
+  public void setEmployeeFieldList(List<WxCpHrEmployeeFieldData> employeeFieldList) {
+    this.fieldInfoList = employeeFieldList;
+  }

  /**
   * From json wx cp hr employee field data resp.
--- a/weixin-java-cp/src/main/java/me/chanjar/weixin/cp/bean/hr/WxCpHrEmployeeFieldInfo.java
+++ b/weixin-java-cp/src/main/java/me/chanjar/weixin/cp/bean/hr/WxCpHrEmployeeFieldInfo.java
@@ -18,30 +18,43 @@ public class WxCpHrEmployeeFieldInfo implements Serializable {
  private static final long serialVersionUID = 2593693598671765396L;

  /**
-   * 字段key.
+   * 字段ID.
   */
-  @SerializedName("field_key")
-  private String fieldKey;
+  @SerializedName("fieldid")
+  private Integer fieldId;

  /**
-   * 字段英文名称.
+   * 字段名称.
   */
-  @SerializedName("field_en_name")
-  private String fieldEnName;
-
-  /**
-   * 字段中文名称.
-   */
-  @SerializedName("field_zh_name")
-  private String fieldZhName;
+  @SerializedName("field_name")
+  private String fieldName;

  /**
   * 字段类型.
-   * 具体取值参见 {@link WxCpHrFieldType}
+   * 1: 文本
+   * 2: 单选/多选
+   * 3: 日期
   */
  @SerializedName("field_type")
  private Integer fieldType;

+  /**
+   * 是否必填.
+   */
+  @SerializedName("is_must")
+  private Boolean isMust;
+
+  /**
+   * 值类型.
+   * 1: 字符串
+   * 2: uint64
+   * 3: uint32
+   * 4: int64
+   * 5: mobile
+   */
+  @SerializedName("value_type")
+  private Integer valueType;
+
  /**
   * 获取字段类型枚举.
   *
@@ -52,22 +65,79 @@ public class WxCpHrEmployeeFieldInfo implements Serializable {
  }

  /**
-   * 是否系统字段.
-   * 0: 否
-   * 1: 是
+   * 选项列表（单选/多选字段专用）.
   */
+  @SerializedName("option_list")
+  private List<Option> optionList;
+
+  /**
+   * 选项.
+   */
+  @Data
+  @NoArgsConstructor
+  public static class Option implements Serializable {
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * 选项ID.
+     */
+    @SerializedName("id")
+    private Integer id;
+
+    /**
+     * 选项值.
+     */
+    @SerializedName("value")
+    private String value;
+  }
+
+  // ===== 以下字段为兼容旧版本 =====
+
+  /**
+   * 字段key（兼容旧版本，实际API不返回此字段）.
+   * @deprecated 使用 fieldId 代替
+   */
+  @Deprecated
+  @SerializedName("field_key")
+  private String fieldKey;
+
+  /**
+   * 字段英文名称（兼容旧版本，实际API不返回此字段）.
+   * @deprecated 此字段在API响应中不存在
+   */
+  @Deprecated
+  @SerializedName("field_en_name")
+  private String fieldEnName;
+
+  /**
+   * 字段中文名称（兼容旧版本）.
+   * @deprecated 使用 fieldName 代替
+   */
+  @Deprecated
+  @SerializedName("field_zh_name")
+  private String fieldZhName;
+
+  /**
+   * 是否系统字段（兼容旧版本，实际API不返回此字段）.
+   * @deprecated 此字段在API响应中不存在
+   */
+  @Deprecated
  @SerializedName("is_sys")
  private Integer isSys;

  /**
-   * 字段详情.
+   * 字段详情（兼容旧版本）.
+   * @deprecated 使用 optionList 直接访问选项列表
   */
+  @Deprecated
  @SerializedName("field_detail")
  private FieldDetail fieldDetail;

  /**
-   * 字段详情.
+   * 字段详情（兼容旧版本）.
+   * @deprecated 使用 optionList 代替
   */
+  @Deprecated
  @Data
  @NoArgsConstructor
  public static class FieldDetail implements Serializable {
@@ -77,15 +147,17 @@ public class WxCpHrEmployeeFieldInfo implements Serializable {
     * 选项列表（单选/多选字段专用）.
     */
    @SerializedName("option_list")
-    private List<Option> optionList;
+    private List<OldOption> optionList;
  }

  /**
-   * 选项.
+   * 旧版选项（兼容旧版本）.
+   * @deprecated 使用 Option 代替
   */
+  @Deprecated
  @Data
  @NoArgsConstructor
-  public static class Option implements Serializable {
+  public static class OldOption implements Serializable {
    private static final long serialVersionUID = 1L;

    /**
--- a/weixin-java-cp/src/main/java/me/chanjar/weixin/cp/bean/hr/WxCpHrEmployeeFieldInfoResp.java
+++ b/weixin-java-cp/src/main/java/me/chanjar/weixin/cp/bean/hr/WxCpHrEmployeeFieldInfoResp.java
@@ -7,6 +7,7 @@ import lombok.NoArgsConstructor;
 import me.chanjar.weixin.cp.bean.WxCpBaseResp;
 import me.chanjar.weixin.cp.util.json.WxCpGsonBuilder;

+import java.io.Serializable;
 import java.util.List;

 /**
@@ -21,10 +22,56 @@ public class WxCpHrEmployeeFieldInfoResp extends WxCpBaseResp {
  private static final long serialVersionUID = 5593693598671765396L;

  /**
-   * 字段信息列表.
+   * 字段分组列表（API实际返回group_list）.
   */
-  @SerializedName("field_info_list")
-  private List<WxCpHrEmployeeFieldInfo> fieldInfoList;
+  @SerializedName("group_list")
+  private List<FieldGroup> groupList;
+
+  /**
+   * 字段信息列表（兼容旧版本方法名）.
+   * @deprecated 请使用 getGroupList() 获取分组后的字段信息
+   */
+  @Deprecated
+  public List<WxCpHrEmployeeFieldInfo> getFieldInfoList() {
+    if (groupList == null || groupList.isEmpty()) {
+      return null;
+    }
+    // 兼容旧版本：将所有分组的字段合并到一个列表
+    List<WxCpHrEmployeeFieldInfo> allFields = new java.util.ArrayList<>();
+    for (FieldGroup group : groupList) {
+      if (group.getFieldList() != null) {
+        allFields.addAll(group.getFieldList());
+      }
+    }
+    return allFields.isEmpty() ? null : allFields;
+  }
+
+  /**
+   * 字段分组.
+   */
+  @Data
+  @NoArgsConstructor
+  public static class FieldGroup implements Serializable {
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * 分组ID.
+     */
+    @SerializedName("group_id")
+    private Integer groupId;
+
+    /**
+     * 分组名称.
+     */
+    @SerializedName("group_name")
+    private String groupName;
+
+    /**
+     * 字段列表.
+     */
+    @SerializedName("field_list")
+    private List<WxCpHrEmployeeFieldInfo> fieldList;
+  }

  /**
   * From json wx cp hr employee field info resp.