/**
 * This method calculates the user score.
 * @param userId the user id
 * @return the user score
 */
public int calculateUserScore(String userId) {
    // ...
}

// 需要理解这样的代码结构
public class UserService {
    /**
     * 根据用户ID获取用户信息，包含用户的积分、等级等详细信息
     *
     * @param userId 用户唯一标识，格式为 "user_" + 数字
     * @return 用户详细信息，如果不存在返回 null
     * @throws IllegalArgumentException 如果 userId 格式不正确
     */
    public UserDTO getUserDetail(String userId) {
        // 复杂的业务逻辑...
    }
}

// Intention Action - 最自然的触发方式
public class GenerateJavaDocIntentionAction {
    // 当用户按下 Alt+Enter 时显示在提示列表中
}

// 快捷键 - 最高效的触发方式
public class GenerateJavaDocShortcutAction {
    // 全局快捷键 Cmd+Shift+D
}

// 编辑器右键菜单
public class GenerateJavaDocForEditorAction {
    // 在编辑器右键菜单中显示
}

public class TaskCollector {
    public List<DocumentationTask> collectTasks(PsiElement element) {
        // 智能识别类、方法、字段等元素
        // 分析代码上下文
        // 生成任务队列
    }
}

public class TaskExecutor {
    public void executeTasks(List<DocumentationTask> tasks) {
        // 调用 AI 服务生成文档
        // 处理流式响应
        // 应用到代码中
    }
}

public interface AIProvider {
    CompletableFuture<String> generateJavaDoc(CodeContext context, PromptTemplate template);
    boolean supportsStreaming();
    ProviderConfig getDefaultConfig();
}

// 生成前
public class UserService {
    // ...
}

// 生成后
/**
 * 用户服务核心业务类
 *
 * <p>提供用户相关的核心业务功能，包括用户注册、登录、信息查询、积分管理等。
 * 该服务采用 Spring 框架实现，集成了缓存机制以保证性能。
 *
 * <p>主要功能：
 * <ul>
 *   <li>用户注册和登录验证</li>
 *   <li>用户信息查询和更新</li>
 *   <li>用户积分计算和等级管理</li>
 *   <li>用户权限控制</li>
 * </ul>
 *
 * @author dong4j
 * @version 1.0.0
 * @since 1.0.0
 */
public class UserService {
    // ...
}

// 生成前
public UserDTO getUserDetail(String userId) {
    // 复杂的业务逻辑...
}

// 生成后
/**
 * 根据用户ID获取用户详细信息
 *
 * <p>通过用户ID查询用户的完整信息，包括基本资料、积分等级、权限状态等。
 * 该方法会先查询缓存，如果缓存不存在则从数据库查询并更新缓存。
 *
 * @param userId 用户唯一标识，格式为 "user_" + 数字，不能为空
 * @return 用户详细信息对象，包含用户的所有相关信息，如果用户不存在则返回 null
 * @throws IllegalArgumentException 当 userId 格式不正确或为空时抛出
 * @throws ServiceException 当查询数据库出现异常时抛出
 */
public UserDTO getUserDetail(String userId) {
    // 复杂的业务逻辑...
}

// 方法级别的 Prompt 模板示例
public String getMethodPromptTemplate() {
    return """
        请为以下 Java 方法生成详细的 JavaDoc 注释。

        要求：
        1. 方法描述要清晰说明方法的功能和用途
        2. 参数说明要详细，包括格式要求、限制条件等
        3. 返回值说明要具体，说明可能的返回情况
        4. 异常说明要准确，列出所有可能抛出的异常
        5. 使用中文描述，保持专业但易懂的语气
        6. 如果方法有特殊的使用场景或注意事项，也要说明

        代码：
        {code}
        """;
}

// 支持的标签配置
public class CustomJavaDocTagConfig {
    private boolean enabled = true;
    private String tagName = "@author";
    private String description = "作者信息";
    private String defaultValue = "dong4j";
}

public class BatchProcessor {
    public void processBatch(List<PsiFile> files) {
        // 分析文件依赖关系
        // 构建任务图
        // 并行执行任务
        // 实时显示进度
    }
}

// 原始代码
public class VeryLongClassNameWithLotsOfDetails {
    public void veryLongMethodNameWithLotsOfParameters(
        String veryLongParameterName1,
        String veryLongParameterName2,
        String veryLongParameterName3) {
        // 大量实现代码...
    }
}

// 压缩后发送给 AI
public class C {
    public void m(String p1, String p2, String p3) {
        // 核心逻辑保留...
    }
}

public class PerformanceModeExecutor {
    public void executeInParallel(List<DocumentationTask> tasks) {
        // 将任务分配给不同的 AI 服务商
        // 并行执行，大幅提升处理速度
        // 汇总结果，显示统计信息
    }
}

// 错误的做法
public class BadJavaDocGenerator {
    public void generateJavaDoc(PsiMethod method) {
        // 生成 JavaDoc
        String javadoc = generateContent(method);

        // 直接修改 PSI
        method.getDocComment().replace(createDocComment(javadoc));

        // 这会触发 PSI 事件，可能导致循环处理！
    }
}

