diff --git a/ruoyi-framework/src/main/java/com/ruoyi/framework/shiro/rememberMe/CustomCookieRememberMeManager.java b/ruoyi-framework/src/main/java/com/ruoyi/framework/shiro/rememberMe/CustomCookieRememberMeManager.java
index 8123092752499ffc8835de97fd25b7084417389c..412b751e4eaad1f492e842ebcee4b3851ff1437d 100644
--- a/ruoyi-framework/src/main/java/com/ruoyi/framework/shiro/rememberMe/CustomCookieRememberMeManager.java
+++ b/ruoyi-framework/src/main/java/com/ruoyi/framework/shiro/rememberMe/CustomCookieRememberMeManager.java
@@ -16,12 +16,75 @@ import com.ruoyi.framework.shiro.service.SysLoginService;
 /**
  * 自定义CookieRememberMeManager
  *
+ * <p>该类继承自 Shiro 的 {@link CookieRememberMeManager}，用于解决"记住我"功能中
+ * HTTP 请求头过大的问题。</p>
+ *
+ * <h2>问题背景</h2>
+ * <p>在原始实现中，"记住我"功能会将用户的所有角色权限信息（permissions）序列化为
+ * Base64 编码后存储在 Cookie 中。当用户拥有大量权限时，Cookie 的大小会变得非常大，
+ * 可能导致 HTTP 请求头超出服务器限制（如 Tomcat 默认的 8192 字节）。</p>
+ *
+ * <h2>解决方案</h2>
+ * <p>本类采用以下策略解决此问题：</p>
+ * <ol>
+ *   <li><b>存储时优化</b>：在 {@link #rememberIdentity(Subject, PrincipalCollection)} 方法中，
+ *       暂时清除角色对象的 permissions 权限字符串，仅序列化必要的用户身份信息。</li>
+ *   <li><b>使用时恢复</b>：在 {@link #getRememberedPrincipals(SubjectContext)} 方法中，
+ *       从服务器重新加载用户的角色权限信息，确保权限验证正常工作。</li>
+ * </ol>
+ *
+ * <h2>使用场景</h2>
+ * <p>适用于以下情况：</p>
+ * <ul>
+ *   <li>用户拥有大量角色权限时</li>
+ *   <li>需要使用"记住我"功能且服务器对请求头大小有限制</li>
+ *   <li>从 Spring Boot 2.x 升级到 Spring Boot 3.x 时需要兼容</li>
+ * </ul>
+ *
+ * <h2>配置方式</h2>
+ * <pre>
+ * 在 {@link com.ruoyi.framework.config.ShiroConfig} 中配置：
+ *
+ * &#64;Bean
+ * public CustomCookieRememberMeManager rememberMeManager()
+ * {
+ *     CustomCookieRememberMeManager cookieRememberMeManager = new CustomCookieRememberMeManager();
+ *     cookieRememberMeManager.setCookie(rememberMeCookie());
+ *     // 设置加密密钥等配置...
+ *     return cookieRememberMeManager;
+ * }
+ * </pre>
+ *
  * @author ruoyi
+ * @see org.apache.shiro.web.mgt.CookieRememberMeManager
+ * @see com.ruoyi.framework.shiro.service.SysLoginService#setRolePermission(SysUser)
  */
 public class CustomCookieRememberMeManager extends CookieRememberMeManager
 {
     /**
-     * 记住我时去掉角色的permissions权限字符串，防止http请求头过大。
+     *去掉角色的permissions权限字符串 记住我时，防止http请求头过大。
+     *
+     * <p>该方法在用户登录并选择"记住我"时调用。</p>
+     *
+     * <h2>处理流程：</h2>
+     * <ol>
+     *   <li>遍历所有主体（Principal），找到 {@link SysUser} 类型的用户信息</li>
+     *   <li>提取每个角色的 permissions 权限集合并暂存到 Map 中</li>
+     *   <li>将角色的 permissions 设置为 null，避免序列化到 Cookie</li>
+     *   <li>调用父类方法将精简后的身份信息序列化为字节数组</li>
+     *   <li>恢复原始的 permissions 数据（不修改原始对象）</li>
+     *   <li>将字节数组存储到 Cookie</li>
+     * </ol>
+     *
+     * <h2>注意事项：</h2>
+     * <ul>
+     *   <li>此方法仅影响 Cookie 中存储的数据，不会修改原始的用户对象</li>
+     *   <li>权限信息会在 {@link #getRememberedPrincipals(SubjectContext)} 中重新加载</li>
+     *   <li>该操作可以显著减少 Cookie 的大小（通常可减少 50%-90%）</li>
+     * </ul>
+     *
+     * @param subject 当前主题
+     * @param principalCollection 用户身份信息集合，包含用户和角色信息
      */
     @Override
     protected void rememberIdentity(Subject subject, PrincipalCollection principalCollection)
@@ -58,6 +121,33 @@ public class CustomCookieRememberMeManager extends CookieRememberMeManager
 
     /**
      * 取记住我身份时恢复角色permissions权限字符串。
+     *
+     * <p>该方法在用户通过"记住我"功能自动登录时调用。</p>
+     *
+     * <h2>处理流程：</h2>
+     * <ol>
+     *   <li>调用父类方法从 Cookie 中解析出用户身份信息</li>
+     *   <li>检查解析结果是否为空，如果为空则直接返回</li>
+     *   <li>遍历解析出的主体，找到 {@link SysUser} 类型的用户信息</li>
+     *   <li>调用 {@link SysLoginService#setRolePermission(SysUser)} 方法重新加载权限</li>
+     *   <li>返回完整的用户身份信息（包含重新加载的权限）</li>
+     * </ol>
+     *
+     * <h2>注意事项：</h2>
+     * <ul>
+     *   <li>此方法确保用户登录后仍能正常使用权限验证功能</li>
+     *   <li>权限信息来自数据库，而非 Cookie，确保数据的实时性</li>
+     *   <li>如果用户权限在 Cookie 存储期间发生变化，此方法能获取最新权限</li>
+     * </ul>
+     *
+     * <h2>异常处理：</h2>
+     * <p>如果 {@link SysLoginService} 获取失败或返回异常，用户仍可登录，
+     * 但部分权限验证功能可能受影响。</p>
+     *
+     * @param subjectContext 主题上下文，包含 Cookie 解析的身份信息
+     * @return 完整的主身份信息集合，包含重新加载的权限
+     * @see org.apache.shiro.subject.PrincipalCollection
+     * @see com.ruoyi.framework.shiro.service.SysLoginService
      */
     @Override
     public PrincipalCollection getRememberedPrincipals(SubjectContext subjectContext)