📝 明确说明 wx-java-cp-multi-spring-boot-starter 中 corp-secret 的配置方式

solon-plugins/wx-java-cp-multi-solon-plugin/src/main/java/com/binarywang/solon/wxjava/cp_multi/configuration/services/AbstractWxCpConfiguration.java

@@ -15,6 +15,7 @@ import org.apache.commons.lang3.StringUtils;
 import java.util.Collection;
 import java.util.List;
 import java.util.Map;
+import java.util.Objects;
 import java.util.Set;
 import java.util.stream.Collectors;
 
@@ -37,6 +38,13 @@ public abstract class AbstractWxCpConfiguration {
     /**
      * 校验同一个企业下，agentId 是否唯一，避免使用 redis 缓存 token、ticket 时错乱。
      *
+     * <p>同一企业（corpId 相同）下可配置多个条目以使用不同的权限 Secret，例如：</p>
+     * <ul>
+     *   <li>自建应用条目：填写应用对应的 corpSecret 和 agentId</li>
+     *   <li>通讯录同步条目：填写通讯录同步 Secret，agentId 可不填（null）</li>
+     * </ul>
+     * <p>但同一 corpId 下不允许出现重复的 agentId（包括多个 null）。</p>
+     *
      * 查看 {@link me.chanjar.weixin.cp.config.impl.AbstractWxCpInRedisConfigImpl#setAgentId(Integer)}
      */
     Collection<WxCpSingleProperties> corpList = corps.values();
@@ -49,8 +57,8 @@ public abstract class AbstractWxCpConfiguration {
         String corpId = entry.getKey();
         // 校验每个企业下，agentId 是否唯一
         boolean multi = entry.getValue().stream()
-          // 通讯录没有 agentId，如果不判断是否为空，这里会报 NPE 异常
-          .collect(Collectors.groupingBy(c -> c.getAgentId() == null ? 0 : c.getAgentId(), Collectors.counting()))
+          // 通讯录没有 agentId，使用字符串转换避免 null 与 agentId=0 冲突
+          .collect(Collectors.groupingBy(c -> Objects.toString(c.getAgentId(), "null"), Collectors.counting()))
           .entrySet().stream().anyMatch(e -> e.getValue() > 1);
         if (multi) {
           throw new RuntimeException("请确保企业微信配置唯一性[" + corpId + "]");

solon-plugins/wx-java-cp-multi-solon-plugin/src/main/java/com/binarywang/solon/wxjava/cp_multi/properties/WxCpSingleProperties.java

@@ -8,6 +8,16 @@ import java.io.Serializable;
 /**
  * 企业微信企业相关配置属性
  *
+ * <p>企业微信中不同的 corpSecret 对应不同的权限范围，常见的有：</p>
+ * <ul>
+ *   <li>自建应用 Secret：在"应用管理 - 自建应用"中查看，只能调用该应用有权限的接口</li>
+ *   <li>通讯录同步 Secret：在"管理工具 - 通讯录同步"中查看，用于管理部门和成员（增删改查）</li>
+ *   <li>客户联系 Secret：在"客户联系"中查看，用于客户联系相关接口</li>
+ * </ul>
+ * <p>如需同时使用多种权限范围（例如：既要操作通讯录，又要调用自建应用接口），
+ * 可在 {@code wx.cp.corps} 下配置多个条目，每个条目使用对应权限的 {@code corpSecret}，
+ * 其中通讯录同步的条目无需填写 {@code agentId}。</p>
+ *
  * @author yl
  * created on 2023/10/16
  */
@@ -20,7 +30,16 @@ public class WxCpSingleProperties implements Serializable {
    */
   private String corpId;
   /**
-   * 微信企业号 corpSecret
+   * 微信企业号 corpSecret（权限密钥）
+   *
+   * <p>企业微信针对不同的功能模块提供了不同的 Secret，每种 Secret 只对对应模块的接口有调用权限：</p>
+   * <ul>
+   *   <li>自建应用 Secret：在"应用管理 - 自建应用"中找到对应应用，查看其 Secret，
+   *       使用时需同时配置对应的 {@code agentId}</li>
+   *   <li>通讯录同步 Secret：在"管理工具 - 通讯录同步"中查看，
+   *       使用此 Secret 可管理部门、成员，无需配置 {@code agentId}</li>
+   *   <li>其他 Secret（客户联系等）：根据需要在企业微信后台查看对应 Secret</li>
+   * </ul>
    */
   private String corpSecret;
   /**
@@ -28,7 +47,10 @@ public class WxCpSingleProperties implements Serializable {
    */
   private String token;
   /**
-   * 微信企业号应用 ID
+   * 微信企业号应用 ID（AgentId）
+   *
+   * <p>使用自建应用 Secret 时，需要填写对应应用的 AgentId。</p>
+   * <p>使用通讯录同步 Secret 时，无需填写此字段。</p>
    */
   private Integer agentId;
   /**