public class GoodJavaDocGenerator {
    public void generateJavaDoc(PsiMethod method) {
        // 使用 WriteCommandAction 确保线程安全
        WriteCommandAction.runWriteCommandAction(project, () -> {
            // 添加标记，避免重复处理
            boolean wasProcessing = isProcessing.setIfAbsent(true);
            if (wasProcessing) {
                return;
            }

            try {
                String javadoc = generateContent(method);
                PsiDocComment comment = createDocComment(javadoc);

                // 使用正确的 PSI 修改 API
                method.getDocComment().replace(comment);
            } finally {
                isProcessing.remove();
            }
        });
    }
}

// 错误的做法：在 UI 线程中处理流式响应
public class BadStreamingHandler {
    public void handleStreamingResponse(String response) {
        // 直接更新 UI，可能导致界面卡顿
        updateUI(response);
    }
}

public class GoodStreamingHandler {
    private final StringBuilder buffer = new StringBuilder();
    private final ScheduledExecutorService scheduler;

    public void handleStreamingResponse(String chunk) {
        // 在后台线程处理
        buffer.append(chunk);

        // 延迟更新 UI，避免频繁刷新
        scheduler.schedule(this::updateUIIfNeeded, 100, TimeUnit.MILLISECONDS);
    }

    private void updateUIIfNeeded() {
        if (buffer.length() > 0) {
            ApplicationManager.getApplication().invokeLater(() -> {
                // 在 UI 线程更新
                updateUI(buffer.toString());
                buffer.setLength(0);
            });
        }
    }
}

// 错误的配置类定义
@State(name = "BadConfig", storages = @Storage("bad_config.xml"))
public class BadConfig {
    public String apiKey; // 不会自动持久化

    public void setApiKey(String apiKey) {
        this.apiKey = apiKey; // 需要手动触发保存
    }
}

@State(name = "JavaDocAISettings",
       storages = @Storage("zeka.stack.intelliai.javadoc.xml"))
public class SettingsState implements PersistentStateComponent<SettingsState> {
    public AIProviderConfig providerConfig = new AIProviderConfig();
    public Set<String> supportedLanguages = new HashSet<>();

    @Nullable
    @Override
    public SettingsState getState() {
        return this;
    }

    @Override
    public void loadState(@NotNull SettingsState state) {
        XmlSerializerUtil.copyBean(state, this);
    }
}

// 重构前：一个没有任何文档的复杂方法
public List<OrderDTO> getOrders(String userId, String status, Date start, Date end) {
    List<Order> orders = orderMapper.findByUserIdAndStatusAndCreateTimeBetween(userId, status, start, end);
    return orders.stream().map(this::convertToDTO).collect(Collectors.toList());
}

// 使用插件生成后
/**
 * 根据用户ID、订单状态和时间范围查询订单列表
 *
 * <p>查询指定用户在给定时间范围内的订单信息，支持按状态筛选。
 * 该方法会调用数据库查询，然后将订单实体转换为 DTO 对象返回。
 * 主要用于订单列表展示和订单管理功能。
 *
 * @param userId 用户唯一标识，不能为空
 * @param status 订单状态筛选条件，可选值：PENDING, PROCESSING, COMPLETED, CANCELLED，可为空表示查询所有状态
 * @param start 开始时间，查询范围的起始时间，不能为空
 * @param end 结束时间，查询范围的结束时间，不能为空
 * @return 订单信息列表，包含订单的基本信息、商品信息、支付状态等，如果无匹配订单则返回空列表
 * @throws IllegalArgumentException 当 userId、start、end 为空时抛出
 * @throws ServiceException 当数据库查询出现异常时抛出
 */
public List<OrderDTO> getOrders(String userId, String status, Date start, Date end) {
    List<Order> orders = orderMapper.findByUserIdAndStatusAndCreateTimeBetween(userId, status, start, end);
    return orders.stream().map(this::convertToDTO).collect(Collectors.toList());
}

// 开发新功能时快速生成文档
/**
 * 用户积分计算服务类
 *
 * <p>提供用户积分计算相关的核心功能，包括积分获取、消费计算、等级评定等。
 * 该服务整合了多种积分来源（购物、签到、分享等），支持复杂的积分规则配置。
 *
 * @author dong4j
 * @version 1.0.0
 * @since 1.0.0
 */
@Service
public class UserScoreService {

    /**
     * 计算用户的总积分
     *
     * <p>汇总用户所有类型的积分，包括可用积分、冻结积分、历史积分等。
     * 该方法会实时查询数据库，确保积分信息的准确性。
     *
     * @param userId 用户唯一标识，不能为空
     * @return 用户积分信息，包含总积分、可用积分、冻结积分等详细信息
     * @throws IllegalArgumentException 当 userId 为空时抛出
     * @throws ServiceException 当查询过程中出现异常时抛出
     */
    public UserScoreInfo calculateTotalScore(String userId) {
        // 实现逻辑...
    }
}