package com.hotwj.platform.securityManagement.trainingParticipant.service;

import com.hotwj.platform.securityManagement.trainingParticipant.domain.bo.HotTrainingParticipantAddBo;
import com.hotwj.platform.securityManagement.trainingParticipant.domain.bo.HotTrainingParticipantBo;
import com.hotwj.platform.securityManagement.trainingParticipant.domain.vo.DriverLearningRecordVo;
import com.hotwj.platform.securityManagement.trainingParticipant.domain.vo.HotTrainingParticipantVo;
import com.hotwj.platform.securityManagement.trainingParticipant.domain.vo.TrainingParticipantStatVo;
import org.dromara.common.mybatis.core.page.PageQuery;
import org.dromara.common.mybatis.core.page.TableDataInfo;

import java.util.Collection;
import java.util.List;
import java.util.Map;

/**
 * 培训参与人员Service接口
 *
 * @author shihongwei
 * @date 2025-12-26
 */
public interface IHotTrainingParticipantService {

    /**
     * 查询培训参与人员
     *
     * @param id 主键
     * @return 培训参与人员
     */
    HotTrainingParticipantVo queryById(Long id);

    /**
     * 分页查询培训参与人员列表
     *
     * @param bo        查询条件
     * @param pageQuery 分页参数
     * @return 培训参与人员分页列表
     */
    TableDataInfo<HotTrainingParticipantVo> queryPageList(HotTrainingParticipantBo bo, PageQuery pageQuery);

    /**
     * 驾驶员学习记录列表（参与培训计划+计划信息）
     */
    TableDataInfo<DriverLearningRecordVo> queryDriverLearningRecordPage(Long companyId, String userId, PageQuery pageQuery);

    /**
     * 按培训ID聚合统计参与人数及完成情况
     */
    List<TrainingParticipantStatVo> queryTrainingParticipantStats(List<Long> trainingIds);

    /**
     * 查询符合条件的培训参与人员列表
     *
     * @param bo 查询条件
     * @return 培训参与人员列表
     */
    List<HotTrainingParticipantVo> queryList(HotTrainingParticipantBo bo);

    /**
     * 新增培训参与人员
     *
     * @param bo 培训参与人员
     * @return 是否新增成功
     */
    Boolean insertByBo(HotTrainingParticipantBo bo);

    /**
     * 批量添加培训参与人员
     *
     * @param bo 添加参数
     * @return 是否添加成功
     */
    Boolean addParticipants(HotTrainingParticipantAddBo bo);

    /**
     * 修改培训参与人员
     *
     * @param bo 培训参与人员
     * @return 是否修改成功
     */
    Boolean updateByBo(HotTrainingParticipantBo bo);

    /**
     * 校验并批量删除培训参与人员信息
     *
     * @param ids     待删除的主键集合
     * @param isValid 是否进行有效性校验
     * @return 是否删除成功
     */
    Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid);

    /**
     * 更新学员某个课程的人脸识别照片
     *
     * @param participantId    培训参与人员ID
     * @param trainingCourseId 企业课程配置ID
     * @param studyPhotoOssId  学习照片OSS文件ID
     * @return 是否更新成功
     */
    boolean updateStudyPhotoOssId(Long participantId, Long trainingCourseId, Long studyPhotoOssId);

    /**
     * 批量计算培训计划学员进度（返回百分比字符串，如 "85%"）
     *
     * @param trainingId 培训ID
     * @param companyId  企业ID
     * @param userIds    学员ID列表（如果为空则不限制）
     * @return Map<UserId, ProgressLabel>
     */
    Map<String, String> calculateProgressBatch(Long trainingId, Long companyId, List<String> userIds);
}
