package com.sundot.airport.exam.service;

import com.sundot.airport.common.dto.ModuleStatisticsDTO;
import com.sundot.airport.common.dto.WeakModuleDetailDTO;

import java.util.List;

/**
 * <b>功能名：</b>IWeakModuleStatisticsService<br>
 * <b>说明：</b> 薄弱模块统计Service接口（用于智能出题） <br>
 * <b>著作权：</b> Copyright (C) 2025 SUNDOT CORPORATION<br>
 * <b>修改履历：
 *
 * @author Simon Lin
 */
public interface IWeakModuleStatisticsService {

    /**
     * 分析用户的薄弱模块（按二级分类）
     * <p>
     * 算法逻辑：
     * 1. 统计用户在指定时间范围内的错题数（按二级分类）
     * 2. 统计用户在指定时间范围内的巡检问题数（按二级分类）
     * 3. 计算综合影响分 = 错题数 × 错题权重 + 巡检问题数 × 巡检权重
     * 4. 按综合影响分降序排序
     * 5. 返回 TOP3 薄弱模块
     * </p>
     *
     * @param userId 用户ID
     * @param statsDays 统计天数（向前推算）
     * @return TOP3薄弱模块列表（按影响度降序）
     */
    List<ModuleStatisticsDTO> analyzeTop3WeakModules(Long userId, Integer statsDays);

    /**
     * 分析用户的薄弱模块（使用系统启用的规则配置）
     *
     * @param userId 用户ID
     * @return TOP3薄弱模块列表（按影响度降序）
     */
    List<ModuleStatisticsDTO> analyzeTop3WeakModulesWithActiveRule(Long userId);

    /**
     * 获取用户的薄弱模块详细信息（用于验证算法逻辑）
     * <p>
     * 包含完整的计算过程和原始数据：
     * - 错题数、巡检问题数
     * - 使用的规则配置（权重、统计天数）
     * - 中间计算结果（错题得分、巡检问题得分）
     * - 最终的综合影响分
     * - 计算公式说明
     * </p>
     *
     * @param userId 用户ID
     * @return TOP3薄弱模块详细信息列表（按影响度降序，包含排名）
     */
    List<WeakModuleDetailDTO> getTop3WeakModulesDetail(Long userId);

    /**
     * 获取用户的薄弱模块详细信息及出题计划（用于验证算法逻辑）
     * <p>
     * 包含完整的计算过程和出题计划：
     * - 薄弱模块分析结果
     * - 题目分配计划（每个模块分配多少题）
     * - 实际题库可用题目数
     * </p>
     *
     * @param userId 用户ID
     * @param questionCount 题目数量
     * @return TOP3薄弱模块详细信息列表（包含出题计划）
     */
    List<WeakModuleDetailDTO> getTop3WeakModulesDetailWithAllocation(Long userId, int questionCount);
}
